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

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

@@ -0,0 +1,66 @@
+/**
+ * Orchestrate the derive → hash → skip-or-write cycle for a collection's
+ * persisted JSON Schema. Called by the Vault at collection-registration
+ * time when the developer opts in via `collection({ persistJsonSchema:
+ * true })`.
+ *
+ * Skip semantics:
+ *
+ *   - Zod validators: skip when the new hash equals the stored hash.
+ *   - Non-Zod (stub envelopes have hash=null): skip when the stored
+ *     envelope's `kind` matches the freshly-detected kind (since there's
+ *     no body to compare yet — a kind change is the only signal).
+ *
+ * @module
+ */
+import type { SchemaUpdateStrategy, UpdateDecision } from '../schema-update/types.js';
+import type { NoydbStore, ClassifiedMarker } from '../../kernel/types.js';
+import type { PersistedSchemaEnvelope } from './types.js';
+import type { PairingMarker } from '../satellites/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+export interface PersistSchemaResult {
+    /** True when a fresh envelope was written to storage. */
+    readonly written: boolean;
+    /** True when an existing envelope matched and the write was skipped. */
+    readonly skipped: boolean;
+    /** The envelope that was either written or matched. */
+    readonly envelope: PersistedSchemaEnvelope;
+    /** The update-strategy decision, present when strategies ran. */
+    readonly decision?: UpdateDecision;
+}
+export declare function persistSchemaIfNeeded(opts: {
+    readonly store: NoydbStore;
+    readonly vault: string;
+    readonly collectionName: string;
+    readonly validator: unknown;
+    readonly dek: EnclaveKey;
+    readonly strategies?: readonly SchemaUpdateStrategy[];
+}): Promise<PersistSchemaResult>;
+/**
+ * Persist (or refresh) the C-A / R10 classified marker into the collection's
+ * `_schemas/<collection>` record, preserving any existing derived JSON-Schema
+ * body. Idempotent — a no-op when an equivalent marker is already stored.
+ * Independent of `persistJsonSchema`: called on the first classified write so a
+ * later naive handle can detect the drift cross-session.
+ */
+export declare function persistClassifiedMarker(opts: {
+    readonly store: NoydbStore;
+    readonly vault: string;
+    readonly collectionName: string;
+    readonly dek: EnclaveKey;
+    readonly marker: ClassifiedMarker;
+}): Promise<void>;
+/**
+ * Persist (or refresh) the R-S9 satellite pairing marker into the collection's
+ * `_schemas/<collection>` record, preserving any existing derived JSON-Schema
+ * body. Idempotent — a no-op when an equivalent marker is already stored.
+ * Independent of `persistJsonSchema`: called on satellite declaration so a
+ * later divergent re-declaration can be detected cross-session.
+ */
+export declare function persistSatelliteMarker(opts: {
+    readonly store: NoydbStore;
+    readonly vault: string;
+    readonly collectionName: string;
+    readonly dek: EnclaveKey;
+    readonly marker: PairingMarker;
+}): Promise<void>;

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

