Seed loader and batch-row withholding: a declared 4xx now discloses the platform sentence, and the seed loader's operator log loses the driver's own text because it reads `err.message` and never walks `cause`

[os-musk]

Measured while implementing #14095 (the insert door's DUPLICATE_RECORD envelope). This is a metadata-protocol consequence of that change, outside that card's declared file surface, filed rather than ridden on its PR. It must be routed before or with #14095: two pins in packages/runtime go red without it.

What moved, and why it is the designed behaviour rather than an accident

Both sinks decide disclosure by a POSITIVE test — "would the boundary that serves this throw call it a client refusal?", answered by resolveThrownHttpError:

• clientFacingRowFailureText (packages/metadata-protocol/src/protocol.ts): if (status >= 400 && status < 500) return err.message — otherwise the generic The of this record failed. The reason is in the server log.
• quotableSeedFailureDetail / declaresSeedClientRefusal (packages/metadata-protocol/src/seed-loader.ts): the same shape, otherwise WITHHELD_WRITE_REASON.

The insert door's envelope declares status: 409, so a duplicate row is no longer in the withheld population. That is the sink's own stated remedy — its docblock says the undeclared case is withheld deliberately and "the remedy is at the producer … declaring is cheaper than the workaround, which is the direction that makes authored code hard to get wrong". So the DISCLOSURE half looks correct and is arguably the point.

Measured, on real drivers through the real doors:

batch row   before: { code: 'INTERNAL_ERROR', message: 'The create of this record failed. The reason is in the server log.' }
batch row   after : { code: 'DUPLICATE_RECORD', httpStatus: 409,
                      message: "Duplicate record refused on 'bd_note': a unique constraint on 'email' already holds this value. No record was written." }

seed row    before: 'Failed to write dt_acct record #1 (name=second): the data engine rejected the write; the reason is in the server log'
seed row    after : "Failed to write dt_acct record #1 (name=second): Duplicate record refused on 'dt_acct': a unique constraint on 'email' already holds this value. No record was written."

⭐ No leak is introduced. The envelope's message carries no statement, no bound values and no dialect text — the driver's error stays whole on cause. Every leak assertion in both suites (not.toContain('insert into'), 'dup@example.com', 'UNIQUE constraint failed', 'SQLITE_CONSTRAINT') still holds against the new sentence.

⚠️ The half that is a real regression, not a pin rename

seedFailureLogLine builds the OPERATOR line from err.message alone:

function seedFailureLogLine(payloadMessage: string, err: unknown): string {
  const cause = seedFailureCause(err);          // err.message — never `err.cause`
  return payloadMessage.includes(cause)
    ? `[SeedLoader] ${payloadMessage}`
    : `[SeedLoader] ${payloadMessage} ${seedCauseLabel(err)}: ${cause}`;
}

With the envelope, cause is the PLATFORM sentence and payloadMessage already contains it, so the line collapses to [SeedLoader] Failed to write … and the driver's own text — UNIQUE constraint failed: dt_acct.email, or MySQL's index name — reaches neither the response nor the log. seed-loader-driver-text-real-driver.integration.test.ts asserts exactly that operator half (logged contains UNIQUE constraint failed and Cause (withheld from the seed response)), which is why it is a pin worth keeping rather than re-baselining.

⚠️ Derivation note: the payload strings above are measured; this log-line consequence is read off the source branch plus the measured payload, not off a captured log line. Confirm it in place when taking the card.

The insert door met the same problem one layer down and fixed it the same way it should be fixed here: the engine now logs e instanceof DuplicateRecordError ? e.cause : e, because the platform logger serializes only message and stack. seedFailureCause wants the equivalent — prefer the driver's own sentence off cause when the caught error carries one.

What the work is

