@noy-db/hub 0.6.0-pre.8 → 0.6.0

package/dist/with-commit/history/history.d.ts

@@ -1,5 +1,31 @@
+import type { RecordIdentity } from '../../kernel/enclave/index.js';
 import type { NoydbStore, EncryptedEnvelope, HistoryOptions, PruneOptions } from '../../kernel/types.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * The identity a history snapshot is **sealed against** — its STORAGE location,
+ * not the live record it is a copy of (#1041).
+ *
+ * ## Why storage, and why this is a decision rather than a detail
+ *
+ * A snapshot is a copy, so two identities are available: the live record
+ * (`collection`/`recordId`) or where the bytes actually land
+ * (`_history`/`historyId(...)`). They are not equivalent under attack.
+ *
+ * Binding the LIVE identity makes a snapshot's AAD **indistinguishable from the
+ * live record's at the same version** — so an untrusted store could serve a
+ * history entry *as the current record* and the client would accept it. It also
+ * leaves entries relocatable within `_history`.
+ *
+ * Binding STORAGE identity closes both. The cost is that the id must be known
+ * *before* the envelope is sealed, where `saveHistory` previously derived it
+ * *after* (from `envelope._v`) — which is precisely the restructure this
+ * function exists to make possible.
+ *
+ * `saveHistory` uses this too, so the sealed identity and the put location have
+ * **one definition** and cannot drift apart. Changing the layout here changes
+ * both at once, by construction.
+ */
+export declare function historyIdentity(collection: string, recordId: string, version: number): RecordIdentity;
 /** Save a history entry (a complete encrypted envelope snapshot). */
 export declare function saveHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, envelope: EncryptedEnvelope): Promise<void>;
 /** Get history entries for a record, sorted newest-first. */

package/dist/with-commit/history/index.d.ts

@@ -17,7 +17,7 @@
  */
 export { withHistory } from './active.js';
 export type { HistoryStrategy } from './strategy.js';
-export { saveHistory, getHistory, getVersionEnvelope, pruneHistory, clearHistory, } from './history.js';
+export { saveHistory, historyIdentity, getHistory, getVersionEnvelope, pruneHistory, clearHistory, } from './history.js';
 export { diff, formatDiff } from './diff.js';
 export type { ChangeType, DiffEntry } from './diff.js';
 export { LedgerStore, LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION, envelopePayloadHash, } from './ledger/store.js';
@@ -30,3 +30,4 @@ export { VaultInstant, CollectionInstant } from './time-machine.js';
 export type { VaultEngine } from './time-machine.js';
 /** The un-opted-in stub for this service — exported so callers can compare against it (#844). */
 export { NO_HISTORY } from './strategy.js';
+export type { RecordIdentity } from '../../kernel/enclave/index.js';

package/dist/with-commit/history/ledger/store.d.ts

@@ -237,7 +237,13 @@ export declare class LedgerStore {
      * version/timestamp/actor) fully intact for audit purposes.
      */
     purgeRecordDeltas(collection: string, id: string): Promise<number>;
-    /** Encrypt a JSON Patch into an envelope for storage. Mirrors encryptEntry. */
+    /**
+     * Encrypt a JSON Patch into an envelope for storage. Mirrors encryptEntry.
+     *
+     * `index` is the ledger index this delta will be stored under — the caller
+     * knows it before the entry exists, and it is what makes the envelope's
+     * identity bindable (#1051).
+     */
     private encryptDelta;
     /**
      * Read all entries in ascending-index order. Used internally by

package/dist/with-commit/history/strategy.d.ts

@@ -33,7 +33,7 @@ import type { LedgerStore } from './ledger/store.js';
 import type { JsonPatch } from './ledger/patch.js';
 import type { DiffEntry } from './diff.js';
 import type { VaultInstant, VaultEngine } from './time-machine.js';
-import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { EnclaveKey, RecordIdentity } from '../../kernel/enclave/index.js';
 /**
  * Options accepted by `HistoryStrategy.buildLedger`. Mirrors the
  * `LedgerStore` constructor verbatim — kept in this file so `core`
@@ -58,6 +58,16 @@ export interface HistoryStrategy {
      * `NO_HISTORY`.
      */
     saveHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, envelope: EncryptedEnvelope): Promise<void>;
