@noy-db/hub 0.4.0 → 0.6.0-pre.0

package/dist/with-pod/index.d.ts

@@ -14,9 +14,30 @@
 export { writePod, readPod, readPodHeader, readPodCover, writeNoydbBundle, readNoydbBundle, readNoydbBundleHeader, resetBrotliSupportCache, } from './bundle.js';
 export type { Cover } from '../with-party/directory/cover/types.js';
 export type { WritePodOptions, WriteNoydbBundleOptions, ReadNoydbBundleOptions, NoydbBundleReadResult, } from './bundle.js';
+export { verifyPodHeader } from './bundle.js';
+export type { PodVerifyResult } from './bundle.js';
+export { signRecord, verifyRecord, signedBytes, POD_SIG_ALG } from './signature.js';
 export { NOYDB_BUNDLE_MAGIC, NOYDB_BUNDLE_PREFIX_BYTES, NOYDB_BUNDLE_FORMAT_VERSION, FLAG_COMPRESSED, FLAG_HAS_INTEGRITY_HASH, COMPRESSION_NONE, COMPRESSION_GZIP, COMPRESSION_BROTLI, validateBundleHeader, encodeBundleHeader, hasNoydbBundleMagic, } from './format.js';
-export type { CompressionAlgo, NoydbPodHeader, NoydbBundleHeader, } from './format.js';
+export type { CompressionAlgo, NoydbPodHeader, NoydbBundleHeader, UnlockMethod, } from './format.js';
 export { generateULID, isULID } from './ulid.js';
 export { wrapPodStore, createPodStore, wrapBundleStore, createBundleStore } from './pod-store.js';
 export type { WrappedPodNoydbStore, WrapPodStoreOptions, WrappedBundleNoydbStore, WrapBundleStoreOptions, } from './pod-store.js';
 export { BundleIntegrityError, BundleSealMismatchError, PodVersionConflictError, BundleVersionConflictError, BackupLedgerError, BackupCorruptedError, } from '../kernel/errors.js';
+export { readPodRedirect } from './bundle.js';
+export { signRedirect, verifyRedirect, followRedirects } from './redirect.js';
+export type { Redirect, RedirectHop, FollowRedirectsResult } from './redirect.js';
+export type { DocSigner } from '../with-audit/attestation/signer.js';
+export { RedirectDepthExceededError, RedirectLoopError, RedirectBadSignatureError, RedirectUnreachableError, } from '../kernel/errors.js';
+export { open } from './open.js';
+export type { OpenPodOptions, OpenPodResult } from './open.js';
+export { deriveSchemaManifest } from '../with-shape/manifest/derive.js';
+export type { DeriveSchemaManifestResult, LookupDEK } from '../with-shape/manifest/derive.js';
+export { loadSchemaManifestEntry } from '../with-shape/manifest/storage.js';
+export type { GetManifestDEK, LoadedSchemaManifest } from '../with-shape/manifest/storage.js';
+export type { SchemaManifest, SchemaManifestEntry } from '../with-shape/manifest/types.js';
+export { MANIFEST_COLLECTION, isManifestReservedCollection } from '../with-shape/manifest/reserved-collections.js';
+export { ManifestConflictError, MigrationRequiredError, PodHeaderVerificationError } from '../kernel/errors.js';
+export type { Noydb } from '../kernel/noydb.js';
+export type { Vault } from '../kernel/vault.js';
+export type { NoydbOptions, NoydbStore } from '../kernel/types.js';
+export type { EchoSecretParts } from '../kernel/enclave/index.js';

