fix(driver-turso): a declared index the remote face skips for a missing key column is logged at error on the durability sink

[objectstack-fleet]

Fixes #20537
Clause-②: no

The remote Turso face now reports a declared index it skips, because a key column never materializes, at error on its existing durability sink. It used to report it at warn on the diagnostic sink. This is the remote half of what PR #20519 did for the local face.

What was wrong (read on cd901d7a5)

RemoteTransport.buildDeclaredIndexDDL (packages/drivers/driver-turso/src/remote-transport.ts) plans no DDL for a declared index whose key column is not a stored column. That covers a misspelt name (statsu on a table whose column is status) and a virtual formula field. Skipping it is right, because DDL naming a missing column would fail the whole sync. But the skip was reported through this.diagnosticSink, which TursoDriver wires to logger.warn:

[RemoteTransport] skipping declared index "NAME" on "TABLE" — column(s) not materialized: statsu

For a UNIQUE index, every write keeps succeeding and duplicates are accepted, and the only trace was a warn. The same transport already has a second sink for this class, durabilitySink (wired to logger.error). Its retrofit arm uses it for a unique AND a plain index it could not create. The local face (SqlDriver.syncDeclaredIndexes) logs this same skip through logDurabilityFailure for unique and plain indexes alike.

What changed

• remote-transport.ts, buildDeclaredIndexDDL. The not-materialised arm now calls this.durabilitySink?.(…), not this.diagnosticSink?.(…). That is triage's direction: no new sink and no second rule. It writes one line per skipped index per sync, as the local face does. The line gives the index name, the object and each missing column, and says whether the index was UNIQUE. It follows the AGENTS.md "Degradation log levels" shape:
  • the consequence: for UNIQUE, "the uniqueness it declares is NOT enforced: duplicate rows are accepted, and nothing looks broken from the outside"; for plain, every query the index serves is a full scan while results stay correct;
  • the fix: make every key column a stored field of the object, or remove the index.
• The doc comments on durabilitySink and buildDeclaredIndexDDL now name this arm.
• turso-driver.ts is not edited. Both sinks were already wired there.
• No DDL, accept set or refusal changes. The same indexes are created and the same ones are skipped.
• Changeset: .changeset/20537-remote-skipped-index-durability.md, @objectstack/driver-turso patch.

The dispatch's hypotheses, measured

• H1 held, with one correction. The skip is in buildDeclaredIndexDDL, the planner, not the sync itself, and all four sync paths call it: syncSchema (new and existing table) and syncSchemasBatch (new and existing table). One edit covers all four, and the pins drive all four.
• H2 held. turso-driver.ts has setDiagnosticSink going to this.logger.warn and setDurabilitySink going to (this.logger.error ?? this.logger.warn), at :1656 and :1667 on this base. No edit was needed.
• H3 held. The local text is in SqlDriver.syncDeclaredIndexes, through logDurabilityFailure, for unique and plain alike. The remote line uses the same consequence-then-fix order.
• H4: the plain index goes on the durability sink too. There are two pieces of evidence:
  • the local face routes the plain skip through logDurabilityFailure, and its doc says "A plain index is DDL that was supposed to run and did not, so it takes the same channel";
  • the remote retrofit arm already reports a plain index it could not create on durabilitySink, with the driver-turso: remote mode never materializes object-level indexes — every declared secondary index is absent on production Turso tenant databases, so hot polling queries full-scan #17609 rationale: queries answer correctly by scanning, nothing looks wrong, and the cost arrives as read volume.
• H5: check:durability-log-level does not see this site, and no vocabulary entry belongs there. Its header says it judges try/catch blocks whose try calls a declared durability-critical operation. This arm has no catch and runs no operation: it plans no DDL. It reports through a sink receiver, which LOGGER_RECEIVERS does not cover by a recorded decision. So no DURABILITY_CRITICAL_CALLEES entry can make it visible. The gate reads 38 seams, all loud, on this head (exit 0).