+    /**
+     * The identity a snapshot of `collection/recordId@version` must be **sealed
+     * against** — its `_history` storage location (#1041).
+     *
+     * On the port because the kernel writes history snapshots but must not import
+     * `with-commit` to learn its layout. Exposing it here keeps the derivation in
+     * the module that owns the layout, and `saveHistory` uses the same function,
+     * so the sealed identity and the put location cannot drift.
+     */
+    historyIdentity(collection: string, recordId: string, version: number): RecordIdentity;
     /**
      * List history envelopes for a record, newest first. Throws under
      * `NO_HISTORY` — callers reach this via `collection.history()` /

package/dist/with-commit/numbering/index.d.ts

@@ -1,8 +1,3 @@
-/**
- * @category capability
- * Deferred numbering engine — store-clock-ordered, gap-free serials assigned
- * at an explicit numbering pass. See the design spec.
- */
 import type { NoydbStore } from '../../kernel/types.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
 import type { DeferredNumberingConfig } from './descriptor.js';

package/dist/with-commit/vault-head/active.d.ts

@@ -0,0 +1,2 @@
+import { type VaultHeadStrategy, type WithVaultHeadOptions } from './strategy.js';
+export declare function withVaultHead(opts?: WithVaultHeadOptions): VaultHeadStrategy;

package/dist/with-commit/vault-head/head.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The vault head's storage layer (#1044).
+ *
+ * A bucket is an ordinary encrypted record at `_head/<collection>::<n>`, so it
+ * inherits #1041's identity binding for free: the store cannot relocate a
+ * bucket, re-author it, or serve one bucket's bytes as another's. What it can
+ * still do is serve an OLD bucket, which is why {@link readBucket} enforces
+ * monotonicity against the caller's own record of what it last wrote.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import type { NoydbStore } from '../../kernel/types.js';
+/** `{ recordId → version }` for one bucket. */
+export type BucketBody = Record<string, number>;
+/**
+ * FNV-1a over `collection/id`. A hash, not a cipher: the bucket a record lands
+ * in is not secret — the store already sees which bucket was written, and it
+ * already saw the record's own address. Choosing something stronger would buy
+ * nothing and cost every write.
+ */
+export declare function bucketIndex(collection: string, id: string, buckets: number): number;
+export declare function bucketId(collection: string, id: string, buckets: number): string;
+export declare function readBucket(store: NoydbStore, vault: string, dek: EnclaveKey, bucket: string): Promise<{
+    body: BucketBody;
+    version: number;
+}>;
+export declare function writeBucket(store: NoydbStore, vault: string, dek: EnclaveKey, bucket: string, body: BucketBody, expectedVersion: number): Promise<void>;

