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

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

@@ -0,0 +1,144 @@
+import type { ViaDescriptor } from './index.js';
+import type { ViaPipeline } from './pipeline.js';
+import type { DictKeyDescriptor, I18nTextDescriptor, StaticDictDescriptor } from '../../port/with/i18n-strategy.js';
+import type { ComputedDescriptor } from '../../port/with/computed-strategy.js';
+import type { LookupDescriptor } from '../../port/with/lookup-strategy.js';
+/** Tagged container returned by {@link via}. Readonly — never mutated after construction. */
+export interface ViaFieldSpec {
+    readonly _noydbVia: true;
+    readonly descriptors: readonly ViaDescriptor[];
+}
+/**
+ * Compose one or more Via feature descriptors for a single field.
+ *
+ * @example
+ * ```ts
+ * vault.collection('invoices', {
+ *   viaFields: { total: via(money({ currency: 'EUR' })) },
+ * })
+ * ```
+ */
+export declare function via(...descriptors: ViaDescriptor[]): ViaFieldSpec;
+/** Runtime predicate for detecting a {@link ViaFieldSpec}. */
+export declare function isViaFieldSpec(x: unknown): x is ViaFieldSpec;
+/** The money/i18n/lookup sugar keys + a `viaFields` map — the inputs {@link mergeViaFields} reconciles. */
+export interface ViaFieldSources {
+    readonly moneyFields?: Record<string, ViaDescriptor> | undefined;
+    readonly i18nFields?: Record<string, I18nTextDescriptor> | undefined;
+    readonly dictKeyFields?: Record<string, DictKeyDescriptor | StaticDictDescriptor> | undefined;
+    /** — lookup()/enumOf()/dict() sugar key (#650 Task 2). */
+    readonly lookupFields?: Record<string, LookupDescriptor> | undefined;
+    readonly viaFields?: Record<string, ViaFieldSpec> | undefined;
+}
+/** The effective per-feature field maps after merging sugar keys with `viaFields`. */
+export interface MergedViaFields {
+    readonly moneyFields: Record<string, ViaDescriptor> | undefined;
+    readonly i18nFields: Record<string, I18nTextDescriptor> | undefined;
+    readonly dictKeyFields: Record<string, DictKeyDescriptor | StaticDictDescriptor> | undefined;
+    /** `via(computed(fn, { deps, mode }))` entries (#638 Task 7) — there is no `computed`
+     *  sugar KEY to merge against here (unlike money/i18n/dictKey); `collection-config.ts`
+     *  unions this with the `computed:` option's own entries before splitting by mode. */
+    readonly computedFields: Record<string, ComputedDescriptor> | undefined;
+    /** `lookupFields` sugar key merged with `via(lookup(...))`/`via(enumOf(...))`/`via(dict(...))`
+     *  entries (#650 Task 2) — a SEPARATE binding from i18n; `dictKey()`/`staticDict()` stay
+     *  routed onto `dictKeyFields`/the i18n binding (the alias, unchanged). */
+    readonly lookupFields: Record<string, LookupDescriptor> | undefined;
+}
+/**
+ * Merge `viaFields` (the {@link via} composer) with the money/i18n sugar
+ * keys into the effective maps every consumer reads — the kernel's
+ * `compileViaBindings` (the `ViaPipeline` bindings) and `vault.ts`'s own
+ * i18n/dict registries (put-time validation, dict-join/search resolution)
+ * both call this so a field declared via `viaFields` behaves identically to
+ * one declared under its feature's sugar key.
+ *
+ * Each `viaFields` entry's descriptors are grouped by `_viaBrand`; an
+ * `'i18n'`-branded descriptor further splits by shape (i18nText vs
+ * dictKey/staticDict) via the existing descriptor-shape predicates. A field
+ * name declared in BOTH a sugar key and `viaFields` throws `ValidationError`
+ * — one declaration site per field (#623 Task 9).
+ */
+export declare function mergeViaFields(sources: ViaFieldSources): MergedViaFields;
+/**
+ * #631 — declare-time cross-binding same-field collision guard. Today the same field named
+ * in two DIFFERENT via-binding families (e.g. the same field in both `moneyFields` and
+ * `blobFields`) resolves silently by compile-order first-wins in `ViaPipeline`'s per-field
+ * posture/clause lookup — undefined pipeline behavior for a config that is almost certainly a
+ * mistake. `mergeViaFields` already guards sugar-vs-`viaFields` and `dictKeyFields`-vs-
+ * `lookupFields` collisions (#623 Task 9); this runs one step later, in `compileViaBindings`
+ * (fresh construction) or {@link guardReconcileCollisions} (late-attach reconcile), because
+ * those are the only seams that also see `classifiedFields`/`blobFields` — neither is part of
+ * `ViaFieldSources`, so `mergeViaFields` never sees them.
+ *
+ * WHY FAMILY-BASED, NOT PROVENANCE-BASED (#631 review, round 2 — Controller ruling): a field
+ * declared via `via(computed(fn), money(...))` and a field declared via two independent sugar
+ * maps (`computed: { total: fn }` + `moneyFields: { total: money(...) }`) are NOT
+ * distinguishable here — `mergeViaFields` folds both declaration STYLES into the IDENTICAL
+ * merged per-family field maps this function receives; provenance (which style produced a given
+ * map entry) is erased before this guard ever runs. Narrowing the exemption to "only
+ * via()-composed fields" would therefore require threading a second, parallel
+ * provenance-tracking data structure through `mergeViaFields` for the sole purpose of refusing a
+ * config that is BEHAVIORALLY IDENTICAL to the sanctioned one — refusing it would be a
+ * behavior-lock violation (breaking a legal, meaningful config), not a bug fix. The exemption is
+ * therefore keyed on the FAMILY SET alone, and instead earned empirically per family (below).
+ *
+ * EXEMPT (test-earned, not merely asserted): `computed` colliding with EXACTLY ONE of
+ * `money`/`i18n`/`lookup` on the same field. `via()`'s descriptor loop only accepts
+ * money/i18n/computed/lookup `_viaBrand`s (`mergeViaFields` throws on any other brand), so a
+ * computed+classified or computed+blob same-field pairing can never arise from composition — it
+ * can only come from mistakenly naming the same field in `computed`/`viaFields` AND
+ * `classifiedFields`/`blobFields`, which this guard still refuses. For the three families that
+ * CAN legitimately arise, each is pinned by an end-to-end runtime test proving the composition
+ * does something real (not just "doesn't throw") — see `computed/virtual.test.ts`:
+ *   - money: the "composed grammar" tests (materialized-mode money formatting the computed
+ *     output; the ORIGINAL evidence this exemption started from — see the money DOES/does NOT
+ *     format the computed output pair).
+ *   - i18n (dictKey) / lookup (dict()): the "composed grammar — computed + i18n/lookup
+ *     families (#631 collision-guard exemption pins)" block, BOTH declaration styles
+ *     (`via(computed(...), dictKey(...)/dict(...))` and the two-independent-sugar-maps form),
+ *     materialized mode — proven to dress `<field>Label` off the computed output identically
+ *     either way (the provenance-erasure claim above, empirically confirmed). Virtual mode for
+ *     both families hits the SAME present-ORDER limitation money's own virtual composed-grammar
+ *     test already documents (i18n/lookup's `present()` runs BEFORE computed's — a virtual field
+ *     is never stored, so there is nothing to dress yet); pinned as a known limitation, not
+ *     grounds to drop the family from the exemption (materialized mode is what proves the family
+ *     genuinely composes).
+ *
+ * 3-CLAIMANT TIGHTENING (#631 review, round 2): the exemption requires EXACTLY TWO claimant
+ * source-keys, not just two families. A field named in `computed` + BOTH `i18nFields` AND
+ * `dictKeyFields` collapses to the same two families (`{computed, i18n}` — `dictKeyFields`
+ * shares the `i18n` family) but is a genuine THREE-claimant collision: two independent i18n
+ * sugar keys both claiming the field is itself a mistake this guard exists to catch, and must
+ * not slip through because the family SET happens to match the earned exemption's shape.
+ */
+export declare function guardCrossBindingFieldCollisions(fieldMaps: Readonly<Record<string, Record<string, unknown> | undefined>>, callerPrefix?: string): void;
+/**
+ * #664 Part 1 — the late-attach reconcile-path sibling of {@link guardCrossBindingFieldCollisions}.
+ * `vault.ts`'s reconcile ladder (a second-or-later `vault.collection(name, {...})` call on an
+ * ALREADY-open collection) never ran the fresh-construction guard above, so two probe recipes
+ * slipped through (round-2 fable review, 2026-07-13):
+ *
+ *  - **(a) incoming×incoming** — the SAME reconcile call names a field in two different
+ *    families (e.g. `moneyFields`+`blobFields` both claiming `"amount"`). Fix: re-run
+ *    {@link guardCrossBindingFieldCollisions} verbatim over THIS call's own merged field maps —
+ *    identical semantics to fresh construction, just invoked one call later.
+ *  - **(b) existing×incoming** — an EARLIER call already compiled a binding covering a field
+ *    (money reconciled onto it, or it shipped with the collection's first declaration), and
+ *    THIS call's incoming family map claims the SAME field for a DIFFERENT family (e.g. call-1
+ *    `classifiedFields:['ssn']`, call-2 `moneyFields:{ssn}`) — undetectable by (a) alone since
+ *    the collision spans two calls. Read via the LIVE collection's compiled bindings
+ *    (`coll._via.bindings`): each `ViaBinding.covers(field)` (`via/index.ts`) plus its `brand` tells us
+ *    which family already owns the field, mapped through the SAME {@link VIA_FIELD_MAP_FAMILY}
+ *    the incoming side uses — no new collection.ts surface needed.
+ *
+ * Both sub-checks honor the SAME #631 exemption (`{computed,money}`/`{computed,i18n}`/
+ * `{computed,lookup}`, exactly-two-claimants) as the fresh guard — a composition that would be
+ * legal in one `vault.collection()` call (`via(computed(fn), money(...))`) must stay legal when
+ * split across two calls (computed declared fresh, money late-attached), since the two paths are
+ * behaviorally equivalent by the same provenance-erasure argument {@link guardCrossBindingFieldCollisions}
+ * documents. `existingFamilies` is collected as a SET (every binding covering the field, not just
+ * the first match) so an already-legally-composed pair (e.g. existing `{computed, money}`) is
+ * checked against the incoming family individually — a THIRD family colliding with either half
+ * is still refused.
+ */
+export declare function guardReconcileCollisions(existingVia: ViaPipeline | undefined, incomingFieldMaps: Readonly<Record<string, Record<string, unknown> | undefined>>): void;

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

