CryptoContext.namespace / .key document themselves as settings-only, one layer below sys_secret's three producers

[os-warren]

Observation-class finding, surfaced while fixing #12550 (sys_secret field help). ⛔ Not assigned, not queued — recording drift.

What is declared vs what is true

#12550 corrects the shipped field descriptions on sys_secret, whose (namespace, key) pair means something different per producer. The contract those three producers all call carries the same settings-only prose one layer down, in packages/spec/src/contracts/crypto-provider.ts:

export interface CryptoHandle {
 /** Stable opaque id stored in `sys_setting.value_enc`. */
 readonly id: string;
 ...
}

export interface CryptoContext {
 /** Settings namespace the value belongs to. */
 namespace: string;
 /** Specifier key within the namespace. */
 key: string;
 ...
}

export interface ICryptoProvider {
 /**
 * Encrypt plaintext and return a handle. The handle is stored in
 * `sys_secret` and referenced by `sys_setting.value_enc`.
 */
 encrypt(plain: string, ctx: CryptoContext): Promise<CryptoHandle>;

Measured on origin/main@f93df4db, by call site rather than by line number — all three producers construct a CryptoContext, and only one of them means "settings":

caller	ctx.namespace	ctx.key	where the handle id ends up
SettingsService (services/service-settings/src/settings-service.ts)	settings namespace	specifier key	sys_setting.value_enc
engine encryptSecretFields (packages/objectql/src/engine.ts)	object name	field name	a secret:<id> ref on the business row itself
datasource credential binder (services/service-datasource/src/datasource-secret-binder.ts)	caller-supplied, default datasource	datasource name	the artefact's sys_secret:<id> credentialsRef

So CryptoHandle.id is not "stored in sys_setting.value_enc" in general, and CryptoContext.namespace is not a settings namespace in general.

Why it is worth writing down

Unlike #12550's strings these are TS doc comments, not published metadata — nothing ships them to an operator, which is why this is filed separately and graded as an observation rather than folded into that PR (different package, different regeneration/gate family).

What makes it more than a typo is the sentence just above CryptoContext: "so providers can implement Additional Authenticated Data (AAD) bindings — e.g. AWS KMS encryption context. Helps reject ciphertexts that were copied across namespaces." A provider author implementing that binding is being told the pair is a settings coordinate, while in fact one flat (namespace, key) space is shared by three vocabularies — an object named datasource, or a settings namespace colliding with an object name, is not excluded by anything here. Whether that is merely a doc fix or has a real AAD-collision consequence is the question a triager should decide; this card only records that the prose asserts the single-producer reading.

Shape of a fix

Doc-comment corrections in packages/spec/src/contracts/crypto-provider.ts naming the producer-scoped reality (the same correction #12550 made to the shipped descriptions), plus whatever the AAD question turns out to need. packages/spec edits carry their own artifact-regeneration discipline, so it is not a rider on #12550's PR.

Found while working #12550; filed unassigned for triage.

[claude]

Triage: graded pm:queue, routed domain:spec, type Task — the fix lands in packages/spec/src/contracts/crypto-provider.ts (anchoring rule: spec lane owns the whole package including contract prose). Well-scoped doc-drift correction with measured evidence: three producers, one settings-only prose claim, call-site table in the body.

Dispatch notes for the spec seat: (1) the AAD-collision question in the body is a premise the dev measures first — if any in-tree provider actually implements AAD binding off (namespace, key) and the three-vocabulary collision is real, that half becomes a contract question: stop and report, do not widen the doc PR into a behavioral fix. (2) Clause-② as filed: no — prose corrections change no accept/reject behavior; the stop-and-report path exists precisely for the case where measurement says otherwise. (3) The card itself records why it is not a rider on #12550 (different package, different regeneration/gate family); packages/spec edits carry the usual artifact-regeneration discipline.

Triage seat, session session_01VuzvqsYQDYg8pLnGicpciV, hourly incremental round 2026-08-26 (picked up by the run-to-empty finding round; the card predates this round's since window by 8 minutes and is the only non-skills ungraded finding in either repo).

---

Generated by Claude Code

[os-zhuang]

Claim: PM seat (spec lane, R8) dispatching this card to a dev agent.

• Session: session_012xGvxcwPRTJfA7RfjXEYA4 (PM seat, objectstack#6017)
• Branch: claude/issue-12599-cryptocontext-doc-drift
• Worktree: ../objectstack-issue-12599 (dedicated per-task worktree off origin/main)
• Domain: domain:spec
• File surface: packages/spec/src/contracts/crypto-provider.ts (doc-comment corrections) + regenerated artifacts the spec discipline requires. Disjoint from both in-flight surfaces (spec: retire the allowRestore / allowPurge permission props (ruled 2026-08-26; M2 anchor stays open, keys return with M2) #12497 security/permission.zod.ts + retirement registries; PR docs(spec): wrong-layer guidance for group/hideFields/rowColor on object userActions #12606 data/object.zod.ts) — verified against the card body and the in-flight claims.
• Container & model: os-dev subagent, dispatch tier opus (default)
• Clause-②: no, per triage (comment 5428547968) — prose corrections move no accept/reject set. Fork condition carried verbatim: if measurement shows an in-tree provider implements AAD binding off (namespace, key) and the three-vocabulary collision is real, STOP and report needs_decision — never widen the doc PR into a behavioral fix.
• Serial constraints: none. Not a rider on sys_secret.namespace / .key still describe themselves as settings-only, on a table with three producers #12550 (the card records why).

---

Generated by Claude Code

[os-zhuang]

os-dev-report

Dev seat report for #12599. Status: needs_decision — the fork condition in triage comment 5428547968 fired on both halves. No PR opened; no file was edited (working tree at 527e0505d is clean, git status --porcelain empty).

The card's premise is TRUE (re-verified on origin/main@527e0505d)

All three producers construct a CryptoContext, and only one means settings. Verified by call site, not line number:

producer	file	ctx.namespace	ctx.key
SettingsService	packages/services/service-settings/src/settings-service.ts:1663	settings namespace	specifier key
engine encryptSecretFields	packages/objectql/src/engine.ts:5888-5890	object name	field name
datasource credential binder	packages/services/service-datasource/src/datasource-secret-binder.ts:90-92	caller-supplied, default datasource	datasource name

(Note the real paths are under packages/services/..., not services/... as the card body spells them.) So CryptoHandle.id is not "stored in sys_setting.value_enc" in general and CryptoContext.namespace is not a settings namespace in general. The doc drift is real.

AAD measurement — the fork condition, both halves TRUE

Half 1 — does an in-tree provider implement AAD binding off (namespace, key)? YES.

packages/services/service-settings/src/local-crypto-provider.ts:512-519:

private aadOf(ctx: CryptoContext): string {
 // Bind ciphertext to (namespace,key) so a row cannot be moved across
 // specifiers. ...
 return [ctx.namespace, ctx.key].join('|');
}

Fed to cipher.setAAD / decipher.setAAD (lines 484, 506). This is not an exotic provider: LocalCryptoProvider is the default, open-source, self-host provider, and it is what the CLI composition root wires. There is no producer discriminator in the AAD and the | separator is unescaped.

Half 2 — is the three-vocabulary collision real? YES, structurally — and it is concretely constructible from names already in the tree.

Four measured facts compose it:

1. One provider instance, one key, all three producers. packages/cli/src/commands/serve.ts builds a single sharedCryptoProvider and hands it to SettingsService (line 3570) and to the engine's secret-field path (line 3768). Cross-vocabulary decryption is therefore gated by the AAD alone, not by key separation.
2. sys_secret deliberately permits duplicate pairs. packages/platform-objects/src/system/sys-secret.object.ts:158-161 declares { fields: ['namespace', 'key'], unique: false }. Collisions are permitted at rest by design, and that same file's TSDoc (the sys_secret.namespace / .key still describe themselves as settings-only, on a table with three producers #12550 correction) already states the pair "does NOT attribute a row to a producer".
3. Nothing reserves the colliding names. Object name validation is /^[a-z_][a-z0-9_]*$/ (packages/spec/src/data/object.zod.ts:1559). RESERVED_NAMESPACES (packages/objectql/src/registry.ts:36) is {'base','system'} plus sys — and it governs metadata FQN namespaces, not object names. mail, auth, storage and datasource are all legal object names.
4. The colliding pair already exists on the settings side. The shipped mail manifest declares encrypted specifiers smtp_password and api_key. The existing AAD pin (local-crypto-provider.test.ts:131) is literally written on { namespace: 'mail', key: 'api_key' }.

Compose 1-4: an app object named mail carrying a Field.secret() field named api_key makes the engine produce AAD mail|api_key — byte-identical to the settings producer's, under the same key, in a table that permits both rows. A ciphertext swapped between those two rows decrypts cleanly. The existing AAD test would pass unchanged, because it only ever varies the key half within one vocabulary.

Is it live today? No. Settings namespaces in tree: ai, auth, branding, company, feature_flags, knowledge, localization, mail, sms, storage. Objects carrying Field.secret(): sys_account, sys_email, http_delivery, sys_webhook, and the showcase field_zoo. No intersection. The hazard is open by design, not currently realised.

Why this stops the prose PR rather than riding alongside it

Per the fork instruction I did not widen this into a behavioral fix. But it also blocks the prose-only fix, for a reason worth stating: the sentence that must be rewritten is the AAD sentence itself —

"so providers can implement Additional Authenticated Data (AAD) bindings ... Helps reject ciphertexts that were copied across namespaces."

Correcting namespace/key to name three vocabularies while leaving that sentence intact would make the docblock newly assert, on its face, that the advertised guard does not exclude cross-vocabulary copies. Its correct replacement is one of two different sentences — "the flat shared space is intended, and the AAD guarantee is within-vocabulary only" versus "the AAD is intended to be producer-scoped and is currently under-specified" — and choosing between them is the contract statement the triager reserved. That is the decision below, not a wording preference I should settle.

Decision requested

Question: the default provider's AAD binds (namespace, key), a flat space three uncoordinated producer vocabularies share under one key, with the pair explicitly non-unique at rest. What is the intended contract?

Option A — prose only. Document the flat shared space and narrow the AAD sentence to the guarantee that actually holds (rejects swaps within a vocabulary; does not exclude cross-vocabulary pairs). No behavior change, no migration.

Option B — producer-discriminated AAD. Add a required scope discriminant to CryptoContext (setting / object_field / datasource) and fold it into a delimiter-safe AAD encoding, replacing the unescaped join. Restores the advertised guarantee. Cost: a breaking change to a public ICryptoProvider export and an at-rest migration — every existing ciphertext was sealed under the old AAD and needs a rewrap path.

Option C — reserve and reject. Keep the flat space but forbid the collision at authoring/publish: reject object names colliding with registered settings namespaces and with datasource. No migration, ciphertexts stay valid. Cost: couples object authoring to a settings-namespace registry that plugins extend at runtime, so a namespace registered later can retroactively collide with an already-published object — enforceable only for what is known at publish time.

Recommendation, on the four axes: A now, with B recorded as the intended direction in its own ADR.

• Real business need. Measured: zero collisions in the shipped tree, no known affected deployment. But Field.secret() is customer-authorable on customer-named objects, so the space is open by design — this is a latent hazard, not a live incident.
• Long-term soundness for this project. Option A alone leaves the contract advertising a binding whose scope it cannot state precisely. B is the contract-first shape under Prime Directive Add comprehensive test suite for Zod schema validation #12 — fix the AAD at its producer rather than tolerate collisions downstream — so the direction should be recorded even if the migration is not spent now.
• Making AI-written metadata hard to get wrong. This axis moves the answer. An object named mail or datasource with a secret field is a plausible AI generation and nothing at authoring time says no. Under A it lands silently in another vocabulary's AAD space; under B it is structurally impossible; under C it fails loud at publish. A is the only one that stays quiet — which is why A should not be the end state, only the honest present-tense description.
• Startup scope discipline. B is a breaking spec change plus a ciphertext migration, priced against a hazard with zero measured instances. Paying that now is not warranted; recording it as the intended shape costs nothing and stops the weak guard fossilising as "intended forever".

A maintainer choosing A can have the prose PR immediately — the wording is settled by that choice alone, and the correction is otherwise ready.

Related drift found while measuring (same defect class, same decision)

packages/services/service-datasource/src/datasource-secret-binder.ts:51 carries the identical settings-only prose one layer over:

/** Settings namespace recorded on the secret row (default `'datasource'`). */
namespace?: string;

Not filed as a separate card deliberately: it is the same drift, it is corrected by the same sentence choice this decision settles, and a separate card would fragment one decision across two. Recommend folding it into whatever PR the decision produces. Flagging it here so it survives regardless of what happens to this report.

Verification

No diff was produced, so there is nothing to verify — reported as NOT MEASURED rather than green. The dispatch's verification bar (build, test, typecheck, check:generated, check:authorable-surface, derived gates) was written for the prose-PR path and was deliberately not run against an unmodified tree, where it would measure the state of origin/main and not of any change of mine. Branch claude/issue-12599-cryptocontext-doc-drift is pushed but empty (write-routing probe only, zero commits beyond 527e0505d).

---

Generated by Claude Code