package/dist/with-commit/vault-head/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@noy-db/hub/vault-head` — detect a store that WITHHOLDS (#1044).
+ *
+ * @packageDocumentation
+ */
+export { withVaultHead } from './active.js';
+export { verifyVaultHead, type HeadDiscrepancy, type HeadVerifyResult, type HeadVerdict, type HeadUnverifiableReason } from './verify.js';
+export { NO_VAULT_HEAD, VAULT_HEAD_COLLECTION, DEFAULT_HEAD_BUCKETS, type VaultHeadStrategy, type WithVaultHeadOptions, type HeadEntry, } from './strategy.js';
+export type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+export type { EnclaveKey } from '../../kernel/enclave/index.js';

package/dist/with-commit/vault-head/strategy.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `withVaultHead()` — the opt-in detector for **omission** (#1044).
+ *
+ * ## What it is for, and what it deliberately is not
+ *
+ * #1041 made every envelope self-authenticating at its identity, and #1042
+ * made the merge reject one that is not. What neither can catch is **absence**:
+ * a store that serves a genuine, unmodified `v1` when `v7` exists, or serves
+ * nothing at all. An authentic old envelope is indistinguishable from an
+ * authentic current one without external knowledge of what *should* be there.
+ *
+ * The head is that external knowledge: an authenticated `{id → version}`
+ * manifest the client writes and the store cannot forge. It is **not** a Merkle
+ * chain over content — content integrity is already handled, so the head needs
+ * only versions.
+ *
+ * ## Why it is opt-in when AAD is not
+ *
+ * AAD costs nothing to coordinate and closes *alteration*, so it is kernel. The
+ * head costs a write per commit and needs anti-entropy; on a single-device
+ * offline vault it defends against nothing. Making it kernel would tax every
+ * user for a multi-writer property. ADR 0003, Decision 3.
+ *
+ * `SECURITY.md` states the split exactly: a store cannot alter, relocate,
+ * re-tier, re-author or rewind a record; **without `withVaultHead()` it can
+ * still withhold or omit.**
+ *
+ * ## Bucketed, and why that is not a compromise
+ *
+ * ADR 0003 left head granularity open and asked for it to be sized early.
+ * Measured, at the documented 50K-record vault ceiling:
+ *
+ * | shape | write cost per commit | detection |
+ * |---|---|---|
+ * | one per-vault manifest | **1.1 MiB** | per-record |
+ * | one per collection | the same problem, renamed | per-record |
+ * | **bucketed, 256 buckets** | **~4.4 KiB** | per-record |
+ *
+ * Bucketing changes *only* write amplification. Each bucket still lists every
+ * one of its records' versions, so detection stays per-record — which is why
+ * this is not a trade-off between cost and strength. Verifying one pulled
+ * record reads one bucket rather than a megabyte.
+ *
+ * ## Wired as a bus OBSERVER, not a call in `collection.ts`
+ *
+ * That is what `kernel-surface` means by "register on the ServiceBus instead of
+ * growing this file", and it keeps the hot write path untouched for anyone who
+ * has not opted in: nothing is registered at all, so `hasHandlers` stays false
+ * and the dispatch never happens.
+ *
+ * Both `afterPut` AND `afterDelete`, because a delete is a version bump like
+ * any other. A head that stopped tracking deleted records would let a store
+ * resurrect one by withholding the tombstone — precisely the omission this
+ * exists to catch.
+ *
+ * ⚠️ The registration must be UNCONDITIONAL on anything but `enabled`. Its first
+ * draft sat inside `#registerForgetHooks()`, which returns early when no forget
+ * subjects are declared, so the head silently recorded nothing unless the vault
+ * happened to use an unrelated feature. The tests caught it only because they
+ * asserted a COUNT rather than "no error" — a head that records nothing raises
+ * no errors and sweeps perfectly clean.
+ *
+ * @packageDocumentation
+ */
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+/** Reserved collection the head's buckets live in. */
+export declare const VAULT_HEAD_COLLECTION: "_head";
+/** Default bucket count — see the sizing table above. */
+export declare const DEFAULT_HEAD_BUCKETS = 256;
+export interface WithVaultHeadOptions {
+    /**
+     * How many buckets the manifest is split across. Higher means smaller writes
+     * and more reads to sweep the whole vault; lower means the opposite.
+     * Changing it on an existing vault re-homes every entry, so treat it as a
+     * layout decision rather than a tuning knob.
+     */
+    readonly buckets?: number;
+}
+/** One record's expected state, as the client last committed it. */
+export interface HeadEntry {
+    readonly collection: string;
+    readonly id: string;
+    readonly version: number;
+}
+export interface VaultHeadStrategy {
+    /**
+     * Is the head actually keeping a manifest?
+     *
+     * An explicit flag rather than an identity check against the stub: the kernel
+     * decides whether to register the write-path observer at all, and
+     * `port-layering` forbids it importing `NO_VAULT_HEAD` to compare. Without
+     * this, every write in a vault that never opted in would still pay a cache
+     * lookup and a no-op call.
+     */
+    readonly enabled: boolean;
+    /** Bucket a record id lands in — pure, so callers can pre-group a batch. */
+    bucketFor(collection: string, id: string): string;
+    /**
+     * Record `entry` as the client's expectation for that record.
+     *
+     * Called on every committed write, INSIDE the same logical operation, so
+     * there is no window where the record exists and the head does not know it.
+     */
+    note(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, entry: HeadEntry): Promise<void>;
+    /**
+     * What the client expects for `collection/id`, or `null` if the head has
+     * never seen it.
+     */
+    expected(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string, id: string): Promise<number | null>;
+    /**
+     * Every record the head knows about in `collection` — the set a sweep
+     * compares against what the store actually serves, which is how DELETION
+     * SUPPRESSION is caught. A withheld record is absent from the store but
+     * present here.
+     */
+    knownIn(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string): Promise<ReadonlyMap<string, number>>;
+}
+/**
+ * The un-opted-in stub. `note` is a NO-OP rather than a throw: the write path
+ * calls it unconditionally, and a vault without the head must simply not keep
+ * one. The READ side throws, because asking what the head expects when there is
+ * no head is a caller error, not a silent "nothing to report" — the latter
+ * would look exactly like a clean sweep.
+ */
+export declare const NO_VAULT_HEAD: VaultHeadStrategy;
+export type { EncryptedEnvelope };

