@noy-db/hub 0.3.0-pre.9 → 0.3.0

package/dist/with-shape/introspection/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Types for {@link VaultSchemaSnapshot} — the structured object returned
+ * by `vault.dumpSchema()`. Consumed by the upcoming `noydb describe`
+ * CLI to emit human-readable YAML/JSON audit output.
+ *
+ * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+ *
+ * @module
+ */
+import type { PersistedSchemaKind } from '../persisted-schemas/types.js';
+import type { Permission } from '../../kernel/types.js';
+import type { CollectionMeta, VaultMeta } from './meta.js';
+/** Flat snapshot of a vault's registered schema. */
+export interface SchemaIntrospection {
+    readonly collections: ReadonlyArray<{
+        name: string;
+        docCount: number;
+    }>;
+    readonly guards: ReadonlyArray<{
+        collection: string;
+        count: number;
+    }>;
+    readonly materializedViews: ReadonlyArray<{
+        name: string;
+        sourceCollections: string[];
+    }>;
+    readonly schemaUpdate: ReadonlyArray<{
+        collection: string;
+        strategies: string[];
+    }>;
+    readonly grants: ReadonlyArray<{
+        collection: string;
+        permission: Permission;
+    }>;
+}
+/** Where the field-level info in the snapshot came from. */
+export type FieldSource = 'persisted' | 'live-validator' | 'sampled' | 'unknown';
+export interface FieldDescriptor {
+    /** Inferred type tag: 'string' | 'number' | 'boolean' | 'enum' | 'object' | 'array' | 'null' | 'opaque'. */
+    readonly type: string;
+    /** Where this field info was sourced from. */
+    readonly source: FieldSource;
+    /** Optional constraints — minLength, maxLength, enum values, gt, etc. */
+    readonly constraints?: Record<string, unknown>;
+    /** True when the schema marks this field optional. */
+    readonly optional?: boolean;
+    /** Foreign-key target as `<collection>.<field>` when declared. */
+    readonly references?: string;
+}
+export interface CollectionStats {
+    readonly records: number;
+    readonly bytes: number;
+    readonly bytesAvg: number;
+    readonly bytesMin: number;
+    readonly bytesMax: number;
+    /** ISO-8601 from min(_ts) across envelopes. Empty string when no records. */
+    readonly oldest: string;
+    /** ISO-8601 from max(_ts) across envelopes. Empty string when no records. */
+    readonly newest: string;
+}
+/**
+ * Collection-level configuration options surfaced by `dumpSchema()`.
+ * Only fields that are actively configured are present; the object is
+ * omitted entirely from `CollectionDescriptor.config` when nothing is set.
+ * Reused by Task 5 in-devtools display.
+ */
+export interface CollectionConfig {
+    readonly i18nFields?: readonly string[];
+    readonly embeddings?: {
+        readonly source: string | readonly string[];
+        readonly dim: number;
+        readonly model?: string;
+    };
+    readonly textIndexes?: readonly string[];
+    readonly textIndexPersist?: boolean;
+    readonly perRecordKeys?: boolean;
+    readonly provenance?: boolean;
+    readonly tiers?: readonly number[];
+    readonly tierMode?: string;
+    readonly crdt?: string;
+    /**
+     * `true` when history is explicitly enabled for this collection.
+     * Omitted when history is not configured or when the default vault-wide
+     * setting applies without explicit per-collection configuration.
+     */
+    readonly history?: boolean;
+    /**
+     * Present when the collection is registered in `vault.archiveRegistry`
+     * (i.e. an archive policy was declared). `true` = archive policy present.
+     */
+    readonly archive?: boolean;
+    /**
+     * Strategy names registered for schema updates on this collection.
+     * Present only when at least one strategy is registered.
+     */
+    readonly schemaUpdate?: readonly string[];
+}
+export interface CollectionDescriptor {
+    readonly fields: Record<string, FieldDescriptor>;
+    readonly indexes: ReadonlyArray<{
+        readonly fields: ReadonlyArray<string>;
+        readonly unique?: boolean;
+    }>;
+    readonly refs: Record<string, {
+        readonly target: string;
+        readonly mode: 'strict' | 'warn' | 'cascade';
+    }>;
+    readonly validator?: {
+        readonly kind: PersistedSchemaKind;
+        readonly source: 'persisted' | 'live-validator';
+    };
+    readonly stats?: CollectionStats;
+    readonly meta?: CollectionMeta;
+    readonly config?: CollectionConfig;
+}
+export interface MaterializedViewDescriptor {
+    readonly sources: ReadonlyArray<string>;
+    readonly groupBy?: ReadonlyArray<string>;
+    readonly aggregate?: Record<string, string>;
+    readonly refresh: string;
+    readonly stats?: CollectionStats;
+}
+export interface OverlayViewDescriptor {
+    readonly base: string;
+    readonly overlay: string;
+}
+export interface DerivationDescriptor {
+    readonly source: string;
+    readonly outputs: ReadonlyArray<string>;
+}
+export interface InternalCollectionStats {
+    readonly records: number;
+    readonly bytes: number;
+}
+export interface VaultSchemaSnapshot {
+    readonly _noydb_snapshot: 1;
+    readonly vault: string;
+    readonly emittedAt: string;
+    readonly subsystems: Record<string, boolean>;
+    readonly aclRoles?: ReadonlyArray<string>;
+    readonly meta?: VaultMeta;
+    readonly collections: Record<string, CollectionDescriptor>;
+    readonly materializedViews: Record<string, MaterializedViewDescriptor>;
+    readonly overlayViews: Record<string, OverlayViewDescriptor>;
+    readonly derivations: Record<string, DerivationDescriptor>;
+    /** Only present when `dumpSchema({ withStats: true })` was called. */
+    readonly internal?: Record<string, InternalCollectionStats>;
+}
+export interface DumpSchemaOptions {
+    /** When true, walk every collection's envelopes to compute counters. Default `false`. */
+    readonly withStats?: boolean;
+    /** Sample N records per collection lacking a persisted/live schema. Default 50. `0` disables sampling. */
+    readonly sampleSize?: number;
+}

