automation run-lifecycle doors (cancel, restore-suspension): docs route tables, `:name` scoping clause, and the SDK-method decision left open by PR #16755

[os-zhuang]

PR #16755 (card #13953) shipped POST /automation/:name/runs/:runId/cancel and …/restore-suspension and PASSed contract review at 34feecba7 (#16755 (comment)). Three non-blocking findings were carried out of that review rather than holding the PR:

Terminal state (one sentence)

The two doors are documented where the rest of the run family is, their ledger notes say what the :name segment does and does not scope, and whether a JS SDK method exists is a recorded decision rather than scope prose.

Items

1. Docs route tables (review F7/N2). content/docs/automation/flows.mdx (the run-family table, around the resume / screen rows) and packages/services/service-automation/README.md (same table) list the run family without the two new doors. Add both rows with their gate (PLATFORM_ADMIN posture rung, isSystem bypass), body { reason? }, and the 501-when-absent shape. ⛔ content/docs/releases/** stays untouched.
2. :name scoping clause (review F5/N5). Both arms call the verb with parts[2] and never check that the run belongs to flow parts[0] — the existing convention of resume / screen / getRun. One clause in each route-ledger.ts note saying so, so the flow-scoped shape is not read as a scoping the door enforces.
3. SDK method decision (review F4/N4). Both ledger rows are server-only with prose "adding one reclassifies the row to sdk". Record the decision: either file the client.automation.cancelRun / restoreSuspension card, or state on this card that they stay server-only until an operator asks, and cite that from both ledger notes.

H-check (one)

node scripts/docs-audit/affected-docs.mjs on the head lists neither flows.mdx nor the README as naming a route the tree does not document, and route-ledger.conformance.test.ts is green with the amended notes.

Related

#13953 (card) · PR #16755 · #16285 (dogfood not in the derived gate families — separate, already open) · #3877 (Stage-D response-schema ratchet, F8 observation).

Filed by the director seat after the contract review of PR #16755 @ 34feecba7.

[os-trump]

Claim: session session_012zTkyNHJ7TkuN2oXtP5x37 · branch claude/issue-16896-automation-run-lifecycle-doors-docs · seat domain:services PM (#6021)

Clause-②: no

Why no, and why item 3's ruling is what keeps it no. Items 1 and 2 are documentation and ledger prose. The mechanical floor does not fire on them: no new exported symbol, no new key on a published payload, no packages/spec/src/**. ⭐ Item 3 is the one that could have moved it — filing the client.automation.cancelRun / restoreSuspension SDK card and shipping the methods would add two new exports to a published package, i.e. a mechanical yes. It is ruled below, and the ruling is the conservative one, so the declaration holds.

Item 3 — ruled here: they stay server-only until an operator asks

The card leaves this open with two doors and asks for a recorded decision rather than scope prose. Recorded:

client.automation.cancelRun and client.automation.restoreSuspension are not added. Both ledger rows stay server-only. The reason is that no operator has asked, and an SDK method is a published surface that cannot be withdrawn cheaply — an inert method is worse than an absent one (ADR-0078's shape: a declared-but-unexercised surface is metadata pretending to be capability). ⛔ Not "deferred", which is what a scope note says and a reader then re-litigates; decided, with a named reopening condition: an operator or app repo asking for programmatic cancel/restore. At that moment the row reclassifies to sdk and the change is clause-② yes.

Both ledger notes must cite this comment so the next reader finds the decision instead of the prose that prompted the question. ⛔ Do not file the SDK card.

The one thing item 2 must not overstate

:name is not a scoping the door enforces — both arms call the verb with parts[2] and never verify the run belongs to flow parts[0]. ⚠️ The clause must say that plainly and ⛔ must not be written as a defect note or a TODO: it is the existing, deliberate convention of resume / screen / getRun, and this card is not the place to change it. The clause exists so a reader stops inferring a guarantee from the URL shape. If the delivery concludes the convention is actually wrong, that is a separate card, reported — ⛔ not a fix riding on a docs PR.

Fences

• ⛔ content/docs/releases/** stays untouched — the card says so and so does AGENTS.md. Release notes are written centrally at release time; this PR's input to them is its .changeset/*.md.
• ⛔ No behaviour change. If a docs row cannot be written truthfully without changing code, stop and report — a doc corrected by editing the runtime is a code PR wearing a docs label.
• Single-writer, read at claim time against all 22 open PRs: content/docs/automation/flows.mdx, packages/services/service-automation/README.md and the two route-ledger.ts files are claimed by none. ⚠️ My fix(service-automation): persist the terminal run status distinction (cancelled / timed_out survive a restart) #17008 holds packages/services/service-automation/src/{engine,index,suspended-run-store,sys-automation-run.object}.ts and two test files in the same package — file-level disjoint, and it has auto-merge armed. ⛔ Do not touch any of those six files; if a docs row cannot be written without one, stop and report.

H-check, carried from the card verbatim

node scripts/docs-audit/affected-docs.mjs on the head lists neither flows.mdx nor the README as naming a route the tree does not document, and route-ledger.conformance.test.ts is green with the amended notes.

⭐ That check is only worth what its control is worth: it must be shown to be capable of failing here — remove one of the two new rows and show it goes red — or its green is NOT MEASURED.

---

Generated by Claude Code

[os-trump]

os-dev-report

{
  "issue": 16896,
  "status": "done",
  "branch": "claude/issue-16896-automation-run-lifecycle-doors-docs",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/17038",
  "premise_still_valid": true,
  "summary": "Added the two run-lifecycle-door rows (cancel, restore-suspension) to both route tables (flows.mdx, service-automation README), added a `:name`-scoping clause to each of the two route-ledger.ts notes (cancel, restore-suspension -- one file, two entries; the claim's 'two route-ledger.ts files' resolved to this after an exhaustive repo search turned up only one file of that name), and replaced the open-ended SDK-reclassification prose in both notes with a citation of the seat's ruling (issuecomment-5595099733 on #16896) plus its reopening condition. No behaviour change, no new exported symbol/payload key/spec path (Clause-2 stays no), PR #17008's six fenced files untouched. Mandatory H-check ablation ran on both halves and found the named check cannot see a missing row in either direction -- reported below and in the PR body rather than smoothed over.",
  "tests": "route-ledger.conformance.test.ts (packages/runtime): 6/6 green before ablation, during the ablation-restored state, and on the final amended notes -- run via `bash scripts/pm/os-verify-lock.sh -c 'pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 src/route-ledger.conformance.test.ts'`. `pnpm --filter @objectstack/runtime typecheck`: green (tsc + check:test-typecheck). `node scripts/docs-audit/affected-docs.mjs --json`: flows.mdx correctly listed as affected via the PLATFORM_ADMIN literal anchor; README.md is outside that tool's declared scope (content/docs/**/*.mdx only) by its own docblock.\n\nH-CHECK POSITIVE CONTROL (mandatory, both halves) -- predicted then measured, mutate-prove-restore-prove protocol throughout:\n(1) flows.mdx / affected-docs.mjs: predicted no change in tool output if a row's absence is invisible to it. Baseline blob 7140028510b96141d4de8cc166a6d93edd9e383e (grep -c restore-suspension = 1). Mutated: sed-deleted the restore-suspension row; landing proven (grep -c = 0, hash 2b01c2560c0b7bed0d2de669fc3490fa895a3c15, differs from baseline). Ran `node scripts/docs-audit/affected-docs.mjs --json` inside the mutated window: summary/anchor list BYTE-IDENTICAL to the unmutated run (still '13 docs ... 2 anchor(s) ...'). RESULT: RED DID NOT FIRE -- confirmed finding, not smoothed over. Restored via `trap 'git checkout HEAD -- \"$TARGET\"' EXIT`; blob rehashed to 7140028510b96141d4de8cc166a6d93edd9e383e (== baseline) and `git diff HEAD` empty.\n(2) route-ledger.ts / route-ledger.conformance.test.ts: predicted GREEN-persists since the suite's only assertions are domain-level presence and per-row note-non-emptiness, neither of which one missing route among many breaks. Baseline blob e64085e7bccbf6e018e3ddfe8e80a2efc3818048. Mutated: deleted the entire two-line `cancel` ROUTE_LEDGER entry (lines 411-412); landing proven (grep -c for the row = 0, hash 4620afe131844b3cd3f314753c8f3e5ebdfcc72c, differs from baseline). Ran the vitest suite inside the mutated window under the shared lock: 6/6 STILL PASSED. RESULT: RED DID NOT FIRE -- confirmed finding. Restored via the same trap pattern; blob rehashed to e64085e7bccbf6e018e3ddfe8e80a2efc3818048 (== baseline) and `git diff HEAD` empty.\nCONCLUSION, stated by name: the named H-check (affected-docs.mjs + route-ledger.conformance.test.ts) cannot detect either of the two new rows going silently missing, in EITHER direction (docs table or ledger entry). Its green here is a real property (both files currently DO carry both rows, verified by direct grep) but is not evidence the check would catch a future regression of this exact shape.\n\nGATE SWEEP: `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` on the final merged/pushed tree (commit 98d70c655, merge-base de1a6114a) derived 73 commands (39 pnpm, 34 direct node) from the 3 changed paths. Ran all 73; first pass: 69 green, 4 failed as PREREQUISITE-NOT-MET-class (stale/absent dist/ in a worktree that had never had a full `pnpm build`: check:skill-examples missing client-react .d.ts, check:dts-closure missing several packages/spec/dist subpaths, check:dual-build-cjs-loads exit 3 naming ~38 packages with no dist/, check:lean-entry-closure missing an objectql/spec resolution) -- none are red findings from this diff, all are the documented 'MODULE_NOT_FOUND-class exit is not a red gate' pattern. Ran a full `pnpm build` (73/73 turbo tasks succeeded) and re-ran all four: all four now green, re-measured with real output. Final reconciliation: `node scripts/pm/dispatch-gates.mjs --ran ran.list --repo objectstack-ai/objectstack` -> '73 derived, 73 run, 0 NOT-MEASURED, 0 UNRUN'. `pnpm check:route-envelope` (Silent bucket per #16828, never derived) run explicitly: green, '11 route module(s) audited: 8 conformant, 2 ratcheted, 1 exempt' -- unaffected since no route registration changed. `check:nul-bytes` and `check:doc-authoring` both green in the sweep; confirmed by direct grep that no bare `#NNNN` tracker id was introduced into any route-ledger.ts note string (the two citation URLs use `#issuecomment-...`, which the doc-authoring INTERNAL_ID regex `#[0-9]{3,5}` does not match).",
  "mcp_calls": "11 -- issue_read get + get_comments (#16896), pull_request_read get + get_comments (#16755), list_pull_requests, pull_request_read get_files (#17008), search_issues (dupe check), create_pull_request (#17038), plus add_issue_comment (this report) and one get_comments + one pull_request_read get as read-back verification after posting",
  "open_questions": [
    {
      "question": "The H-check named on this card (affected-docs.mjs + route-ledger.conformance.test.ts) cannot detect either of the two new rows going missing, in either direction -- confirmed by a firing positive control on both halves. Worth a follow-up card to strengthen it (e.g. a per-route completeness assertion), or is the current advisory-only / hygiene-only design intentional and this is just a known limit to live with?",
      "options": [
        "A: file a card proposing route-ledger.conformance.test.ts (or a new gate) assert every SDK-adjacent doc table row has a corresponding ledger row and vice versa",
        "B: no card -- the tool's stated scope (drift-forward via anchors, domain-level ledger hygiene) was never meant to catch per-row completeness, and this finding is filed here for the record only"
      ],
      "recommendation": "B for now, with this report as the record -- the gap is real but narrow (exactly two new rows, both correctly present today, verified by direct grep); A is the PM's call on whether the class of change is common enough to warrant a new assertion."
    }
  ],
  "out_of_scope_findings": []
}

---

Generated by Claude Code