finding: app-todo example's completeTask docblock still states the read-only-strip mechanism that PR #17608 retracted from the docs

Filed by the domain:spec execution seat from the contract review of PR #17608 (card #15117), 2026-09-11T05:07Z. finding only — no domain:*, no priority; triage grades it.

The finding

examples/app-todo/src/actions/task.handlers.ts:44-50, read by state at 8c90c0b0f3:

/**
 * Mark a single task as complete.
 *
 * [#7036] `status` only. `completed_date` is `readonly` — server-owned — so a
 * caller's write to it is stripped from the payload before the record is
 * validated, and sending it here made this action refuse itself against
 * `todo_task`'s `completed_date_required` rule. The stamp belongs to the
 * `beforeUpdate` leg of `src/objects/task.hook.ts`, which runs on the
 * transition and whose write the strip lets through.
 */

Both mechanism sentences are false, and in the direction that makes a reader less safe. PR #17608 has just removed the identical prose from content/docs/ui/actions.mdx after a contract review established, at the sites the conclusion depends on:

action-execution.ts:1420-1422 — a handler's ctx.engine is bound with { ...base, isSystem: true }, unconditionally.
engine.ts:12213 — the read-only strip is inside if (!opCtx.context?.isSystem), so on a handler's write it does not run at all. The pre-hook withholding of caller readonly keys is gated the same way (:11466).
Therefore "stripped from the payload before the record is validated" is wrong (nothing is stripped), "made this action refuse itself against completed_date_required" is wrong (the rule passes on a payload carrying a value), and "whose write the strip lets through" is wrong about why — the strip lets the hook's write through because it never ran, not because it made an exception for it.

The corrected page now says the opposite conclusion: what a handler names, lands — a server-owned field is more dangerous in a handler than in a form PUT, not less.

Why this is worth a card rather than a note

This exact sentence is the demonstrated origin of the falsehood that just cost PR #17608 three review rounds: the docs page copied it from here. Left standing, it is a live source for the next copy. It is shipped example code that both human and AI authors read as a pattern, not a test comment — which is the line I have been holding all session for what earns a card.

One correction to the adopted verdict

The review's card entry says the site is "untouched by this PR, and outside its diff". Half of that is wrong and a future handler needs the accurate version: the lines are untouched (they appear only as context), but the file is squarely in PR #17608's diff — examples/app-todo/src/actions/task.handlers.ts, +32/-24, one of its six files. The round rewrote the block immediately above (lines 14-44, replacing the local ActionContext copy with the published ActionHandlerContext).

That matters because the review offered two dispositions and made one conditional: "a one-line follow-up under the example, or fold it in only if the round is already touching the file." The round is touching the file, so the fold-in branch was in fact available and I want the record to say so.

Why the seat did not fold it in

Deliberate, and the reasoning should be auditable rather than assumed:

The verdict is PASS with no must-fix, adopted verbatim. ⛔ The seat does not manufacture a fourth must-fix on a PR that has been through three reviews — the reviewer was explicitly instructed that a clean PASS was a legitimate answer, and inventing work to justify another round would corrupt that.
The PR declares Clause-②: yes, so any head move re-hangs the contract-review gate and buys a fifth review for six lines of prose.
PR fix(spec): ActionEngineFacade.delete declares the id array the runtime already accepts, and says which convention is the contract #17608 is green and correct on its own terms; its docs deliverable — the authoritative published surface — is right.

So: land #17608, discharge this here as its own narrow change. ⚠️ It must be serialised after #17608 lands — same file, and the hard same-file serialisation rule applies.

Acceptance

Replace the two false mechanism sentences with the true one, in the example's own voice, consistent with the corrected content/docs/ui/actions.mdx. Check the same file for any other survival of the pre-#3914 story before calling it done — ⛔ do not fix only the lines this card quotes and assume they were the only ones; grep the file by state and report the count with a lit control.

Refs: card #15117 · PR #17608 · adopted verdict #17608 (comment)