@@ -0,0 +1,185 @@
+import type { ViaGraph } from './graph.js';
+import type { Collection } from '../collection.js';
+import type { EncryptedEnvelope } from '../types.js';
+/** One deleted child's resolved rollup PARENT intent (#640) — ids + a field name only. A
+ *  resolved `parentId` is an id, same class as any touched record id — never a stored value. */
+export interface RollupDeleteIntent {
+    readonly into: string;
+    readonly parentId: string;
+    readonly field: string;
+}
+/** One collection's batched touches this session (#640 widens the #638 `Set<string>` shape):
+ *  `puts` — the original semantics, unchanged; `deletes` — a deleted record's id mapped to its
+ *  resolved rollup-parent intents, captured PRE-invalidation by `Collection._onRecordMutated`'s
+ *  sync-apply delete case (the FK is only readable there — see `kernel/collection.ts
+ *  #_rollupDeleteIntents`). */
+export interface GraphTouch {
+    readonly puts: Set<string>;
+    readonly deletes: Map<string, readonly RollupDeleteIntent[]>;
+}
+/** Per-session touched set — collection → its `GraphTouch`. Metadata only — ids (collection
+ *  names, record ids INCLUDING resolved rollup parent ids) and field names; NEVER record payload
+ *  or key material. A resolved parentId is an id, same class as the touched ids — not a stored
+ *  value. */
+export type GraphBatch = Map<string, GraphTouch>;
+/** Get-or-create `batch`'s `GraphTouch` entry for `collection` (#640) — shared by
+ *  `Vault._collectGraphTouch`/`_collectGraphDelete` so each stays a one-line call. */
+export declare function touchFor(batch: GraphBatch, collection: string): GraphTouch;
+/** #640 — sync, I/O-free: `deleted`'s resolved rollup PARENT intents (the FK is only readable
+ *  NOW, before the record is gone) — a pure function so `Collection._rollupDeleteIntents` stays
+ *  a one-line delegator under the kernel-surface ceiling. `registry` is `this.derivationSource
+ *  ?.registry()`; `collectionName` is `this.name` (the CHILD/`rollup.from` side). Generic over
+ *  the registry's own spec shape so this file never imports a `with-formula` type (port-layering
+ *  — via/dispatch.ts must not gain a with-* import). */
+export declare function resolveRollupDeleteIntents<S extends {
+    source: string;
+    rollup?: {
+        from: string;
+        key: string;
+        field: string;
+    };
+}>(registry: {
+    strategiesForSource(name: string): ReadonlyArray<{
+        spec: S;
+    }>;
+} | undefined, collectionName: string, deleted: Record<string, unknown>): RollupDeleteIntent[];
+/** #640 — resolve a `RollupDeleteIntent` back to its registry `spec`. The wave's per-intent
+ *  driver needs `spec.rollup.compute`, which `GraphBatch`'s metadata-only pin forbids batching —
+ *  so it's re-resolved here, post-boundary, instead of carried across it. `undefined` if the
+ *  intent's originating strategy was unregistered between collect time and wave time (residual
+ *  gap, freshness-only). */
+export declare function findRollupSpecForIntent<S extends {
+    source: string;
+    rollup?: {
+        from: string;
+        field: string;
+    };
+}>(registry: {
+    strategiesForSource(name: string): ReadonlyArray<{
+        spec: S;
+    }>;
+} | undefined, collectionName: string, intent: RollupDeleteIntent): S | undefined;
+/** One dedup ledger for a single wave — a target is recomputed at most once (mark-on-check). */
+export declare class WaveContext {
+    private readonly _seen;
+    seen(targetKey: string): boolean;
+}
+/** The slice of `Vault` the wave needs: the shared graph (the #553 zero-cost skip) and cached-
+ *  collection lookup — never constructs, since a touched collection is, by construction,
+ *  already open (it just fired `_onRecordMutated`). */
+export interface VaultLike {
+    readonly graph: ViaGraph;
+    _getCollection(name: string): Collection<Record<string, unknown>> | undefined;
+    /** #640 (#644 item 3) — structured wave-error surfacing, additive to the existing console.warn. */
+    _emit(event: string, payload: unknown): void;
+}
+/**
+ * Run ONE dispatch wave for a completed batch: for each touched (collection, id), decrypt the
+ * applied envelope (id threaded), then run the SAME `dispatchDerivations` +
+ * `dispatchMaterializedViews` the local-write path uses — with a shared `WaveContext` so N
+ * touched records feeding the SAME target recompute once. #553: a collection with no graph
+ * out-edges (e.g. money-only) is skipped before any decrypt/dispatch async work.
+ */
+export declare function runGraphDispatchWave(vault: VaultLike, batch: GraphBatch): Promise<void>;
+/** A record's post-freeze source mutation, for the `'derivation:skipped-frozen'` event
+ *  and the optional audit-trail entry. See {@link putDerivedOutput}. */
+export interface DerivationSkippedFrozen {
+    readonly source: {
+        readonly collection: string;
+        readonly id: string;
+    };
+    readonly target: {
+        readonly collection: string;
+        readonly id: string;
+    };
+    readonly period: string;
+    readonly endDate: string;
+}
+/** The minimal put-capable shape `putDerivedOutput` needs. Any `Collection<T>` structurally
+ *  satisfies this — its real `options` type is a superset of what's declared here. */
+export interface CollectionLike {
+    put(id: string, value: unknown, options?: {
+        readonly source?: string;
+    }): Promise<void>;
+}
+export interface PutDerivedOutputCtx {
+    readonly emit: (ev: string, p: unknown) => void;
+    readonly source: {
+        readonly collection: string;
+        readonly id: string;
+    };
+    readonly audit?: ((e: DerivationSkippedFrozen) => Promise<void>) | undefined;
+}
+/**
+ * Attempt a dispatch-driven output write. On `PeriodClosedError` (the closed-period
+ * `beforePut` gate — `freezePeriod`/`archivePeriod` add no separate gate, per seam map
+ * Part 7): SKIP (no `_ts` stamped — the gate throws before any write happens), emit
+ * `'derivation:skipped-frozen'` on the event bus (ALWAYS), and append an audit-trail entry
+ * when the with-history ledger is active. Returns `'written' | 'skipped-frozen'`. Any OTHER
+ * error propagates unchanged — this helper narrows exactly one error class. The SOURCE
+ * write is never wrapped through this helper — only derived-output writes are (§7).
+ */
+export declare function putDerivedOutput(outColl: CollectionLike, id: string, value: unknown, ctx: PutDerivedOutputCtx, options?: {
+    readonly source?: string;
+}): Promise<'written' | 'skipped-frozen'>;
+/** Structural (no static import — kernel spine may not statically reach a with-* service,
+ *  the S4 gate recipe `check-architecture.mjs`'s port-layering check enforces) shape of the
+ *  with-history `LedgerStore.append` seam this helper needs. */
+interface AuditLedgerLike {
+    append(input: {
+        readonly op: 'lifecycle';
+        readonly collection: string;
+        readonly id: string;
+        readonly version: number;
+        readonly actor: string;
+        readonly payloadHash: string;
+        readonly reason?: string;
+    }): Promise<unknown>;
+}
+/** @internal — the optional with-history ledger audit hook for `putDerivedOutput`, present
+ *  only when the ledger is active (mirrors every other kernel event's `if (this.ledger)`
+ *  gate). Encoded as a `'lifecycle'` entry — the existing "non-data audit event" op (the
+ *  same convention `forget`'s JSON-summary-in-`reason` entry uses; `ledger/entry.ts:88-104`). */
+export declare function ledgerAuditHook(ledger: AuditLedgerLike | undefined, actor: string): ((e: DerivationSkippedFrozen) => Promise<void>) | undefined;
+/** `recomputeRollup`/`dispatchRollupsOnDelete`'s per-target write outcome (#638 Task 6):
+ *  `'written'`/`'skipped-frozen'` mirror {@link putDerivedOutput}'s result; `'noop'` covers
+ *  no-parent/no-change/deduped-by-wave — nothing to report either way. */
+export type RollupOutcome = 'written' | 'skipped-frozen' | 'noop';
+/** Mutable accumulator `forgetDerivedFanout` writes into, one per `Vault.forget()` call — keeps
+ *  the per-ref loop's call site to a single line under vault.ts's tight kernel-surface ceiling.
+ *  Maps 1:1 onto `ForgetResult`'s additive fields (`with-audit/forget/strategy.ts`). */
+export interface ForgetFanoutStats {
+    recordsErased: number;
+    aggregatesRecomputed: number;
+    readonly residueFrozen: string[];
+    /** #650 Task 5 (#648) — referencing records tombstoned via a `'ref'` edge's `cascade` policy. */
+    lookupReferencesCascaded: number;
+    /** #650 Task 5 (#648) — referencing fields cleared via a `'ref'` edge's `nullify` policy. */
+    lookupReferencesNullified: number;
+    /** #650 Task 5 review (Important fix) — `'ref'` edges whose compare-key could NOT be resolved,
+     *  even from the LIVE pre-shred row (the backing row itself is unreadable) — propagation was
+     *  skipped for these, reported here so the skip is never silent. `backing:key:collection.field`
+     *  entries, one per un-propagated edge. */
+    readonly lookupReferencesResidue: string[];
+}
+/**
+ * #622 — after `_writeTombstone(ref.id, actor)` erases the forgotten subject's own record, fan
+ * out to its derived residue via the graph (spec §5): record-grain artifacts (MV rows,
+ * array-shape derivation rows, same-id record-shape derivation copies) are ERASED through the
+ * SAME `!internal` housekeeping-bypass machinery the ordinary delete path uses (no user
+ * `onDelete` re-fires — the shred-is-not-a-domain-delete property `_writeTombstone` protects);
+ * aggregate-grain rollups are RECOMPUTED without the forgotten contribution in open periods, or
+ * skip+audit (via `putDerivedOutput`, already wired into the rollup/MV output paths) in frozen
+ * ones. Mutates `stats` in place. `envelope` is `ref`'s PRE-tombstone envelope, decoded only if
+ * a rollup edge is actually present — the #553 zero-cost-skip discipline: no decrypt for the
+ * common case of a forgotten record with no aggregate-grain consumer, and no work at all when
+ * `ref.collection` has no graph out-edges. `lookupCompareKeys` is the `'ref'` edges' compare-key
+ * map, resolved from the LIVE row BEFORE any shred (`VaultLinks.checkLookupRefsRestrict`'s return
+ * value — `Vault.forget()`'s pre-shred restrict check doubles as the live-resolve pass) — see
+ * {@link applyLookupRefsFanout}.
+ */
+export declare function forgetDerivedFanout(vault: VaultLike, ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope | null, stats: ForgetFanoutStats, lookupCompareKeys: ReadonlyMap<string, string | undefined>): Promise<void>;
+export {};