package/dist/with-commit/vault-head/verify.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The sweep — comparing what the head expects against what the store serves (#1044).
+ *
+ * This is the only place absence becomes visible. #1041 and #1042 can reject a
+ * record that lies about itself; neither can notice one that never arrived, or
+ * one served at an older version than the client wrote. Both are indistinguishable
+ * from the truth without an independent record of what should be there.
+ *
+ * @packageDocumentation
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { VaultHeadStrategy } from './strategy.js';
+/** One record the store is not serving faithfully. */
+export interface HeadDiscrepancy {
+    readonly collection: string;
+    readonly id: string;
+    /** What the client last committed. */
+    readonly expected: number;
+    /**
+     * What the store serves now — or `null` when it serves nothing.
+     *
+     * The two are different attacks wearing the same result. `null` is
+     * **suppression**: the record is gone. A lower number is **rollback**: an
+     * authentic older version served in place of the current one, which is the
+     * case no amount of per-envelope authentication can see.
+     */
+    readonly actual: number | null;
+    readonly kind: 'withheld' | 'rolled-back';
+}
+/**
+ * Why a sweep could not reach a conclusion.
+ *
+ * - `'no-expectations'` — the head holds nothing for this collection. A fresh
+ *   vault, a head switched on after the fact, or a **restore from a snapshot**:
+ *   `_head` is `_`-prefixed, so `loadAll` excludes it and a restored vault has
+ *   no head to compare against.
+ * - `'store-cannot-cas'` — the store does not advertise `capabilities.casAtomic`,
+ *   so two writers racing on one bucket can silently lose an entry. A lost entry
+ *   is a record the sweep stops expecting, which is a false clean.
+ */
+export type HeadUnverifiableReason = 'no-expectations' | 'store-cannot-cas';
+/**
+ * ## Three-way, deliberately (#1101)
+ *
+ * - `'verified'` — the head held expectations, every one was met, and the store
+ *   can serialize head writes.
+ * - `'unverifiable'` — the sweep could not conclude. See `because`.
+ * - `'tampered'` — at least one discrepancy. Positive evidence, so it wins over
+ *   any `unverifiable` reason present at the same time.
+ *
+ * **The middle value is the point, and collapsing it is wrong in a different
+ * direction each way:** folded into "clean" it hides withholding, which is the
+ * one thing this service exists to catch; folded into "tampered" it cries wolf
+ * on a vault that is merely unexamined.
+ *
+ * That is not hypothetical. #1044's own first bug was a head that recorded
+ * nothing and swept **perfectly clean** — the degraded state rendered
+ * identically to a healthy one, which is why its test asserts `checked` before
+ * anything else. A two-way verdict makes that state a supported outcome.
+ */
+export type HeadVerdict = 'verified' | 'unverifiable' | 'tampered';
+export interface HeadVerifyResult {
+    readonly verdict: HeadVerdict;
+    readonly checked: number;
+    readonly discrepancies: readonly HeadDiscrepancy[];
+    /**
+     * Non-empty only when `verdict === 'unverifiable'`.
+     *
+     * There is deliberately no `clean: boolean`. It could not distinguish "no
+     * expectations" from "all expectations met" — both rendered `true` — and that
+     * indistinguishability *was* the defect. Replacing it rather than keeping it
+     * alongside forces every caller to face the three-way.
+     */
+    readonly because: readonly HeadUnverifiableReason[];
+}
+/**
+ * Sweep one collection.
+ *
+ * **A record the store serves that the head does NOT know is not reported.**
+ * That is not an oversight: the head can be enabled on an existing vault, and
+ * every pre-existing record would otherwise read as an anomaly. The head's
+ * claim is one-directional — *what I wrote must still be there* — and an
+ * unknown record simply falls outside it.
+ *
+ * **A HIGHER version than expected is also not reported**, for the same reason:
+ * another device legitimately advanced it. The head detects going backwards, not
+ * moving forwards.
+ */
+export declare function verifyVaultHead(head: VaultHeadStrategy, store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string): Promise<HeadVerifyResult>;

package/dist/with-formula/materialized-views/dependency-analyzer.d.ts

@@ -65,6 +65,10 @@ export declare function summarizeUnionPlan<T extends Record<string, unknown>>(sp
  * one-to-one attachments and collect legs are independent
  * hash-grouped passes, so declaration order never changes the
  * materialized rows — a pure reorder must NOT force a refresh.
+ * `from` (#1140) constrains the legal orderings (a leg must follow the
+ * alias it attaches to) without making order meaningful: each descriptor
+ * carries its own `@alias`, and aliases are unique, so the sorted set
+ * still determines the leg graph exactly.
  *
  * The projection `map` is NOT fingerprinted (identical limitation as
  * the UNION arm `map`); consumers must bump the MV's `name` when

package/dist/with-formula/materialized-views/projection-legs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Projection-leg topology (#810, extended by #1140).
+ *
+ * A projection MV's legs originally all attached to the PRIMARY row: a forward
+ * leg named an FK field on `projection.source`, and a reverse `collect` leg's
+ * `on` field had to `ref()` the source itself. Anything two FKs away was
+ * therefore inexpressible — `bill → entity → client` has no leg shape, because
+ * the bill has no `clientId` and `clients.entityId` refs `entities`, not
+ * `bills`.
+ *
+ * `from` closes that: a leg may attach to a previously-declared ALIAS instead of
+ * to the primary row. This module owns the two questions that follow from it —
+ * *is this leg graph well-formed?* and *which collection does a leg's rows come
+ * from?* — so neither the registry nor the executor has to re-derive them.
+ *
+ * **Why cycles are impossible by construction, and there is no depth cap.**
+ * `from` may only name an alias declared EARLIER in `joins`. A leg can therefore
+ * never reach forward, the graph is a forest rooted at the primary row, and its
+ * depth is bounded by the number of legs. Validation refuses an unknown or
+ * not-yet-declared alias, which is the same check.
+ */
+import type { ProjectionJoinLeg, ProjectionSpec } from './types.js';
+/** Reverse (one-to-many) leg — discriminated on `collect`, as the type is. */
+export declare function isCollectLeg(leg: ProjectionJoinLeg): leg is Extract<ProjectionJoinLeg, {
+    collect: string;
+}>;
+/**
+ * Refuse a malformed leg graph where `withMaterializedView()` checks the rest of
+ * the leg shape — at spec CONSTRUCTION, not at vault open and not at first
+ * materialization. Alias wiring is pure configuration: it needs no refs, no
+ * records and no store, so the earliest failure is the best one.
+ * (Ref EXISTENCE still resolves at first materialization, unchanged — refs
+ * cannot exist until after `openVault()` returns.)
+ */
+export declare function validateProjectionLegs<T extends Record<string, unknown>>(mvName: string, projection: ProjectionSpec<T>): void;
+/**
+ * The collection a leg's rows come from — the primary source for a root leg, the
+ * `from` leg's own target otherwise.
+ *
+ * Returns `null` when a forward `ref()` somewhere along the chain is not
+ * declared yet, which at registration time is the normal case rather than an
+ * error: refs are declared after `openVault()` returns, so the registry retries
+ * this on every dispatch until it resolves (`_pendingForwardDeps`).
+ *
+ * `resolveRef` is passed in rather than imported so this module stays free of
+ * vault wiring — the registry hands it the ref registry's `getOutbound`, the
+ * executor hands it a join context lookup. Both answer the same question.
+ */
+export type RefLookup = (collection: string, field: string) => {
+    target: string;
+} | null;
+export declare function resolveLegOwner(leg: ProjectionJoinLeg, joins: ReadonlyArray<ProjectionJoinLeg>, source: string, resolveRef: RefLookup): string | null;
+/**
+ * The collection a FORWARD leg resolves INTO — i.e. its dependency. `null` while
+ * any ref in the chain (including this leg's own) is still undeclared.
+ */
+export declare function resolveForwardLegTarget(leg: Extract<ProjectionJoinLeg, {
+    field: string;
+}>, joins: ReadonlyArray<ProjectionJoinLeg>, source: string, resolveRef: RefLookup): string | null;

package/dist/with-formula/materialized-views/registry.d.ts

@@ -54,6 +54,33 @@ export declare class MaterializedViewRegistry {
      * target has resolved (see `_resolvePendingForwardDeps`).
      */
     private readonly _pendingForwardDeps;
+    /**
+     * Query-form strategies whose `query()` callback could not be planned at
+     * registration time because a `.join()` names a field whose `ref()` is not
+     * declared YET (#1139).
+     *
+     * Registration runs inside `openVault()`; a collection's refs can only be
+     * declared afterwards, so for a query-form MV that joins a declared FK there
+     * is NO call ordering the consumer can choose — the plan is simply built too
+     * early. Rather than failing the vault open, the strategy is parked here and
+     * replanned from {@link resolvePendingPlans}, which every write dispatch and
+     * `vault.refreshView()` call runs first. This is the query-form counterpart
+     * of `_pendingForwardDeps`, one level up: that defers a leg's TARGET, this
+     * defers the whole plan.
+     *
+     * Only `RefNotDeclaredError` parks a strategy. Every other planning failure
+     * still throws out of `openVault()` exactly as before, so a typo'd source or
+     * a malformed spec keeps its loud, early error.
+     *
+     * A parked strategy is invisible until it resolves: it contributes no
+     * `_bySource` entries and no cycle-detection edges (same caveat as a
+     * late-resolved forward target — `edges()` runs once at vault open). It also
+     * cannot be dispatched, which is why {@link hasPendingPlans} forces the
+     * conservative branch in `Collection._txAtomicSafe`: the atomic write path
+     * skips MV dispatch, and skipping it here would mean the write that was
+     * supposed to trigger the first replan is the one that gets missed.
+     */
+    private readonly _pendingPlans;
     /**
      * Register an MV. Invokes `spec.query()` once at registration time to
      * read the plan + join context; the resulting `Query<T>` is discarded
@@ -68,6 +95,29 @@ export declare class MaterializedViewRegistry {
     register(spec: MaterializedViewSpec<any>, db: MVQueryContext, options?: {
         knownCollections?: (name: string) => boolean;
     }): Promise<void>;
+    /**
+     * `true` while any query-form strategy is still unplanned (#1139). Read by
+     * `Collection._txAtomicSafe`, which must refuse the atomic write path while
+     * this holds — see the `_pendingPlans` doc comment for why.
+     */
+    hasPendingPlans(): boolean;
+    /**
+     * Replan every parked query-form strategy (#1139). Called at the head of both
+     * write dispatchers and of `vault.refreshView()`, so a strategy resolves on the
+     * first write or refresh after its source collection's refs are declared —
+     * which is the earliest moment it could produce a correct plan, and strictly
+     * before the first moment it could have any output to produce.
+     *
+     * Each entry is handed straight back to {@link register}, so a strategy that
+     * is STILL unplannable simply re-parks itself and the next dispatch tries
+     * again. Idempotent and cheap: the array empties as strategies resolve, and
+     * both callers skip the await entirely once it is empty.
+     *
+     * A late-resolved strategy does NOT retro-feed `edges()` — the unified cycle
+     * pass runs once at vault open, before refs exist. Same caveat, and the same
+     * reason, as a late-resolved forward-leg target.
+     */
+    resolvePendingPlans(): Promise<void>;
     /** All MVs that depend on `source`, in registration order. */
     mvsForSource(source: string): ReadonlyArray<RegisteredMV>;
     /**

package/dist/with-formula/materialized-views/types.d.ts

@@ -154,19 +154,27 @@ export interface ProjectionSpec<TRow extends Record<string, unknown>> {
  *   FK on the projection source into an attached right-side record
  *   (record | null) under `as`.
  * - **Reverse "collect" leg** — every row of `collect` whose `on`
- *   field references the primary record's id, attached as a
+ *   field references the attach point's id, attached as a
  *   possibly-empty ARRAY under `as`. `on` must carry a `ref()`
- *   declared on the `collect` collection targeting the projection
- *   `source` — checked at first materialization (parity with
- *   join-time ref errors). `maxRows` here is a PER-PRIMARY-ROW
- *   fan-out ceiling (default: the join default); exceeding it throws
- *   `JoinTooLargeError`.
+ *   declared on the `collect` collection targeting that attach point
+ *   — checked at first materialization (parity with join-time ref
+ *   errors). `maxRows` here is a PER-ROW fan-out ceiling (default:
+ *   the join default); exceeding it throws `JoinTooLargeError`.
+ *
+ * Both kinds attach to the primary row by default, and to a
+ * previously-declared alias when `from` is set (#1140).
  */
 export type ProjectionJoinLeg = {
-    /** FK field on the projection source (must have a `ref()` declared). */
+    /** FK field on this leg's attach point (must have a `ref()` declared). */
     readonly field: string;
     /** Alias under which the resolved right-side record attaches. */
     readonly as: string;
+    /**
+     * Attach to a previously-declared FORWARD leg's alias instead of to the
+     * primary row (#1140) — `field` is then read off that leg's record and
+     * resolved through a `ref()` on ITS collection. See the union's doc.
+     */
+    readonly from?: string;
     /** Per-side row ceiling override. `undefined` → the join default. */
     readonly maxRows?: number;
     /** Planner strategy override. `undefined` → auto-select. */
@@ -174,11 +182,40 @@ export type ProjectionJoinLeg = {
 } | {
     /** Sibling collection to collect from. */
     readonly collect: string;
-    /** FK field on `collect` (`ref()` targeting the projection source required). */
+    /** FK field on `collect` — a `ref()` targeting this leg's attach point. */
     readonly on: string;
     /** Alias under which the collected array attaches. */
     readonly as: string;
-    /** Per-primary-row fan-out ceiling. `undefined` → the join default. */
+    /**
+     * Attach to a previously-declared FORWARD leg's alias instead of to the
+     * primary row (#1140): `on` must then `ref()` THAT leg's collection, and
+     * rows are matched against that leg's record id.
+     *
+     * This is what makes a two-hop lookup expressible. For
+     * `bill → entity → client`, the client is not reachable from the bill: a
+     * forward leg would need a `bill.clientId` that does not exist, and a
+     * collect leg would need `clients.entityId` to ref `bills` when it refs
+     * `entities`. With `from` it is one line:
+     *
+     * ```ts
+     * joins: [
+     *   { field: 'entityId', as: 'entity' },
+     *   { from: 'entity', collect: 'clients', on: 'entityId', as: 'clients' },
+     * ]
+     * ```
+     *
+     * The alternatives it replaces are both bad: denormalizing a redundant FK
+     * onto the source reintroduces exactly the duplicated relationship a
+     * projection MV exists to avoid, and dropping back to app code forfeits
+     * the dependency tracking it was adopted for.
+     *
+     * `from` may only name a leg declared EARLIER, and only a FORWARD one — a
+     * collect leg holds an array, not a record. Both are refused at
+     * registration. The backward-only rule is also why no depth cap is
+     * needed: a cycle cannot be spelled.
+     */
+    readonly from?: string;
+    /** Per-row fan-out ceiling. `undefined` → the join default. */
     readonly maxRows?: number;
 };
 /**
@@ -198,6 +235,23 @@ export interface MaterializedViewSpec<TRow extends Record<string, unknown>> {
      * without pre-existing in-scope references; called again at each
      * refresh.
      *
+     * **One exception to "at registration time" (#1139).** Registration runs
+     * inside `openVault()`, and a collection's `refs` can only be declared after
+     * that returns — so a query that `.join()`s a declared FK cannot possibly
+     * resolve it on the registration call. When that happens the strategy is
+     * PARKED rather than failed, and replanned on the first write dispatch or
+     * `vault.refreshView()` — by which time the refs exist. The callback must
+     * therefore be safe to invoke more than once before the view first
+     * materializes, which it already had to be (it runs again at every refresh).
+     *
+     * Every other planning failure — a typo'd collection, a malformed spec, a
+     * throw from your own callback — still surfaces out of `openVault()`
+     * immediately. Only a not-yet-declared ref defers.
+     *
+     * While parked, the strategy is invisible: it contributes no cycle-detection
+     * edge (that pass runs once, at vault open) and appears in neither
+     * `refreshView()` nor the source dispatch map until it resolves.
+     *
      * Built via the same `Query<T>` chainable builder used elsewhere —
      * `.where()`, `.join()`, `.groupBy()`, `.aggregate()`. The
      * dependency analyzer walks the returned plan to determine source
@@ -243,10 +297,14 @@ export interface MaterializedViewSpec<TRow extends Record<string, unknown>> {
      *
      * Dependencies are all AUTO: `{source} ∪ forward ref() targets ∪
      * collect collections` (explicit {@link sources} remains additive).
-     * Forward targets resolve from the source collection's `ref()`
+     * Forward targets resolve from the attach point's `ref()`
      * declarations; those are declared by user code AFTER the vault
      * opens (registration time), so the registry folds them into the
      * dependency set on the first MV dispatch that finds them declared.
+     * A leg-relative forward leg (#1140) resolves its whole `from` chain
+     * the same way, so a two-hop leg simply lands one dispatch later
+     * than a one-hop one. A collect leg needs none of this: its
+     * dependency is the literal `collect` name whatever it attaches to.
      */
     projection?: ProjectionSpec<TRow>;
     /**

package/dist/with-party/directory/cover/storage.d.ts

@@ -1,11 +1,3 @@
-/**
- * Persistence helpers for `_meta/public-envelope` — the cover's
- * frozen wire location. Mirrors the bypass-AES pattern used by
- * `_meta/handle` and `_meta/policy` — the document is plaintext
- * JSON, the envelope's `_iv` field is left empty.
- *
- * @module
- */
 import type { NoydbStore } from '../../../kernel/types.js';
 import type { Cover } from './types.js';
 /**

package/dist/with-party/directory/storage.d.ts

@@ -1,14 +1,3 @@
-/**
- * Persistence helpers for the vault-level user-directory toggle
- * (`_meta/directory`). Mirrors the bypass-AES pattern used by
- * `_meta/policy` — the directory document is plain JSON, the
- * envelope's `_iv` field is left empty.
- *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/plaintext-bypass.md — every `_iv: ''` write site
- *
- * @module
- */
 import type { NoydbStore } from '../../kernel/types.js';
 import type { DirectoryConfig } from './types.js';
 /** Reserved collection name for vault-level metadata documents. */