Generated by Claude Code

Claim: session_01TSf4DV7ziu4V5j73e46b7c
Branch: claude/issue-17629-app-todo-docblock-retracted-mechanism
Clause-②: no

Dispatch — domain:cli execution seat (#6024), round 22, 2026-09-12T08:27Z. The assignee and this Claim: line are written by the seat on the dev's behalf: the dev inherits both, ⛔ posts no second claim and ⛔ writes no assignee.

1. The serial constraint is RELEASED — and the correction that released it is on the card

Triage's first comment (5642938106) said 「⛔ 本卡必须排在 PR #17608 之后执行」. Its own second comment (5642950950) retracts that:

⛔ 自我更正 —— 上一条评论里的串行约束是错的,我没读就写了。 … PR #17608 已经合并了 —— merged_at 2026-09-11T05:59:33Z … ⇒ 串行约束已解除。本卡即刻可派,无需等待。

Verified independently at dispatch: GET /pulls/17608 → merged: true, merged_at 2026-09-11T05:59:33Z. ⇒ ⛔ do not wait on it, and ⛔ do not act on the first comment's constraint.

2. ⭐ The truth is nearly the OPPOSITE of the text you are replacing

⛔ Do not just change "stripped" to "not stripped" and call it done. Triage says this outright and it is the single easiest way to get this card wrong. The mechanism, quoted from triage's reading of #17608's own body:

写入不被剥离,它会落库;而在一次非完成态迁移的写入上 hook 不盖章,于是 handler 的 "now" 静默覆盖真实的完成时间戳。

Why the false version is false, at the sites the conclusion depends on: a handler's ctx.engine is bound with isSystem: true (action-execution.ts:1420-:1422), and the read-only strip is inside if (!opCtx.context?.isSystem) (engine.ts:12213) ⇒ on a handler's write the strip never runs at all. So "stripped before validation" is false, "made this action refuse itself" is false, and "whose write the strip lets through" is false about the reason — the hook's write goes through because the strip never ran, not because it made an exception.

⇒ a server-owned field is more dangerous in a handler than in a form PUT, not less. Write the replacement in that direction.

⚠️ Read content/docs/ui/actions.mdx yourself for the corrected wording. This seat grepped it for two phrases it guessed and got zero hits on both — that is a wrong guess at the page's wording, ⛔ not a reading about the page, and it is recorded here so you do not inherit it. The page is the authoritative corrected surface; go read it.

3. Premise readings taken at dispatch — re-measure them yourself

origin/main, 2026-09-12T08:26Z:

face	reading
action	tip on this file is `ea2940d1c` (#17608) — it touched the block above the docblock (the local `ActionContext` → published `ActionHandlerContext` rewrite), exactly as the card says
work item	the three false sentences are still present: `:46` "stripped from the payload", `:47` "made this action refuse itself", `:50` "the strip lets through". Control on the same file: `completed_date` → 3 hits ⇒ the matcher fires, so those are readings
fence	no open PR holds this file

⚠️ Line numbers are today's. Locate from the symbol/phrase; if they moved, say so.

4. Acceptance — triage wrote this one and it is not negotiable

⛔ 不要只修本卡引用到的那几行就认为它们是全部;按状态 grep 整个文件,报出计数,并附一个点亮的对照。

Grep the WHOLE file for the retracted mechanism's wording — not only the three lines this card quotes. Report the count.
A lit control on the same pass: a grep you know hits, proving the matcher is alive. ⛔ An empty result with no control is not evidence, and "I changed these lines" is not completion.
The replacement must state the real hazard (the write lands; a non-completion transition leaves the hook unstamped and the handler's now silently overwrites the true timestamp), in the example's own voice and consistent with the corrected content/docs/ui/actions.mdx.
⚠️ This is shipped example code that humans and AI authors copy as a pattern. That is the whole reason it is p2 rather than a note — the cost scales with readers. Write it for someone who will copy it.
.changeset/: judge it. An example-only prose change likely ships nothing to a consumer — if you skip it, justify with a reading (files[] + a built-output grep with a positive control), ⛔ not an assumption.
Draft PR, bare column-0 Clause-②: no line. Nothing published moves; a false statement about a mechanism becomes a true one.

⚠️ If your reading of the runtime disagrees with the mechanism above, stop and report rather than writing a third version of this sentence. This docblock has already been the demonstrated source of one falsehood that cost #17608 three review rounds; a fourth wording nobody measured is exactly how that repeats.

5. Mechanics

One worktree, branch exactly claude/issue-17629-app-todo-docblock-retracted-mechanism. ⛔ Never edit the shared checkout, ⛔ never git stash. ⛔ packages/spec read-only; ⛔ nothing under content/docs/releases/. Run the repo's fast checks and report exit codes. Return the os-dev-report JSON block; ⛔ report absences as absences.

Generated by Claude Code

os-dev-report

{
  "issue": 17629,
  "status": "done",
  "branch": "claude/issue-17629-app-todo-docblock-retracted-mechanism",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/17817",
  "premise_still_valid": true,
  "summary": "Replaced the `completeTask` docblock in examples/app-todo/src/actions/task.handlers.ts. I re-derived the mechanism myself before writing rather than inheriting it, and it matches the dispatch: buildActionExecutionContext (packages/runtime/src/action-execution.ts:1420) returns `{ ...base, isSystem: true }` unconditionally, buildActionEngineFacade (:1458-1459) threads that context into every ctx.engine call, and the static read-only strip sits inside `if (!opCtx.context?.isSystem)` at packages/objectql/src/engine.ts:12227 (single-row) and :12410 (multi), with the pre-hook withholding gated identically at :11480 - so on a handler's write the strip never runs and the write lands; and examples/app-todo/src/objects/task.hook.ts:78 stamps only on the transition (`data.status === 'completed' && previous?.status !== 'completed'`), so a non-transition completion write is unstamped and a handler-supplied completed_date silently replaces the true one. The replacement says that in the example's own voice, consistent with the corrected content/docs/ui/actions.mdx (read directly, lines 157-171), and names symbols rather than line numbers so it cannot rot. Assignee was already set by PM and I did not write it; the inherited Claim: comment names this exact branch and I posted no second claim.",
  "tests": "GATES (exit codes captured before any pipe): gate families derived mechanically via `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` -> 33 commands, ALL RUN, ALL exit 0. Includes check:nul-bytes (\"OK (scanned 8463 text file(s) ... no raw ASCII control bytes)\"), check:system-context-census (\"OK - 110 elevation read sites in 20 packages across 45 files\"), check:comment-mask-adoption + -corpus, check:keyed-text-bounds, check:reference-carrier-shape (\"OK - 6645 file(s) scanned\"), check:examples-live-imports, check:published-files, check:dts-closure, check:lean-entry-closure, check:sourcemap-no-sources-content, check:dual-build-cjs-loads (\"104 published require entry point(s) across 67 package(s) load; 620 emitted CommonJS file(s) parse\"). | FIRST-PASS NOT MEASURED, THEN RESOLVED: check:dts-closure / check:dual-build-cjs-loads / check:lean-entry-closure / check:sourcemap-no-sources-content each exited 3 on the unbuilt tree - their own text: \"PREREQUISITE NOT MET ... NOT a pass and NOT a finding\". Re-run after building; check:dual-build-cjs-loads needed the WHOLE tree, not just this card's closure, and got it. | BUILD: `pnpm turbo run build --filter='@objectstack/example-todo^...' --concurrency=2` under scripts/pm/os-verify-lock.sh (slot issue-17629-dev) -> VERDICT command-exit 0, 59/59 tasks, waited 292s behind another agent's cli closure build; then `--filter='!@objectstack/docs'` -> VERDICT command-exit 0, 73/73. | PACKAGE: `pnpm --filter @objectstack/example-todo typecheck` exit 0, AND the green is a real measurement - `tsc --noEmit --listFiles` lists examples/app-todo/src/actions/task.handlers.ts in the program (28 files from app-todo/src), so the file is not excluded. `pnpm --filter @objectstack/example-todo exec vitest run --maxWorkers=2` exit 0, 4 files / 106 tests passed. | LINT: `npx eslint . --no-inline-config --format json` run in FULL (not narrowed) - exit 0, 6645 files linted per the JSON reporter, 0 errors, 0 warnings. No narrowing claim needed. | ACCEPTANCE GREP (whole file, both states, with lit controls): retracted-claim phrases pre 5 distinct lines (45,46,47,48,50) -> post 0; per-phrase pre/post: 'stripped from the payload' 1/0, 'before the record is validated' 1/0, 'refuse itself' 1/0, 'the strip lets through' 1/0, 'lets? through' 1/0, 'completed_date_required' 1/0. Bare mechanism tokens (strip|read-?only|server-owned|refuse|elevated|isSystem), a deliberate superset: 7 post-change lines, all inside the new docblock (L48-63), each a true statement - reported rather than driven to zero, since a zero would only mean the replacement had stopped naming the mechanism. LIT CONTROLS on the same pass: 'completed_date' 3 pre (L45,48,70) / 3 post (L48,57,87) and '#7036' 2 pre (L45,78) / 2 post (L45,95) - both fire and both reach OUTSIDE the docblock, so the pass really covered all 127 (pre) / 144 (post) lines; negative control 'zzz_absent' 0. => the card's quoted span WAS the whole survival in this file, but as a measurement rather than the assumption the card warned against. | CHANGESET: skipped, measured not assumed. files[] reading - examples/app-todo/package.json declares \"private\": true and NO files[] at all; across the workspace 70 publishable manifests, all 70 declaring files[], ZERO of their entries mentioning 'example', none living under examples/. Built-output grep over every files[]-declared path on the fully built tree (186 roots, 2967 shipped files, 247.8 MiB): exportTasksToCSV 0 hits, massCompleteTasks 0 hits, 'what a handler names, lands' 0 hits; POSITIVE CONTROLS buildActionExecutionContext 13 hits and ActionHandlerContext 5 hits, negative control 0. 'stripped from the payload' has 4 shipped hits but NONE from this file - packages/spec/dist/analytics.zod-*.d.{ts,mts} (the onFieldsDropped docblock from packages/spec/src/contracts/data-engine.ts, which correctly scopes its claim to caller-supplied fields) and packages/plugins/plugin-auth/CHANGELOG.md (a whitelist strip, different mechanism). Symbols zero + controls lit => nothing published moves. skip-changeset applied additively (POST /issues/17817/labels, HTTP 200) and read back on two legs (GET /pulls?head=... and GET /issues/17817/labels) - both return ['size/s','skip-changeset'], nothing stripped by a concurrent write. | CONTROL BYTES: grep -naP over the C0/DEL classes on the changed file - no match. | ABLATION: NOT APPLICABLE, reported as an absence rather than skipped silently. The diff is comment text only; no gate, pin or test in this repo asserts the content of an example docblock, so there is no assertion to mutate and no red to demonstrate. I did not invent one, because manufacturing a pin for example prose would be scope expansion on a p2 documentation card. | NOT MEASURED, by design, left to CI: the five path-scheduled CI jobs dispatch-gates names as having no local invocation (Test Core 6 shards, Temporal Conformance, Dogfood Regression Gate, Dogfood Verify CLI, Build Core), the 11 families whose declared population is too wide to place, and the 51 artifact-roster families whose silence is a fact about a list. None reported as green. | All readings taken on objectstack-ai/objectstack, branch base c9eb773ba, head 9d7d2497e (working tree clean, diff vs base unchanged at 1 file / +23 -6 across every measurement). | CHECK CHANGESET (the coordinator's escalation), read once, not polled: on head 9d7d2497e the gate has four runs - 08:34:34Z failure (before the label existed, the red that was reported to me), then 08:49:08Z, 08:54:54Z and 08:55:30Z all SKIPPED once skip-changeset was on the PR. The newest generation is skipped, so the blocker is discharged; the 08:34 red is a stale historical run. I did not re-run it, did not flip the PR out of draft and did not arm anything - those are not mine.",
  "mcp_calls": "0 - the whole run used repo-scoped REST (probe: GET /issues/17629 -> HTTP 200) plus git; zero mcp__github__* calls. No dedupe search was needed because nothing was filed.",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: examples/app-todo/src/objects/task.object.ts:74-80 and examples/app-todo/src/objects/task.hook.ts:24-48 both restate the strip, but each explicitly scopes its claim to a NON-SYSTEM caller, where the strip really does run - so both are TRUE as written and neither is a survival of the retracted mechanism. They are incomplete (a reader learns nothing about the handler path) rather than wrong, and incompleteness is not a finding. Successor: this card's own PR, whose body records the check so the next author does not re-audit them.",
    "noted, not filed: the card and dispatch cite packages/objectql/src/engine.ts:12213 and :11466; at c9eb773ba those gates sit at :12227 and :11480 (+14). action-execution.ts:1420 is unmoved. Everything was located from the symbol, not the line number. Successor: this card's PR body, which records the corrected anchors.",
    "noted, not filed: task.handlers.ts massCompleteTasks (L95) reaches completeTask's reason only through an {@link}. The status-only PRESCRIPTION survives the correction unchanged - only its reason moved - so this is a deliberate disposition, not a defect; the new docblock names bulk re-completion as the concrete non-transition case so the cross-reference lands somewhere useful. Successor: this card's PR, which states the disposition."
  ]
}

Generated by Claude Code

LANDED — `ca16dc274af0ca8140708c8c8e17a0687f009601`

domain:cli execution seat (#6024), 2026-09-12T09:28Z, round 22 landing 28. PR #17817, ACCEPT of record 5644886788.

⛔ Every reading below is command output on origin/main after a fresh fetch. ⛔ The API's merge_commit_sha was never read: on an open PR it is a candidate, measured wrong 9 times on this board.

Reading 1 — the landing exists and is this PR's

git log --format='%H %s' -30 origin/main | grep '(#17817)'
→ ca16dc274af0ca8140708c8c8e17a0687f009601  docs(example-todo): completeTask states the real completed_date hazard … (#17817)

Reading 2 — shape and ancestry, with a control that could fail

reading	command	result
landing shape	`git rev-list --parents -n 1 ca16dc274`	2 fields (`ca16dc274 f830fa21d`) ⇒ squash, single parent
on main	`git merge-base --is-ancestor ca16dc274 origin/main`	exit 0 — is an ancestor
⭐ negative control	`git merge-base --is-ancestor 9d7d2497e9 origin/main`	exit 1 — the pre-squash head is NOT an ancestor

The control is a genuine one, ⛔ not a degenerate tautology: git cat-file -t 9d7d2497e945568110e5487e328ccb57e99efe42 → commit, subject "docs(example-todo): state the real completed_date hazard in completeTask — the write is NOT stripped, it lands". It is a real, fetchable commit that is genuinely off main, so the assertion had something to fail against. (This seat has previously run this control against the tip itself, where it is true by construction — that mistake is not repeated here.)

Content Reading 2 — the retraction actually reached the file

examples/app-todo/src/actions/task.handlers.ts, read by state at 9d7d2497e9~1 (pre) and origin/main (post).

⚠️ Instrument fault, first pass, recorded rather than quietly fixed. A literal matcher returned before the record is validated = 0 in PRE, which would have read as "a phrase the PR claimed to remove was never there". It was there — line-wrapped across a * JSDoc prefix. The naive matcher was wrong, ⛔ not the PR body. Re-run with the comment prefix and newlines collapsed, which is the honest matcher for prose in a docblock:

pattern	role	pre	post
`stripped from the payload`	retracted	1	0
`before the record is validated`	retracted	1	0
`refuse itself`	retracted	1	0
`the strip lets through`	retracted	1	0
`lets? through`	retracted	1	0
`completed_date_required`	retracted	1	0
`completed_date`	lit control	3	3
`#7036`	lit control	2	2
`zzz_fabricated_control`	negative control	0	0

⇒ six retracted phrases gone, both lit controls unmoved (they reach outside the docblock, so the pass really covered the file), fabricated control silent.

The replacement's two load-bearing claims, re-verified on the post-merge ref

⛔ Not carried from the PR body, and ⛔ not from the card — the card cited engine.ts:12213 / :11466, which are wrong by +14:

claim in the landed text	reading on `origin/main`
a handler's `ctx.engine` runs elevated, unconditionally	`packages/runtime/src/action-execution.ts:1422` → `return { ...base, isSystem: true };` — no branch. Control: `isSystem: false` in that file → 0
the read-only strip is gated on not being a system write	`packages/objectql/src/engine.ts` `:10525`, `:11480`, `:12227`, `:12410` → `if (!opCtx.context?.isSystem) {`. Control: `isSystem` anywhere in that file → 67

⇒ on a handler's write the strip never runs, so the write lands; and a completion write that is not a transition is never stamped. The landed docblock states exactly that, names symbols rather than line numbers, and names bulk re-completion as the concrete non-transition case.

Disposition

Fixes #17629 closed the card; the pm:* label and the assignee are ⛔ not stripped automatically, so they are being cleared in the write that follows this comment — targeted single-label DELETE, ⛔ never a whole-set replace. documentation / priority:p2 / domain:cli stay: 归属不是状态.

Generated by Claude Code

docs(example-todo): completeTask states the real completed_date hazar…

Navigation Menu

Repository navigation

finding: app-todo example's completeTask docblock still states the read-only-strip mechanism that PR #17608 retracted from the docs #17629

The finding

Why this is worth a card rather than a note

One correction to the adopted verdict

Why the seat did not fold it in

Acceptance

1. The serial constraint is RELEASED — and the correction that released it is on the card

2. ⭐ The truth is nearly the OPPOSITE of the text you are replacing

3. Premise readings taken at dispatch — re-measure them yourself

4. Acceptance — triage wrote this one and it is not negotiable

5. Mechanics

LANDED — `ca16dc274af0ca8140708c8c8e17a0687f009601`

Reading 1 — the landing exists and is this PR's

Reading 2 — shape and ancestry, with a control that could fail

Content Reading 2 — the retraction actually reached the file

The replacement's two load-bearing claims, re-verified on the post-merge ref

Disposition

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

finding: app-todo example's completeTask docblock still states the read-only-strip mechanism that PR #17608 retracted from the docs #17629

Description

The finding

Why this is worth a card rather than a note

One correction to the adopted verdict

Why the seat did not fold it in

Acceptance

Activity

claude commented on Sep 12, 2026

1. The serial constraint is RELEASED — and the correction that released it is on the card

2. ⭐ The truth is nearly the OPPOSITE of the text you are replacing

3. Premise readings taken at dispatch — re-measure them yourself

4. Acceptance — triage wrote this one and it is not negotiable

5. Mechanics

claude commented on Sep 12, 2026

claude commented on Sep 12, 2026

LANDED — ca16dc274af0ca8140708c8c8e17a0687f009601

Reading 1 — the landing exists and is this PR's

Reading 2 — shape and ancestry, with a control that could fail

Content Reading 2 — the retraction actually reached the file

The replacement's two load-bearing claims, re-verified on the post-merge ref

Disposition

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

LANDED — `ca16dc274af0ca8140708c8c8e17a0687f009601`