package/dist/with-shape/introspection/walk.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Orchestrate the structural walk of a Vault, producing a
+ * {@link VaultSchemaSnapshot}. Called from `Vault.dumpSchema()`.
+ *
+ * @module
+ */
+import type { DumpSchemaOptions, VaultSchemaSnapshot } from './types.js';
+import type { Collection } from '../../kernel/collection.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+import type { RefRegistry } from '../../kernel/refs.js';
+import type { VaultMeta } from './meta.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * The minimal slice of Vault internal state the walker needs.
+ * Exposed via `vault._introspectState()` to keep the public Vault
+ * surface narrow.
+ *
+ * @internal
+ */
+export interface VaultIntrospectState {
+    readonly name: string;
+    readonly adapter: NoydbStore;
+    readonly collectionCache: Map<string, Collection<unknown>>;
+    readonly refRegistry: RefRegistry;
+    readonly getDEK: (collectionName: string) => Promise<EnclaveKey>;
+    /** The active unlocked keyring — role/permissions/userId for access-scoped ops. */
+    readonly keyring: UnlockedKeyring;
+    readonly subsystems: Record<string, boolean>;
+    /** Vault-level descriptive metadata, when set via `openVault({meta})`. */
+    readonly vaultMeta?: VaultMeta;
+    readonly mvRegistry: unknown;
+    readonly overlayRegistry: unknown;
+    readonly derivationRegistry: unknown;
+    /**
+     * Returns the registered schema-update strategy names for a collection,
+     * or `undefined` when none are registered. Populated from
+     * `vault.#schemaUpdateNames` in `_introspectState()`.
+     */
+    readonly getCollectionSchemaUpdateNames?: (col: string) => readonly string[] | undefined;
+    /**
+     * Returns `true` when the collection has an archive policy registered
+     * in `vault.archiveRegistry`, `false` otherwise. Populated from
+     * `vault.archiveRegistry` in `_introspectState()`.
+     */
+    readonly hasCollectionArchive?: (col: string) => boolean;
+}
+export declare function dumpVaultSchema(vault: {
+    _introspectState(): VaultIntrospectState;
+}, opts: DumpSchemaOptions): Promise<VaultSchemaSnapshot>;

