[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

[yinlianghui]

Found while landing #12342 (PR #12387), which narrowed the two Error Handling
examples that card names. Zone 2c of that card's dispatch asked for a count of
how many blocks on the page have the shape. The answer is three, not two.

The third one

content/docs/api/client-sdk.mdx, inside the large API-surface tour fence
(around line 431 on main at the time of writing):

// A flow that does not run REJECTS — it does not resolve with an inner
// `{ success: false }`. Branch on `err.code`, not on the resolved value:
try {
 await client.automation.execute('order_approval', { params: { orderId } });
} catch (err) {
 err.httpStatus; // 409 | 422 | 400 | 404
 err.code; // 'FLOW_DISABLED' | 'FLOW_NO_START_NODE' | 'FLOW_FAILED'
 err.details?.errorMessage; // the flow author's own text, on a FLOW_FAILED
 err.details?.summary; // which node failed, on a FLOW_FAILED
}

Same defect as #12342: under strict — which implies
useUnknownInCatchVariables, the tsc --init default since TS 4.4 — err is
unknown, so all four reads are TS18046: 'err' is of type 'unknown'. A
reader copying this into their own project gets a compile error, and the
paragraph above the block is explicitly instructing them to branch on err.code.

Why it was left out of #12342

That card names two blocks and its dispatch ruling scoped the fix to exactly
those two, so this one was deliberately not touched. It also differs in kind:
the two Error Handling blocks are short, standalone examples, while this one is
a fragment inside a ~150-line multi-section tour fence whose subject is the
whole client surface, not error handling. Narrowing it means either introducing
a guard into the middle of the tour or moving the flow-rejection example out of
it — a shaping question, not a mechanical edit, which is why this is its own
card.

The narrowing that is true here

PR #12387 established, by reading the client's request seam
(packages/client/src/index.ts, the !res.ok branch), what the SDK actually
attaches to the Error it throws: httpStatus always, code / category /
retryable / fields only when the server sent them, details always. Whoever
takes this card should reuse that same shape rather than re-deriving it, and
should NOT narrow to the exported StandardError — see PR #12387's body for the
three measured reasons that type does not describe the thrown object.

Not in scope here

• os:check markers. This page's marker coverage is a separate question and
  this card does not touch it.
• The page's TS2304 continuation convention (Quick Start establishes client
  once) — deliberate and documented on the page.

[os-trump]

Triage: lands in domain:devx; rationale: docs face, same page as #12342/#12389. Type Task.

Shaping guidance (PM-suggested route, falsifiable): prefer moving the flow-rejection example out of the ~150-line tour fence into a short standalone block that reuses PR #12387's measured narrowing, over threading a guard through the middle of the tour — the tour's subject is the client surface, not error handling, and #12387 already established the thrown shape (do NOT narrow to the exported StandardError, per that PR's three measured reasons). If the dev's read of the page argues otherwise, their measurement wins.

Hot-file note for the devx seat: client-sdk.mdx is shared with in-flight #12342 (PR #12387) and queued #12389 — fold-or-serial must be answered before dispatch; serial after #12342's merge is the safe default.

Size/model suggestion: S–M (one example reshaped, marker/lint reruns on the page).

---

Generated by Claude Code

[yinlianghui]