package/dist/kernel/via/graph-wiring.d.ts

@@ -0,0 +1,145 @@
+import type { ViaGraph } from './graph.js';
+import { resolveComputedEdges, type CollectionOpts, type GraphEdge } from '../collection-config.js';
+import { type ClassifiedEntry } from '../../port/with/classified-strategy.js';
+import { type HasWritableViaPipeline } from './pipeline.js';
+type ComputedFieldsParam = NonNullable<Parameters<typeof resolveComputedEdges>[1]>;
+/**
+ * Register one collection's field postures (`binding.posture` + `covers()`)
+ * and computed/via-binding-deps edges onto the vault's shared graph. Called
+ * from `Vault.collection()`'s fresh-construction path, right after the real
+ * `Collection` is built from the SAME `opts` — `resolveCollectionConfig` is a
+ * pure function, so re-running it here (Collection's constructor already ran
+ * it once internally) costs a one-time, side-effect-free recomputation at
+ * collection-declare time, not a per-write cost.
+ */
+export declare function registerCollectionGraphSources<T>(graph: ViaGraph, name: string, opts: CollectionOpts<T>): void;
+/** The slice of `Vault.collection()`'s reconcile-path options relevant to
+ *  graph registration — money/computed/classifiedFields are the only
+ *  options `Vault.collection()`'s reconcile branches actually attach
+ *  (i18nFields/dictKeyFields are construction-only, never reconciled). */
+export interface ReconcileGraphOptions {
+    readonly moneyFields?: Record<string, unknown>;
+    readonly classifiedFields?: Record<string, ClassifiedEntry>;
+    readonly computed?: ComputedFieldsParam;
+}
+/** Phase 1's output — what phase 2 (`commitReconcileGraphEdges`) applies once
+ *  every `_apply*` mutation for this reconcile call has succeeded. */
+export interface ReconcilePlan {
+    readonly edges: readonly GraphEdge[];
+    readonly depslessComputedFields: readonly string[];
+    readonly classifiedFieldNames: readonly string[];
+}
+/**
+ * Phase 1 (validate) of the reconcile-path's two-phase graph wiring (#638
+ * Task 2 fix wave 2). Pure — throws `ValidationError`, never mutates `graph`.
+ *
+ * Evaluates the COMBINED existing+incoming computed/classified state, using
+ * `graph` as the vault-side memory of what a PRIOR, separate
+ * `vault.collection()` call already registered (review Finding I1): a
+ * depsless computed field declared while no classified field existed yet
+ * registers no edge (`registerCollectionGraphSources` marks it instead), so a
+ * LATER call newly introducing a PERSISTABLE (`recoverable`/`digest-only`)
+ * classified field must still see it and refuse, regardless of which call
+ * declared which piece first. `storage: 'never'` fields are exempt from this
+ * specific check: `enforceClassifiedWrite` rejects the whole write BEFORE
+ * computed fields ever evaluate (`Collection._putInternal`'s pipeline order —
+ * enforceWrite, then computed), so a `never`-stored value structurally cannot
+ * reach a computed field's output. (`resolveComputedEdges` below, unchanged,
+ * still blanket-refuses a depsless field THIS SAME call introduces alongside
+ * ANY classified field regardless of storage — same as fresh construction.)
+ * Given that, once a PERSISTABLE classified field is successfully committed
+ * for a collection, no depsless computed field can survive uncaught (this
+ * very check, or the identical fresh-construction one, would already have
+ * refused it) — so this check only needs THIS call's own incoming
+ * `classifiedFields`, never `graph`'s classified memory.
+ *
+ * Each `computed` entry's own `deps` (#638 Task 7 — the reconcile path only ever sees the
+ * `computed:` sugar option, per `ReconcileGraphOptions`'s doc comment; `via(computed(...))`
+ * is construction-only like i18nFields/dictKeyFields) are resolved via `resolveComputedEdges`
+ * exactly like the fresh-construction path — Finding I2ii's original knownFields-sharing
+ * concern is back in play for the Task 7 review's CRITICAL fix: on a collection that
+ * declares classified fields, `resolveComputedEdges` now checks every `deps` entry against
+ * a `knownFields` universe built via the SAME `collectKnownFieldNames` helper the fresh path
+ * uses (never a hand-rolled second universe), scoped to THIS call's own
+ * `moneyFields`/`classifiedFields`/`computed` options (see `resolveComputedEdges`'s own doc
+ * comment for the full rationale and its documented residual limit). On a non-classified
+ * collection a plain, non-via field is still a legal dep, unchanged from Task 7.
+ *
+ * Callers MUST call this BEFORE any `_apply*` mutation runs, and must only
+ * call `commitReconcileGraphEdges` with the result AFTER every `_apply*` for
+ * this call has succeeded (Finding M2 — no partial graph state may survive a
+ * reconcile call whose config is ultimately rejected).
+ */
+export declare function validateReconcileGraphEdges(graph: ViaGraph, name: string, options: ReconcileGraphOptions): ReconcilePlan;
+/**
+ * Phase 2 (commit) — call ONLY after every `_apply*` mutation belonging to
+ * this reconcile call has succeeded (see {@link validateReconcileGraphEdges}'s
+ * doc comment, Finding M2). Registers `plan`'s edges, skipping any target
+ * already registered so `registerDerived`'s at-most-once contract holds
+ * across repeated identical `vault.collection()` calls, not just within one
+ * (Finding I2i); registers the late-attached classified field(s)' sealed
+ * posture (Finding M1 — fresh construction gets this for free from
+ * `registerCollectionGraphSources`'s compiled-binding loop, which the
+ * reconcile path has no equivalent of); and updates the depless-computed /
+ * classified graph memory {@link validateReconcileGraphEdges} reads.
+ */
+export declare function commitReconcileGraphEdges(graph: ViaGraph, name: string, plan: ReconcilePlan): void;
+/**
+ * Rebuild `coll`'s Via pipeline with the graph's taint overlay layered on
+ * (#638 Task 3 — the assignment→enforcement bridge): `postureFor` (query
+ * gate + `redactForExport`, `kernel/via/pipeline.ts`) enforces it with zero
+ * new surface, and any field the overlay resolves to `encryptedAtRest:
+ * 'sealed'` gets the `taint` binding added so it is ACTUALLY sealed at rest
+ * via `ctx.sealedSlots` (the same mechanism classified uses).
+ *
+ * No-op when the collection has no tainted fields — `coll.via` stays exactly
+ * what `resolveCollectionConfig` built, preserving `this.via === undefined`
+ * for an all-plain collection (#553's sync-stack guarantee). Called once
+ * after `registerCollectionGraphSources` (fresh construction) and once after
+ * `commitReconcileGraphEdges` (reconcile) — a late-attached classified/
+ * computed field can newly taint a field an EARLIER call already built the
+ * pipeline for, so both call sites must refresh.
+ *
+ * Writes through `Collection._setVia` (`kernel/collection.ts`, #666) rather
+ * than the old untyped structural-cast reach-in — `_setVia` does both of the
+ * cast site's old two steps itself: reassigns `this.via` AND resyncs the
+ * codec's OWN `via` snapshot (captured at construction, `collection.ts`'s
+ * `this.codec = new RecordCodec({..., via: this.via})`, which does not
+ * automatically follow a later `this.via` reassignment) so `encryptRecord`/
+ * `decryptRecord` seal/unseal through the taint binding too, not a stale
+ * pre-taint pipeline.
+ *
+ * #642 — `graph.taintedPostures(name)` also carries the collection's `'*'`
+ * target (a derivation/MV/overlay OUTPUT collection's whole-record fold,
+ * `via/graph.ts`'s `taintedPostures`/`taintSealedFields` already surface it
+ * under the literal key `'*'`, no `via/graph.ts` change needed). Split it off
+ * BEFORE building the field-specific overlay — `'*'` is never a real record
+ * field — and re-derive it as `defaultPosture` through the SAME
+ * `buildTaintOverlay` sealed→`queryable:'none'` clamp (reused, not
+ * duplicated, by feeding it a one-entry map). A sealed default folds into
+ * the SAME single `taintBinding` call via `sealAllFields` — every field
+ * (present-time, at-rest) is covered without a second binding.
+ */
+export declare function applyTaintOverlay(coll: HasWritableViaPipeline, graph: ViaGraph, name: string): void;
+/**
+ * #642 — the cross-collection re-apply gap (seam map finding 4/10): when the
+ * OUTPUT/parent collection was opened (its overlay built) BEFORE the
+ * classified SOURCE collection ever registered a field, the output's `'*'`
+ * fold (or a rollup's real-field fold) was computed against an empty/stale
+ * source posture. `applyTaintOverlay` alone never re-fires for an already-
+ * open dependent — this hook closes that: after `name` registers its OWN
+ * field postures (called right after `applyTaintOverlay(coll, graph, name)`
+ * at each collection-construction call site), re-run `applyTaintOverlay` for
+ * every OPEN collection that graph-depends on `name`.
+ *
+ * Pure wiring — re-applies OVERLAYS only (a pipeline rebuild), never
+ * re-registers a graph edge (`registerDerived`'s at-most-once contract, D-2
+ * wave-2 law, is untouched). `graph.dependentsOf(name)` already excludes
+ * `'ref'` edges (a referencing field must not seal just because its backing
+ * dimension changed — the phase-D lookup identity contract). A dependent
+ * collection that hasn't been opened yet (`getOpenCollection` returns
+ * `undefined`) is skipped — it will fold correctly on its OWN first-open
+ * `applyTaintOverlay` call, which reads the graph fresh.
+ */
+export declare function reapplyDependentOverlays(graph: ViaGraph, name: string, getOpenCollection: (n: string) => HasWritableViaPipeline | undefined): void;
+export {};

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

