@noy-db/hub 0.3.0-pre.1 → 0.3.0-pre.11

package/dist/kernel/via/index.d.ts

@@ -0,0 +1,200 @@
+import type { EncryptedEnvelope } from '../types.js';
+/** Awaitable type for potentially async results. */
+type Awaitable<T> = T | Promise<T>;
+/** Declared security posture — a property the kernel enforces (enforcement activates in phases B/C). */
+export interface ViaPosture {
+    readonly encryptedAtRest: 'envelope' | 'sealed';
+    readonly queryable: 'none' | 'det-exact' | 'ordered' | 'full';
+    readonly exportable: boolean;
+    readonly forgettable: boolean;
+}
+/** Opaque marker every feature descriptor extends; the kernel never sees concrete descriptor types. */
+export interface ViaDescriptor {
+    readonly _viaBrand: string;
+}
+/** Per-call write context (A: minimal; B/C extend). */
+export interface ViaWriteCtx {
+    readonly id: string;
+    /** Owning vault name (event payload identity — e.g. i18n:script-violation). */
+    readonly vault: string;
+    /** Prior stored record (decoded), lazily resolved. Null when creating. */
+    readonly prior: () => Promise<Record<string, unknown> | null>;
+    /** Typed event emission (e.g. i18n:script-violation). */
+    readonly emit: (event: string, payload: unknown) => void;
+}
+/** Per-call read context — mirrors LocaleReadOptions loosely; features narrow. */
+export interface ViaReadCtx {
+    readonly locale?: unknown;
+    readonly fallback?: unknown;
+    readonly layer: string;
+}
+/** One sealed slot's ciphertext — matches the existing `iv:data` sealed map entries (seam map §2 step 2). */
+export interface SealedSlotRef {
+    readonly iv: string;
+    readonly data: string;
+}
+/**
+ * A scoped crypto capability handed to a `via` feature's `encodeAtRest`/
+ * `decodeAtRest`/`erase` hooks — never the keyring, never the enclave.
+ * `sealedSlots` is pre-bound to one `(collection, recordId)`; `reservedEnvelopes`
+ * is a whole-envelope encrypt/decrypt door scoped to collection names under a
+ * declared prefix (e.g. `_dict_`).
+ */
+export interface ViaCryptoCtx {
+    readonly sealedSlots: {
+        seal(field: string, plaintext: unknown): Promise<SealedSlotRef>;
+        unseal(field: string, ref: SealedSlotRef): Promise<unknown>;
+        delete(field: string): Promise<void>;
+    };
+    reservedEnvelopes(prefix: string): {
+        encrypt(collection: string, json: string, v: number): Promise<EncryptedEnvelope>;
+        decrypt(collection: string, env: EncryptedEnvelope): Promise<string>;
+    };
+}
+/** Per-call erase context — `forget()`'s per-ref participation door (phase C). */
+export interface ViaEraseCtx {
+    readonly id: string;
+    readonly vault: string;
+    readonly live: unknown;
+    readonly crypto: ViaCryptoCtx;
+}
+/**
+ * What an `erase` hook reports back to `forget()`'s summary ledger entry.
+ * `retainedShared` is additive (#629 Task 10) — content NOT erased because
+ * still referenced by another live record (blob's shared-chunk dual
+ * accounting, `shredAllForRecord()`'s `retainedShared` count). Absent/0 for
+ * bindings with no such concept (a sealed field is never "shared").
+ */
+export interface ViaEraseReport {
+    readonly shredded: number;
+    readonly residue: readonly unknown[];
+    readonly retainedShared?: number;
+}
+/**
+ * A feature bound to one collection's declared config. Record-grain hooks —
+ * every hook receives the whole record (matches the real engine signatures,
+ * e.g. quantizeMoneyFields(record, moneyFields)). All hooks optional;
+ * absent = passthrough. Query-participation hooks are SYNC (#553).
+ */
+export interface ViaBinding {
+    readonly brand: string;
+    readonly posture: ViaPosture;
+    /** Declared dependencies (field paths / cross-record specs). MANDATORY for any future
+     *  derive-bearing binding — phase C validates well-formedness (strings, non-empty,
+     *  reference declared fields) and graph-registers a derived edge for each covered
+     *  field at declare time, right after `compileViaBindings` builds the bindings
+     *  (unknown source field throws `ValidationError`). See
+     *  `kernel/collection-config.ts`'s `resolveViaBindingDepsEdges`. */
+    readonly deps?: readonly string[];
+    /** Collection-name prefixes this binding's `reservedEnvelopes` capability may address (e.g. `_dict_`). */
+    readonly reservedPrefixes?: readonly string[];
+    /**
+     * Does this binding own `field`? Backs `ViaPipeline.postureFor` (#629 Task
+     * 8's posture consumer) — a passive coverage check, independent of
+     * `buildClause`/`compareForOrder` (which some bindings, e.g. classified and
+     * blob, never define). SYNC, no side effects.
+     *
+     * Contract (documentation only — not enforced at runtime, future work):
+     * any binding declaring a non-default posture value — `queryable: 'none'`
+     * (#629 Task 8) or `exportable: false` (#629 Task 9's `redactForExport`)
+     * — MUST implement `covers()`. `postureFor`'s consumers only engage for
+     * fields a binding actively claims via `covers()`; a binding that omits
+     * it would silently fall through to the generic (unrefused/unredacted)
+     * path instead.
+     */
+    covers?(field: string): boolean;
+    /** Refuse a write before crypto runs (classified step-3 slot: storage:'never' rejection + validators). Throws to refuse. */
+    enforceWrite?(record: Record<string, unknown>, ctx: ViaWriteCtx): void | Promise<void>;
+    /** First pipeline stage (money canonicalizeIncomingMoney). SYNC. */
+    ingest?(record: Record<string, unknown>): Record<string, unknown>;
+    /** Decode STORED form to canonical for internal boundaries (gates, derivations, patch bases). SYNC. */
+    canonicalizeStored?(record: Record<string, unknown>): Record<string, unknown>;
+    /** Post-validation write encoding (money quantize; i18n translate→script→validate→densify). May be async. */
+    encodeWrite?(record: Record<string, unknown>, ctx: ViaWriteCtx): Awaitable<Record<string, unknown>>;
+    /** Final write-pipeline stage: seal/encrypt declared fields via `crypto` before the envelope body is built (classified step-2 slot). */
+    encodeAtRest?(record: Record<string, unknown>, crypto: ViaCryptoCtx): Promise<{
+        record: Record<string, unknown>;
+        sealed?: Record<string, SealedSlotRef>;
+    }>;
+    /** First read-pipeline stage: unseal/decrypt declared fields via `crypto` before `present` runs (classified sealed-handle slot). */
+    decodeAtRest?(record: Record<string, unknown>, sealed: Record<string, SealedSlotRef>, crypto: ViaCryptoCtx, opts: {
+        asHandles: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Read-time presentation (money decode+virtuals; i18n locale/labels/strip). May be async. */
+    present?(record: Record<string, unknown>, ctx: ViaReadCtx): Awaitable<Record<string, unknown>>;
+    /**
+     * Late read-time presentation (#669) — runs AFTER every binding's `present()` in the
+     * money+computed present-order segment (`ViaPipeline`'s `_presentOrder`, `kernel/via/
+     * pipeline.ts`), BEFORE the "everything else" segment (i18n/lookup dressing, taint
+     * redaction) runs. Exists for a binding that needs to react to a virtual computed
+     * field's fresh OWN-field output before anything dresses it (money's MAJOR-UNITS
+     * quantize-and-present for a field that is BOTH money AND `mode:'virtual'` computed) —
+     * `present()` alone can't express "run after computed for THESE fields only, before
+     * computed for all others", since it's a per-BINDING fold, not per-field. Folded over
+     * `bindings` in declaration order (mirrors every other per-binding fold), so lookup/
+     * i18n dressing and taint/redaction (both in the "everything else" segment) still see
+     * the already-dressed value.
+     */
+    presentLate?(record: Record<string, unknown>, ctx: ViaReadCtx): Awaitable<Record<string, unknown>>;
+    /** Returns an opaque clause payload when this binding covers `field`, else undefined. */
+    buildClause?(field: string, op: string, value: unknown): unknown | undefined;
+    /** Evaluate a payload produced by buildClause against a raw stored value. */
+    evaluateClause?(actual: unknown, op: string, payload: unknown): boolean;
+    /**
+     * Optional: the STORED-form operand for a direct secondary-index probe
+     * against a payload produced by `buildClause` (#625) — lets
+     * `candidateRecords()` (`query/builder.ts`) hit `CollectionIndexes.
+     * lookupEqual`/`lookupIn` for `==`/`in` clauses instead of falling back
+     * to a linear scan + per-record `evaluateClause`. Returning `undefined`
+     * means "no sound probe for this op/payload" (e.g. a comparison whose
+     * stored form isn't a single index-bucketable value, or an op the index
+     * can't serve) — the caller falls back to the scan. A binding that
+     * never implements this hook always falls back, unchanged from before
+     * this hook existed.
+     */
+    indexProbe?(op: string, payload: unknown): unknown | undefined;
+    /**
+     * Optional: canonicalize a raw STORED field value into the bucket key an
+     * eager index should use (#672) — lets `CollectionIndexes` group a
+     * pre-declaration / non-canonical stored value (e.g. a money field's
+     * leftover `'0100'` written before its `money()` declaration) under the
+     * SAME key a canonical write produces (`'100'`), so the index-probe fast
+     * path (`indexProbe` above) and the fallback scan (`evaluateClause`)
+     * agree on which records match. `undefined` means "not mine / can't
+     * canonicalize this value" — the caller buckets the raw stringified
+     * value, unchanged from before this hook existed. MUST agree with what
+     * this binding's own `evaluateClause`/`indexProbe` treat as equal, or
+     * the fast path and the scan will disagree.
+     */
+    canonicalizeIndexKey?(field: string, rawValue: unknown): string | undefined;
+    /** Decode a raw stored record for query/scan results and callback views ('raw' — no virtuals). */
+    decodeResults?(record: unknown): unknown;
+    /** Exact ordering for a covered field; undefined when the field is not covered. */
+    compareForOrder?(field: string, a: unknown, b: unknown): number | undefined;
+    /**
+     * Per-key, PER-CALL-locale label resolution for `orderBy(field, dir,
+     * { by: 'label' })` (#650 Task 7) — the sibling `compareForOrder` above
+     * structurally cannot serve, since it carries no locale parameter.
+     * `locale` is the query's per-call locale (`undefined` for a locale-less
+     * query — a binding may fall back to its own descriptor-level default,
+     * mirroring `present`'s displayLocale hinge). `undefined` return = this
+     * binding doesn't resolve a label for `key` at `field` — caller falls
+     * back to the raw stored value, same graceful-degrade discipline every
+     * other via query hook uses. SYNC (#553 — query participation).
+     */
+    resolveOrderLabel?(field: string, key: string, locale: string | undefined): string | undefined;
+    /** Rewrite an aggregate spec (money exact reducers). */
+    wrapReducers?(spec: unknown): unknown;
+    /** `forget()`'s per-ref erasure door — shred/report this binding's residue for one record (classified/blob forget participation). */
+    erase?(ctx: ViaEraseCtx): Promise<ViaEraseReport>;
+    describeFragment?(): Record<string, unknown>;
+}
+/** Binder: constructs a binding from a collection's declared config. Installed by the feature's declaration factory. */
+export type ViaBinder = (config: unknown) => ViaBinding;
+/** @internal — called (idempotently, first-wins) by a feature's declaration factory, e.g. money(). */
+export declare function installViaBinder(brand: string, binder: ViaBinder): void;
+/** @internal — registry presence check. Used by tests (mirrors isMoneyEngineInstalled) and by vault's i18n validator delegators as a no-i18n-ever-declared fast path. */
+export declare function isViaInstalled(brand: string): boolean;
+/** @internal — resolve a binder; throws when the declaration factory never ran (hand-rolled descriptors). */
+export declare function viaBinder(brand: string): ViaBinder;
+export {};

package/dist/kernel/via/pipeline.d.ts

@@ -0,0 +1,266 @@
+import type { ViaBinding, ViaPosture, ViaWriteCtx, ViaReadCtx, ViaCryptoCtx, SealedSlotRef, ViaEraseCtx, ViaEraseReport } from './index.js';
+/** Opaque per-clause query payload carried on FieldClause (replaces the money-only slot). */
+export interface ViaClause {
+    readonly brand: string;
+    readonly payload: unknown;
+}
+/**
+ * The graph-computed taint overlay (#638 Task 3) — `postureFor`'s
+ * assignment→enforcement bridge. `postures`/`sealFields` are the
+ * enforcement-facing shapes `via/taint-binding.ts#buildTaintOverlay`
+ * produces from `ViaGraph.taintedPostures`/`taintSealedFields`;
+ * `provenance` (optional — introspection only, never consulted by
+ * `postureFor`) is `ViaGraph.taintProvenance`'s output, surfaced by
+ * `describe()`.
+ */
+export interface ViaTaintOverlay {
+    readonly postures: ReadonlyMap<string, ViaPosture>;
+    readonly sealFields: ReadonlySet<string>;
+    readonly provenance?: ReadonlyMap<string, readonly string[]>;
+    /** #642 — the whole-record floor for a derivation/MV/overlay OUTPUT collection (the '*' target's
+     *  folded, clamped effective posture). postureFor falls back to it for ANY field; redactForExport
+     *  picks it up per-field; a sealed default drives taintBinding's sealAllFields mode. O(1) read. */
+    readonly defaultPosture?: ViaPosture;
+}
+export declare class ViaPipeline {
+    readonly bindings: readonly ViaBinding[];
+    readonly taint?: ViaTaintOverlay | undefined;
+    /**
+     * Present-phase-ONLY order (#665, corrected under #665 review) — a stable
+     * THREE-WAY partition of `bindings` computed once here at construction:
+     * every `'money'`-brand binding first (existing relative order), then
+     * every `'computed'`-brand binding (existing relative order), then
+     * everything else (existing relative order). `present()` folds over this
+     * instead of `bindings` so a `mode: 'virtual'` computed field's value
+     * exists before i18n/lookup's dressing `present()` hooks run on it
+     * (today's `compileViaBindings` order is money→i18n→lookup→classified→
+     * blob→computed, `collection-config.ts:554`, so dressing unconditionally
+     * ran BEFORE the value it dresses existed). This reorder is binding-level,
+     * not conditioned on any particular field composition — it applies to
+     * EVERY collection that compiles a `'computed'` binding at all, not only
+     * ones stacking a dresser on the SAME field as a computed one. EVERY other
+     * phase (`ingest`/`encodeWrite`/`encodeAtRest`/`enforceWrite`/etc.) keeps
+     * folding over `bindings` unchanged — those write/query phases need
+     * money-first (`_applyMoneyFields` PREPENDS money, `_applyClassifiedFields`
+     * APPENDS classified to preserve it, `kernel/collection.ts:1275-1284,1364-
+     * 1368`).
+     *
+     * Money is deliberately carved OUT of the generic "everything else" slice
+     * and kept FIRST — the original two-way `[computed..., rest...]` partition
+     * regressed money's composed-field behavior from a benign missing-dressing
+     * gap into VALUE CORRUPTION: money's `present()` DECODES its input as a
+     * STORED SCALED-INT (and derives `<field>Formatted` from it) — it is not a
+     * pure dressing CONSUMER like i18n/lookup, which only ADD a `<field>Label`
+     * key and never rewrite the field's own value. Running money AFTER
+     * computed on a field composing `computed(virtual)` + `money(...)` on
+     * ITSELF means money's decode sees the virtual field's raw MAJOR-unit
+     * output (e.g. `21`) and misreads it as a scaled-int, producing a
+     * corrupted value (`'0.21'`) instead of the pre-#665 result (the raw `21`
+     * surviving untouched, with no `Formatted` key added — a benign
+     * missing-dressing gap, not a wrong value). Money-first restores money's
+     * exact pre-#665 present position — byte-identical money behavior; the
+     * materialized composition pins from the #631 work and the money suites
+     * all ran under money-first. i18n/lookup are genuine dressing consumers
+     * (they only ADD, never rewrite), so they stay after computed, which is
+     * the fix #665 intended. A `'taint'` binding (appended LAST by
+     * `via/graph-wiring.ts#applyTaintOverlay`) stays last here too (it's
+     * neither money nor computed, so it lands at the tail of the "everything
+     * else" slice), preserving its "runs after computed, redacts tainted
+     * virtual output" contract (`via/taint-binding.ts`'s `taintBinding` doc
+     * comment).
+     *
+     * Money-dressing a virtual computed field's OWN output (the composed
+     * `computed(virtual) + money` case) is NOT resolved by this partition
+     * alone — #669 resolves it with a separate mid-fold hook instead:
+     * `ViaBinding.presentLate` runs after every binding's `present()` in this
+     * money+computed segment, before the "everything else" segment below, so
+     * money can quantize/reinterpret a virtual field's fresh MAJOR-UNITS
+     * output as if it were a stored value, without perturbing this ordering
+     * or the #665 invariant above it (`_presentLateBoundary` below marks
+     * exactly where that mid-fold point sits within `_presentOrder`).
+     */
+    private readonly _presentOrder;
+    /** #669 — index into `_presentOrder` where the money+computed segment ends and the
+     *  "everything else" segment begins (`moneyBindings.length + computedBindings.length`);
+     *  `present()` runs every binding's `presentLate` at exactly this boundary. */
+    private readonly _presentLateBoundary;
+    private constructor();
+    /** undefined when there is nothing to enforce — the zero-via fast path is
+     *  `this.via === undefined` (#553: keeps an all-plain collection sync). A
+     *  `'*'`-defaulted output collection (#642) counts as "something to enforce"
+     *  even with zero field-specific postures and zero bindings. */
+    static build(bindings: readonly ViaBinding[], taint?: ViaTaintOverlay): ViaPipeline | undefined;
+    /** Refuse a write before crypto runs: awaits each binding's `enforceWrite` in order — first throw wins. */
+    enforceWrite(record: Record<string, unknown>, ctx: ViaWriteCtx): Promise<void>;
+    ingest(record: Record<string, unknown>): Record<string, unknown>;
+    canonicalizeStored(record: Record<string, unknown>): Record<string, unknown>;
+    encodeWrite(record: Record<string, unknown>, ctx: ViaWriteCtx): Promise<Record<string, unknown>>;
+    /**
+     * Final write-pipeline stage: folds each binding's `encodeAtRest` in
+     * order, threading the record and accumulating the sealed-slot map. A
+     * field belongs to exactly one via feature — two bindings sealing the
+     * same field is a brand-keyed collision and throws.
+     */
+    encodeAtRest(record: Record<string, unknown>, crypto: ViaCryptoCtx): Promise<{
+        record: Record<string, unknown>;
+        sealed?: Record<string, SealedSlotRef>;
+    }>;
+    /** First read-pipeline stage: folds each binding's `decodeAtRest` in order. */
+    decodeAtRest(record: Record<string, unknown>, sealed: Record<string, SealedSlotRef>, crypto: ViaCryptoCtx, opts: {
+        asHandles: boolean;
+    }): Promise<Record<string, unknown>>;
+    present(record: Record<string, unknown>, ctx: ViaReadCtx): Promise<Record<string, unknown>>;
+    buildClause(field: string, op: string, value: unknown): ViaClause | undefined;
+    evaluateClause(clause: ViaClause, actual: unknown, op: string): boolean;
+    /**
+     * Resolve a `buildClause` payload to an index-probe operand (#625) —
+     * mirrors `evaluateClause`'s brand dispatch. `undefined` (a binding
+     * with no `indexProbe`, or one that declines to probe this op/payload)
+     * means the caller (`candidateRecords()`) must fall back to a scan.
+     */
+    indexProbe(clause: ViaClause, op: string): unknown | undefined;
+    /**
+     * Resolve a raw STORED field value to its canonical eager-index bucket
+     * key (#672) — folds every binding's `canonicalizeIndexKey`, first
+     * non-undefined wins (same fold discipline as `buildClause`). `undefined`
+     * means no binding claims `field` (or the value can't be canonicalized)
+     * — the caller buckets the raw stringified value, unchanged from before
+     * this hook existed.
+     */
+    canonicalizeIndexKey(field: string, rawValue: unknown): string | undefined;
+    decodeResults(record: unknown): unknown;
+    /** undefined = no binding covers the field → caller falls back to generic compare. */
+    compareForOrder(field: string, a: unknown, b: unknown): number | undefined;
+    /** undefined = no binding resolves an order-sort label for `key` at `field`/`locale` (#650 Task 7 —
+     *  the `orderBy(..., {by:'label'})` per-call-locale channel `compareForOrder` above can't serve). */
+    resolveOrderLabel(field: string, key: string, locale: string | undefined): string | undefined;
+    /**
+     * Which posture governs `field`, if any binding covers it — `undefined`
+     * means no binding declares `field` (the generic, non-via query path
+     * applies). #629 Task 8's posture consumer: `.where()`/`.orderBy()`
+     * consult this before building/evaluating a clause, refusing fields whose
+     * posture is `queryable: 'none'` (e.g. blob); every other posture
+     * ('det-exact'/'ordered'/'full') is left to the existing per-binding
+     * buildClause/evaluateClause/compareForOrder machinery, unchanged.
+     *
+     * #638 Task 3: the graph-computed taint overlay is consulted FIRST — a
+     * derived field's assigned (most-restrictive-of-sources) posture wins over
+     * whatever a binding would otherwise report for that field name (no
+     * binding covers a computed/derived field today, so this never actually
+     * shadows one — see `via/taint-binding.ts`'s `taintBinding.covers`, which
+     * only claims the sealed subset for `encodeAtRest`/`decodeAtRest`, not for
+     * this lookup).
+     */
+    postureFor(field: string): ViaPosture | undefined;
+    /**
+     * Refuse any field-based reducer over a `queryable: 'none'` field (blob) —
+     * metadata-only: walks each reducer's `.field` and checks posture, no
+     * rewriting. Reducers with no `.field` (e.g. `count()`) are skipped.
+     *
+     * Shared by `wrapReducers` below (which ALSO applies each binding's
+     * rewrite, e.g. money's exact-BigInt reducer swap) and by
+     * `ScanBuilder.aggregate()` (#629 Task 8 review fix wave 1), which must
+     * call THIS, not `wrapReducers` — wiring full `wrapReducers` into
+     * `ScanBuilder.aggregate()` would newly activate money/i18n reducer
+     * wrapping on a path that has never run it, a parity-breaking behavior
+     * change for existing brands.
+     */
+    refuseUnqueryableReducers<S>(spec: S): void;
+    /**
+     * Rewrite an aggregate spec (money exact reducers), then refuse any
+     * field-based reducer over a `queryable: 'none'` field (blob) — the same
+     * posture gate `.where()`/`.orderBy()` apply, extended to `.aggregate()`
+     * (both the bare-spec and builder forms funnel through here).
+     */
+    wrapReducers<S>(spec: S): S;
+    /**
+     * Deliberate export-layer redaction (#629 Task 9's posture consumer):
+     * for every OWN field the decoded record carries, if the covering
+     * binding's posture declares `exportable: false` (classified today;
+     * money/i18n/blob are all `true`), replace the value with
+     * {@link EXPORT_REDACTION_MARKER} — the same `'[sealed]'` string
+     * `SealedHandle.toJSON()` (`kernel/types.ts`) already emits, so this is
+     * byte-parity with today's accidental redaction, now independent of the
+     * field's runtime shape. `SealedHandle.toJSON()` stays untouched as
+     * defense-in-depth: a record read via `collection.get()` and
+     * JSON.stringify'd outside `exportStream()` still gets the accident's
+     * redaction on its own. Never mutates the input; returns a new object
+     * only when a field was actually redacted.
+     */
+    redactForExport(record: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Shared fold over a subset of `this.bindings`: runs each binding's
+     * `erase`, concatenating shredded/retainedShared counts and residue.
+     * Consults `posture.forgettable` (#629 Task 10) — a binding declaring
+     * `forgettable: false` is skipped even if it defines `erase` (none does
+     * today; a future non-forgettable binding is supported without a brand check).
+     */
+    private foldErase;
+    /** `forget()`'s per-ref erasure door: folds every binding's `erase`. */
+    erase(ctx: ViaEraseCtx): Promise<ViaEraseReport>;
+    /**
+     * `forget()`'s SEALED-posture-only erase fold (#629 Task 10, `Collection._onViaErase`'s
+     * one caller) — classified today; metadata-filtered on
+     * `posture.encryptedAtRest`, not brand-checked. `undefined` when no
+     * sealed-posture binding is compiled in — `vault.ts` then falls back to
+     * its own bare-`sensitive` classification, which no via binding covers.
+     */
+    eraseSealed(ctx: ViaEraseCtx): Promise<ViaEraseReport | undefined>;
+    /** True iff any binding implements decodeResults (query fast-path gating). */
+    get hasResultDecode(): boolean;
+    /**
+     * True iff any binding declares an at-rest hook (`encodeAtRest`/
+     * `decodeAtRest`) — the codec boundary's async-stack gate (#629 Task 3
+     * consults this to choose between the hook path and today's inline
+     * sealed-slot path; a stack with only sync hooks, e.g. money-only, stays
+     * `false`).
+     */
+    get hasAtRestHooks(): boolean;
+    /**
+     * Fold every binding's `describeFragment()` into one `brand -> fragment`
+     * map (#650 Task 7 — the first-ever consumer; `describeFragment` was
+     * declared at `via/index.ts:136` since #623 with zero callers until this task).
+     * `undefined` when no compiled binding implements it. Consumed by
+     * `Collection.describe()`/`describeAsync()`, threaded to `buildDescription`
+     * as `BuildDescriptionInput.viaFragments`.
+     */
+    describeFragments(): Record<string, Record<string, unknown>> | undefined;
+}
+/**
+ * The marker `redactForExport` writes for a non-exportable field —
+ * intentionally the same literal `SealedHandle.toJSON()` (`kernel/types.ts`)
+ * returns, so the two independent redaction layers (deliberate + accident)
+ * produce byte-identical export output. Duplicated, not imported, because
+ * `SealedHandle.toJSON()` is untouched by #629 Task 9 (belt-and-braces —
+ * `via/export-posture-b.test.ts` asserts both layers agree on this string).
+ */
+export declare const EXPORT_REDACTION_MARKER = "[sealed]";
+/**
+ * Structural shape `exportRedact` needs from a collection: just the typed
+ * `_via` accessor `Collection` exposes (`kernel/collection.ts`, #634). A
+ * named interface rather than the real `Collection` type, because
+ * `collection.ts` imports `ViaPipeline` from this module — importing
+ * `Collection` back here would be circular.
+ */
+interface HasViaPipeline {
+    readonly _via: ViaPipeline | undefined;
+}
+/**
+ * Widened sibling of {@link HasViaPipeline}: `via/graph-wiring.ts`'s
+ * `applyTaintOverlay` (#666) needs to REASSIGN the live pipeline, not just
+ * read it — `_setVia` is `Collection`'s typed writer seam (`kernel/
+ * collection.ts`, beside `_via`), replacing the earlier untyped `coll as {
+ * via; codec: { setVia } }` cast. Exported (unlike `HasViaPipeline`) because
+ * its one consumer lives in a different module.
+ */
+export interface HasWritableViaPipeline extends HasViaPipeline {
+    _setVia(pipeline: ViaPipeline | undefined): void;
+}
+/**
+ * `vault.ts`'s `exportStream()` reach-in (#629 Task 9): apply the owning
+ * collection's export redaction to one decoded record. Typed via {@link
+ * HasViaPipeline} against `Collection`'s `_via` accessor (#634) — replaces
+ * the earlier untyped any-cast reach-in.
+ */
+export declare function exportRedact(coll: HasViaPipeline, record: unknown): unknown;
+export {};

package/dist/kernel/via/reconcile.d.ts

@@ -0,0 +1,153 @@
+/**
+ * kernel/via/reconcile.ts — #664 the late-attach reconcile-path dispatch.
+ *
+ * `vault.ts`'s reconcile branch (a SECOND-OR-LATER `vault.collection(name, {...})` call on an
+ * already-open collection) used to be a flat 5-branch `if (coll && X) coll._applyX(...)` ladder
+ * with no collision guard and no i18n/dictKey machinery at all (i18nFields/dictKeyFields were
+ * silently ignored on re-open — only the fresh-construction branch ever wired them). This module
+ * moves that whole ladder OUT of `vault.ts` (a kernel-surface-ceiling-guarded file) into ONE
+ * dispatch entry point, {@link reconcileViaAttach}, that:
+ *
+ *  1. runs the late-attach collision guard ({@link guardReconcileCollisions}, via/compose.ts)
+ *     BEFORE any mutation — both the incoming×incoming and existing×incoming recipes;
+ *  2. routes the FIVE pre-existing reconciles (money/computed/fieldMeta/meta/classified) through
+ *     their unchanged `Collection._applyX` methods (collection.ts is NOT touched — this dispatch
+ *     only orchestrates, matching the pre-#664 call order exactly);
+ *  3. commits the two-phase graph-edge reconcile (`via/graph-wiring.ts`) + taint overlay, exactly
+ *     as before;
+ *  4. wires i18n/dictKey late-attach via {@link reconcileI18nFields}/{@link reconcileDictKeyFields}
+ *     — rebuilding the pipeline through {@link Collection._setVia} (#666's writer seam), mirroring
+ *     the fresh-construction wiring (`collection-config.ts#compileViaBindings`'s i18n slot +
+ *     `vault.ts`'s registry population) without duplicating it in a second place;
+ *  5. (#664 Part 2b) wires lookup()/enumOf()/dict() late-attach via {@link reconcileLookupFields}
+ *     — tier-scoped: enum/static tiers are a clean, self-contained attach; the reserved (dict)
+ *     tier additionally updates the SAME vault registries the fresh path populates
+ *     (`dictKeyFieldRegistry`/`reservedLookupCollections`/`staticDescriptorByField`/`staticByName`/
+ *     `staticDictNames`, via `collectLookupDictCompat`); the matrix (`backing:'collection'`) tier
+ *     is gated by {@link refuseUnattachableMatrixLookupFields} — refuses with a `ValidationError`
+ *     unless the backing collection is already open (this vault session) and prefetch-enabled.
+ *
+ * `ViaReconcileVaultCtx` takes the vault-resident registry Maps/closures the i18n/dictKey wiring
+ * needs as a plain structural bag of ARGUMENTS (mirroring `via/lookup/registry.ts`'s own
+ * "#650 Task 1" extraction pattern) — never a `Vault` import (this file is part of the kernel
+ * spine's `port/with/`-only import discipline — S5 port-layering, `scripts/check-architecture.mjs`
+ * `checkPortLayering`), so `vault.ts` passes `this` once its relevant fields are readable from
+ * outside the class (see `Vault`'s field declarations).
+ */
+import type { Collection } from '../collection.js';
+import { type HasWritableViaPipeline } from './pipeline.js';
+import { type MergedViaFields } from './compose.js';
+import type { ViaGraph } from './graph.js';
+import { type I18nStrategy, type I18nTextDescriptor, type DictKeyDescriptor, type StaticDictDescriptor, type DictionaryHandle } from '../../port/with/i18n-strategy.js';
+import { type LookupDescriptor } from '../../port/with/lookup-strategy.js';
+type AnyCollection = Collection<Record<string, unknown>>;
+/**
+ * Structural reconcile-capable collection handle: `_via`/`_setVia` (#666's writer seam) plus the
+ * five pre-existing `_applyX` late-attach methods (#623/#629/#638). Every parameter type is
+ * DERIVED off `Collection` itself via `Parameters<...>` rather than imported by name — several
+ * (`FieldMeta`, `CollectionMeta`, `ComputedFields`) are with-* service types the kernel spine may
+ * not statically import (S5 port-layering); deriving them off the already-typed `Collection`
+ * method avoids a second, duplicate type declaration too (mirrors `via/graph-wiring.ts`'s
+ * `ComputedFieldsParam` trick).
+ */
+export interface ReconcilableCollection extends HasWritableViaPipeline {
+    _applyMoneyFields(moneyFields: Parameters<AnyCollection['_applyMoneyFields']>[0]): void;
+    _applyComputed(computed: Parameters<AnyCollection['_applyComputed']>[0]): void;
+    _applyFieldMeta(fieldMeta: Parameters<AnyCollection['_applyFieldMeta']>[0]): void;
+    _applyMeta(meta: Parameters<AnyCollection['_applyMeta']>[0]): void;
+    _applyClassifiedFields(classifiedFields: Parameters<AnyCollection['_applyClassifiedFields']>[0]): void;
+    /** #671 items 1-3 — the reader + writer seam for `getDictionary`/legacy describe() lists/`presentForJoin`. */
+    readonly _viaFieldsSnapshot: AnyCollection['_viaFieldsSnapshot'];
+    _reconcileReadState(patch: Parameters<AnyCollection['_reconcileReadState']>[0]): void;
+}
+/** The vault-resident state/closures the i18n/dictKey late-attach wiring reads and writes —
+ *  the SAME registries `vault.ts`'s fresh-construction branch populates (`i18nFieldRegistry`
+ *  :884-886, the dictKeyFields split :903-940, `dictLabelResolver`/`i18nPutValidator`/
+ *  `autoTranslateHook` :1111-1155), passed as plain values (never `this: Vault`) so this module
+ *  never imports the `Vault` class. */
+export interface ViaReconcileVaultCtx {
+    readonly i18nStrategy: I18nStrategy;
+    /** — named `locale`, not `defaultLocale`, to match `Vault`'s own field name 1:1 (so `this`
+     *  satisfies this interface structurally with zero adapter object at the call site). */
+    readonly locale: string | undefined;
+    readonly translateText: ((text: string, from: string, to: string, field: string, collection: string) => Promise<string>) | undefined;
+    readonly i18nFieldRegistry: Map<string, Record<string, I18nTextDescriptor>>;
+    readonly dictKeyFieldRegistry: Map<string, Record<string, string>>;
+    readonly staticDescriptorByField: Map<string, Record<string, StaticDictDescriptor>>;
+    readonly reservedLookupCollections: Map<string, string>;
+    readonly staticByName: Map<string, StaticDictDescriptor>;
+    readonly staticDictNames: Set<string>;
+    dictionary(name: string): DictionaryHandle;
+    enforceI18nOnPut(collectionName: string, record: unknown): void;
+    enforceStaticDictOnPut(collectionName: string, record: unknown): void;
+    /** #664 Part 2b — the matrix-tier lookup late-attach gate: "is this dimension already open in
+     *  this vault session" (never constructs a fresh collection) — `Vault._getCollection`. */
+    getOpenCollection(name: string): AnyCollection | undefined;
+    /** #664 Part 2b — the vault's CONSTRUCTING collection accessor the lookup binding's lazy
+     *  closures (`getLookupBacking`/`membership`/`getAltIndex`/`snapshotFor`) read through — mirrors
+     *  `vault.ts`'s fresh-construct `(n) => this.collection<Record<string, unknown>>(n)` closure
+     *  verbatim. Only ever invoked, for a matrix-tier dimension, once {@link getOpenCollection}'s
+     *  gate has already confirmed it is open — never the door that opens it. */
+    getCollection(name: string): AnyCollection;
+}
+/**
+ * #664 Part 2 — late-attach i18nText fields. First-wins (mirrors `_applyMoneyFields`'s own
+ * first-wins convention): a no-op once the collection already has an 'i18n' binding, whether
+ * that binding came from fresh construction or an earlier reconcile call. `dictKeyFields` is an
+ * optional SECOND family arriving in the SAME `vault.collection()` call (`mergeViaFields` already
+ * combined them for this one call) — passed through so ONE binding rebuild covers both, exactly
+ * like `compileViaBindings` builds ONE 'i18n' binding from both maps at fresh construction.
+ */
+export declare function reconcileI18nFields(coll: ReconcilableCollection, vaultCtx: ViaReconcileVaultCtx, name: string, i18nFields: Record<string, I18nTextDescriptor> | undefined, dictKeyFields?: Record<string, DictKeyDescriptor | StaticDictDescriptor>): void;
+/**
+ * #664 Part 2 — late-attach dictKeyFields (dictKey()/staticDict()) with NO i18nFields in the same
+ * call — the dictKey-only late-attach door. First-wins, same convention as
+ * {@link reconcileI18nFields} (and, transitively, a no-op if that sibling function already
+ * handled a combined i18nFields+dictKeyFields call for this collection).
+ */
+export declare function reconcileDictKeyFields(coll: ReconcilableCollection, vaultCtx: ViaReconcileVaultCtx, name: string, dictKeyFields: Record<string, DictKeyDescriptor | StaticDictDescriptor> | undefined): void;
+/**
+ * #664 Part 2b — late-attach lookup()/enumOf()/dict() fields, tier-scoped (issue #664, spec-
+ * ratified tier policy):
+ *
+ *  - **enum** (`backing:'static'`, no `table`) / **static** (`+table`) — self-contained:
+ *    membership/labels come from the declared `keys`/`table` alone, no vault registry touch, no
+ *    cross-collection read. Clean attach, same shape as i18n/dictKey's own reconcile door.
+ *  - **reserved** (`dict()` / `lookup(dim, { backing:'reserved' })`) — additionally registers into
+ *    the SAME vault registries the fresh path populates (`vault.ts`'s dictKeyFields/lookupFields
+ *    registry-population loop) — `dictKeyFieldRegistry`/`reservedLookupCollections` for a bare
+ *    dict field; `staticDescriptorByField`/`staticByName`/`staticDictNames` for a table-bearing
+ *    static field — via `collectLookupDictCompat` (#650 Task 2's alias-equivalence bridge, the
+ *    SAME helper the fresh path already calls), reused verbatim, not duplicated.
+ *  - **matrix** (`backing:'collection'`) — gated by {@link refuseUnattachableMatrixLookupFields}.
+ *
+ * First-wins (mirrors {@link reconcileI18nFields}): a no-op once the collection already has a
+ * 'lookup' binding, whether from fresh construction or an earlier reconcile call.
+ *
+ * Post-attach, registers the SAME cross-collection `'ref'` graph edges the fresh path does
+ * (`registerLookupRefEdges` — internally skips the static tier, which has no backing collection to
+ * reference-check) — `ViaGraph.referencingEdgesOf` sees them immediately, so delete-time
+ * restrict/cascade/nullify semantics are live post-attach too, same as a fresh declaration.
+ */
+export declare function reconcileLookupFields(coll: ReconcilableCollection, vaultCtx: ViaReconcileVaultCtx, graph: ViaGraph, name: string, lookupFields: Record<string, LookupDescriptor> | undefined): void;
+/** The late-attach reconcile call's field-declaring options — the slice of `vault.collection()`'s
+ *  `options` a reconcile call may carry, plus the `mergeViaFields` output that feeds both the
+ *  guard and the money/i18n/dictKey/lookup reconciles. `blobFields` has no `_apply*` door (guard
+ *  visibility only — an incoming×incoming collision with `blobFields` must still refuse, even
+ *  though a bare blobFields late-attach is otherwise silently inert, matching pre-#664 behavior). */
+export interface ReconcileLateAttachPlan {
+    readonly effectiveViaFields: MergedViaFields;
+    readonly computed?: Parameters<AnyCollection['_applyComputed']>[0];
+    readonly fieldMeta?: Parameters<AnyCollection['_applyFieldMeta']>[0];
+    readonly meta?: Parameters<AnyCollection['_applyMeta']>[0];
+    readonly classifiedFields?: Parameters<AnyCollection['_applyClassifiedFields']>[0];
+    readonly blobFields?: Record<string, unknown>;
+}
+/**
+ * #664 — the ONE late-attach reconcile dispatch `vault.ts` calls, replacing its former 5-branch
+ * `_apply*` ladder. Order: guard (before any mutation) → the matrix-tier lookup gate (also before
+ * any mutation — see below) → the five pre-existing reconciles, UNCHANGED call order/semantics →
+ * graph-edge commit + taint overlay (unchanged) → i18n/dictKey → lookup (#664 Part 2b).
+ */
+export declare function reconcileViaAttach(coll: ReconcilableCollection, graph: ViaGraph, name: string, vaultCtx: ViaReconcileVaultCtx, plan: ReconcileLateAttachPlan): void;
+export {};