package/dist/with-shape/links/lazy-handle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Lazy link-set handle factory (#553).
+ *
+ * `vault.links(name)` is a SYNC accessor, but every method on the handle
+ * it returns is async — so the handle can defer loading the `LinkSet`
+ * storage engine to the first actual link I/O. This keeps `link-set.ts`
+ * out of the floor bundle for consumers that never use links, while the
+ * handle object itself stays cached and referentially stable per name.
+ *
+ * Besides the public {@link LinkSetHandle} surface, the handle carries
+ * the two cascade internals the ref/link enforcement facade consults
+ * (`vault-facade.ts` casts the handle to `LinkSet` and duck-types them).
+ */
+import { type LinkRow, type LinkSpec, type LinkSetHandle } from './names.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+/** @internal The lazy handle: public surface + facade cascade internals. */
+export type LazyLinkSetHandle = LinkSetHandle & {
+    readonly _collectionName: string;
+    _rowsTouchingEndpoint(collection: string, id: string): Promise<LinkRow[]>;
+};
+/** @internal Constructor args for the deferred {@link LinkSet}. */
+export interface LazyLinkSetDeps {
+    readonly adapter: NoydbStore;
+    readonly vault: string;
+    readonly name: string;
+    readonly spec: LinkSpec;
+    readonly encrypted: boolean;
+    readonly getDEK: (collectionName: string) => Promise<EnclaveKey>;
+    readonly actor: string;
+    readonly emitter: NoydbEventEmitter;
+    readonly endpointExists: (collection: string, id: string) => Promise<boolean>;
+}
+/** @internal Build the handle; the LinkSet engine dynamic-imports on first use. */
+export declare function makeLazyLinkSetHandle(d: LazyLinkSetDeps): LazyLinkSetHandle;

package/dist/with-shape/links/link-set.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `_links_*` reserved collections — managed bidirectional many-to-many
+ * junctions (design B).
+ *
+ * Where `refArray` (design A) stores an id-array on one owning record,
+ * `vault.link()` creates a first-class junction: a dedicated encrypted
+ * `_links_<name>` collection whose rows are `{ a, b, meta? }` link tuples.
+ * It is queryable from BOTH sides (`of(id)`), carries optional per-link
+ * metadata, and cascades on endpoint delete.
+ *
+ * Each link is slot-typed: `a` is an id in the `a` endpoint collection,
+ * `b` an id in the `b` endpoint collection (they may be the same
+ * collection for self-links). A link's identity is the ordered pair
+ * `(a, b)`; `of(id)` matches either slot.
+ *
+ * Rows are encrypted under a dedicated `_links_<name>` DEK — same
+ * zero-knowledge stack as every other collection (the store sees only
+ * ciphertext). Backup/restore rides the normal `loadAll` path.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { NoydbError } from '../../kernel/errors.js';
+export { LINK_COLLECTION_PREFIX, linkCollectionName, isLinkCollectionName, linkRowKey, LinkIntegrityError, } from './names.js';
+export type { LinkOnDelete, LinkSpec, LinkRow, LinkSetHandle } from './names.js';
+import type { LinkSpec, LinkRow, LinkSetHandle } from './names.js';
+/**
+ * @internal — the concrete handle. The Vault owns construction (one per
+ * link name) and the cascade hooks; consumers use the {@link LinkSetHandle}
+ * surface via `vault.links(name)`.
+ */
+export declare class LinkSet implements LinkSetHandle {
+    private readonly adapter;
+    private readonly vault;
+    private readonly name;
+    private readonly spec;
+    private readonly encrypted;
+    private readonly getDEK;
+    private readonly actor;
+    private readonly emitter;
+    /** Vault-provided existence check for endpoint validation on connect(). */
+    private readonly endpointExists;
+    private readonly collName;
+    private dekPromise;
+    constructor(adapter: NoydbStore, vault: string, name: string, spec: LinkSpec, encrypted: boolean, getDEK: (collectionName: string) => Promise<EnclaveKey>, actor: string, emitter: NoydbEventEmitter, 
+    /** Vault-provided existence check for endpoint validation on connect(). */
+    endpointExists: (collection: string, id: string) => Promise<boolean>);
+    private dek;
+    private encryptEntry;
+    private decryptEntry;
+    connect(aId: string, bId: string, meta?: Record<string, unknown>): Promise<void>;
+    disconnect(aId: string, bId: string): Promise<void>;
+    has(aId: string, bId: string): Promise<boolean>;
+    of(id: string): Promise<LinkRow[]>;
+    list(): Promise<LinkRow[]>;
+    /** @internal — rows where the deleted endpoint id matches the relevant slot. */
+    _rowsTouchingEndpoint(collection: string, id: string): Promise<LinkRow[]>;
+    /** @internal — the storage collection name (for tx pre-image capture). */
+    get _collectionName(): string;
+}
+/** Thrown by `connect()` when an endpoint record does not exist. */
+export declare class LinkEndpointError extends NoydbError {
+    readonly link: string;
+    readonly endpoint: string;
+    readonly missingId: string;
+    constructor(link: string, endpoint: string, missingId: string);
+}

package/dist/with-shape/links/names.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Link-set naming helpers, declaration types, and errors — the tiny,
+ * always-loadable slice of the links feature (#553).
+ *
+ * Split out of `link-set.ts` so the kernel floor (reserved-name guard in
+ * `vault.collection()`, the lazy `vault.links()` handle) and the ref/link
+ * enforcement facade can bind these few lines WITHOUT statically pulling
+ * the `LinkSet` storage engine; that class now loads via dynamic import
+ * on first link I/O. `link-set.ts` re-exports everything here, so import
+ * paths and class identities are unchanged for existing consumers.
+ */
+import { NoydbError } from '../../kernel/errors.js';
+export declare const LINK_COLLECTION_PREFIX = "_links_";
+/** Storage collection name for a logical link set. */
+export declare function linkCollectionName(name: string): string;
+/** True for any reserved link-collection name. */
+export declare function isLinkCollectionName(name: string): boolean;
+/** What happens to a link's rows when one of its endpoint records is deleted. */
+export type LinkOnDelete = 'cascade' | 'strict' | 'warn';
+/**
+ * Declaration for a link set, passed to `vault.link(name, spec)`. `a` and
+ * `b` are the endpoint collection names (slot-typed). `onDelete` governs
+ * what happens to link rows when an endpoint record is deleted:
+ * `'cascade'` (default) removes the touching link rows, `'strict'` blocks
+ * the endpoint delete while links exist, `'warn'` leaves orphan rows
+ * (surfaced by `vault.checkIntegrity()`).
+ */
+export interface LinkSpec {
+    readonly a: string;
+    readonly b: string;
+    readonly onDelete?: LinkOnDelete;
+}
+/** One link tuple as returned by `of()` / `list()`. */
+export interface LinkRow {
+    readonly a: string;
+    readonly b: string;
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Compose the row key for an ordered `(a, b)` pair. Each id is
+ * URI-encoded and joined with `|` — encodeURIComponent escapes `|`, so the
+ * key is unambiguous regardless of id contents.
+ */
+export declare function linkRowKey(aId: string, bId: string): string;
+/** Public handle returned by `vault.links(name)`. */
+export interface LinkSetHandle {
+    /** Create (or overwrite the metadata of) the link `(aId, bId)`. Validates both endpoints exist. */
+    connect(aId: string, bId: string, meta?: Record<string, unknown>): Promise<void>;
+    /** Remove the link `(aId, bId)`. Idempotent — a no-op if it doesn't exist. */
+    disconnect(aId: string, bId: string): Promise<void>;
+    /** Whether the link `(aId, bId)` exists. */
+    has(aId: string, bId: string): Promise<boolean>;
+    /** All links touching `id` on EITHER endpoint. */
+    of(id: string): Promise<LinkRow[]>;
+    /** All links in the set. */
+    list(): Promise<LinkRow[]>;
+}
+/** Thrown when a `strict` link blocks deletion of an endpoint that still has links. */
+export declare class LinkIntegrityError extends NoydbError {
+    readonly link: string;
+    readonly endpoint: string;
+    readonly id: string;
+    readonly count: number;
+    constructor(link: string, endpoint: string, id: string, count: number);
+}

package/dist/with-shape/links/vault-facade.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Vault-side refs / managed-links enforcement facade.
+ *
+ * Holds the foreign-key enforcement entry points the collection write path
+ * reaches through the `refEnforcer` facade closure (`enforceRefsOnPut` /
+ * `enforceRefsOnDelete`), the managed-link `onDelete` policy
+ * (`enforceLinksOnDelete`), the `joinResolver` half (`resolveRef` /
+ * `resolveSource`), the `checkIntegrity()` reporter, and the cascade-cycle
+ * breaker set (`cascadeInProgress`). The ref/link registries stay
+ * vault-resident (they are populated by `vault.collection()` / `vault.link()`
+ * and read by the backup path) and arrive by reference through
+ * {@link VaultLinksDeps}; every other `Vault` dependency arrives via the deps
+ * interface.
+ *
+ * Internal service — reached through `vault.enforceRefsOnPut(...)` etc.
+ */
+import { type RefDescriptor, type RefViolation, type RefRegistry } from '../../kernel/refs.js';
+import { type LinkSpec, type LinkSetHandle } from './names.js';
+import type { JoinableSource } from '../../kernel/query/index.js';
+import type { Collection } from '../../kernel/collection.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { TxContext } from '../../with-commit/tx/transaction.js';
+import type { ViaGraph } from '../../kernel/via/graph.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+/** Everything the moving refs/links methods touched on the vault's `this.*`. */
+export interface VaultLinksDeps {
+    /** Per-vault foreign-key registry (vault-resident; read by reference). */
+    readonly refRegistry: RefRegistry;
+    /** Registered link specs, keyed by link name (vault-resident; read by reference). */
+    readonly linkRegistry: ReadonlyMap<string, LinkSpec>;
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** Vault namespace name. */
+    readonly vault: string;
+    /** Collection accessor (bound `vault.collection`). */
+    collection<T = unknown>(name: string): Collection<T>;
+    /** Declared link-set accessor (bound `vault.links`). */
+    links(name: string): LinkSetHandle;
+    /** Cache lookup for an already-opened collection (used by `resolveSource`). */
+    getCachedCollection(name: string): Collection<unknown> | undefined;
+    /** The active transaction context, or null outside a tx. */
+    getActiveTxContext(): TxContext | null;
+    /** The vault's event emitter — the `lookup:propagation-residue` channel (#654). */
+    readonly emitter: NoydbEventEmitter;
+}
+export declare class VaultLinks {
+    private readonly deps;
+    /**
+     * Set of collection record-ids currently being deleted as part of a cascade.
+     * Populated on entry to `enforceRefsOnDelete` and drained on exit. Used to
+     * break mutual-cascade cycles: deleting A → cascade to B → cascade back to A
+     * would otherwise recurse forever, so we short-circuit when we see an
+     * already-in-progress delete on the same (collection, id) pair.
+     */
+    private readonly cascadeInProgress;
+    constructor(deps: VaultLinksDeps);
+    /**
+     * Enforce strict outbound refs on a `put()`. Called by Collection
+     * just before it writes to the adapter. For every strict ref
+     * declared on the collection, check that the target id exists in
+     * the target collection; throw `RefIntegrityError` if not.
+     *
+     * `warn` and `cascade` modes don't affect put semantics — they're
+     * enforced at delete time or via `checkIntegrity()`.
+     */
+    enforceRefsOnPut(collectionName: string, record: unknown): Promise<void>;
+    /**
+     * Enforce inbound ref modes on a `delete()`. Called by Collection
+     * just before it deletes from the adapter. Walks every inbound
+     * ref that targets this (collection, id) and:
+     *
+     *   - `strict`: throws if any referencing records exist
+     *   - `cascade`: deletes every referencing record
+     *   - `warn`:    no-op (checkIntegrity picks it up)
+     *
+     * Cascade cycles are broken via `cascadeInProgress` — re-entering
+     * for the same (collection, id) returns immediately so two
+     * mutually-cascading collections don't recurse forever.
+     */
+    enforceRefsOnDelete(graph: ViaGraph, collectionName: string, id: string): Promise<void>;
+    /**
+     * Find the records in `collection` whose `field` currently equals `key` — the SAME
+     * list()+filter machinery `enforceRefsOnDelete`'s classic ref-restrict/cascade loop above
+     * already uses (bounded by the referencing collection's size, never by the whole vault or by
+     * "which collections reference this" — that part is the graph's O(1) `_out` reverse index).
+     */
+    private findLookupReferencingRecords;
+    /**
+     * Resolve the VALUE a referencing field actually stores for the row being deleted (`rawKey`,
+     * the backing row's PUT-id) under a given edge's `keyField` — a referencing field always stores
+     * `row[keyField]`, never the PUT-id when the two differ (matrix tier's `lookup(dim, {key})`;
+     * mirrors Task 3's `checkLookupMembership` review fix, Important 1). `keyField === 'id'`
+     * (reserved/static tiers, and the matrix default) needs no row read: `rawKey` IS the value.
+     * Reads the backing row AT MOST ONCE per distinct non-`'id'` `keyField`, even across multiple
+     * edges — `backingCollection` is only `.get()`-able for the matrix tier, which is exactly the
+     * only tier that can ever have `keyField !== 'id'`.
+     */
+    private resolveLookupCompareKey;
+    /**
+     * Phase 1 (#650 Task 5, #648) — restrict check, never mutates. Throws
+     * `DictKeyInUseError(dimension, key, usedBy, count)` naming the FIRST referencing collection
+     * still holding a matching record, for every `onDelete:'restrict'` edge the graph's O(1)
+     * `referencingEdgesOf(backingCollection)` reverse lookup finds pointing at this dimension. A
+     * dimension with no declared lookup-referencing edges is a no-op — undeclared refs keep
+     * dangling (today's behavior, unaffected). Called by `Vault.forget()` BEFORE any shred (the
+     * spec §4 "restrict refuses before any shred" design decision) — cascade/nullify propagation
+     * for the SAME edges happens separately, after the shred, via `forgetDerivedFanout`.
+     *
+     * Also resolves (and RETURNS) the live compare-key for EVERY referencing edge, restrict AND
+     * cascade/nullify alike (#650 Task 5 review, Important fix): `forgetDerivedFanout`'s cascade/
+     * nullify propagation runs AFTER `_writeTombstone`, when a non-`'id'` `keyField`'s value can no
+     * longer be read off the (now-shredded) row — resolving it HERE, at the one point every
+     * referencing edge's backing row is still guaranteed live, eliminates that post-shred
+     * dependency.
+     *
+     * #654: a `restrict` edge whose compare-key CANNOT be resolved (the backing row is missing the
+     * `keyField` or holds a non-scalar value — corruption-class rarity) THROWS
+     * `RestrictRefUnresolvableError` naming the unresolvable edge, fail-closed — whether a
+     * referencer exists can't be proven, so the delete/forget is refused rather than silently
+     * allowed through. Non-restrict edges keep `continue`ing on an unresolvable compare-key (their
+     * `undefined` still lands in the returned map so `forgetDerivedFanout`'s cascade/nullify twin
+     * can report it as residue instead of silently skipping — unchanged from before #654).
+     */
+    checkLookupRefsRestrict(graph: ViaGraph, dimension: string, backingCollection: string, key: string): Promise<ReadonlyMap<string, string | undefined>>;
+    /**
+     * Phase 2 (#650 Task 5, #648) — apply `cascade`/`nullify` propagation for this dimension's
+     * non-restrict referencing edges (restrict edges are skipped — phase 1 above already refused
+     * or the caller already checked). `cascade` deletes each matching record through its ordinary
+     * `collection.delete()` (an origin-tagged, fanout-visible delete — participates in sync/history/
+     * the graph dispatch wave exactly like any other delete); `nullify` clears the referencing field
+     * via an ordinary `collection.put()`. Returns the counts so callers (forget's `ForgetFanoutStats`)
+     * can report the propagation additively.
+     *
+     * #654: an edge whose compare-key can't be resolved is no longer a bare silent `continue` — it
+     * pushes a `backing:key:collection.field` entry onto `residue` (mirroring
+     * `applyLookupRefsFanout`'s forget-path residue format, `kernel/via/dispatch.ts`) so the caller
+     * (`enforceLookupRefsOnDelete` below) can surface it instead of dropping it on the floor.
+     */
+    applyLookupRefsPropagation(graph: ViaGraph, backingCollection: string, key: string): Promise<{
+        cascaded: number;
+        nullified: number;
+        residue: string[];
+    }>;
+    /**
+     * Convenience: the full restrict-then-propagate sequence for an ORDINARY (non-forget) delete of
+     * a lookup-referenced row — `checkLookupRefsRestrict` then `applyLookupRefsPropagation`. Used by
+     * `enforceRefsOnDelete` above (matrix-tier: the backing row IS an ordinary `Collection` record)
+     * and by `LookupHandle.delete()`'s injected `checkReferencesOnDelete` callback (reserved tier).
+     *
+     * #654: when `applyLookupRefsPropagation` reports residue, it is emitted here as a structured
+     * `lookup:propagation-residue` event — the delete/put return shape both callers consume stays
+     * `void`/unrelated, so an event is the additive channel that keeps the skip from ever being
+     * silent (mirrors the forget path's `ForgetResult.lookupReferencesResidue` channel).
+     */
+    enforceLookupRefsOnDelete(graph: ViaGraph, dimension: string, backingCollection: string, key: string): Promise<{
+        cascaded: number;
+        nullified: number;
+        residue: string[];
+    }>;
+    /**
+     * @internal — apply link `onDelete` policy when an endpoint record is
+     * deleted. `'strict'` throws (blocks the delete), `'cascade'`
+     * removes the touching link rows (tx-atomic when a transaction is active),
+     * `'warn'` leaves orphans for `checkIntegrity()`.
+     */
+    private enforceLinksOnDelete;
+    /**
+     * Look up the `RefDescriptor` the left collection declared for a
+     * given field name. Returns `null` when the field has no ref
+     * declaration — the Query builder turns that into an actionable
+     * error at plan time (before any records are touched).
+     *
+     * Implements the `joinResolver.resolveRef` half of the structural
+     * interface that `Collection.query()` consumes. See
+     * `query/join.ts` for the full design.
+     */
+    resolveRef(leftCollection: string, field: string): RefDescriptor | null;
+    /**
+     * Resolve a right-side join source by target collection name.
+     * Returns `null` for unknown collections so the Query executor can
+     * surface an actionable error naming the missing target.
+     *
+     * Implements the `joinResolver.resolveSource` half of the
+     * structural interface. The returned JoinableSource is a thin
+     * wrapper that reads the target collection's in-memory cache via
+     * `list()` / `get()` synchronously — the cache is populated by an
+     * earlier `ensureHydrated()` call through the target's query/list
+     * path. If the target has not been opened yet in this session the
+     * join will see an empty snapshot; consumers who hit this can
+     * open the target collection explicitly before running the query.
+     *
+     * Only same-vault targets are resolvable — cross-vault
+     * joins are explicitly forbidden by the architecture`).
+     */
+    resolveSource(collectionName: string): JoinableSource | null;
+    /**
+     * Walk every collection that has declared refs, load its records,
+     * and report any reference whose target id is missing. Modes are
+     * reported alongside each violation so the caller can distinguish
+     * "this is a warning the user asked for" from "this should never
+     * have happened" (strict violations produced by out-of-band
+     * writes).
+     *
+     * Returns `{ violations: [...] }` instead of throwing — the whole
+     * point of `checkIntegrity()` is to surface a list for display
+     * or repair, not to fail noisily.
+     */
+    checkIntegrity(): Promise<{
+        violations: RefViolation[];
+    }>;
+}

package/dist/with-shape/persisted-schemas/canonicalize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Deterministic JSON serializer: sorts object keys lexicographically at every
+ * depth so structurally-equivalent objects produce identical strings. Array
+ * order is preserved (arrays are semantically ordered).
+ *
+ * Used by {@link sha256Hex} to fingerprint a derived JSON Schema for
+ * hash-based skip on persisted-schema writes.
+ *
+ * @module
+ */
+export declare function canonicalize(value: unknown): string;

package/dist/with-shape/persisted-schemas/derive.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Derive a {@link PersistedSchemaEnvelope} from a Standard Schema v1
+ * validator. Supports zod 3 (via the optional `zod-to-json-schema` peer-dep)
+ * and zod 4 (via its native `z.toJSONSchema()`); both are loaded lazily so
+ * hub never statically imports zod. Other validator families write a stub
+ * envelope flagging the kind.
+ *
+ * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+ *
+ * @module
+ */
+import type { PersistedSchemaEnvelope } from './types.js';
+/**
+ * Heuristic Zod detection — uses the Standard Schema v1 `~standard.vendor`
+ * property (present in Zod v3.23+ and Zod v4+). Falls back to the
+ * `_def.typeName` heuristic for older Zod v3 builds that predate Standard
+ * Schema support.
+ */
+export declare function isZodSchema(value: unknown): boolean;
+/**
+ * Returns `true` when the validator was created with the Zod v4 native API
+ * (i.e. `import { z } from 'zod'` where zod resolves to v4). Zod v4 native
+ * schemas carry a `_zod` property whereas Zod v3 schemas (and the v3-compat
+ * shim shipped inside zod@4 at `zod/v3`) use `_def.typeName`.
+ *
+ * Kept duck-typed so hub never statically imports zod.
+ */
+export declare function isZod4Schema(value: unknown): boolean;
+export declare function derivePersistedSchema(validator: unknown): Promise<PersistedSchemaEnvelope>;

package/dist/with-shape/persisted-schemas/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Persisted JSON Schema — opt-in encrypted per-collection schema snapshot.
+ *
+ * Enable per collection via `vault.collection(name, { schema, persistJsonSchema: true })`.
+ * The derived JSON Schema is written to a `_schemas/<collection>` envelope
+ * encrypted with the collection's DEK; the next opening of the vault
+ * re-derives, hashes, and skips the write when nothing has changed.
+ *
+ * v0 supports Zod via the optional `zod-to-json-schema` peer-dep. Other
+ * Standard Schema validators (Valibot, ArkType, Effect Schema) write a
+ * stub envelope flagging the kind without a JSON Schema body.
+ *
+ * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+ *
+ * @module
+ */
+export type { PersistedSchemaEnvelope, PersistedSchemaKind } from './types.js';
+export { derivePersistedSchema, isZodSchema } from './derive.js';
+export { SCHEMAS_COLLECTION, loadPersistedSchema, savePersistedSchema, } from './storage.js';
+export { persistSchemaIfNeeded } from './register.js';
+export type { PersistSchemaResult } from './register.js';