@@ -0,0 +1,165 @@
+import type { ViaPosture } from './index.js';
+/** A (collection, field) node. Artifact-grain targets (rollup field, MV row-class,
+ *  overlay output) are modelled as a field node whose `field` is the artifact key. */
+export interface FieldRef {
+    readonly collection: string;
+    readonly field: string;
+}
+export type EdgeKind = 'computed' | 'derivation' | 'rollup' | 'mv' | 'overlay' | 'ref';
+/** `'virtual'` (#638 Task 7) marks a `computed(fn, { mode: 'virtual' })` field's edge —
+ *  never stored (rides the `present` phase), so it can never be sealed at rest
+ *  ({@link ViaGraph.taintSealedFields} excludes it) and is always non-queryable
+ *  regardless of source posture ({@link ViaGraph.effectivePosture} clamps it). */
+export type Grain = 'record' | 'aggregate' | 'virtual';
+/** Delete/forget-time referential policy for a `'ref'` edge (#650 Task 5, spec §4) — duplicated
+ *  (not imported) from `via/lookup/descriptor.ts`'s `OnDelete`: the kernel spine may not
+ *  statically import `via/**` (Check 14, `via-layering`). Keep the two in sync by hand. */
+export type OnDelete = 'restrict' | 'cascade' | 'nullify';
+/** Plain (non-via) field baseline — max-permissive; taint only ever tightens. */
+export declare const DEFAULT_POSTURE: ViaPosture;
+/** The per-axis "most restrictive" fold — pure, exported for direct unit testing. */
+export declare function foldPosture(a: ViaPosture, b: ViaPosture): ViaPosture;
+/** Security-axes-only fold for a wildcard collection node (#642): sealed-wins encryptedAtRest,
+ *  AND exportable, OR forgettable — queryable is NOT folded (stays base.queryable; the sealed
+ *  clamp to 'none' is buildTaintOverlay's job, so inheriting `sealed` never over-restricts a
+ *  blob-adjacent output to unqueryable). Pure; exported for unit testing. Distinct from
+ *  {@link foldPosture} (which folds all four axes) — do NOT reuse foldPosture here. */
+export declare function foldWildcardSecurity(base: ViaPosture, contributor: ViaPosture): ViaPosture;
+/** Metadata-only dependency graph, ONE per vault. Never stores values or key material. */
+export declare class ViaGraph {
+    /** Declared source-field postures (registerField), keyed by node id. */
+    private readonly _posture;
+    /** Every derived target's registration, keyed by the target's node id. */
+    private readonly _in;
+    /** source node id -> derived targets that depend on it (dispatch/erasure). */
+    private readonly _out;
+    /** Memoized effective posture per derived target node id. */
+    private readonly _effectiveCache;
+    /** Memoized whole-collection security-axes fold for `'*'` wildcard LEAF nodes (#642),
+     *  keyed by collection name — see {@link _wildcardContribution}. Cleared alongside
+     *  `_effectiveCache` on every `registerField`/`registerDerived` (a later-registered
+     *  field must re-fold on the next read — registration ordering is free). */
+    private readonly _wildcardCache;
+    /** Collections with at least one classified field (#638 Task 2 fix wave 2,
+     *  Finding I1 — the reconcile path's combined-state leak guard memory). */
+    private readonly _classifiedCollections;
+    /** Computed field names declared with no `deps` entry, per collection
+     *  (Finding I1 — such a field registers no edge when no classified field is
+     *  present yet, so a LATER, separate reconcile call attaching classifiedFields
+     *  still needs to see it regardless of declaration order). */
+    private readonly _depslessComputed;
+    /** Declare a source field's posture (money/i18n/classified/plain). Plain fields
+     *  default to `DEFAULT_POSTURE`; a later declaration for the same node wins-first (idempotent). */
+    registerField(collection: string, field: string, posture: ViaPosture): void;
+    /** A derived target depends on `sources` (may be cross-collection). `kind`/`grain`
+     *  drive dispatch + erasure semantics; sources drive taint. Re-registering the same
+     *  target replaces `_in` but does not prune stale `_out` edges — callers must
+     *  register each target at most once per graph lifetime. `onDelete`/`keyField` (#650 Task 5)
+     *  are meaningful only for `kind === 'ref'` edges — {@link referencingEdgesOf} reads them back. */
+    registerDerived(target: FieldRef, sources: readonly FieldRef[], kind: EdgeKind, grain: Grain, onDelete?: OnDelete, keyField?: string): void;
+    /** Whether `target` already has a registered in-edge — lets a caller skip
+     *  re-registering the same target (#638 Task 2 fix wave 2, Finding I2i:
+     *  `registerDerived`'s at-most-once contract must hold across repeated
+     *  identical `vault.collection()` calls, not just within a single one). */
+    hasDerived(target: FieldRef): boolean;
+    /** Mark/query a collection as having declared at least one classified field. */
+    markClassified(collection: string): void;
+    isClassified(collection: string): boolean;
+    /** Mark/query a collection's depsless (no declared `deps`) computed
+     *  field names — see `_depslessComputed`'s doc comment above. */
+    markDepslessComputed(collection: string, field: string): void;
+    depslessComputedFields(collection: string): ReadonlySet<string>;
+    /** Every field name the graph already has memory of for `collection` — from an
+     *  EARLIER, separate `vault.collection()` call (registered postures, derived
+     *  targets, depsless-computed names) — regardless of which via feature declared
+     *  it. #645 — `via/graph-wiring.ts`'s reconcile-path `knownFields` universe
+     *  (`collectKnownFieldNames`) is scoped to THIS call's own options only, so a
+     *  computed field attached in a LATER call whose `deps` correctly names a field
+     *  declared in an EARLIER call was spuriously refused as "unknown"; this method
+     *  lets that call site union in the graph's cross-call memory. Excludes the `'*'`
+     *  wildcard target (an overlay/derivation whole-record fold node, never a real
+     *  record field — see {@link registerDerived}'s doc comment). */
+    knownFieldNames(collection: string): ReadonlySet<string>;
+    /** Reject cycles at declare time (vault open). Throws `DerivationCycleError` for a
+     *  derivation/rollup/computed cycle, `MaterializedViewCycleError` for an MV cycle —
+     *  same classes + message shape the registries throw today (behavior lock). */
+    assertAcyclic(): void;
+    /** A leaf (non-derived) node's own posture contribution: its declared posture,
+     *  or `DEFAULT_POSTURE` if never declared via `registerField`. */
+    private _declaredPosture;
+    /** A node's posture contribution when folded into a dependent: recurse if it is itself
+     *  derived; else its declared/default posture — UNLESS it is a `'*'` LEAF node consumed
+     *  by a folded formula kind (#642, `derivation|rollup|mv|overlay`), in which case it
+     *  contributes its collection's whole-record security fold ({@link _wildcardContribution}).
+     *  `kind` is the CONSUMING edge's kind, threaded from {@link _computeEffective}. `'ref'`
+     *  edges (and the provenance-only untyped call, `kind` left `undefined`) keep `'*'` =
+     *  identity — the phase-D lookup reliance (`via/lookup/registry.ts:392-397`) that a
+     *  referencing field must not seal just because its dimension collection has a classified
+     *  column. */
+    private _contribution;
+    /** Lazy fold (#642) of a collection's REGISTERED field postures on the security axes only
+     *  ({@link foldWildcardSecurity} — sealed-wins encryptedAtRest, AND exportable, OR
+     *  forgettable; queryable stays at DEFAULT_POSTURE's 'full', never folded), seeded at
+     *  DEFAULT_POSTURE. This is the collection-level posture a `'*'` LEAF node contributes to a
+     *  folded-kind formula edge (derivation/rollup/mv/overlay) — see {@link _contribution}. A
+     *  plain (unregistered) field contributes nothing (the identity), so the fold is strictly
+     *  more conservative than deps-based taint and never hits the KNOWN-LIMIT wall (it names no
+     *  fields — seam map §1d). Memoized per collection in `_wildcardCache`. */
+    private _wildcardContribution;
+    private _computeEffective;
+    /** Strictest source posture on every axis, per §2. `undefined` when `target` has no
+     *  in-edges (not a derived field). Transitive: folds through chained derivations. */
+    effectivePosture(target: FieldRef): ViaPosture | undefined;
+    /** Per-collection { field → effectivePosture } overlay the pipeline consumes (Task 3). */
+    taintedPostures(collection: string): ReadonlyMap<string, ViaPosture>;
+    /** Materialized (`grain !== 'virtual'`) derived fields on `collection` whose effective
+     *  encryptedAtRest resolves to 'sealed' — the taint-seal set (Task 3). #638 Task 7
+     *  makes the `grain !== 'virtual'` filter meaningful: a `computed(fn, { mode: 'virtual' })`
+     *  field is never stored (rides the `present` phase, seam map Part 4's money-Formatted/
+     *  i18n-Label precedent), so it is EXCLUDED here even when its effective `encryptedAtRest`
+     *  folds to `'sealed'` — there is no envelope slot to seal. It still surfaces in
+     *  {@link taintedPostures} (query refusal via `postureFor`'s `queryable` clamp above, and
+     *  export refusal via `exportable`) — only the AT-REST SEALING ACTION is skipped. */
+    taintSealedFields(collection: string): ReadonlySet<string>;
+    /** Fields on `collection` whose registered edge is `grain === 'virtual'` (#638 Task 7) —
+     *  `via/graph-wiring.ts#applyTaintOverlay` intersects this with `exportable === false`
+     *  postures to know which virtual fields need PRESENT-TIME (not just export-time)
+     *  redaction, since a virtual field's value is only ever materialized inside `present()`. */
+    virtualFields(collection: string): ReadonlySet<string>;
+    /** Per-collection { field → immediate source field names that forced its
+     *  effective posture away from `DEFAULT_POSTURE` } — `describe()`'s
+     *  provenance (Task 3). Only the DIRECT declared sources are named (not the
+     *  ultimate origin several hops up a transitive chain); a source absent
+     *  from the result contributed nothing restrictive. */
+    taintProvenance(collection: string): ReadonlyMap<string, readonly string[]>;
+    private _targetsDependingOn;
+    /** Dispatch (Task 4): every derived target triggered by a write to `collection`. Excludes
+     *  `'ref'` edges (#650 Task 5 review, folded Minor) — a `'ref'` edge is consulted only by the
+     *  delete/forget-time restrict/cascade/nullify path ({@link referencingEdgesOf}), never by the
+     *  sync/cutover/restore dispatch wave (`runGraphDispatchWave`); counting it here defeated that
+     *  wave's zero-cost early-continue, costing every write to a referenced backing collection an
+     *  unconditional decrypt + two no-op dispatch passes. {@link derivedArtifactsOf} (erasure
+     *  fanout) still includes `'ref'` edges — the forget path genuinely needs them. */
+    dependentsOf(collection: string): ReadonlyArray<{
+        readonly target: FieldRef;
+        readonly kind: EdgeKind;
+        readonly grain: Grain;
+    }>;
+    /** Erasure (Task 6): derived artifacts of a forgotten record whose source is `collection`. */
+    derivedArtifactsOf(collection: string): ReadonlyArray<{
+        readonly target: FieldRef;
+        readonly kind: EdgeKind;
+        readonly grain: Grain;
+    }>;
+    /** Referencing edges pointing AT a backing dimension (delete/forget-time restrict/cascade/
+     *  nullify, #650 Task 5) — an O(1) reverse lookup via the existing `_out` map (keyed at the
+     *  dimension's wildcard `field:'*'` node, the same convention every whole-collection source
+     *  already uses), NEVER a scan across collections or records. `backing` is the collection name
+     *  a lookup field's edge was registered against (a reserved dimension's `_dict_<name>`/
+     *  `_lookup_<name>` collection name, or a matrix dimension's own collection name). */
+    referencingEdgesOf(backing: string): ReadonlyArray<{
+        readonly referencing: FieldRef;
+        readonly onDelete: OnDelete;
+        readonly keyField: string;
+    }>;
+}