Tests

packages/drivers/driver-turso/src/remote-transport-unbuildable-declared-index.test.ts has 18 cases. They use the real @libsql/client over file::memory:, as the declared-index parity suite does:

• The card's matrix (16 cases). {misspelt statsu, formula column} × {UNIQUE, plain}, each over syncSchema and syncSchemasBatch, against a new table and an existing one. Each case asserts:
  • exactly one durability-sink line names the index, with the table and the column quoted;
  • UNIQUE is present for the unique cells and absent for the plain ones;
  • no diagnostic-sink line names the column or the index;
  • the sync resolves;
  • the index is absent from sqlite_master.
• End to end (2 cases). TursoDriver in remote mode (libsql://… with a supplied client), through initObjects. The line lands on logger.error and never on logger.warn.

The prose is not pinned beyond the named subjects and the UNIQUE word, as in the local #20432 suite.

Commands, run on 90e8f132f:

• pnpm --filter @objectstack/driver-turso exec vitest run --maxWorkers=2 src/remote-transport-unbuildable-declared-index.test.ts: 1 file, 18 passed.
• pnpm --filter @objectstack/driver-turso exec vitest run --maxWorkers=2 (whole package): 79 files passed, 2126 passed, 22 skipped, verdict command-exit 0.
• pnpm --filter @objectstack/driver-turso typecheck: command-exit 0. The package tsconfig includes src/**/*, and tsc --noEmit --listFiles lists the new test file once.

Reverse verification (ablation). The fix was committed first. The mutation went through scripts/ablation-replace.mjs in WRAP mode, with its own trap and restore. It turned the new arm's this.durabilitySink?.( back into this.diagnosticSink?.(, and nothing else.

• Landed on disk: anchor count went 1 to 0, and durabilitySink?.( / diagnosticSink?.( counts went 2/3 to 1/4. The blob went 1c7cb45f2828 to 672bd32cd8c6.
• Result: predicted all 18 red. Observed 18 failed of 18, on a comparison (expected [] to have a length of 1 but got +0).
• Restored: blob equals HEAD (1c7cb45f2828), git diff HEAD is empty, and the tree is clean.
• No dist step: the suite imports the subject by a relative path (./remote-transport.js, ./turso-driver.js), so vitest reads src.

Gates

• Derived gates. Derived after the final commit with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at 90e8f132f: 61 commands. The dispatch-time list had 48; the 13 added come from the changeset and test-file families. All 61 ran and exited 0. --ran with the exit codes recorded reads: "61 derived, 61 run, 0 NOT-MEASURED, 0 UNRUN (a DERIVED zero)".
• Three gates needed a full build first. check:dual-build-cjs-loads, check:lean-entry-closure and check:type-check-debt first exited 3 (PREREQUISITE NOT MET, not measured). After a full build (turbo run build --filter='./packages/*' --filter='./packages/*/*', 71 of 71 tasks, with the tree clean afterwards), each exited 0.
• pnpm check:driver-conformance, before and after: "50 covered cell(s), 0 in the DEBT ledger, 0 exempt" both times.
• pnpm check:durability-log-level: not in the derived set; run for H5. Exit 0.
• Lint, narrowed to the two touched .ts files with eslint --no-inline-config --format json: 2 files, 0 errors, 0 warnings.
  • Both files are matched by the config and neither is ignored.
  • eslint.config.mjs never enables type-aware linting (no parserOptions.project), so this diff cannot move the verdict on any file it does not touch.
  • The full pnpm lint run is CI's.

Acceptance notes

• The reason for a missing column is not given per column. The local line says, per column, why it has no column ("not a field of the object" or "a formula field"), through describeMissingIndexColumns. That helper is exported from schema-drift.ts but not from @objectstack/driver-sql's package entry. Reusing it would widen that package's public surface, outside this card's claimed files. A copy here would be the second copy this file's shared-normalizer imports exist to prevent. So the remote line names the missing columns and gives both possible reasons in one clause. Carrier: none.
• With no durability sink set, the skip is not logged at all. Before, it went to the diagnostic sink. TursoDriver wires both sinks together at construction, so no composition in this repo changes. The retrofit arm already works this way, and the durabilitySink doc says what still surfaces a missing UNIQUE (the enveloped conflictKeys refusal).
• Remote drift detection is not in this card. The remote face refuses it by design, so os migrate plan still cannot show the skipped index on a remote datasource. Only the log line changes here.
• The branch is two commits behind main (89801cd96, 0cb72cfc7: service-automation and spec migration text). Neither touches packages/drivers, so no merge was made. CI validates the merge ref.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

2 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 7 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 0cb72cfc72ff6bc15b5e6374c2c818b9d9ead534 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d3e217b8d0c054010aeb420cad9480bd12d8d844 — the merge of head 90e8f132f70c6f1e72eb8de113560af647d96655 into base 0cb72cfc72ff6bc15b5e6374c2c818b9d9ead534, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d3e217b8d0c054010aeb420cad9480bd12d8d844 && git checkout d3e217b8d0c054010aeb420cad9480bd12d8d844
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0cb72cfc72ff6bc15b5e6374c2c818b9d9ead534 90e8f132f70c6f1e72eb8de113560af647d96655 && git checkout -B drift-repro 0cb72cfc72ff6bc15b5e6374c2c818b9d9ead534 && git merge --no-ff 90e8f132f70c6f1e72eb8de113560af647d96655

node scripts/docs-audit/affected-docs.mjs --json 0cb72cfc72ff6bc15b5e6374c2c818b9d9ead534

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 90e8f132f70c6f1e72eb8de113560af647d96655
Local-runs: none

PR #20650 (card #20537), the net diff against main at this head: 3 files, +268/-8. Inputs read: the card body and all three comments (triage 5882218115, the dispatch Claim 5890821367, the os-dev-report 5891472582), the PR body and file list, the diff, and the head's check-runs. Nothing was built, run or re-run.

① Derived judgments

• Accept set: unchanged — right. In RemoteTransport.buildDeclaredIndexDDL the diff replaces one sink call and its message; the missing computation, the continue, the emitted dedupe and the planned list are byte-for-byte what main has. The same indexes are planned and the same ones are skipped; no DDL text moves. The changeset's "No DDL, accept set or refusal changes" sentence is true.
• Public surface: unchanged — right. RemoteTransport is a package export (src/index.ts), and setDiagnosticSink / setDurabilitySink keep their signatures. The only behavioural change is which registered sink the skip reaches. A transport driven standalone with only a diagnostic sink registered now hears nothing for this skip; the file's own docs call that composition unsupported, TursoDriver registers both sinks at construction (turso-driver.ts lines 1656 and 1667 on main), and the PR's acceptance notes say so. Patch-level behaviour, no API motion.
• Channel and level — right. The new arm calls this.durabilitySink?.(...), which TursoDriver wires to (this.logger.error ?? this.logger.warn); that is the same channel the retrofit arm (retrofitDeclaredIndexes) already uses for an index it could not create, and the same level the local face's SqlDriver.syncDeclaredIndexes uses through logDurabilityFailure for this same skip (sql-driver.ts around line 14659 on main). The warn fallback on an error-less injected logger is pre-existing and shared with the local face, not introduced here. On head the file has 2 durabilitySink?.( sites and 3 diagnosticSink?.( sites (was 1 and 4), matching the dev's ablation counts.
• Coverage of the four sync doors — right. On main all four paths call the one planner: syncSchema on a new table (line 2058) and an existing one (2086), syncSchemasBatch on a new table (2168) and an existing one (2214). One edit covers all four, and the new suite's 16-case matrix drives all four; the skipped index never enters planned, so the retrofit leg cannot report it a second time.
• Runtime log message, sentence by sentence — every one true against main and the diff. (a) declared UNIQUE index "NAME" on "TABLE" was NOT created: no column for 'x' — true. (b) "a key column must be a stored field of the object — a name that is not a field, or a virtual formula field computed on read, has no column" — true and, for the remote face, exhaustive: materializedColumns (line 2101 on main) admits the builtin columns plus every declared field except type: 'formula', so those two are the only ways a key column can be missing here. (c) UNIQUE consequence: "The uniqueness it declares is NOT enforced: duplicate rows are accepted, and nothing looks broken from the outside" — true; this is the owed part ① (what is not durable, and that the system keeps looking healthy). (d) Plain consequence: "Every query this index exists to serve is answered by scanning the whole table instead: nothing looks broken from the outside and results stay correct" — true, and the retrofit arm's plain text on main says the same. (e) Fix: "Fix the metadata so every column in the index's fields is a stored field of the object, or remove the index ("os validate" refuses a name that is not a field)" — true; packages/lint/src/validate-object-field-refs.ts on main judges indexes[].fields[] at error on the three commands and the publish door, and its own header says a formula key is judged as existing and left to the sync's skip — so the prescription's scoping is exactly right. This is the owed part ②. Both owed parts sit in the one string the sink receives, so they are in the first line printed. It is said once per skipped index per sync (a boot-time act), not per write. The string carries no tracker number; the [#20537] citations are in code comments, the convention this file already follows.
• Changeset prose, sentence by sentence — true. "In remote mode (a libsql:// URL)" — true; the parenthetical is one example of remote mode (turso-driver.ts also routes https://, http://, wss://, ws:// without a syncUrl there), not a false claim. "skips a declared index whose key column is not a stored column: a name that is not a field of the object (a misspelling), or a virtual formula field, which is computed on read and has no column" — true (see (b)). "The skip itself is unchanged, since DDL naming a missing column would fail the whole sync" — true, and main's own doc on the planner says the same. "It used to be reported through the driver's warn diagnostics, so a skipped UNIQUE index left duplicates accepted while the log said warn" — true (diagnosticSink to logger.warn, line 1656). "now logged at error, on the same channel the remote face already uses for a declared index it could not create, and the local face uses for the same skip" — true. "one line per skipped index per sync" — true per planned entry; a same-named entry declared twice with a missing column prints twice, which is the pre-existing loop order on both faces and not this card's matter. "names the object, the index and the missing column, says whether the index was UNIQUE, states what is not enforced ... and says how to fix it" — true against the string in the diff. "No DDL, accept set or refusal changes" — true.
• "Do not over-apply it" — the plain index belongs at error here. AGENTS.md's durability class names "DDL that was supposed to run did not" outright; the local face already routes the plain skip through logDurabilityFailure ("A plain index is DDL that was supposed to run and did not, so it takes the same channel"), and the remote durabilitySink doc's [driver-turso: remote mode never materializes object-level indexes — every declared secondary index is absent on production Turso tenant databases, so hot polling queries full-scan #17609] paragraph already grades a plain index it could not create the same way. Putting the plain skip on the diagnostic sink would have split one class across two levels on one face. Right.
• Tests — right shape. remote-transport-unbuildable-declared-index.test.ts: 16 matrix cases on the real @libsql/client over file::memory: assert exactly one durability line naming the index, table and column, UNIQUE present or absent, zero diagnostic lines naming either, the sync resolving, and the index absent from sqlite_master; 2 cases drive TursoDriver in remote mode through initObjects and read logger.error versus logger.warn. The file reads nothing outside its package (@objectstack/driver-sql's buildIndexName is on that package's entry, src/index.ts line 91), so the cross-package-inputs gate has nothing to see. Prose is pinned only on the named subjects and the UNIQUE word, as the local [finding] a misspelt field name in a field's relatedListColumns, lookupColumns, lookupFilters[].field or dependsOn passes every authoring door, and fails only at view or picker time #20432 suite does.
• Doc comments — consistent with the code. The durabilitySink doc gains a paragraph naming this arm; the planner's doc widens "(a virtual formula field)" to include the misspelt name and states the sink. No governed surface, no CHANGELOG.md, no turso-driver.ts edit (the Claim's read-only constraint held).
• Check-runs on this head, as read at 2026-09-29T13:47Z: 31 runs; 12 success (Governed Surface Queue Guard, Check Changeset, Check PR Size, Type Check · source gates, the four claim/card guards, Auto Label, Check Documentation Links, Flag docs affected by code changes, filter); 3 skipped (Console Pin Gate, Build Docs, Packed-tarball smoke); 16 in_progress, among them every remaining required context: Lint & Repo Gates, the three Type Check jobs, Test Core 1 to 6, Dogfood Regression Gate 1 to 3, Build Core, Temporal Conformance (live PG + MySQL); 0 failure. Not polled. in_progress is not a pass: the landing seat reads those green before arming.

② Semver level

• .changeset/20537-remote-skipped-index-durability.md declares '@objectstack/driver-turso': patch. The diff publishes a bug fix in a released package (a log level and message on an existing seam) with no export, key or config motion: patch is the level AGENTS.md's checklist requires, and skip-changeset would have been wrong. Check Changeset is success on this head.
• Clause-②: no — present in the changeset body and in the PR body, both bare with no (widening) / (narrowing) arm. Correct: nothing an author can write is accepted or refused differently. No ADR-0087 marker is owed and none is written.
• The package sits in the changesets fixed group, so the group bumps together at release; the declared level for this change is still the right input.

③ Boundary flags

The report's open_questions is empty. Its four flags, each answered:

1. The plain (non-unique) skip also goes to the durability sink — right, not escalated. Triage left it to "whichever sink the durability rule assigns it"; the rule assigns undone declared DDL to error, and both existing conventions on main (local syncDeclaredIndexes, remote retrofit arm and the durabilitySink doc) already do so. See ①.
2. check:durability-log-level does not see this site — right, and no vocabulary entry was owed. The gate's first rule judges a catch whose try calls a DURABILITY_CRITICAL_CALLEES name; this arm sits in a planner with no try/catch and performs no operation. Its receiver, this.durabilitySink?.(, is outside LOGGER_RECEIVERS (logger / log / console) by the header's recorded limitation 3. No DURABILITY_CRITICAL_CALLEES entry can make a non-catch site visible, so adding one would have been noise. The AGENTS.md invariant "what this checker cannot see, that test holds" is met by the 18-case suite pinning the channel and the level. Not escalated.
3. The branch was not merged with origin/main — verified, not escalated. Merge-base cd901d7; main is ahead by 89801cd (service-automation, core/security, service-messaging) and 0cb72cf (spec migrations text, docs, changeset). Neither touches packages/drivers; GitHub reports the PR mergeable. The queue rebuilds on the merge ref, which is the §10 re-verification.
4. describeMissingIndexColumns was not shared — right, noted where it belongs. On main, packages/drivers/driver-sql/src/index.ts re-exports buildIndexName from schema-drift.js but not describeMissingIndexColumns; sharing it would widen a published package's surface outside the card's claimed files. Because the remote face's only two missing-column causes are the two the message already names (①, (b)), the operator loses no information they need to act. Recorded in the PR's acceptance notes with carrier none, which is what Prime Directive chore: version packages #10 asks for a note that is neither a defect, a contract violation nor a trap. If a later card wants byte-parity with the local line, it is a driver-sql export with an api-surface regeneration, not a driver-turso change.

Other deviations in the report (the extra check:durability-log-level run, model-free commit trailers, no labels written, worktree cleanup) are conforming and need no answer.

Implemented-by: claude/issue-20537-remote-skip-durability-sink
Reviewed-by: session_01DEvba2nBuD4tWzfq8r8NFY

VERDICT: PASS

---

Generated by Claude Code