@@ -0,0 +1,61 @@
+/**
+ * Read / write the per-collection persisted-schema envelope. Mirrors the
+ * standard noy-db record envelope shape and is **AES-GCM encrypted with
+ * the collection's DEK** — the schema body (field names, enum values,
+ * constraints) is sensitive metadata, so it gets the same encryption
+ * envelope as the records it describes.
+ *
+ * Storage layout:
+ *
+ *   <vault>/_schemas/<collection>   →   EncryptedEnvelope
+ *
+ * The DEK passed to {@link savePersistedSchema} / {@link loadPersistedSchema}
+ * is the same key the collection uses for its records.
+ *
+ * @module
+ */
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { PersistedSchemaEnvelope } from './types.js';
+/** Reserved collection name where persisted schemas live. */
+export declare const SCHEMAS_COLLECTION: "_schemas";
+/**
+ * A decrypted persisted-schema read paired with the wrapping envelope's
+ * `_v`. The version is the optimistic-concurrency token: pass it back to
+ * {@link savePersistedSchema} as `expectedVersion` to make the write a CAS
+ * that rejects a stale put (see #583 — the `_schemas` record is shared by
+ * the JSON-Schema writer and the classified-marker writer).
+ */
+export interface PersistedSchemaEntry {
+    /** Wrapping envelope `_v` (0 when no record exists yet). */
+    readonly version: number;
+    /** Decrypted payload, or `undefined` when absent/corrupt/wrong-DEK. */
+    readonly payload: PersistedSchemaEnvelope | undefined;
+}
+/**
+ * Read the persisted-schema envelope for one collection together with its
+ * wrapping `_v`. The version reflects the raw stored envelope even when the
+ * payload cannot be decrypted/parsed (so a CAS still guards a corrupt record
+ * rather than silently clobbering it).
+ */
+export declare function loadPersistedSchemaEntry(store: NoydbStore, vault: string, collection: string, dek: EnclaveKey): Promise<PersistedSchemaEntry>;
+/**
+ * Read and decrypt the persisted-schema envelope for one collection.
+ * Returns `undefined` when no envelope has been written or when decryption
+ * fails (e.g. wrong DEK passed). Tolerates corrupted records — JSON parse
+ * failures surface as `undefined`, mirroring `_meta/handle`'s contract.
+ */
+export declare function loadPersistedSchema(store: NoydbStore, vault: string, collection: string, dek: EnclaveKey): Promise<PersistedSchemaEnvelope | undefined>;
+/**
+ * Encrypt and persist a schema envelope for one collection. Always
+ * overwrites any prior write (callers gate on hash equality before calling
+ * to avoid no-op writes).
+ *
+ * Pass `expectedVersion` — the `version` from {@link loadPersistedSchemaEntry}
+ * captured at load time — to make the write an optimistic CAS: on a store with
+ * `casAtomic`, `store.put` throws {@link ConflictError} when the record was
+ * bumped concurrently, so a lost update on the shared `_schemas` record is
+ * rejected instead of silently clobbering the other writer's field (#583).
+ * When omitted, keeps the legacy unconditional last-writer-wins behaviour.
+ */
+export declare function savePersistedSchema(store: NoydbStore, vault: string, collection: string, dek: EnclaveKey, payload: PersistedSchemaEnvelope, expectedVersion?: number): Promise<void>;

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

@@ -0,0 +1,54 @@
+/**
+ * Persisted-schema envelope shape.
+ *
+ * Stored encrypted under `_schemas/<collection>` with the same DEK as the
+ * collection's records. Auditors who can unlock the collection's data can
+ * also read its schema; nothing more.
+ *
+ * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+ *
+ * @module
+ */
+import type { ClassifiedMarker } from '../../kernel/types.js';
+import type { PairingMarker } from '../satellites/types.js';
+/** Family of Standard Schema v1 validator the persisted snapshot was derived from. */
+export type PersistedSchemaKind = 'Zod' | 'Valibot' | 'ArkType' | 'Effect' | 'Unknown';
+/**
+ * Plaintext payload encrypted into the `_data` field of the
+ * `_schemas/<collection>` envelope. The wrapper `EncryptedEnvelope` adds
+ * `_noydb`, `_v`, `_ts`, `_iv`, `_data` per the standard noy-db record
+ * format.
+ */
+export interface PersistedSchemaEnvelope {
+    readonly _noydb_schema: 1;
+    /** Detected validator family. */
+    readonly kind: PersistedSchemaKind;
+    /**
+     * JSON Schema (Draft 2020-12) derived from the validator. Null when
+     * derivation isn't yet supported for `kind`; in that case `reason` is
+     * populated.
+     */
+    readonly jsonSchema: object | null;
+    /** SHA-256 (hex) of the canonicalised JSON Schema, or null when unavailable. */
+    readonly hash: string | null;
+    /** Human-readable reason when `jsonSchema` is null. */
+    readonly reason?: string;
+    /** ISO-8601 timestamp of the most recent derivation write. */
+    readonly derivedAt: string;
+    /**
+     * C-A / R10 config-drift marker. Present when the collection declares
+     * classified digest-only fields. A handle opened WITHOUT `classifiedFields`
+     * (a naive handle, whose codec has `vdigFields === null`) reads this back and
+     * refuses to write — a silent plaintext/tag-drop write would corrupt the
+     * classified record. Independent of `persistJsonSchema`: a classified
+     * collection that never opts into schema persistence still writes this marker.
+     */
+    readonly classified?: ClassifiedMarker;
+    /**
+     * R-S9 satellite pairing marker. Present when this collection is declared
+     * as a satellite (`satelliteOf`). A later re-declaration of the same
+     * satellite must match `(base, fieldsHash, joined)` exactly or is refused —
+     * the satellite-pair analogue of {@link classified}'s config-drift guard.
+     */
+    readonly satellite?: PairingMarker;
+}