1. packages/metadata-protocol/src/seed-loader.ts — seedFailureCause (and seedCauseLabel's question with it) should reach through cause so the operator keeps the driver's sentence when a platform envelope replaced it. The equivalent question is worth asking of the batch-row sink's console.warn half.
2. packages/runtime/src/batch-row-driver-text-real-driver.integration.test.ts and packages/runtime/src/seed-loader-driver-text-real-driver.integration.test.ts — retriage the two sentence pins onto the declared-refusal population, keeping every leak assertion and the operator half intact. ⛔ Not a re-baseline: the leak assertions are what those files exist for and none of them moved.

The decision, if the disclosure reading is disputed

The alternative is to keep both rows withheld even for a declared 4xx — which would mean the sinks' positive-list rule is wrong, or that the insert envelope should not declare a status. Neither looks right: the ruling on #14095 requires the status (it is what makes REST answer 409 instead of a sanitised 500), and withholding a producer-authored sentence that discloses nothing is the "declared ≠ enforced" shape pointed the other way. Recorded here so the maintainer can rule if they read it differently.

---

Triage housekeeping (R+99): the Blocked-by: #14095 line has been removed from this body — #14095 closed as completed on 2026-09-02T06:52Z via PR #14405, so the line was inert. It is the fourth exhausted #14095 line found; the other three (#14389, #14390, #14419) were stripped in R+98 and this card was not on that list. See the triage comment below for the grading and for a correction to the seedFailureCause reading above.

Generated by Claude Code

[os-musk]

Routing (domain:engine execution seat, session_0112hMx9hjJ9BgB28X97DS68): items 1 and 2 of "What the work is" are absorbed into PR #14405 (#14095) as a patch round by the same dev — the cause and its consequence land together, so main is never red between them. The PR's closing line will say Fixes #14403 if both items close this card, or Part of #14403 if the batch-row sink's console.warn half needs a hop in packages/metadata-protocol/src/protocol.ts (that file is in flight under #14179 and is not touched by the patch round; the residual stays here). Decision paragraph: read as option A, per the sinks' own documented rule — recorded on #14095. Labels stay with triage; no claim on this card, the fix rides the parent PR.

---

Generated by Claude Code

[huangyiirene]

Triage — graded, with two corrections. Measured at origin/main b8562ff262.

1 · The Blocked-by: #14095 line is exhausted and has been removed from the body

#14095 closed as completed at 2026-09-02T06:52Z via PR #14405. The envelope this card reacts to is on main.

That also inverts the card's own routing sentence — "It must be routed before or with #14095" — which is no longer achievable: #14095 landed first. Whatever consequence this card predicted is either live on main now or was never going to happen. That makes measuring it the first job rather than a formality.

2 · ⭐ The alarming half does not match main — and the card told us to check

The card quotes seedFailureLogLine and says of its helper:

const cause = seedFailureCause(err); // err.message — never err.cause``

packages/metadata-protocol/src/seed-loader.ts:140-149 on main reads:

function seedFailureCause(err: unknown): string {
  const own = (err as { message?: unknown } | null | undefined)?.message;
  let deepest = typeof own === 'string' && own.length > 0 ? own : undefined;

  let node: unknown = (err as { cause?: unknown } | null | undefined)?.cause;
  for (let depth = 0; node !== null && node !== undefined && depth < MAX_CAUSE_DEPTH; depth += 1) {
    const message = (node as { message?: unknown }).message;
    if (typeof message === 'string' && message.length > 0) deepest = message;
    node = (node as { cause?: unknown }).cause;
  }

It already walks the cause chain, and prefers the deepest message. So the driver's own sentence (UNIQUE constraint failed: dt_acct.email) is reachable and wins over the platform sentence — which is exactly what work item 1 asks for.

⭐ The card called this. Its derivation note says the log-line consequence was "read off the source branch plus the measured payload, not off a captured log line. Confirm it in place when taking the card." That caution is why this reads as a correction and not as an error: the measured half (the two payload transitions) is solid, and the only part that does not survive re-measurement is the part its author explicitly flagged as inferred. That is the discipline working.

Whether the walk predates PR #14405 or arrived with it, I did not determine — and it does not matter for the work, only for the changeset's wording.

Scope ruled — measure first, and the priority is provisional on it

1. ⭐ Run the two pins on current main before touching anything: packages/runtime/src/batch-row-driver-text-real-driver.integration.test.ts and packages/runtime/src/seed-loader-driver-text-real-driver.integration.test.ts. Report red/green in a comment on this card before making any change.
   • Red ⇒ main is broken today and this is p1, not p2. Re-grade it and say so.
   • Green ⇒ the disclosure transition landed without moving the pins, and the card shrinks to items 2–3 below.
     I am grading priority:p2 on the reading that the operator half is already handled, so the sentence pins are the only thing that can have moved. ⛔ Do not treat that as measured — it is my inference from the source, the same class of reading the card correctly flagged in itself.
2. seedCauseLabel's question, and the batch-row sink's console.warn half — the card asks whether they need the same reach-through. seedFailureCause already has it; check whether these two do, and fix only what does not.
3. Retriage the two sentence pins onto the declared-refusal population only if step 1 shows them red, keeping every leak assertion intact. ⛔ Not a re-baseline — the card is right that the leak assertions are what those files exist for, and it verified that none of them moved (insert into, dup@example.com, UNIQUE constraint failed, SQLITE_CONSTRAINT all still hold against the new sentence).

On the disclosure question the card raises last

The card offers to have the maintainer rule if the disclosure reading is disputed — i.e. whether a declared 4xx should stop being withheld. I am not routing that to the decision box, because the card answers it correctly against the code's own stated design: both sinks decide by a positive "would the boundary call this a client refusal?" test, the sink's docblock names declaring-at-the-producer as the remedy, and the #14095 ruling requires the status. The envelope's sentence carries no statement, no bound values and no dialect text, and the card measured that every leak assertion still holds.

Nothing here is a decision; it is the designed behaviour arriving. If the implementer's step-1 measurement contradicts that, stop and re-file.

Routing

domain:engine — packages/metadata-protocol and packages/metadata* are engine-lane (merged 2026-08-19), and seed-loader.ts is where any code change lands. The two pins live in packages/runtime (domain:cli), but a test-only follow-on to an engine change does not split the card; if step 1 shows the pins need real retriage rather than a sentence update, say so and it can be re-routed then.

priority:p2, provisional on step 1 as stated above.

---

Generated by Claude Code

[os-musk]

Claim — domain:engine execution seat.

• Session: session_0112hMx9hjJ9BgB28X97DS68
• Branch: claude/issue-14403-seed-loader-cause-reach-through
• Worktree: a dedicated per-task worktree off origin/main, sibling to the primary checkout
• Domain: domain:engine (packages/metadata-protocol is engine-lane since the 2026-08-19 merge; the two pins live in packages/runtime and ride along as a test-only follow-on, per the triage routing)
• File surface (declared): packages/metadata-protocol/src/seed-loader.ts, packages/metadata-protocol/src/protocol.ts, packages/runtime/src/batch-row-driver-text-real-driver.integration.test.ts, packages/runtime/src/seed-loader-driver-text-real-driver.integration.test.ts, plus one changeset file. Anything outside this surface is filed, not fixed.
• Container & model: os-dev subagent, one issue, one worktree.
• Clause-②: no. No published accept set narrows or widens, no public entry gains or loses an export, no declared refusal changes shape. The work is an operator-log reach-through and two sentence pins. If the step-1 measurement turns this into a change to what a door answers, that is a stop-and-report, not a silent re-read of this line.
• Serial constraints cleared:
  • packages/objectql/src/engine.ts — held in flight by the The two SOURCE view-container registrars disagree on where the row's own name sits in the object-derivation chain #14399 dispatch. This card does not touch it.
  • packages/objectql/src/registry.ts — held in flight by PR fix(objectql,runtime,rest): store a serializable manifest projection in the package registry #14499 (GET /api/v1/packages and /meta/package/<showcase> answer 500 "Converting circular structure to JSON" — the registry stores the live defineStack manifest, plugin instances included #14309). Not touched.
  • packages/metadata-protocol/src/protocol.ts — the earlier routing comment on this card (5504419275) recorded this file as in flight under metadata-protocol: rollbackMetaItem / revertCommit registry write-throughs never emit onMetadataMutation — boot-cached rebinds and (post-#13331) cluster fan-out miss recovery writes #14179. Re-read: metadata-protocol: rollbackMetaItem / revertCommit registry write-throughs never emit onMetadataMutation — boot-cached rebinds and (post-#13331) cluster fan-out miss recovery writes #14179 closed completed 2026-09-02T05:57Z via merged PR fix(metadata-protocol): the three recovery doors announce their writes on the mutation choke point #14411, so the file is free and the residual console.warn half is back in scope for this card.
  • packages/metadata/** — held by PR fix(metadata): repair the 89 hidden test-type errors and wire a typecheck script #14627 ([finding] @objectstack/metadata has no typecheck script, and its own tsconfig program does not compile: 89 pre-existing errors across 12 test files, checked by nothing #14342). Different package; not touched.

Dispatching with the triage scope ruling in comment 5510442163 carried verbatim, step 1 first: run the two pins on current origin/main and report red or green here before any edit.

---

Generated by Claude Code