[finding] The Error Codes table on `content/docs/api/client-sdk.mdx` omits `VALIDATION_FAILED` — the one code the page's own examples branch on

[yinlianghui]

Found while landing #12342 (PR #12387), which had to establish what
error.code can actually hold before writing a narrowing for it.

The gap

content/docs/api/client-sdk.mdx has an Error Codes table listing nine
codes: VALIDATION_ERROR, INVALID_QUERY, UNAUTHENTICATED,
PERMISSION_DENIED, RESOURCE_NOT_FOUND, RATE_LIMIT_EXCEEDED,
INTERNAL_ERROR, SERVICE_UNAVAILABLE, NOT_IMPLEMENTED. Every one is a
member of StandardErrorCode (packages/spec/src/api/errors.zod.ts).

VALIDATION_FAILED is not in the table. It is also not in StandardErrorCode
— it is registered in ERROR_CODE_LEDGER
(packages/spec/src/api/error-code-ledger.zod.ts), so
ErrorCode.parse('VALIDATION_FAILED') succeeds and it is a real, live wire
value. Producers emit it from packages/rest (error-response.ts,
rest-server.ts, import-runner.ts) and packages/objectql
(record-validator.ts), and packages/types/src/validation-failure.ts is built
around it.

And it is the code both of the page's own error-handling examples use — one
in a trailing comment, one in a live if (error.code === 'VALIDATION_FAILED')
branch, immediately above the table that does not list it.

Why it matters

A reader who works from the table concludes a per-field validation failure
arrives as VALIDATION_ERROR and writes that branch. It never matches. The
examples are right and the table is incomplete, which is the worse way round:
the table is the part that reads like a reference.

The table also has no column or note distinguishing the closed
StandardErrorCode catalog from the ledger-registered codes, so there is no
place for a reader to learn that the vocabulary is a union of two sets. That is
arguably the real fix rather than adding one row.

Open question for triage

Whether the page should list the ledger codes at all, or state the union and
point at the spec as the authority, is a docs-shape decision — a full ledger
dump on this page would be large and would need to stay in sync. Filed as a
finding rather than a fix so triage can rule on which.

Not in scope

The narrowing defect on the same page's examples (#12342, landed as PR #12387)
and the third unnarrowed catch block (#12388) are separate; this card is only
about the code vocabulary the table publishes.

[os-trump]

Triage: lands in domain:devx; rationale: the fix is entirely on content/docs/api/client-sdk.mdx (docs face); the spec vocabulary itself is correct and untouched. Type Task.

Answer to the card's open question, as a PM-suggested route (falsifiable — the dev's own reading of the page wins): do not dump the ledger onto the page. State that the wire vocabulary is the union of the closed StandardErrorCode catalog and the ledger-registered codes, point at packages/spec as the authority for the full set, and add the one VALIDATION_FAILED row the page's own examples branch on. A full ledger table would need to stay in sync forever, which is the drift shape this docs surface keeps paying for; the union note fixes the reader's wrong conclusion at minimal surface.

Hot-file note for the devx seat: client-sdk.mdx is shared with in-flight #12342 (PR #12387) and queued #12388. Fold-or-serial is a must-answer before dispatch — #12388/#12389 differ in defect shape (catch-narrowing vs. table vocabulary), so a fold has to pass all five gates, and serial-after-#12342's-merge is the safe default.

Size/model suggestion: S mechanical once the shape above is accepted.

---

Generated by Claude Code

[yinlianghui]

