Repository navigation
SDK lossless mutations, structured recovery, and snapshot lease safety - #961
Conversation
Fail fast on unresolved local dependency targets across SDK, CLI, bulk, and MCP paths while preserving explicit forward-reference and external-reference escape hatches. Make acceptance-criteria repairs atomic, move type coercion into structured receipts, harden snapshot lease renewal, refresh generated contracts, and add full behavioral coverage and operator documentation. Tracks pm-x3dq0l, pm-lppm6y, pm-embm6t, and pm-usq49n; also records pm-obh6lo dependency integration evidence.
…updates Bumps the github-actions group with 5 updates in the / directory: | Package | From | To | | --- | --- | --- | | [pnpm/action-setup](https://github.com/pnpm/action-setup) | `6.0.9` | `6.0.10` | | [github/codeql-action/init](https://github.com/github/codeql-action) | `4.37.4` | `4.37.6` | | [github/codeql-action/analyze](https://github.com/github/codeql-action) | `4.37.4` | `4.37.6` | | [CodSpeedHQ/action](https://github.com/codspeedhq/action) | `5.0.1` | `5.0.3` | | [github/codeql-action/upload-sarif](https://github.com/github/codeql-action) | `4.37.4` | `4.37.6` | Updates `pnpm/action-setup` from 6.0.9 to 6.0.10 - [Release notes](https://github.com/pnpm/action-setup/releases) - [Commits](pnpm/action-setup@0ebf471...0977fd9) Updates `github/codeql-action/init` from 4.37.4 to 4.37.6 - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@f205ea1...5595cca) Updates `github/codeql-action/analyze` from 4.37.4 to 4.37.6 - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@f205ea1...5595cca) Updates `CodSpeedHQ/action` from 5.0.1 to 5.0.3 - [Release notes](https://github.com/codspeedhq/action/releases) - [Changelog](https://github.com/CodSpeedHQ/action/blob/main/CHANGELOG.md) - [Commits](CodSpeedHQ/action@8847237...4296e51) Updates `github/codeql-action/upload-sarif` from 4.37.4 to 4.37.6 - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](github/codeql-action@f205ea1...5595cca) --- updated-dependencies: - dependency-name: CodSpeedHQ/action dependency-version: 5.0.3 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions - dependency-name: github/codeql-action/analyze dependency-version: 4.37.6 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions - dependency-name: github/codeql-action/init dependency-version: 4.37.6 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions - dependency-name: github/codeql-action/upload-sarif dependency-version: 4.37.6 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions - dependency-name: pnpm/action-setup dependency-version: 6.0.10 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: github-actions ... Signed-off-by: dependabot[bot] <support@github.com>
Attach every updated workflow and the security/docs/transport verification command to pm-obh6lo so the Dependabot changes remain traceable when incorporated into the broad SDK branch.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Reviewer's GuideImplements lossless acceptance-criteria and dependency-mutation contracts across SDK/CLI/create/update/update-many, adds explicit unresolved-dependency and type-coercion signaling, hardens workspace snapshot lock renewal, and refreshes tests/docs/tooling to align with the new behavior. Sequence diagram for dependency target validation on update mutationssequenceDiagram
actor User
participant Cli
participant UpdateCommand as runUpdate
participant DepValidation as assertDependencyTargetsResolvable
participant Store as locateItem
User->>Cli: pm update --dep ... [--allow-unresolved-deps]
Cli->>UpdateCommand: runUpdate(options)
UpdateCommand->>DepValidation: assertDependencyTargetsResolvable({ pmRoot, dependencies, idPrefix, itemFormat, typeToFolder, allowUnresolvedDeps })
loop each local dependency id
DepValidation->>Store: locateItem(pmRoot, id, idPrefix, itemFormat, typeToFolder)
Store-->>DepValidation: located|null
end
alt all targets located
DepValidation-->>UpdateCommand: []
else some missing and allowUnresolvedDeps == true
DepValidation-->>UpdateCommand: ["dependency_target_unresolved:<id>", ...]
else some missing and allowUnresolvedDeps != true
DepValidation-->>UpdateCommand: throw PmCliError(code=dependency_target_not_found)
end
UpdateCommand-->>Cli: result with aggregated warnings
Sequence diagram for workspace snapshot restore heartbeat lease renewalsequenceDiagram
actor User
participant Restore as restoreWorkspaceSnapshotWithRecovery
participant Heartbeat as WorkspaceLockHeartbeat
participant FS as renew
User->>Restore: restoreWorkspaceSnapshotWithRecovery(lockPath, lockTtlSeconds)
Restore->>Heartbeat: new WorkspaceLockHeartbeat(lockPath, intervalMs)
Restore->>Heartbeat: start()
Heartbeat->>Heartbeat: scheduleRenewal()
Heartbeat->>FS: renew()
FS-->>Heartbeat: read lock file and validate ownership
Restore->>Heartbeat: refreshNow()
Heartbeat->>Heartbeat: scheduleRenewal()
Heartbeat->>FS: renew()
FS-->>Heartbeat: read lock file and validate ownership
Heartbeat->>Heartbeat: assertHealthy()
alt ownership lost
Heartbeat-->>Restore: throw PmCliError
else ownership retained
Heartbeat-->>Restore: lease renewed
end
Restore-->>User: snapshot restored or recovery error
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe PR adds dependency-target validation, atomic acceptance-criteria mutation rules, structured warnings and errors, workspace lease refresh handling, refreshed GitHub Actions pins, and related tests, documentation, contract fixtures, and project-management records. ChangesMutation contracts and dependency validation
Workspace lease renewal
Pinned GitHub Actions
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant MutationCommand
participant Lifecycle
participant DependencyValidator
participant WorkspaceLookup
MutationCommand->>Lifecycle: submit create or update options
Lifecycle->>DependencyValidator: validate dependency targets
DependencyValidator->>WorkspaceLookup: resolve local target IDs
WorkspaceLookup-->>DependencyValidator: target results
DependencyValidator-->>Lifecycle: warnings or structured error
Lifecycle-->>MutationCommand: mutation result
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 2📝 Generate docstrings 💡
🛠️ Fix failing CI checks 💡
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Merging this PR will improve performance by 1.78%
|
| Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|
| ⚡ | createQueryFingerprint |
1.5 ms | 1.4 ms | +1.78% |
Tip
Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.
Comparing feat/sdk-lossless-mutations-structured-recovery (30e7b22) with main (229fd3f)
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Regenerate the aggregate contract fixture after hosted static CI identified missing dependency and acceptance-criteria error catalog entries. Record the exact CI disposition and generated artifact linkage on the active PM lineage.
|
@greptileai review @coderabbitai full review Exact-head update 6054f45 regenerates the canonical aggregate contract fixture after hosted static CI identified missing structured error catalog entries. Please review the full PR at this head. |
|
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/sdk/dependency-flag-validation.ts`:
- Around line 89-92: Update the target sorting in the resolutions flow around
the unresolved dependency collection to use a deterministic code-unit comparator
instead of localeCompare. Preserve deduplication and ensure the resulting order
is reused consistently for warning tokens, unresolved_targets, and
recovery.missing structured output.
In `@src/sdk/generated-error-code-catalog.ts`:
- Around line 10-22: Update the catalog source entry for
acceptance_criteria_mutation_conflict to include update-many in
emitting_commands, then regenerate generated-error-code-catalog.ts. Preserve the
existing update declaration and ensure catalog consumers expose both mutation
commands.
In `@src/sdk/workspace-snapshot.ts`:
- Around line 875-879: Move the heartbeatStopped = false assignment before await
heartbeat.refreshNow() in the heartbeat restart callback, ensuring the outer
cleanup invokes heartbeat.stop() even when refreshNow() rejects.
In `@tests/fixtures/contracts/full.json`:
- Around line 19746-19748: The shared acceptanceCriteria description is
incorrectly additive for all actions. Update the acceptanceCriteria description
handling in the tool-parameter table/schema generation so update and update-many
mention removeAc/addAc atomic repairs, while create and plan use wording that
does not imply those unsupported fields.
In `@tests/helpers/itemFactory.ts`:
- Line 76: Update the item factory helper around the args construction to make
unresolved dependencies opt-in via an explicit test override. Remove the
unconditional "--allow-unresolved-deps" entry from the base arguments, and
append it only when that override is enabled, preserving default
dependency-target validation for all other tests.
In `@tests/unit/sdk/workspace-snapshot.spec.ts`:
- Around line 259-272: Update the heartbeat refresh test around
heartbeat.start() to create an expired lock fixture deterministically, without
starting the periodic scheduler; invoke only heartbeat.refreshNow(), then verify
competing acquisition is rejected. Replace the resulting deterministic-test
evidence through the pm CLI, appending to the PM history rather than editing
.agents/pm/history/*.jsonl or generated projections directly.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 6ad313ce-1f2d-450d-8b44-b6e3a5069233
📒 Files selected for processing (53)
.agents/pm/chores/pm-obh6lo.toon.agents/pm/history/pm-embm6t.jsonl.agents/pm/history/pm-lppm6y.jsonl.agents/pm/history/pm-obh6lo.jsonl.agents/pm/history/pm-usq49n.jsonl.agents/pm/history/pm-x3dq0l.jsonl.agents/pm/issues/pm-embm6t.toon.agents/pm/issues/pm-lppm6y.toon.agents/pm/issues/pm-usq49n.toon.agents/pm/issues/pm-x3dq0l.toon.github/workflows/auto-release.yml.github/workflows/ci.yml.github/workflows/codeql.yml.github/workflows/codspeed.yml.github/workflows/docs.yml.github/workflows/nightly.yml.github/workflows/release.yml.github/workflows/scorecard.ymldocs/AGENT_GUIDE.mddocs/COMMANDS.mddocs/SDK.mdsdk/public-surface.jsonsrc/core/shared/errors.tssrc/sdk/cli-contracts/commander-mutation-options.tssrc/sdk/cli-contracts/flag-contracts.tssrc/sdk/cli-contracts/registration-helpers.tssrc/sdk/cli-contracts/tool-option-contracts.tssrc/sdk/cli-contracts/tool-parameter-tables.tssrc/sdk/cli-contracts/tool-schema.tssrc/sdk/dependency-flag-validation.tssrc/sdk/generated-error-code-catalog.tssrc/sdk/lifecycle/create.tssrc/sdk/lifecycle/update-many.tssrc/sdk/lifecycle/update.tssrc/sdk/workspace-snapshot.tstests/fixtures/contracts/full.jsontests/helpers/itemFactory.tstests/integration/cli.integration.spec.tstests/integration/dependency-alias.integration.spec.tstests/integration/mcp-dynamic-package-actions.spec.tstests/unit/commands/context-command.spec.tstests/unit/commands/create-command.spec.tstests/unit/commands/deps-command.spec.tstests/unit/commands/list-command.spec.tstests/unit/commands/lossless-mutation-contracts.spec.tstests/unit/commands/next-command.spec.tstests/unit/commands/reindex-command.spec.tstests/unit/commands/templates-command.spec.tstests/unit/commands/update-command.spec.tstests/unit/commands/update-many-command.spec.tstests/unit/commands/validate-command.spec.tstests/unit/sdk/graph/run.spec.tstests/unit/sdk/workspace-snapshot.spec.ts
Use locale-independent dependency ordering, attribute criteria conflicts to bulk updates, scope criteria guidance per action, preserve default validation in test factories, and make snapshot activation cleanup plus refresh-only lease tests deterministic. Verified with focused 71-test review suite, generated-contract checks, lint/static gates, and 7141 tests at exact 100/100/100/100 coverage.
|
@greptileai review @coderabbitai full review All six prior thread findings are implemented, replied to, reacted to, and resolved at exact head ac47bef. Focused review tests pass 71/71 and full coverage passes 7141/7141 at 100/100/100/100. Please perform a fresh full-head review. |
|
|
|
Disposition for Sourcery guide #961 (comment): acknowledged as an accurate architecture map. Its sequence diagrams match the implemented dependency validation and lease-renewal paths; it raised no code finding. Sourcery review availability is separately rate-limited and is not counted as approval. |
|
Disposition for CodeRabbit summary #961 (comment): all six actionable findings from review 4895007964 were verified, implemented at ac47bef, individually replied to and up-voted, and all six threads are resolved. The exact head passes hosted static, type, compatibility, smoke, coverage, security, benchmark, and platform gates. |
|
Disposition for CodSpeed report #961 (comment): acknowledged as useful exact-head evidence. The reported pagination benchmark improves 1.6%, ten benchmarks are unchanged, and independent repository SDK and CLI timing gates pass. |
|
Disposition for Codecov report #961 (comment): acknowledged. Codecov confirms all modified coverable lines and tests are green; the independent full local run is 7141/7141 with exactly 100% statements, branches, functions, and lines. |
|
Disposition for CodeRabbit re-request #961 (comment): the requested 6054f45 review was rate-limited, so it is recorded as unavailable rather than approval. The subsequent actionable review was fully addressed, and a later exact-head request was made after those fixes. |
|
Disposition for final CodeRabbit re-request #961 (comment): the fresh ac47bef review was rate-limited for 35 minutes, beyond the requested bounded review window. No provider approval is inferred; exact-head hosted gates, the thread-aware inventory, six resolved findings, and independent 100/100/100/100 coverage are the merge evidence. |
|
Review-object disposition inventory: Sourcery review 4894936728 is an unavailable weekly-limit response, not approval. CodeRabbit review 4895007964 supplied six actionable findings; every finding was implemented, reacted to, replied to, and resolved. Follow-up CodeRabbit review objects 4895107701, 4895107866, 4895108314, 4895108776, 4895108792, and 4895108846 acknowledge those six thread replies; each review and its corresponding inline acknowledgement has been up-voted, and exact head ac47bef is fully green. |
Close and release the five actively delivered items with exact-head review and verification evidence, leave no item in progress, and regenerate CHANGELOG.md exclusively through pm-changelog 2026.8.7.
|
@greptileai review @coderabbitai full review Final exact-head update 2befdf4 contains only canonical pm close/release history and CHANGELOG.md generated by pm-changelog 2026.8.7. All five delivered items are closed and no item remains in progress. Please review this final head. |
|
|
Populate resolution on all four delivered issues and full expected/actual/resolution evidence on the Actions chore, restoring the validate-resolution ratchet to its declared ceiling without weakening governance.
|
@greptileai review @coderabbitai full review Final governance correction at head 30e7b22 populates typed resolution evidence on the delivered items after the hosted tracker ratchet identified the omission. The ratchet now passes at its original ceiling; no gate was weakened. Please review this final head. |
|
|
|
Final CodeRabbit availability disposition: the 2befdf4 closeout review and the 30e7b226 typed-resolution review were both rate-limited. Each status is acknowledged and up-voted, but neither is treated as approval. The earlier full review produced six findings that are all fixed and resolved; the final exact head has no code changes beyond those reviewed fixes, all hosted checks are green, and the tracker ratchet specifically passes at its original ceiling. |
Summary
PM lineage
Verification
Review notes
The generated public-surface acknowledgement is intentional: the typed SDK now exposes explicit unresolved-dependency control and richer structured error details. Existing implicit dangling local edges now fail closed unless callers opt in.
Summary by Sourcery
Enforce lossless, fail-fast mutation contracts for acceptance criteria and dependencies across SDK, CLI, bulk, and MCP flows, while tightening workspace snapshot lock renewal and refreshing public contracts, docs, and CI tooling.
New Features:
Bug Fixes:
Enhancements:
CI:
Documentation:
Tests:
Summary by cubic
Makes SDK/CLI mutations lossless and predictable: unresolved local dependencies fail fast by default (opt-in allowed), acceptance-criteria edits are atomic, snapshot restore leases are safer, and outputs use clear, structured JSON. Also publishes structured mutation error codes with emitting-command mapping, enforces schema guardrails, updates docs/contracts/CHANGELOG, and pins GitHub Actions to newer SHAs.
New Features
pnpm/action-setup,github/codeql-action/*, andCodSpeedHQ/action.Migration
Written for commit 30e7b22. Summary will update on new commits.