fix(verify): os verify never creates key material in the key home; the harness seals under an in-process data key

[objectstack-fleet]

Fixes #21499

Clause-②: no

What changed

bootStack (packages/verify/src/harness.ts) composed the settings service with no crypto provider and bound the engine to a bare LocalCryptoProvider. bootStack forces a development posture, where both providers resolve a data key the way a server does: an env key, then the key file in the key home, and with neither they mint the key file. So os verify, a one-shot command over an in-memory database, left key material in the key home. On a host that already had a key, the harness sealed its throwaway fixtures under that real key.

The harness now holds ONE LocalCryptoProvider over an explicit random key (harnessCryptoProvider, module-private):

• no env read, no key-file read, no write anywhere: the key never leaves the process's memory;
• the settings service (new SettingsServicePlugin({ cryptoProvider })) and the engine (setCryptoProvider) get the same instance, so secret fields and encrypted settings still seal AND open on a keyless host. That is why the CLI's one-shot shape from PR fix(cli): a one-shot command never mints a data key in the key home (#21471) #21497 ("read an existing key, or refuse every call") does not fit here;
• one key per PROCESS, not per boot: two boots over one databaseFile (the harness's restart) open each other's secrets, as a real host's stable key would let them.

Shape choices, measured (dispatch zone 2)

• A1, confirmed at base 6f17d1d364. harness.ts:498 was new SettingsServicePlugin() with no provider, and :694 was engine.setCryptoProvider(new LocalCryptoProvider()). packages/cli/src/commands/verify.ts:195 and :219 call bootStack(config, { multiTenant }) and bootStack(config, { multiTenant, security }). BootOptions has no crypto option.
• A2: no public option is needed. No caller of bootStack in this repository passes or needs a key: every boot is an in-memory database or a caller-owned temp file. So the harness owns its provider internally. BootOptions and every export are unchanged, Clause-②: no holds, and packages/cli/src/commands/verify.ts is untouched.
• Per process, not per boot. Measured by ablation (below): a per-boot key breaks the restart case with an AES-GCM authentication failure.

Evidence

Public door. Built CLI, examples/app-todo, os verify --json, development posture, no env key, a fresh empty key home (OS_HOME):

@objectstack/verify built from	exit	stdout	key home after	stderr line announcing a minted key
the base harness (6f17d1d364, rebuilt; dist preflight: marker absent)	1	764 B	dev-crypto-key	1
this PR (rebuilt; dist preflight: marker present)	1	764 B, byte-identical	empty	0

Both runs exit 1 on the same pre-existing fidelity gap on todo_task.tags (see Acceptance notes). It is unrelated to this change.

Pin packages/verify/src/harness.key-custody.test.ts. Every boot runs in a hook, and the cases only assert.

• Committed red first (465c22036a), against the unfixed harness: 4 failed, 3 passed.
  • The empty key home gained dev-crypto-key.
  • Both sealed rows opened under a pre-existing key file's key: [true, true].
  • Both sealed rows opened under OS_SECRET_KEY: [true, true].
  • The restart case's key home gained dev-crypto-key.
  • The control stayed green: the default provider reports generated-file in this posture and home.
• With the change (7c3a1843ce): 7 passed.
• Ablation, a per-boot key in place of the per-process one, through scripts/ablation-replace.mjs:
  • the anchor went 1 to 0 and the blob changed;
  • after the restore, the blob equals HEAD and git diff HEAD is empty;
  • the restart describe's hook fails with Unsupported state or unable to authenticate data (6 passed, 1 skipped, file red).
  • The pin imports ./harness.js from source, so no dist/ leg applies to it.

Local runs at HEAD e8a091457c:

• pnpm --filter @objectstack/verify exec vitest run: 17 files, 127 tests passed.
• pnpm --filter @objectstack/verify typecheck: exit 0, tsc plus the test layer. --listFiles on the test config holds the new test (17 of 17 test files).
• node scripts/pm/dispatch-gates.mjs --commands: 62 families derived and all 62 run. The --ran reconciliation reads 0 NOT-MEASURED and 0 UNRUN.
  • check:dual-build-cjs-loads first exited 3 (PREREQUISITE NOT MET: 9 packages had no dist/). After a cache-replay build of those 9 it exited 0.
• pnpm lint over the whole repository, unnarrowed: exit 0.

Not run locally: CI's full suites, and the CLI integration tier (no packages/cli file is touched).

Serial note

PR #21497 adds an enumeration pin over packages/cli/src. It had not landed when this PR was opened, and this branch sits on 6f17d1d364. This diff touches no packages/cli file, so that pin's population is unchanged. The seat merges main and re-runs that pin at landing.

Acceptance notes

• os verify --json on examples/app-todo exits 1 on main with one fidelity gap. The derived write puts the scalar important into todo_task.tags, a select with multiple: true, and reads back the array ["important"]. It is reported to the seat as a finding and is not touched here.
• Every bootStack under vitest also stops minting into the runner's key home. The harness forces a development posture, so the old default minted there too.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/verify, touching 3 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via bootStack (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

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 — 3 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 2ee8383f4e16248322a45a3e4fde5de75598eef4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 9e8db835a446205cceed04d9c721f3a5524e6b52 — the merge of head e8a091457cee686bf1cbabf1c7c4e8d36a7ef8ae into base 2ee8383f4e16248322a45a3e4fde5de75598eef4, 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 9e8db835a446205cceed04d9c721f3a5524e6b52 && git checkout 9e8db835a446205cceed04d9c721f3a5524e6b52
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2ee8383f4e16248322a45a3e4fde5de75598eef4 e8a091457cee686bf1cbabf1c7c4e8d36a7ef8ae && git checkout -B drift-repro 2ee8383f4e16248322a45a3e4fde5de75598eef4 && git merge --no-ff e8a091457cee686bf1cbabf1c7c4e8d36a7ef8ae

node scripts/docs-audit/affected-docs.mjs --json 2ee8383f4e16248322a45a3e4fde5de75598eef4

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 2ee8383f4e16248322a45a3e4fde5de75598eef4 → pass the list as
args.docs, on the commit named under Which tree this was computed on.