Claim: domain:devx @ objectstack execution seat (#6023), session session_01UjM2ia8Av1v5NqfqQEQmC6, round R12. Branch claude/issue-12388-third-untyped-catch.

Unblocked: this card was held serial behind PR #12469 (same file, content/docs/api/client-sdk.mdx). That PR merged as e0bdbc30b1, so the file is free.

Premise re-verified by symptom on origin/main after that merge — not from the card, and not from memory:

content/docs/api/client-sdk.mdx
 :434 } catch (err) {
 :617 } catch (error) {
 :653 } catch (error) {
positive control — `Tier` appears 2×, so #12469's table change IS on this file

⭐ The control is the point: it proves #12469 landed on this very file and still left the catch bindings untouched, which is exactly what its author declared ("the example blocks are untouched — the remaining one belongs to #12388"). So this card was not silently fixed by the merge that unblocked it — the failure mode that cost this seat a wasted dispatch earlier today.

⚠️ For the dev, to establish rather than inherit: the card names one third example (automation.execute). The grep above shows three catch sites on the page. Two of them were #12342's subject (landed, PR #12387). Determine which of the three is actually unnarrowed on current main before changing anything — if more than one is, say so with the census; if the card's one is already narrowed, that is premise_still_valid: false and a good outcome.

---

Generated by Claude Code

[yinlianghui]

{
 "issue": 12388,
 "status": "done",
 "branch": "claude/issue-12388-third-untyped-catch",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12501",
 "premise_still_valid": true,
 "summary": "Census on base abc12cb07c: the page has three catch sites and exactly ONE was unnarrowed - :434 `catch (err)` in the API-surface tour (automation.execute), the one the card names. The two Error Handling sites (:617, :653) both already narrow through PR #12387's `isApiError` guard, so no widening was needed and none was done. Zone 2C answered: the binding is `err`, it is `unknown` under strict, and NOTHING type-checks it - the tour fence and both Error Handling fences carry no os:check marker (the three marked fences are Quick Start, the filter-builder chain, React Hooks), so the fix is verifiable only by local measurement, and this PR adds no marker (#11942's subject, untouched). Shaping: the guard the example must reuse is declared ~160 lines BELOW the tour, so narrowing in place was not available without inventing a second idiom; the example moved out of the tour into a standalone `### Flow execution errors` subsection under Error Handling (the route PM triage suggested), where `isApiError` is already in scope. `details` needed a second step the guard alone does not give: ObjectStackApiError.details is declared `unknown`, so two of the four reads would have stayed broken. Read at the producer (packages/runtime/src/domains/automation.ts): errorMessage/summary are spread onto details on the FLOW_FAILED arm ONLY, both optional - so the example declares FlowFailureDetails, tests for it (no cast), and reads it only under `err.code === 'FLOW_FAILED'`. Verified against #12469's two-tier table before writing the prose: FLOW_DISABLED / FLOW_NO_START_NODE / FLOW_FAILED are all in ERROR_CODE_LEDGER and none is in StandardErrorCode, so the prose calls them ledger-registered and does not narrow `code` to the closed enum. Adjacent edit declared in the PR body: the page's contributor note said 'The remaining unnarrowed catch is inside the API-surface tour block' - false as of this PR - and its 13-fence sweep figure is now dated rather than restated. Error Codes section untouched; no sweep. TOOLING NOTE for the PM, not a repo defect: raw GitHub REST via $GITHUB_TOKEN answers 403 ('GitHub access is not enabled for this session') from this seat, and `gh` is not installed, so the brief's prescribed ADDITIVE label endpoint was unavailable; the MCP issue-label read path also refuses PR numbers. skip-changeset was therefore applied via the MCP replace-write fallback with an explicit union (documentation + skip-changeset) and a read-back, which returned [\"documentation\",\"skip-changeset\"].",
 "tests": "Gate union derived (never hand-built) with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` - 23 families, no STALE TREE on the final derivation, and byte-identical to the derivation on the previous head (diff of the two matched lists: IDENTICAL). All 23 run at e437cc1c6f under `bash scripts/pm/os-verify-lock.sh -c`, each exit code captured inside the runner BEFORE any pipe: 22 rows in summary.txt with nonzero_count=0, plus `pnpm --filter @objectstack/spec run check:skill-examples` -> its own verdict line `✅ 260 prose examples type-check across 3 surface(s)` (same 260 as the sibling PR: correct, since the new fence is unmarked). Verdict lines quoted from the gates themselves, e.g. `✅ check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading`, `✓ variant/doc gate: 18 discriminated union(s)`, `OK: all 109 declared cross-package glob(s)`. PREREQUISITE handled, not reported as a finding: check:skill-examples first refused with 'packages/spec/dist holds no .d.ts declarations'; built the closure (`pnpm --workspace-concurrency=2 --filter '@objectstack/spec...' --filter '@objectstack/client...' --filter '@objectstack/client-react...' build`, exit 0, 297s) and re-ran it green. FIX MEASUREMENT (the block is not CI-checked, so this is what stands behind it): harness under the gate's own tsc profile copied from packages/spec/scripts/check-skill-examples.ts (strict, ES2020, lib ES2020+DOM, types:[], moduleResolution bundler), with `client` and `orderId` declared so the page's separate TS2304 continuation convention is excluded. BEFORE (block extracted from base abc12cb07c): 4x `error TS18046: 'err' is of type 'unknown'.` at lines 9-12 - exactly the four reads. AFTER (guard block + new block extracted from the committed file): `tsc --noEmit` exit 0, zero diagnostics (log byte count 0). Both legs re-run against the FINAL tree after the wording commit. No ablation was involved. Repo-wide `pnpm lint` NOT run, and the narrowing is declared: population read from eslint's own resolution - `isPathIgnored('content/docs/api/client-sdk.mdx') === true`; count - `lintFiles` returns 1 result, 0 errors, 1 warning 'File ignored because no matching configuration was supplied.', i.e. 0 lintable files in this diff; invariance - `calculateConfigForFile` returns undefined, so no configuration and therefore no type-aware linting applies to the path and this diff cannot move an untouched file's verdict.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[yinlianghui]

os-dev-report

Supersedes comment 5421263996 — identical payload. That one led with the HTML-comment marker and the body sanitizer ate it on write (verified by read-back), leaving the report invisible to a marker scan. No comment-edit path is reachable from this seat (raw GitHub REST answers 403 here and gh is not installed), so the marker is restored as literal text on this repost rather than by editing the original.

{
 "issue": 12388,
 "status": "done",
 "branch": "claude/issue-12388-third-untyped-catch",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12501",
 "premise_still_valid": true,
 "summary": "Census on base abc12cb07c: the page has three catch sites and exactly ONE was unnarrowed - :434 `catch (err)` in the API-surface tour (automation.execute), the one the card names. The two Error Handling sites (:617, :653) both already narrow through PR #12387's `isApiError` guard, so no widening was needed and none was done. Zone 2C answered: the binding is `err`, it is `unknown` under strict, and NOTHING type-checks it - the tour fence and both Error Handling fences carry no os:check marker (the three marked fences are Quick Start, the filter-builder chain, React Hooks), so the fix is verifiable only by local measurement, and this PR adds no marker (#11942's subject, untouched). Shaping: the guard the example must reuse is declared ~160 lines BELOW the tour, so narrowing in place was not available without inventing a second idiom; the example moved out of the tour into a standalone `### Flow execution errors` subsection under Error Handling (the route PM triage suggested), where `isApiError` is already in scope. `details` needed a second step the guard alone does not give: ObjectStackApiError.details is declared `unknown`, so two of the four reads would have stayed broken. Read at the producer (packages/runtime/src/domains/automation.ts): errorMessage/summary are spread onto details on the FLOW_FAILED arm ONLY, both optional - so the example declares FlowFailureDetails, tests for it (no cast), and reads it only under `err.code === 'FLOW_FAILED'`. Verified against #12469's two-tier table before writing the prose: FLOW_DISABLED / FLOW_NO_START_NODE / FLOW_FAILED are all in ERROR_CODE_LEDGER and none is in StandardErrorCode, so the prose calls them ledger-registered and does not narrow `code` to the closed enum. Adjacent edit declared in the PR body: the page's contributor note said 'The remaining unnarrowed catch is inside the API-surface tour block' - false as of this PR - and its 13-fence sweep figure is now dated rather than restated. Error Codes section untouched; no sweep. TOOLING NOTE for the PM, not a repo defect: raw GitHub REST via $GITHUB_TOKEN answers 403 ('GitHub access is not enabled for this session') from this seat, and `gh` is not installed, so the brief's prescribed ADDITIVE label endpoint was unavailable; the MCP issue-label read path also refuses PR numbers. skip-changeset was therefore applied via the MCP replace-write fallback with an explicit union (documentation + skip-changeset) and a read-back, which returned [\"documentation\",\"skip-changeset\"]. The same 403 is why this report needed a repost instead of an edit.",
 "tests": "Gate union derived (never hand-built) with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` - 23 families, no STALE TREE on the final derivation, and byte-identical to the derivation on the previous head (diff of the two matched lists: IDENTICAL). All 23 run at e437cc1c6f under `bash scripts/pm/os-verify-lock.sh -c`, each exit code captured inside the runner BEFORE any pipe: 22 rows in summary.txt with nonzero_count=0, plus `pnpm --filter @objectstack/spec run check:skill-examples` -> its own verdict line `✅ 260 prose examples type-check across 3 surface(s)` (same 260 as the sibling PR: correct, since the new fence is unmarked). Verdict lines quoted from the gates themselves, e.g. `✅ check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading`, `✓ variant/doc gate: 18 discriminated union(s)`, `OK: all 109 declared cross-package glob(s)`. PREREQUISITE handled, not reported as a finding: check:skill-examples first refused with 'packages/spec/dist holds no .d.ts declarations'; built the closure (`pnpm --workspace-concurrency=2 --filter '@objectstack/spec...' --filter '@objectstack/client...' --filter '@objectstack/client-react...' build`, exit 0, 297s) and re-ran it green. FIX MEASUREMENT (the block is not CI-checked, so this is what stands behind it): harness under the gate's own tsc profile copied from packages/spec/scripts/check-skill-examples.ts (strict, ES2020, lib ES2020+DOM, types:[], moduleResolution bundler), with `client` and `orderId` declared so the page's separate TS2304 continuation convention is excluded. BEFORE (block extracted from base abc12cb07c): 4x `error TS18046: 'err' is of type 'unknown'.` at lines 9-12 - exactly the four reads. AFTER (guard block + new block extracted from the committed file): `tsc --noEmit` exit 0, zero diagnostics (log byte count 0). Both legs re-run against the FINAL tree after the wording commit. No ablation was involved. Repo-wide `pnpm lint` NOT run, and the narrowing is declared: population read from eslint's own resolution - `isPathIgnored('content/docs/api/client-sdk.mdx') === true`; count - `lintFiles` returns 1 result, 0 errors, 1 warning 'File ignored because no matching configuration was supplied.', i.e. 0 lintable files in this diff; invariance - `calculateConfigForFile` returns undefined, so no configuration and therefore no type-aware linting applies to the path and this diff cannot move an untouched file's verdict.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code