package/dist/with-pod/open.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `open(podBytesOrFile)` — the pod READ-path orchestrator (#941 Task 4).
+ *
+ * A free function (never a `Vault` method — `kernel/vault.ts` is at its
+ * line ceiling and open() needs no vault-internal state that isn't already
+ * reachable through published seams). Composes, in order:
+ *
+ *   1. `readPod` — parse + integrity-check the container (throws
+ *      `BundleIntegrityError` on a corrupted/truncated pod).
+ *   2. `verifyPodHeader` — only when `opts.trustedKeys` is supplied.
+ *      `'unsigned'` is benign (legacy pod, or `writePod({ sign: false })`)
+ *      and open() proceeds; `'untrusted'` / `'tampered'` are fail-closed —
+ *      `PodHeaderVerificationError` — mirroring `followRedirects`'s
+ *      `RedirectBadSignatureError` posture: once a caller opts into
+ *      verification, an unverifiable header is a hard stop.
+ *   3. `createNoydb` + `openVault` + `vault.load(dumpJson)` — the exact
+ *      unlock+restore sequence `bundle-roundtrip.test.ts` drives by hand.
+ *      The pod header carries no vault name (minimum-disclosure —
+ *      `format.ts`'s forbidden-fields list), so the caller names the
+ *      target vault via `opts.vault`.
+ *   4. Re-derive the `SchemaManifest` from the just-restored `_schemas/*`
+ *      (the source of truth — Task 3's `deriveSchemaManifest`), via a
+ *      NON-MINTING `LookupDEK` built from `loadKeyring`'s already-unwrapped
+ *      `UnlockedKeyring.deks` map directly (`with-party/team/keyring.js`).
+ *      **Not** `ensureCollectionDEK` (#941 review fix — Important 2): that
+ *      helper mints+persists a fresh DEK into `_keyring/<user>` for any
+ *      collection absent from the keyring, which is correct for a WRITE
+ *      path but wrong here — `deriveSchemaManifest` only ever reads
+ *      collections that already have a `_schemas` envelope, so an absent
+ *      DEK means "this principal can't decrypt this sibling" (e.g. a
+ *      collection-scoped grantee), never "new collection." The old
+ *      minting call polluted a scoped principal's freshly-restored keyring
+ *      with garbage sibling DEKs on every `open()`. The returned
+ *      `manifest` is that principal's own visible slice — see
+ *      `derive.ts`'s `LookupDEK` doc and `sync.ts`'s module doc for the
+ *      full rationale (the same distinction governs why the sync path
+ *      must SKIP rather than write a partial manifest).
+ *   5. Generation check (AC #4 coexistence): compare the HIGHEST
+ *      per-collection generation stamp carried by the restored manifest
+ *      against THIS store's schema-fence generation as it stood
+ *      immediately before the restore (0 for a brand-new vault; whatever a
+ *      coexisting local vault already had). If the pod is ahead and
+ *      `!opts.allowGenerationAhead`, throw `MigrationRequiredError` (the
+ *      same class `SchemaFenceController`'s write-path gate throws) — the
+ *      reader hasn't reconciled schema changes that happened elsewhere.
+ *      `allowGenerationAhead: true` is the documented dev override: open
+ *      proceeds, with a console warning. Divergence in the OTHER direction
+ *      (reader ahead of the pod) is non-fatal but also warned (#941
+ *      review, Important 3 — AC #4 coexistence divergence must be
+ *      observable in either direction, not just the bypass case).
+ *
+ *      NOTE: this deliberately reads per-collection entries, not
+ *      `manifest.generation` itself. `_meta/schema-fence` is local
+ *      session-coordination state and does NOT travel in a pod dump
+ *      (`with-pod/backup.ts`'s reserved-collection list carries `_schemas`
+ *      and `_manifest` but not `_meta`) — a fresh re-derive's top-level
+ *      `generation` is always driven by the (untouched-by-restore) target
+ *      store's own fence, not the pod's. Each `_schemas/<collection>`
+ *      envelope's own `generation` field DOES travel (it's stamped at
+ *      declare-time from the writer's real fence), so per-collection
+ *      entries are the only signal that survives a restore intact.
+ *
+ * @module
+ */
+import type { NoydbPodHeader } from './format.js';
+import type { PodVerifyResult } from './bundle.js';
+import type { Noydb } from '../kernel/noydb.js';
+import type { Vault } from '../kernel/vault.js';
+import type { NoydbOptions, NoydbStore, EchoSecretParts } from '../kernel/types.js';
+import type { SchemaManifest } from '../with-shape/manifest/types.js';
+export interface OpenPodOptions {
+    /** The ciphertext store to restore into (and where the opened `Vault` lives). */
+    readonly store: NoydbStore;
+    /**
+     * The target vault name. The pod header deliberately carries no vault
+     * name (minimum-disclosure — `NoydbPodHeader`'s forbidden-fields list),
+     * so the caller names the vault to restore into/open.
+     */
+    readonly vault: string;
+    /** User identifier — passed through to `createNoydb`. */
+    readonly user: string;
+    /** That user's secret — passed through to `createNoydb` / `loadKeyring`. */
+    readonly secret: string | EchoSecretParts;
+    /**
+     * Trusted signing keys (`keyId → publicKeyB64`). When supplied,
+     * `verifyPodHeader` runs and its result is returned as `verification`.
+     * Omitted → no verification attempted, `verification` is absent.
+     */
+    readonly trustedKeys?: Readonly<Record<string, string>>;
+    /**
+     * Passthrough to `createNoydb` for every option beyond `store`/`user`/
+     * `secret` (history/indexing/blobs/… strategies, `secretMode`, etc.).
+     */
+    readonly noydbOptions?: Omit<NoydbOptions, 'store' | 'user' | 'secret'>;
+    /**
+     * Dev override for the generation-ahead fence (AC #4). Default `false`:
+     * a pod whose schema manifest generation is ahead of this store's
+     * pre-restore fence generation throws `MigrationRequiredError`. `true`
+     * opens anyway, logging a console warning.
+     */
+    readonly allowGenerationAhead?: boolean;
+}
+export interface OpenPodResult {
+    readonly db: Noydb;
+    readonly vault: Vault;
+    readonly header: NoydbPodHeader;
+    /** Present iff `opts.trustedKeys` was supplied. */
+    readonly verification?: PodVerifyResult;
+    /** The pod's schema manifest, re-derived from the just-restored `_schemas/*`. */
+    readonly manifest?: SchemaManifest;
+}
+/**
+ * Open a `.noydb` pod: verify its integrity (and, opt-in, its signature),
+ * unlock + restore it into `opts.vault`, and re-derive its schema manifest.
+ * See the module doc for the full flow and the errors each step can throw.
+ */
+export declare function open(podFileOrBytes: Uint8Array, opts: OpenPodOptions): Promise<OpenPodResult>;

package/dist/with-pod/redirect.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Redirect record (#944) — a signed "this moved, go there" pointer carried
+ * in the pod's PLAINTEXT header (`NoydbPodHeader.redirect`, see
+ * `format.ts`) so a dispatcher can follow it pre-auth: no secret, no
+ * decompression.
+ *
+ * The record carries its OWN inner `sig` (via `signRecord`/`verifyRecord`
+ * from `signature.ts`) — independent from, and in addition to, the #943
+ * pod-header signature. A Redirect is REQUIRED to be signed: there is no
+ * legacy unsigned install base for this new record type, so an absent or
+ * invalid signature is invalid for following, not merely "unverified".
+ *
+ * Minimum-disclosure: the record is kept to exactly
+ * `{ v, target, reason, issuedBy, sig }` — no timestamps, no identities
+ * beyond the signer's `keyId` fingerprint.
+ */
+import type { DocSigner } from '../with-audit/attestation/signer.js';
+/**
+ * A signed pointer to another pod. `target` is a locator string or URL —
+ * the forthcoming #945 `Locator` type isn't built yet, so `target` stays a
+ * plain string for now (forward-seam noted, not blurred: a Redirect says
+ * "go elsewhere once"; a Locator will say "where cargo lives").
+ */
+export interface Redirect {
+    readonly v: 1;
+    readonly target: string;
+    readonly reason: 'moved' | 'release' | 'tombstone' | 'repoint';
+    readonly issuedBy: string;
+    readonly sig: string;
+}
+/**
+ * Sign a new Redirect record with `signer`. Builds the record minus `sig`,
+ * signs it via the #943 `signRecord` convention, and returns the complete
+ * signed record.
+ */
+export declare function signRedirect(signer: DocSigner, fields: {
+    readonly target: string;
+    readonly reason: Redirect['reason'];
+}): Promise<Redirect>;
+/**
+ * Verify a Redirect record's signature against `trustedKeys`
+ * (`keyId → publicKeyB64`). Fails closed: an `issuedBy` not present in
+ * `trustedKeys` is untrusted/unverifiable and returns `false`, same as a
+ * tampered or forged signature.
+ */
+export declare function verifyRedirect(record: Redirect, trustedKeys: Readonly<Record<string, string>>): Promise<boolean>;
+/** One followed hop's provenance — surfaced so a UI can show "moved from X via Y". */
+export interface RedirectHop {
+    readonly target: string;
+    readonly reason: Redirect['reason'];
+    readonly issuedBy: string;
+}
+/** Result of {@link followRedirects}: the terminal (non-redirect) pod's bytes, plus the ordered hop list that led there. */
+export interface FollowRedirectsResult {
+    readonly terminal: Uint8Array;
+    readonly hops: readonly RedirectHop[];
+}
+/**
+ * Follow a chain of Redirect records starting from `start`'s pod bytes,
+ * fetching each hop's target via `fetcher`, until a pod with no `redirect`
+ * header field (the terminal) is reached.
+ *
+ * HTTP-redirect discipline: each hop's Redirect is verified against
+ * `opts.trustedKeys` BEFORE it is followed (fail closed — an untrusted or
+ * forged hop never advances the walk), loops are detected on the target
+ * about to be followed, and the hop count is capped at `opts.maxDepth`
+ * (default 8). `fetcher` throwing or returning `null` for a target means
+ * that hop is unreachable.
+ *
+ * @throws {RedirectBadSignatureError} a hop's Redirect fails verification.
+ * @throws {RedirectLoopError} a hop's target was already followed in this chain.
+ * @throws {RedirectDepthExceededError} more than `maxDepth` hops were followed.
+ * @throws {RedirectUnreachableError} `fetcher` threw or returned `null` for a target.
+ */
+export declare function followRedirects(start: Uint8Array, fetcher: (target: string) => Promise<Uint8Array | null>, opts: {
+    readonly trustedKeys: Readonly<Record<string, string>>;
+    readonly maxDepth?: number;
+}): Promise<FollowRedirectsResult>;

package/dist/with-pod/signature.d.ts

@@ -0,0 +1,13 @@
+export declare const POD_SIG_ALG: "ed25519";
+/** The exact bytes a signature covers: utf8(canonicalJson(payload)). Exported for cross-checking. */
+export declare function signedBytes(payload: Record<string, unknown>): Uint8Array;
+/**
+ * Sign an arbitrary canonical record. `payload` MUST already exclude any
+ * `sig` field.
+ */
+export declare function signRecord(privateKeyPkcs8B64: string, payload: Record<string, unknown>): Promise<string>;
+/**
+ * Verify. `payload` is the record WITHOUT `sig`. Fails closed (false) on
+ * any malformed input.
+ */
+export declare function verifyRecord(publicKeyB64: string, sig: string, payload: Record<string, unknown>): Promise<boolean>;

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

@@ -0,0 +1,100 @@
+/**
+ * `Vault.listBehaviors()` builder (#947 Task 3) — a read-only, typed
+ * enumeration of the five behavior registries a vault can carry: guards,
+ * derivations, materialized views, overlays, satellites. Each entry
+ * carries the behavior's stable name (the declared `name`, or a
+ * deterministic fallback for an unnamed guard/derivation) plus the
+ * SERIALIZABLE half of its spec — every function-valued field (`check`,
+ * `derive`, `compute`, a rollup's `compute`, an MV's `query`/`rowKey`/
+ * `map`, …) is stripped before it reaches the caller. Registries the
+ * vault never initialized (no guard/derivation/MV/overlay/satellite
+ * strategy was passed to `createNoydb`) contribute an empty array.
+ *
+ * @module
+ */
+import type { GuardRegistry } from '../../with-audit/guards/registry.js';
+import type { DerivationRegistry } from '../../with-formula/derivations/registry.js';
+import type { MaterializedViewRegistry } from '../../with-formula/materialized-views/registry.js';
+import type { OverlayedViewRegistry } from '../../with-formula/overlay-views/registry.js';
+import type { OverlayFieldMergeMode } from '../../with-formula/overlay-views/types.js';
+import type { SatelliteRegistry } from '../satellites/registry.js';
+/** One guard's public identity + declarative (non-function) config. */
+export interface GuardBehaviorEntry {
+    readonly name: string;
+    readonly collection: string;
+    readonly frozenFields?: {
+        readonly fields: readonly string[];
+    };
+    readonly amendment?: {
+        readonly roles: readonly ('admin' | 'owner')[];
+    };
+}
+/** One derivation output declaration, functions (`key`) stripped. */
+export interface DerivationOutputEntry {
+    readonly shape: 'record' | 'array';
+    readonly collection: string;
+    readonly optional?: boolean;
+    readonly denorm?: readonly string[];
+    readonly maxFanout?: number;
+}
+/** One derivation's public identity + declarative (non-function) config. */
+export interface DerivationBehaviorEntry {
+    readonly name: string;
+    readonly source: string;
+    readonly sources?: readonly string[];
+    readonly triggerBy?: ReadonlyArray<{
+        readonly collection: string;
+        readonly on: string;
+        readonly maxFanout?: number;
+    }>;
+    readonly rollup?: {
+        readonly from: string;
+        readonly key: string;
+        readonly field: string;
+    };
+    readonly deterministic: true;
+    readonly outputs: Readonly<Record<string, DerivationOutputEntry>>;
+    readonly lifecycle: 'eager' | 'lazy' | {
+        readonly mode: 'eager' | 'lazy';
+        readonly maxDepth?: number;
+    };
+    readonly strict?: boolean;
+}
+/** One materialized view's identity + its spec, functions stripped recursively. */
+export interface MaterializedViewBehaviorEntry {
+    readonly name: string;
+    readonly spec: Readonly<Record<string, unknown>>;
+}
+/** One overlay's identity + config — `OverlayedViewSpec` carries no function fields. */
+export interface OverlayBehaviorEntry {
+    readonly name: string;
+    readonly base: string;
+    readonly overlay: string;
+    readonly shadowField: string;
+    readonly shadowValue: unknown;
+    readonly mergeMode?: OverlayFieldMergeMode;
+}
+/** One satellite pairing — `SatelliteSpec` carries no function fields. */
+export interface SatelliteBehaviorEntry {
+    readonly name: string;
+    readonly base: string;
+    readonly fields: readonly string[];
+    readonly joined?: string;
+}
+/** Typed, read-only enumeration of all five behavior registries. */
+export interface BehaviorSummary {
+    readonly guards: readonly GuardBehaviorEntry[];
+    readonly derivations: readonly DerivationBehaviorEntry[];
+    readonly materializedViews: readonly MaterializedViewBehaviorEntry[];
+    readonly overlays: readonly OverlayBehaviorEntry[];
+    readonly satellites: readonly SatelliteBehaviorEntry[];
+}
+/** The five registries `Vault.listBehaviors()` reads from — `null` when the vault never initialized that strategy. */
+export interface BehaviorRegistries {
+    readonly guards: GuardRegistry | null;
+    readonly derivations: DerivationRegistry | null;
+    readonly materializedViews: MaterializedViewRegistry | null;
+    readonly overlays: OverlayedViewRegistry | null;
+    readonly satellites: SatelliteRegistry | null;
+}
+export declare function buildBehaviorSummary(registries: BehaviorRegistries): BehaviorSummary;

package/dist/with-shape/introspection/derivation-key.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The deterministic fallback key for an UNNAMED derivation, shared by
+ * `dumpSchema`'s `describeDerivations` (walk.ts) and `listBehaviors`'s
+ * `buildDerivationEntries` (behaviors.ts) so the two surfaces always key the
+ * same unnamed derivation identically.
+ *
+ * Base key = the derivation's output-collection names, sorted and joined by
+ * `+` (or `source` when it has no outputs). On collision with any key already
+ * assigned in this enumeration (named or fallback, passed in `used`), a
+ * deterministic `#occurrence` suffix is appended (`base`, `base#1`, `base#2`, …)
+ * so two derivations with the same output set both appear.
+ *
+ * Takes the already-extracted output-collection list + source (rather than a
+ * `DerivationSpec`) so both the typed builder and walk.ts's duck-typed registry
+ * walk can call it without a shared concrete type.
+ */
+export declare function fallbackDerivationName(outputCollections: readonly string[], source: string, used: ReadonlySet<string>): string;

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

@@ -20,8 +20,20 @@ import type { I18nTextDescriptor } from '../../via/i18n/core.js';
 import type { ComputedFields } from '../../with-formula/computed/index.js';
 import type { RefDescriptor } from '../../kernel/refs.js';
 import type { ClassifiedFieldSpec } from '../../via/classified/descriptor.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
 export interface DescribedField {
     readonly key: string;
+    /**
+     * Stable, opaque per-field identity (#946) — survives a rename (the field
+     * keeps its id when its name/`key` changes). Sourced from the persisted
+     * schema's `PersistedSchemaEnvelope.fieldIds` map, so it is only present on
+     * the async `describeAsync()` path for a collection that has persisted a
+     * schema (`persistJsonSchema: true`) at least once; absent on the sync
+     * `describe()` path (no store I/O) and on any field with no persisted id
+     * yet.
+     */
+    readonly id?: string;
     /** Sync: inferred from config ('number'|'enum'|'string'|'array'|'unknown'). Async (Task 4): validator-derived. */
     readonly type: string;
     readonly optional: boolean;
@@ -175,6 +187,24 @@ export interface ZodFieldSlot {
  * No static zod import — all zod access is lazy via derivePersistedSchema.
  */
 export declare function deriveZodFields(schema: unknown): Promise<Record<string, ZodFieldSlot>>;
+/**
+ * Resolve the persisted-schema `fieldIds` map for `describeAsync()`'s
+ * `BuildDescriptionInput` (#946). Returns a spreadable partial so the call
+ * site can inline it with `...(await resolveDescribeFieldIds(...))` without
+ * an intermediate local — `collection.ts`'s `describe()` bodies are under a
+ * near-zero line-ceiling headroom.
+ *
+ * Silent-degrades to `{}` (no ids — every `DescribedField.id` stays
+ * `undefined`, never a describe() crash) on any failure: `getDEK` throwing,
+ * no persisted envelope yet, or an envelope with no `fieldIds` (legacy /
+ * never-persisted). Mirrors the leak/degrade posture of
+ * `satellites/dead-filter.ts`'s `liveBaseIdSetsForBundle`, but degrading to
+ * "no ids" is lossless here (unlike that filter's data-exposure tradeoff) —
+ * describe() simply omits `id` for every field.
+ */
+export declare function resolveDescribeFieldIds(store: NoydbStore, vaultName: string, collectionName: string, getDEK: (collectionName: string) => Promise<EnclaveKey>): Promise<{
+    fieldIds?: Record<string, string>;
+}>;
 export interface BuildDescriptionInput {
     readonly collection: string;
     readonly fieldMeta: Record<string, FieldMeta> | undefined;
@@ -223,6 +253,12 @@ export interface BuildDescriptionInput {
      * until they gain a consumer too.
      */
     readonly viaFragments?: Record<string, Record<string, unknown>> | undefined;
+    /**
+     * Persisted-schema `fieldName -> id` map (#946), resolved by the async
+     * describe path via {@link resolveDescribeFieldIds}. The sync path passes
+     * no `fieldIds` (no store I/O), so every field's `id` is `undefined` there.
+     */
+    readonly fieldIds?: Record<string, string> | undefined;
 }
 export { FieldMetaUnknownFieldError };
 /**

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

@@ -16,3 +16,4 @@ export type { FieldMeta, SemanticType } from './field-meta.js';
 export type { CollectionDescription, DescribedField, DescribeOptions } from './describe.js';
 export { applyListProjection } from './projection.js';
 export type { ListProjectionOptions } from './projection.js';
+export type { BehaviorSummary, GuardBehaviorEntry, DerivationBehaviorEntry, DerivationOutputEntry, MaterializedViewBehaviorEntry, OverlayBehaviorEntry, SatelliteBehaviorEntry, } from './behaviors.js';

package/dist/with-shape/introspection/subsystem-matrix.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Builds the `subsystems` block of the vault schema snapshot (#948 seam 5):
+ * the 4 registry-presence booleans (guards / derivations / materializedViews
+ * / overlayViews) UNION the 27 strategy-derived booleans — one per
+ * {@link StrategyKey}, `true` iff that service's resolved strategy differs
+ * from its un-opted-in default.
+ *
+ * The 4 registry keys are canonical: if a strategy key ever collides with one
+ * of them, the registry value wins (registries are spread last).
+ *
+ * @module
+ */
+import { type StrategyBag } from '../../port/with/strategies.js';
+/** The 4 registry-presence keys already reported before #948 seam 5. */
+export interface SubsystemRegistries {
+    readonly guards: boolean;
+    readonly derivations: boolean;
+    readonly materializedViews: boolean;
+    readonly overlayViews: boolean;
+}
+/** Registry keys UNION the 27 strategy-derived booleans, keyed by {@link StrategyKey} name. */
+export declare function buildSubsystemMatrix(strategies: StrategyBag, registries: SubsystemRegistries): Record<string, boolean>;

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

@@ -104,6 +104,7 @@ export interface CollectionDescriptor {
     readonly refs: Record<string, {
         readonly target: string;
         readonly mode: 'strict' | 'warn' | 'cascade';
+        readonly isArray?: true;
     }>;
     readonly validator?: {
         readonly kind: PersistedSchemaKind;
@@ -127,6 +128,7 @@ export interface OverlayViewDescriptor {
 export interface DerivationDescriptor {
     readonly source: string;
     readonly outputs: ReadonlyArray<string>;
+    readonly name?: string;
 }
 export interface InternalCollectionStats {
     readonly records: number;
@@ -137,7 +139,6 @@ export interface VaultSchemaSnapshot {
     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>;

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

@@ -10,6 +10,7 @@
  * paths and class identities are unchanged for existing consumers.
  */
 import { NoydbError } from '../../kernel/errors.js';
+import type { RefDescriptor } from '../../kernel/refs.js';
 export declare const LINK_COLLECTION_PREFIX = "_links_";
 /** Storage collection name for a logical link set. */
 export declare function linkCollectionName(name: string): string;
@@ -30,6 +31,19 @@ export interface LinkSpec {
     readonly b: string;
     readonly onDelete?: LinkOnDelete;
 }
+/**
+ * Validate + register a `vault.link(name, spec)` declaration. `a`/`b`
+ * accept either a collection name or a `ref(target)` descriptor (only
+ * `target` is used). Idempotent for an identical re-declaration; throws
+ * `ValidationError` for an invalid endpoint or a conflicting
+ * re-declaration. Body extracted out of `Vault.link()` (shrink-first,
+ * #947) — the kernel floor keeps a thin delegator.
+ */
+export declare function declareLink(linkRegistry: Map<string, LinkSpec>, name: string, spec: {
+    a: string | RefDescriptor;
+    b: string | RefDescriptor;
+    onDelete?: LinkSpec['onDelete'];
+}): void;
 /** One link tuple as returned by `of()` / `list()`. */
 export interface LinkRow {
     readonly a: string;

package/dist/with-shape/manifest/derive.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Derive the pod-wide {@link SchemaManifest} from the per-collection
+ * `_schemas/<collection>` records — the source of truth (#941 Task 3).
+ *
+ * The manifest is an INDEX, never a cache with independent state: every
+ * field in a {@link SchemaManifestEntry} is a direct projection of the
+ * matching `PersistedSchemaEnvelope` (`hash` → `contentHash`, `fieldIds` →
+ * `fieldIds`, `generation` → `generation`, falling back to the live fence's
+ * `currentSchemaVersion` for a legacy pre-#946 envelope that never got a
+ * generation stamp). Re-running this function against the same stored state
+ * always produces the same manifest — that's what makes round-trip identity
+ * (AC #2: dump → restore → re-derive matches the original) hold for free,
+ * with no special-cased restore logic.
+ *
+ * A collection whose `_schemas/<collection>` envelope decrypts successfully
+ * but has no derivable content (`hash === null` — a stub envelope for a
+ * non-Zod validator) is legitimately omitted from the index: there is no
+ * content hash to bind.
+ *
+ * ## Scoped principals: "cannot decrypt" is NOT "doesn't exist"
+ *
+ * A `_schemas/<collection>` envelope is encrypted under **that data
+ * collection's own DEK** — the same key its records use — NOT a shared
+ * `_schemas`-wide key. In a team vault, a collection-scoped grantee (e.g.
+ * `grant(..., { role: 'operator', permissions: { invoices: 'rw' } })`) holds
+ * only the DEKs their `permissions` name, plus every system-prefixed (`_*`)
+ * collection's DEK — `_manifest` included, by `grant()`'s "propagate system
+ * collections to every role" rule (`keyring.ts`). So a member scoped to
+ * `invoices` CAN decrypt `_manifest/schema` (the pod-wide index) but CANNOT
+ * decrypt a sibling's `_schemas/customers` envelope — even though that
+ * envelope is right there in `store.list(vault, SCHEMAS_COLLECTION)`.
+ *
+ * `lookupDEK` (the {@link LookupDEK} passed in) reflects this: it returns
+ * `undefined` for a collection name whose DEK the caller does not hold —
+ * deliberately NEVER minting a fresh one (see the module doc on
+ * `LookupDEK` for why). This function distinguishes that case
+ * (`undecodableCollections`) from "the schema envelope legitimately has no
+ * derivable content" (`hash === null`) — the caller (`sync.ts`) MUST treat
+ * an incomplete view differently: writing a manifest derived from a
+ * partial view would silently drop every collection this principal can't
+ * see. See `sync.ts`'s module doc for how the sync path handles this.
+ *
+ * @module
+ */
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { SchemaManifest } from './types.js';
+/**
+ * A NON-MINTING DEK lookup: returns the collection's DEK if the caller
+ * already holds it, `undefined` otherwise. Deliberately distinct from
+ * `storage.ts`'s `GetManifestDEK` (which mints+persists a fresh DEK for an
+ * absent collection — correct for a caller about to WRITE that collection,
+ * e.g. `_manifest` itself). `deriveSchemaManifest` only ever READS sibling
+ * collections it never created and has no business minting keys for — an
+ * absent DEK here means "not my collection to see," never "new collection
+ * that needs a key." Minting here would be worse than a no-op: it would
+ * silently persist a garbage DEK into the caller's OWN `_keyring/<user>`
+ * file (via `ensureCollectionDEK`'s `persistKeyring` side effect) that
+ * still can't decrypt anything — see `sync.ts` / `with-pod/open.ts`'s
+ * fix notes (#941 review).
+ */
+export type LookupDEK = (collectionName: string) => Promise<EnclaveKey | undefined>;
+export interface DeriveSchemaManifestResult {
+    /** The derived manifest — an index over every collection this principal could decrypt. */
+    readonly manifest: SchemaManifest;
+    /**
+     * Names present in `_schemas` (per `store.list`) whose envelope this
+     * principal could NOT decrypt — either no DEK held for that collection,
+     * or the DEK held failed to decrypt/parse it (treated the same: the
+     * caller cannot verify what's there, so it cannot safely be omitted or
+     * asserted). Empty for a principal with full visibility (typically the
+     * owner/admin/custodian). Non-empty means `manifest.collections` is
+     * DEFINITELY INCOMPLETE relative to the pod's true collection set —
+     * see `sync.ts` for why that must gate whether the manifest gets written.
+     */
+    readonly undecodableCollections: readonly string[];
+}
+/**
+ * Read the fence generation + every `_schemas/<collection>` envelope this
+ * principal can decrypt, and project them into a fresh {@link SchemaManifest}.
+ * `lookupDEK` is called once per collection found under `_schemas` (never
+ * mints — see {@link LookupDEK}). Names whose DEK isn't held, or whose
+ * envelope fails to decrypt/parse despite holding a DEK, are reported via
+ * `undecodableCollections` rather than silently dropped from the result.
+ */
+export declare function deriveSchemaManifest(store: NoydbStore, vault: string, lookupDEK: LookupDEK): Promise<DeriveSchemaManifestResult>;

package/dist/with-shape/manifest/reserved-collections.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The reserved `_manifest` collection — one record per pod, holding the
+ * manifest-set (schema / behavior / storage / access / app manifests, per
+ * the manifest-engine roadmap #941). A single collection is gated: records
+ * inside it are keyed by manifest kind. Only `schema` (record id `schema`)
+ * is implemented (#941, P0); `behavior`/`storage`/`access`/`app` are
+ * reserved record ids for future kinds (P1-P3) — not built yet.
+ *
+ * Reserved so `vault.collection('_manifest')` is refused (manifests are
+ * privileged, strict-CAS, ledger-audited records — never reachable through
+ * the generic public collection handle) and so the collection travels in a
+ * pod dump like every other reserved internal collection.
+ *
+ * Kept dependency-free (mirrors `with-party/team/reserved-secret-collections.ts`)
+ * so both the kernel (`vault.ts`) and other shape-layer modules can import it
+ * without an import cycle.
+ */
+/** Reserved collection holding the pod's manifest-set records. */
+export declare const MANIFEST_COLLECTION: "_manifest";
+/**
+ * The set of reserved manifest collection names. Currently just the single
+ * `_manifest` collection — record ids inside it (not collection names)
+ * distinguish manifest kinds.
+ */
+export declare const MANIFEST_RESERVED_COLLECTIONS: ReadonlySet<string>;
+/** True when `name` is a reserved manifest collection. */
+export declare function isManifestReservedCollection(name: string): boolean;