package/dist/with-shape/satellites/dead-filter.d.ts

@@ -0,0 +1,21 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * Build a live-base id set for every satellite collection detectable from
+ * its persisted `_schemas/<name>` pairing marker (#591 Task 10).
+ *
+ * The bundle-export path (`with-pod/bundle.ts`) has no reachable
+ * `SatelliteRegistry` — that registry is private to `Vault` and adding an
+ * accessor would grow a kernel file past its line-ceiling ratchet. The
+ * marker persisted by `ensureSatelliteMarker` (`_schemas/<satellite>`,
+ * decrypted with the satellite collection's own DEK — see
+ * `with-shape/persisted-schemas/storage.ts`) is the fallback pairing-info
+ * source that's always reachable from just a raw store + a per-collection
+ * DEK accessor, so export uses that instead of the in-memory registry.
+ *
+ * Returns a `Map` from satellite collection name to its base's live id set
+ * (existence.ts rule 1: absent or tombstoned base ⇒ not live). Only
+ * satellite collections are present as keys — callers should treat a
+ * missing key as "not a satellite, don't filter."
+ */
+export declare function liveBaseIdSetsForBundle(store: NoydbStore, vaultName: string, collectionNames: readonly string[], getDEK: (collectionName: string) => Promise<EnclaveKey>): Promise<Map<string, Set<string>>>;

package/dist/with-shape/satellites/declare.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Satellite declaration wiring (#591, archetype-③) — the full body behind
+ * `Vault.collection()`'s thin call-site: in-session reconcile (idempotent
+ * identical redeclare / R-S9 divergent refusal), sync validation
+ * (R-S3/R-S5/R-S8), the R-S7 forget-coverage gate, lazy registry + poison
+ * write-gate creation, registration, and the fire-and-forget postRegister
+ * (marker persistence + R-S1 cross-check). Kept dependency-narrow: no
+ * `Vault` import — the kernel supplies a {@link SatelliteDeclareContext}.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import { SatelliteRegistry } from './registry.js';
+/** The narrow slice of Vault that declaration wiring needs. */
+export interface SatelliteDeclareContext {
+    readonly adapter: NoydbStore;
+    readonly vaultName: string;
+    /** `forgetStrategy.subjects` — collection → subject field (R-S7 gate input). */
+    readonly forgetSubjects: Record<string, string>;
+    readonly getDEK: (collectionName: string) => Promise<EnclaveKey>;
+    /** The base collection's attached Standard Schema validator, if constructed. */
+    readonly getBaseSchema: (base: string) => unknown;
+    /** The base collection's constructed crdt mode, if any (R-S8 direction i). */
+    readonly getBaseCrdt: (base: string) => unknown;
+    /** True when `name` is an already-constructed collection (R-S5 joined-name guard). */
+    readonly collectionExists: (name: string) => boolean;
+    /** Registers the vault-wide poison write-gate; invoked at most once per vault. */
+    readonly registerPoisonHook: (hook: (e: {
+        readonly vault: string;
+        readonly collection: string;
+    }) => void) => void;
+    /**
+     * Iterates the vault's SyncEngine(s) (#591 Task 11) — used to wire the
+     * live pair-expander (once per vault, alongside `registerPoisonHook`; the
+     * closure captures the registry itself, not a snapshot, so pairs declared
+     * later are still picked up by push/pull filters) and to retroactively
+     * re-mirror conflict resolvers on every successful pair registration.
+     * No-op when sync is not configured.
+     */
+    readonly forEachSyncEngine: (fn: (engine: PairSyncEngine) => void) => void;
+}
+/** The narrow slice of SyncEngine that satellite declaration wiring drives (#591 Task 11). */
+interface PairSyncEngine {
+    setPairExpander(expander: (names: readonly string[]) => readonly string[]): void;
+    remirrorPairResolvers(names: readonly string[]): void;
+}
+export interface SatelliteDeclarationOptions {
+    readonly satelliteOf: string;
+    readonly fields?: readonly string[] | undefined;
+    readonly joined?: string | undefined;
+    readonly perRecordKeys?: boolean | undefined;
+    readonly crdt?: unknown;
+}
+/**
+ * Register `collectionName` as a satellite per `options`. Returns the
+ * (possibly newly created) registry — the caller stores it back on the vault.
+ * A refused declaration throws {@link SatelliteConfigError} and leaves NO
+ * side effect (no registry created, no hook registered).
+ */
+export declare function declareSatellite(ctx: SatelliteDeclareContext, collectionName: string, options: SatelliteDeclarationOptions, existingRegistry: SatelliteRegistry | null): SatelliteRegistry;
+export {};

package/dist/with-shape/satellites/existence.d.ts

@@ -0,0 +1,5 @@
+import type { NoydbStore } from '../../kernel/types.js';
+/** One undecrypted adapter `get` on the base — the store-shape the spec pins (zero extra crypto). */
+export declare function isBaseLive(adapter: NoydbStore, vault: string, base: string, id: string): Promise<boolean>;
+/** The set of base ids that are currently live — used to id-filter satellite `list()` results. */
+export declare function liveBaseIdSet(adapter: NoydbStore, vault: string, base: string): Promise<Set<string>>;

package/dist/with-shape/satellites/fanout.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fan-out writes for a base↔satellite pair (#591, Task 6): a joined `put`
+ * splits the record across both collections and writes base-then-satellite;
+ * a pair `delete` removes satellite-then-base. Either function reverts every
+ * already-executed leg (best-effort, raw adapter writes) and compensates
+ * each reverted collection's cache/dirty-tracking/change-stream on failure.
+ *
+ * Both legs are driven through `Collection.put`/`.delete` (encryption,
+ * ledger, history, cache, sync-dirty, change-emit all fire normally); only
+ * the REVERT writes go straight to the raw adapter, via the shared
+ * `bestEffortRevert` helper (`kernel/best-effort-revert.ts`) also used by
+ * `revertExecuted` (`with-commit/tx/transaction.ts`) — a neutral kernel-level
+ * home so this always-on satellite path can share the revert shape without
+ * depending on with-commit, a gated service.
+ *
+ * `deps.base()`/`deps.satellite()` may return either a raw `Collection` or
+ * one of this package's proxies (`makeSatelliteProxy` / `makeBaseProxy`) —
+ * every handle is unwrapped via `RAW_TARGET` before use so fan-out never
+ * re-enters a proxy's own `put`/`delete` override. Re-entering would either
+ * deadlock (the satellite proxy's `put` takes the same non-reentrant
+ * `registry.withPairLock` this module already holds) or recurse forever
+ * (the base proxy's `delete` calls straight back into `pairDelete`).
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { SatelliteSpec } from './types.js';
+import type { SatelliteRegistry } from './registry.js';
+export interface FanoutDeps {
+    readonly spec: SatelliteSpec;
+    readonly base: () => unknown;
+    readonly satellite: () => unknown;
+    readonly adapter: NoydbStore;
+    readonly vaultName: string;
+    readonly registry: SatelliteRegistry;
+}
+/** Split `record` across the pair by `spec.fields`, base leg first, satellite leg second. */
+export declare function joinedPut(deps: FanoutDeps, id: string, record: Record<string, unknown>): Promise<void>;
+/** Remove both legs of the pair, satellite first, base second. */
+export declare function pairDelete(deps: FanoutDeps, id: string): Promise<void>;

package/dist/with-shape/satellites/forget.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Forget fan-out (#591, Task 8): expands the base refs resolved from the
+ * encrypted subject index with a synthesized same-id ref for every base ref
+ * whose collection has a declared satellite.
+ *
+ * A satellite record is NEVER itself indexed in `_subject_index` (its writes
+ * only ever go through `joinedPut`, which never touches the subject-field
+ * write hook — see `noydb.ts#registerForgetHooks`), so `lookupSubject` alone
+ * would leave the satellite half of a pair permanently un-erasable. The
+ * synthesized ref carries `satelliteOf` (the base collection name) so:
+ *   - `vault.forget()`'s classification line can inherit `perRecordKeys`
+ *     from the BASE's forget-strategy entry (the satellite itself is never a
+ *     `subjects` key), and
+ *   - the synthesized ref's tombstone write can be held to R-S4 fail-loud
+ *     semantics distinct from a base ref's existing resilient handling.
+ *
+ * The synthesized ref is INTERLEAVED into the SAME list the caller iterates —
+ * immediately BEFORE its base ref, not appended after the whole list — so it
+ * traverses every purge stage below the tombstone (history, `_idx`/`_ftindex`,
+ * blobs, `_sealed`/`_sealed_cek`, vectors) identically to a base ref — there
+ * is no separate satellite-only code path.
+ *
+ * Ordering is load-bearing (retry black hole, #591 review C1): `vault.forget()`'s
+ * per-ref loop removes each ref's subject-index entry (the retry anchor) only
+ * at the END of that ref's own iteration. If the satellite ref instead ran
+ * AFTER its base ref (as a simple append), an R-S4 abort mid-satellite-ref (or
+ * a crash) would leave the base ref already fully processed — including its
+ * subject-index entry already removed — so a retried `forget(subjectId)` finds
+ * nothing to resolve and returns a clean, empty result while the satellite's
+ * heavy data stays un-shredded forever. Interleaving the satellite ref BEFORE
+ * its base ref means any R-S4 abort happens before the base's subject-index
+ * anchor is touched, so a retry re-discovers the same base ref (and
+ * re-synthesizes its satellite ref) until both actually shred.
+ */
+import type { SubjectRef } from '../../with-audit/forget/subject-index.js';
+import type { SatelliteRegistry } from './registry.js';
+/** A subject ref synthesized from a base ref via a declared satellite pairing. */
+export interface SatelliteSubjectRef extends SubjectRef {
+    readonly satelliteOf: string;
+}
+/**
+ * Expand `refs` (as resolved by `lookupSubject`) with one synthesized ref per
+ * base ref whose collection has a registered satellite. `registry` may be
+ * `null` (no satellite ever declared in this vault) — returns `refs`
+ * unchanged, byte-identical to pre-#591 behaviour.
+ */
+export declare function expandRefsWithSatellites(refs: readonly SubjectRef[], registry: SatelliteRegistry | null): ReadonlyArray<SubjectRef | SatelliteSubjectRef>;

package/dist/with-shape/satellites/index.d.ts

@@ -0,0 +1,3 @@
+/** Satellite collections barrel — spec/schema types + config error (#591). @module */
+export type { SatelliteSpec, PairingMarker, JoinedHandle } from './types.js';
+export { SatelliteConfigError } from '../../kernel/errors.js';

package/dist/with-shape/satellites/joined.d.ts

@@ -0,0 +1,19 @@
+/**
+ * JoinedHandle — the full-record access point for a base↔satellite pair
+ * declared with `joined:` (#591, Task 7). Deliberately narrow (spec § The
+ * model): get/put/delete/list/describe only, never a `Collection<T>` cast —
+ * reactive members (`subscribe`, `live`, …) are simply absent from the
+ * returned object, not stubbed.
+ *
+ * Reads compose under existence authority (spec § Convergence & existence
+ * authority, rule 1): the base row alone decides whether a record exists at
+ * all — `get`/`list` check it via an undecrypted adapter read
+ * (`isBaseLive`/`liveBaseIdSet`) before merging in the satellite side, so a
+ * base-absent-or-tombstoned id reads as fully gone even if a satellite
+ * envelope still lingers. Writes/deletes delegate wholesale to the Task 6
+ * fan-out (`joinedPut`/`pairDelete`), which already holds the pair lock and
+ * reverts on partial failure — this module adds no write logic of its own.
+ */
+import type { JoinedHandle, SatelliteSpec } from './types.js';
+import type { FanoutDeps } from './fanout.js';
+export declare function makeJoinedHandle<T extends Record<string, unknown>>(spec: SatelliteSpec, deps: FanoutDeps): JoinedHandle<T>;

package/dist/with-shape/satellites/marker.d.ts

@@ -0,0 +1,10 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { SatelliteSpec } from './types.js';
+/**
+ * Persist-or-reconcile the pairing marker in `_schemas/<satellite>`.
+ * First declaration writes { base, fieldsHash, joined }; later declarations
+ * must match exactly or are refused (R-S9). Lazy imports keep the satellite
+ * spine tree-shakeable (config-drift.ts pattern).
+ */
+export declare function ensureSatelliteMarker(store: NoydbStore, vaultName: string, spec: SatelliteSpec, dek: EnclaveKey): Promise<void>;

package/dist/with-shape/satellites/migrate-cek.d.ts

@@ -0,0 +1,26 @@
+/** The narrow slice of `Collection` the migration pass needs (mirrors `fanout.ts`'s `CollectionHandle` narrowing). */
+export interface SatelliteCekMigrationTarget {
+    /** Public config snapshot (`Collection.getConfig()`) — used to confirm the handle is genuinely in per-record-CEK mode before walking. */
+    getConfig(): {
+        readonly perRecordKeys?: boolean;
+    } | undefined;
+    _applyCutoverTransform(transform: (doc: Record<string, unknown>) => Record<string, unknown>): Promise<number>;
+}
+export interface SatelliteCekMigrationResult {
+    /** Records touched by this call (both freshly minted and already-migrated re-touches on a resumed run). */
+    readonly migrated: number;
+}
+/**
+ * Re-encrypt every record in `coll` under a per-record CEK. `coll` must be
+ * a collection handle already opened with `perRecordKeys: true` — see the
+ * file header for how the caller gets one past R-S7. Throws
+ * `SatelliteConfigError` (does NOT proceed) if `coll` is not genuinely in
+ * per-record-CEK mode — see the file header's mode-assertion note.
+ * Idempotent/resumable: safe to call again after a partial failure. NOT
+ * fenced against concurrent writers — see the file header's no-quiesce
+ * precondition; run this before the collection serves traffic.
+ *
+ * @param name The satellite collection's name — used only for the error
+ *   message below; identical to what the caller passed to `vault.collection()`.
+ */
+export declare function migrateSatelliteCek(name: string, coll: SatelliteCekMigrationTarget): Promise<SatelliteCekMigrationResult>;

package/dist/with-shape/satellites/post-register.d.ts

@@ -0,0 +1,6 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { SatelliteSpec } from './types.js';
+import type { SatelliteRegistry } from './registry.js';
+/** Async post-registration: R-S9 marker reconcile + R-S1/R-S5 derivable-schema cross-check. Failures poison, never throw. */
+export declare function postRegister(store: NoydbStore, vaultName: string, spec: SatelliteSpec, getDEK: (collectionName: string) => Promise<EnclaveKey>, baseSchema: unknown, registry: SatelliteRegistry): Promise<void>;

package/dist/with-shape/satellites/proxy.d.ts

@@ -0,0 +1,37 @@
+import { RAW_TARGET } from './raw-target.js';
+import type { SatelliteSpec } from './types.js';
+import type { SatelliteRegistry } from './registry.js';
+export { RAW_TARGET };
+/**
+ * Correlates a collection handle's `list()` output with the ids implied by
+ * cache-insertion order — `list()` returns bare records (no `id` field
+ * unless the caller put one), so ids are recovered positionally against the
+ * cache's own key order instead. Read AFTER `target.list()` resolves, so a
+ * not-yet-hydrated cache on the first read doesn't race a still-empty key
+ * snapshot. Invariant: `list()` must preserve cache-insertion order
+ * (collection.ts `list()` maps `[...cache.values()]`) — positional
+ * correlation depends on it. Drops any record whose position has no
+ * corresponding cache key (should not happen in practice; defensive only).
+ * Exported so `joined.ts` (#591, Task 7) can get the same [id, record]
+ * correlation for the base side without duplicating this logic.
+ */
+export declare function listWithIds(target: any): Promise<Array<[string, unknown]>>;
+/**
+ * Wraps a satellite's real `Collection<T>` in a `Proxy` that enforces
+ * existence authority (spec § Convergence & existence authority, rule 1)
+ * and R-S6 on top of it. Every member not explicitly overridden below
+ * falls through to the real collection unchanged — this is why the full
+ * ~50-member surface (describe, count, putMany, …) survives without
+ * hand-stubbing. Caches nothing: every call re-checks live base state.
+ */
+export declare function makeSatelliteProxy(target: any, spec: SatelliteSpec, registry: SatelliteRegistry): any;
+/**
+ * Wraps a satellite's BASE collection in a `Proxy` whose overrides are
+ * `delete` and `deleteMany` — both routed through `pairDelete` (this task) so
+ * removing a base record also removes its satellite row, in order, with
+ * revert-on-failure. `satellite()` is a thunk, not a resolved handle: at the
+ * moment a base is first requested the paired satellite may not exist yet in
+ * some call orders, and `fanout.ts` re-resolves + unwraps it lazily per call
+ * anyway.
+ */
+export declare function makeBaseProxy(target: any, spec: SatelliteSpec, registry: SatelliteRegistry, satellite: () => unknown): any;

package/dist/with-shape/satellites/raw-target.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Escape hatch: `proxied[RAW_TARGET]` returns the unwrapped collection — no
+ * existence check, no pair lock, no fan-out. Needed by callers (`fanout.ts`,
+ * a proxy's own internals) that already hold the pair mutex themselves;
+ * going back through a proxy's `put`/`delete` would re-enter
+ * `registry.withPairLock` on the same base and deadlock (non-reentrant —
+ * see `registry.ts:withPairLock`) or recurse forever (the base proxy's
+ * `delete` calls `pairDelete`, which must not call back into it).
+ *
+ * Lives in its own module (not `proxy.ts`) so `fanout.ts` can import it
+ * without creating a `proxy.ts` ⇄ `fanout.ts` import cycle — `proxy.ts`
+ * imports `pairDelete` from `fanout.ts` for `makeBaseProxy`.
+ */
+export declare const RAW_TARGET: unique symbol;

package/dist/with-shape/satellites/registry.d.ts

@@ -0,0 +1,19 @@
+import type { SatelliteSpec } from './types.js';
+export declare class SatelliteRegistry {
+    private readonly byBase;
+    private readonly bySat;
+    private readonly byJoin;
+    private readonly poisoned;
+    private readonly locks;
+    register(spec: SatelliteSpec): void;
+    satelliteOf(base: string): SatelliteSpec | null;
+    bySatellite(name: string): SatelliteSpec | null;
+    byJoined(name: string): SatelliteSpec | null;
+    isPairMember(name: string): boolean;
+    allSpecs(): readonly SatelliteSpec[];
+    expandNames(names: readonly string[]): string[];
+    poison(satellite: string, reason: string): void;
+    assertNotPoisoned(satellite: string): void;
+    /** Per-base async mutex: chains sections on a stored promise tail. */
+    withPairLock<R>(base: string, fn: () => Promise<R>): Promise<R>;
+}

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

@@ -0,0 +1,37 @@
+import type { CollectionDescription } from '../introspection/describe.js';
+/** One base↔satellite pair. v1: exactly one satellite per base. */
+export interface SatelliteSpec {
+    readonly base: string;
+    readonly satellite: string;
+    readonly fields: readonly string[];
+    readonly joined?: string | undefined;
+}
+/** Persisted into `_schemas/<satellite>` under `x-satellite` (R-S9 drift guard). */
+export interface PairingMarker {
+    readonly base: string;
+    readonly fieldsHash: string;
+    readonly joined?: string | undefined;
+    /**
+     * Lifetime epoch (#597) — an opaque, stable-per-collection-lifetime stamp
+     * minted the first time this marker is persisted and carried forward
+     * unchanged by every later re-declare of the SAME collection. Optional:
+     * markers persisted before this field existed have none. Deliberately
+     * excluded from `satelliteMarkersEqual` — see that function's comment.
+     * ADDITIVE ONLY today: there is no delete-collection API, so a stale
+     * marker on a reused name is unreachable; the epoch-MISMATCH rejection
+     * this would enable is a deferred follow-up once name reuse is possible.
+     */
+    readonly epoch?: string;
+}
+/**
+ * The full-record handle — deliberately NARROW (spec § The model): never a
+ * `Collection<T>` cast. `describe()` works (the @noy-db/ui contract);
+ * reactive APIs are absent from the type entirely.
+ */
+export interface JoinedHandle<T extends Record<string, unknown> = Record<string, unknown>> {
+    get(id: string): Promise<T | null>;
+    put(id: string, record: T): Promise<void>;
+    delete(id: string): Promise<void>;
+    list(): Promise<T[]>;
+    describe(): Promise<CollectionDescription>;
+}

package/dist/with-shape/satellites/validate.d.ts

@@ -0,0 +1,17 @@
+import type { SatelliteSpec } from './types.js';
+export interface SatelliteDeclarationInput {
+    readonly satellite: string;
+    readonly satelliteOf: string;
+    readonly fields: readonly string[] | undefined;
+    readonly joined?: string | undefined;
+    /** True when the named base is itself registered as a satellite (R-S3). */
+    readonly baseIsSatellite: boolean;
+    /** True when the declaring collection (or its base) sets crdtMode (R-S8). */
+    readonly crdtMode: boolean;
+    /** True when `joined` names an already-declared plain (non-pair) collection (R-S5). */
+    readonly joinedCollidesWithCollection: boolean;
+}
+/** Sync declaration refusals R-S3/R-S5/R-S8. Async cross-checks live in registry.ts. */
+export declare function validateSatelliteDeclaration(input: SatelliteDeclarationInput): SatelliteSpec;
+/** Order-insensitive stable hash of the fields list (FNV-1a over the sorted, joined names). */
+export declare function hashFields(fields: readonly string[]): string;

package/dist/with-shape/schema-update/client-registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Schema-cutover client registry. Each client keeps a
+ * heartbeat doc at `_meta/schema-fence:client:<clientId>` carrying its
+ * liveness (`lastSeen`) and the fence generation it has quiesced for
+ * (`quiescedAtVersion`). Plaintext envelope, like the fence doc.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+export interface ClientDoc {
+    readonly clientId: string;
+    readonly lastSeen: number;
+    readonly quiescedAtVersion: number | null;
+    /**
+     * Session that owns this writer (one user's writers across vaults). Additive
+     * and optional so legacy client docs (written without it) keep parsing;
+     * readers default it.
+     */
+    readonly sessionId?: string;
+}
+export declare function writeClientDoc(store: NoydbStore, vault: string, clientId: string, doc: {
+    lastSeen: number;
+    quiescedAtVersion: number | null;
+    sessionId?: string;
+}): Promise<void>;
+export declare function listClientDocs(store: NoydbStore, vault: string): Promise<ClientDoc[]>;
+/**
+ * True when every *active* client (lastSeen within staleMs of now) has
+ * `quiescedAtVersion === generation`. Stale clients are ignored. An empty
+ * active set is vacuously quiesced.
+ */
+export declare function activeQuiesced(store: NoydbStore, vault: string, opts: {
+    generation: number;
+    now: number;
+    staleMs: number;
+    excludeClientId?: string;
+}): Promise<boolean>;

package/dist/with-shape/schema-update/cutover.d.ts

@@ -0,0 +1,5 @@
+/** The coordinatedCutover update strategy (single-step — no from/to). */
+import type { SchemaUpdateStrategy, TransformFn } from './types.js';
+export declare function coordinatedCutover(opts: {
+    readonly transform: TransformFn;
+}): SchemaUpdateStrategy;

package/dist/with-shape/schema-update/delta.d.ts

@@ -0,0 +1,2 @@
+import type { SchemaDelta } from './types.js';
+export declare function computeSchemaDelta(stored: object, fresh: object, collection: string): SchemaDelta;

package/dist/with-shape/schema-update/dispatch.d.ts

@@ -0,0 +1,3 @@
+/** Ordered strategy evaluation: first non-`allow` decision wins. */
+import type { SchemaDelta, SchemaUpdateStrategy, UpdateContext, UpdateDecision } from './types.js';
+export declare function evaluateStrategies(delta: SchemaDelta, strategies: readonly SchemaUpdateStrategy[], ctx: UpdateContext): Promise<UpdateDecision>;