Claim: devx@objectstack seat (#6023) · session session_01UjM2ia8Av1v5NqfqQEQmC6 · R10
Branch claude/issue-12389-error-codes-table · dedicated worktree · model tier: standard.

Declared file surface: the ### Error Codes section of content/docs/api/client-sdk.mdx. ⛔ Not the whole page.

Serial: ⚠️ #12388 is held behind you — it is about a third example on this same file (automation.execute in the API-surface tour). One writer at a time. ⚠️ #11942 is pm:blocked on the same file (its 13 fences carry zero os:check markers).

Symptom verified before dispatch (this seat, origin/main):

### Error Codes → content/docs/api/client-sdk.mdx:667
VALIDATION_FAILED → :619, :632, :655 — all BEFORE :667

All three occurrences are in the examples and the prose; none is in the table. The card's claim holds.

---

Zone 1 — rulings (scope, not facts; not renegotiable)

1. The surface is the ### Error Codes section. ⛔ Do not touch the example blocks — [finding] A third example on content/docs/api/client-sdk.mdx reads err.code off an untyped catch binding — the automation.execute block inside the API-surface tour #12388 owns the remaining one.
2. ⛔ Do not add os:check markers (that is [finding] content/docs/api/client-sdk.mdx — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 os:check markers, so none of them is ever compiled #11942's subject, blocked). ⚠️ Which means nothing compiles or checks your table row either — say so plainly rather than implying it is verified.
3. ⛔ Never content/docs/releases/**.
4. Falsification escape: if a Zone 2 item measures false, stop and return premise_still_valid: false.

Zone 2 — assumptions; falsify before building on them

a. ⭐ Read what the table is a table OF before adding a row. VALIDATION_FAILED is not in StandardErrorCode — measured at packages/spec/src/api/errors.zod.ts:52, that enum has VALIDATION_ERROR and not VALIDATION_FAILED (count 0, with a positive control). It is ledger-registered. ⚠️ If the table's contract is "the StandardErrorCode enum", then adding this row makes the table false and the honest finding is the opposite one: the page's examples branch on a code the published enum does not carry. Establish which before writing.
b. I assume the fix is a row. If (a) says otherwise, the fix may be a stated distinction between enum codes and ledger-registered codes — report rather than papering it.
c. I have not counted whether other codes the page's examples use are also missing. Count them; fix the one the card names and report the rest.

Zone 3 — suggested route (not binding)

Read the table's own header and any statement of what it enumerates → decide row-vs-distinction from that → keep it short. Gate union at the final commit; run the docs link checker if it is in the union. Exit codes before any pipe.

---

Generated by Claude Code

[yinlianghui]

{
 "issue": 12389,
 "status": "done",
 "branch": "claude/issue-12389-error-codes-table",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12469",
 "premise_still_valid": true,
 "summary": "Zone 2a's measurement holds and its warning branch does NOT fire, so the row is admissible — but only alongside the distinction. Measured on base 68c5dbaab2: StandardErrorCode has 50 members and the table listed 9, all of them enum members. 9-of-50 refutes 'the table is the enum': it was a curated subset with an UNSTATED contract, which is precisely why readers mistake it for the authority. So the fix is contract + row, not row alone (what the card itself calls 'arguably the real fix'). Delivered inside the declared `### Error Codes` section only: (1) a short statement of the two-tier vocabulary per ADR-0112 — closed StandardErrorCode catalog + per-package ERROR_CODE_LEDGER, exported ErrorCode as their union, packages/spec as authority, no ledger dump; (2) a Tier column so each row declares its set; (3) the VALIDATION_FAILED row (ledger, 400, carries fields[]); (4) a sharpened VALIDATION_ERROR description, because a reader picking the wrong one of the two adjacent codes IS the defect — VALIDATION_ERROR is request-shape refusal (query-multiplicity.ts:140, query-allowlist.ts:196, package-routes.ts:752, storage-service.ts:120, metadata-service-contract.ts:105), VALIDATION_FAILED is record-level validation on a write (error-response.ts:631, rest-server.ts:9671 -> 400); (5) a note that Category/Retryable are semantic classification, not wire guarantees — `grep -rn 'category:' packages/rest/src/error-response.ts` returns nothing, so the per-field envelope sends neither, closing the gap with the narrowing example's 'optional — set only when the server sent it'. Zone 2c counted: six codes appear on the page outside the table (VALIDATION_FAILED :619/:632/:655; ROLLED_BACK + NOT_ATTEMPTED :579-580; FLOW_DISABLED/FLOW_FAILED/FLOW_NO_START_NODE :436-438) and ALL SIX are ledger-registered with none in StandardErrorCode — which is the argument for the union note rather than five more rows; their omission stops being misleading once the table declares itself a subset, so no further rows were added and nothing was filed. ZONE 1 RULING 2, STATED PLAINLY: no os:check markers were added (that is #11942's blocked subject), there is no generated source for the Category/Retryable columns anywhere in packages/spec, and therefore NOTHING in CI verifies this table or the row I added — it is hand-measured against the spec and CI will not notice if it drifts. Scope: one file, 35 insertions / 11 deletions, entirely inside `### Error Codes`; the example blocks (#12388's territory) are untouched. Two notes for the PM: (a) the additive labels POST prescribed by the dev contract returns HTTP 403 from this seat (the proxy-injected token has no direct api.github.com write), so `skip-changeset` went on via the declared FALLBACK — read labels, union, whole-set write — read-back confirms ['documentation', 'size/s', 'skip-changeset']; (b) the platform appended a second `_Generated by [Claude Code](...)_` footer to the PR body at creation time, so the body carries the signature twice; recorded, not corrected.",
 "tests": "Docs-only change; no unit tests apply and none were added (there is no test surface for an .mdx table). Gate union derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no paths — the script read its own change set: '1 path(s) vs merge base 68c5dbaab', three-dot semantics; the --repo assertion held against this checkout's origin). 23 families matched; ran all 23 plus check-nul-bytes at the FINAL commit `5b76c2b049` (HEAD echoed by the runner itself), each exit code captured before any pipe via a `run()` wrapper writing '### EXIT=$rc' — result 24/24 green, 'TOTAL FAILED=0'. Gates' own verdict lines: '✓ check-docs-single-h1: 180 page(s) under content/docs/ carry no body-level `# ` heading'; '✅ check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading'; '✓ doc authoring guard: 390 files clean — no bare metadata literals.'; '✓ check-doc-frontmatter: 2 content root(s) verified, each against its own floor — content/docs 403, content/blog 3.'; '✅ 229 generated files in sync with packages/spec' (spec check:docs); spec check:skill-examples green over '260 marked example(s) across 101 file(s), 3 surface(s)'. Three of those gates first REFUSED to measure on unbuilt prerequisites (check:doc-formula-expressions wanted @objectstack/formula built, check:doc-security-posture wanted @objectstack/lint, check:skill-examples wanted @objectstack/client-react .d.ts) — each printed 'PREREQUISITE NOT MET — nothing was measured'; I built the closure (turbo run build --filter for the three, 33 tasks, 4m36s under the shared lock) and re-ran to green rather than reading the refusals as findings. All heavy commands went through `bash scripts/pm/os-verify-lock.sh -c`; one acquisition waited 185s behind objectstack-issue-12398's build and I waited in-turn rather than ending the round. DECLARED NARROWING of repo-wide `pnpm lint`, with all three pieces of evidence: (i) population read from eslint's own config — `eslint.config.mjs` contains the string 'mdx' zero times (`grep -c mdx` = 0) and no `files` glob covers .mdx; (ii) file count from `--format json` — `pnpm exec eslint content/docs/api/client-sdk.mdx --no-inline-config --format json` returns 1 file entry, errorCount 0, with the message 'File ignored because no matching configuration was supplied.'; (iii) invariance — no type-aware linting is configured and this diff changes no ESLint config, so it cannot move a verdict on any untouched file. CI runs the full farm regardless. No ablation was performed: there is no guard to mutate here (see the Zone 1 ruling 2 note above — this table is checked by nothing), so an ablation would have had no subject.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui]

os-dev-report

(Supersedes comment 5420732327 — the HTML-comment marker on that one was eaten by GitHub's body sanitizer after it landed, making it invisible to a marker scan. Same report, literal-text marker. No API path from this seat can edit the earlier comment.)

{
 "issue": 12389,
 "status": "done",
 "branch": "claude/issue-12389-error-codes-table",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12469",
 "premise_still_valid": true,
 "summary": "Zone 2a's measurement holds and its warning branch does NOT fire, so the row is admissible — but only alongside the distinction. Measured on base 68c5dbaab2: StandardErrorCode has 50 members and the table listed 9, all of them enum members. 9-of-50 refutes 'the table is the enum': it was a curated subset with an UNSTATED contract, which is precisely why readers mistake it for the authority. So the fix is contract + row, not row alone (what the card itself calls 'arguably the real fix'). Delivered inside the declared `### Error Codes` section only: (1) a short statement of the two-tier vocabulary per ADR-0112 — closed StandardErrorCode catalog + per-package ERROR_CODE_LEDGER, exported ErrorCode as their union, packages/spec as authority, no ledger dump; (2) a Tier column so each row declares its set; (3) the VALIDATION_FAILED row (ledger, 400, carries fields[]); (4) a sharpened VALIDATION_ERROR description, because a reader picking the wrong one of the two adjacent codes IS the defect — VALIDATION_ERROR is request-shape refusal (query-multiplicity.ts:140, query-allowlist.ts:196, package-routes.ts:752, storage-service.ts:120, metadata-service-contract.ts:105), VALIDATION_FAILED is record-level validation on a write (error-response.ts:631, rest-server.ts:9671 -> 400); (5) a note that Category/Retryable are semantic classification, not wire guarantees — `grep -rn 'category:' packages/rest/src/error-response.ts` returns nothing, so the per-field envelope sends neither, closing the gap with the narrowing example's 'optional — set only when the server sent it'. Zone 2c counted: six codes appear on the page outside the table (VALIDATION_FAILED :619/:632/:655; ROLLED_BACK + NOT_ATTEMPTED :579-580; FLOW_DISABLED/FLOW_FAILED/FLOW_NO_START_NODE :436-438) and ALL SIX are ledger-registered with none in StandardErrorCode — which is the argument for the union note rather than five more rows; their omission stops being misleading once the table declares itself a subset, so no further rows were added and nothing was filed. ZONE 1 RULING 2, STATED PLAINLY: no os:check markers were added (that is #11942's blocked subject), there is no generated source for the Category/Retryable columns anywhere in packages/spec, and therefore NOTHING in CI verifies this table or the row I added — it is hand-measured against the spec and CI will not notice if it drifts. Scope: one file, 35 insertions / 11 deletions, entirely inside `### Error Codes`; the example blocks (#12388's territory) are untouched. Three notes for the PM: (a) the additive labels POST prescribed by the dev contract returns HTTP 403 from this seat (the proxy-injected token has no direct api.github.com write), so `skip-changeset` went on via the declared FALLBACK — read labels, union, whole-set write — read-back confirms ['documentation', 'size/s', 'skip-changeset']; (b) the platform appended a second `_Generated by [Claude Code](...)_` footer to the PR body at creation time, so the body carries the signature twice; recorded, not corrected; (c) the report comment's HTML marker was sanitized away after landing, hence this literal-text repost.",
 "tests": "Docs-only change; no unit tests apply and none were added (there is no test surface for an .mdx table). Gate union derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no paths — the script read its own change set: '1 path(s) vs merge base 68c5dbaab', three-dot semantics; the --repo assertion held against this checkout's origin). 23 families matched; ran all 23 plus check-nul-bytes at the FINAL commit `5b76c2b049` (HEAD echoed by the runner itself), each exit code captured before any pipe via a `run()` wrapper writing '### EXIT=$rc' — result 24/24 green, 'TOTAL FAILED=0'. Gates' own verdict lines: '✓ check-docs-single-h1: 180 page(s) under content/docs/ carry no body-level `# ` heading'; '✅ check-doc-anchors: 278 internal fragment link(s) across 408 source file(s) all resolve to a real heading'; '✓ doc authoring guard: 390 files clean — no bare metadata literals.'; '✓ check-doc-frontmatter: 2 content root(s) verified, each against its own floor — content/docs 403, content/blog 3.'; '✅ 229 generated files in sync with packages/spec' (spec check:docs); spec check:skill-examples green over '260 marked example(s) across 101 file(s), 3 surface(s)'. Three of those gates first REFUSED to measure on unbuilt prerequisites (check:doc-formula-expressions wanted @objectstack/formula built, check:doc-security-posture wanted @objectstack/lint, check:skill-examples wanted @objectstack/client-react .d.ts) — each printed 'PREREQUISITE NOT MET — nothing was measured'; I built the closure (turbo run build --filter for the three, 33 tasks, 4m36s under the shared lock) and re-ran to green rather than reading the refusals as findings. All heavy commands went through `bash scripts/pm/os-verify-lock.sh -c`; one acquisition waited 185s behind objectstack-issue-12398's build and I waited in-turn rather than ending the round. DECLARED NARROWING of repo-wide `pnpm lint`, with all three pieces of evidence: (i) population read from eslint's own config — `eslint.config.mjs` contains the string 'mdx' zero times (`grep -c mdx` = 0) and no `files` glob covers .mdx; (ii) file count from `--format json` — `pnpm exec eslint content/docs/api/client-sdk.mdx --no-inline-config --format json` returns 1 file entry, errorCount 0, with the message 'File ignored because no matching configuration was supplied.'; (iii) invariance — no type-aware linting is configured and this diff changes no ESLint config, so it cannot move a verdict on any untouched file. CI runs the full farm regardless. No ablation was performed: there is no guard to mutate here (see the Zone 1 ruling 2 note above — this table is checked by nothing), so an ablation would have had no subject.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

---

Generated by Claude Code