@noy-db/hub 0.6.0-pre.21 → 0.6.0-pre.23

package/dist/{stale-NI7SAXAZ.js → stale-MIO5KGEP.js}

@@ -6,17 +6,17 @@ import {
   isMVStale,
   markMVStale,
   resolveStaleMVOnRead
-} from "./chunk-EES37S2V.js";
+} from "./chunk-L5PTLL7A.js";
 import "./chunk-5D2ALSM5.js";
-import "./chunk-OHOKBMTM.js";
+import "./chunk-FUE2KPKM.js";
 import "./chunk-PENPHA45.js";
-import "./chunk-GQXFOAYZ.js";
-import "./chunk-KV6JM2IA.js";
-import "./chunk-TMBSPLUG.js";
+import "./chunk-OMXUQAZJ.js";
+import "./chunk-PUGHLCBW.js";
+import "./chunk-2LHPMFSR.js";
 import "./chunk-LP7BEXCT.js";
-import "./chunk-AU3AUJIZ.js";
+import "./chunk-RQQIB7CD.js";
 import "./chunk-IGNJOJEP.js";
-import "./chunk-CWM4GQD2.js";
+import "./chunk-HKANJAOP.js";
 import "./chunk-PZ5AY32C.js";
 export {
   MV_STALE_COLLECTION,
@@ -27,4 +27,4 @@ export {
   markMVStale,
   resolveStaleMVOnRead
 };
-//# sourceMappingURL=stale-NI7SAXAZ.js.map
+//# sourceMappingURL=stale-MIO5KGEP.js.map

package/dist/{storage-3VNGSHXS.js → storage-NLYOMCDM.js}

@@ -3,16 +3,16 @@ import {
   loadPersistedSchema,
   loadPersistedSchemaEntry,
   savePersistedSchema
-} from "./chunk-6WO62AJW.js";
-import "./chunk-OHOKBMTM.js";
+} from "./chunk-SZFNO7L4.js";
+import "./chunk-FUE2KPKM.js";
 import "./chunk-PENPHA45.js";
-import "./chunk-GQXFOAYZ.js";
-import "./chunk-KV6JM2IA.js";
-import "./chunk-TMBSPLUG.js";
+import "./chunk-OMXUQAZJ.js";
+import "./chunk-PUGHLCBW.js";
+import "./chunk-2LHPMFSR.js";
 import "./chunk-LP7BEXCT.js";
-import "./chunk-AU3AUJIZ.js";
+import "./chunk-RQQIB7CD.js";
 import "./chunk-IGNJOJEP.js";
-import "./chunk-CWM4GQD2.js";
+import "./chunk-HKANJAOP.js";
 import "./chunk-PZ5AY32C.js";
 export {
   SCHEMAS_COLLECTION,
@@ -20,4 +20,4 @@ export {
   loadPersistedSchemaEntry,
   savePersistedSchema
 };
-//# sourceMappingURL=storage-3VNGSHXS.js.map
+//# sourceMappingURL=storage-NLYOMCDM.js.map

package/dist/{store-coordination-provider-TYKNR3OU.js → store-coordination-provider-XCX77ZBE.js}

@@ -2,17 +2,17 @@ import {
   loadFence,
   saveFence
 } from "./chunk-FFSQFH6D.js";
-import "./chunk-OHOKBMTM.js";
+import "./chunk-FUE2KPKM.js";
 import {
   buildRecordEnvelope
 } from "./chunk-PENPHA45.js";
-import "./chunk-GQXFOAYZ.js";
-import "./chunk-KV6JM2IA.js";
-import "./chunk-TMBSPLUG.js";
+import "./chunk-OMXUQAZJ.js";
+import "./chunk-PUGHLCBW.js";
+import "./chunk-2LHPMFSR.js";
 import "./chunk-LP7BEXCT.js";
-import "./chunk-AU3AUJIZ.js";
+import "./chunk-RQQIB7CD.js";
 import "./chunk-IGNJOJEP.js";
-import "./chunk-CWM4GQD2.js";
+import "./chunk-HKANJAOP.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/with-shape/schema-update/client-registry.ts
@@ -145,4 +145,4 @@ function unref(timer) {
 export {
   StoreCoordinationProvider
 };
-//# sourceMappingURL=store-coordination-provider-TYKNR3OU.js.map
+//# sourceMappingURL=store-coordination-provider-XCX77ZBE.js.map

package/dist/sync/index.js

@@ -2,20 +2,20 @@ import {
   PresenceHandle,
   SyncEngine,
   SyncTransaction
-} from "../chunk-4N5Q23KV.js";
+} from "../chunk-JXFQEOAQ.js";
 import {
   NO_SYNC
 } from "../chunk-T7IR4N2S.js";
-import "../chunk-A4TOGAUW.js";
-import "../chunk-OHOKBMTM.js";
+import "../chunk-VXH5Z22C.js";
+import "../chunk-FUE2KPKM.js";
 import "../chunk-PENPHA45.js";
-import "../chunk-GQXFOAYZ.js";
-import "../chunk-KV6JM2IA.js";
-import "../chunk-TMBSPLUG.js";
+import "../chunk-OMXUQAZJ.js";
+import "../chunk-PUGHLCBW.js";
+import "../chunk-2LHPMFSR.js";
 import "../chunk-LP7BEXCT.js";
-import "../chunk-AU3AUJIZ.js";
+import "../chunk-RQQIB7CD.js";
 import "../chunk-IGNJOJEP.js";
-import "../chunk-CWM4GQD2.js";
+import "../chunk-HKANJAOP.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/with-sync/active.ts

package/dist/team/index.js

@@ -2,7 +2,7 @@ import {
   MemoryDeviceSealProvider,
   beginEchoUnlock,
   withTeam
-} from "../chunk-45YHJ3GV.js";
+} from "../chunk-PFHF3A72.js";
 import {
   NO_TEAM,
   burnPaperRecoveryEntry,
@@ -31,7 +31,7 @@ import {
   unwrapMagicLinkGrant,
   updateAuthenticator,
   writeMagicLinkGrant
-} from "../chunk-NCCEDL2K.js";
+} from "../chunk-66X4XWTM.js";
 import "../chunk-3ENNPCIW.js";
 import {
   buildEchoBlock,
@@ -53,21 +53,21 @@ import {
   updateKeyringIdentity,
   verifyPrompt,
   verifyTypedEcho
-} from "../chunk-CAGI4LLJ.js";
-import "../chunk-LX46B56Q.js";
-import "../chunk-NW4TY6VC.js";
-import "../chunk-PPCOKVFA.js";
-import "../chunk-OHOKBMTM.js";
+} from "../chunk-AK6EWGDO.js";
+import "../chunk-GJ5TMHKC.js";
+import "../chunk-3UIS6O6N.js";
+import "../chunk-6ZTPSVY7.js";
+import "../chunk-FUE2KPKM.js";
 import "../chunk-PENPHA45.js";
-import "../chunk-GQXFOAYZ.js";
-import "../chunk-KV6JM2IA.js";
-import "../chunk-TMBSPLUG.js";
+import "../chunk-OMXUQAZJ.js";
+import "../chunk-PUGHLCBW.js";
+import "../chunk-2LHPMFSR.js";
 import "../chunk-LP7BEXCT.js";
-import "../chunk-AU3AUJIZ.js";
+import "../chunk-RQQIB7CD.js";
 import "../chunk-IGNJOJEP.js";
 import {
   TeamNotEnabledError
-} from "../chunk-CWM4GQD2.js";
+} from "../chunk-HKANJAOP.js";
 import "../chunk-PZ5AY32C.js";
 export {
   MemoryDeviceSealProvider,

package/dist/tiers/index.js

@@ -11,20 +11,20 @@ import {
   putAtTier,
   syncDerivedOutputs,
   withTiers
-} from "../chunk-4YL2LMXK.js";
-import "../chunk-NW4TY6VC.js";
-import "../chunk-PPCOKVFA.js";
-import "../chunk-OHOKBMTM.js";
+} from "../chunk-UW5YKCE4.js";
+import "../chunk-3UIS6O6N.js";
+import "../chunk-6ZTPSVY7.js";
+import "../chunk-FUE2KPKM.js";
 import "../chunk-PENPHA45.js";
-import "../chunk-GQXFOAYZ.js";
-import "../chunk-KV6JM2IA.js";
-import "../chunk-TMBSPLUG.js";
+import "../chunk-OMXUQAZJ.js";
+import "../chunk-PUGHLCBW.js";
+import "../chunk-2LHPMFSR.js";
 import "../chunk-LP7BEXCT.js";
-import "../chunk-AU3AUJIZ.js";
+import "../chunk-RQQIB7CD.js";
 import "../chunk-IGNJOJEP.js";
 import {
   TiersNotEnabledError
-} from "../chunk-CWM4GQD2.js";
+} from "../chunk-HKANJAOP.js";
 import "../chunk-PZ5AY32C.js";
 export {
   NO_TIERS,

package/dist/to/index.js

@@ -5,7 +5,7 @@ import {
   PodVersionConflictError,
   StoreCapabilityError,
   UnknownStoreKindError
-} from "../chunk-CWM4GQD2.js";
+} from "../chunk-HKANJAOP.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/port/to/locator.ts

package/dist/transactions/index.js

@@ -3,16 +3,16 @@ import {
   TxContext,
   TxVault,
   runTransaction
-} from "../chunk-2LFOMUEA.js";
+} from "../chunk-LBDG6FHB.js";
 import {
   lazy
 } from "../chunk-5D2ALSM5.js";
 import "../chunk-4AOERLTV.js";
-import "../chunk-CWM4GQD2.js";
+import "../chunk-HKANJAOP.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/with-commit/tx/dry-run.ts
-var loadGuardExecutor = lazy(() => import("../executor-DVJAWN3B.js"));
+var loadGuardExecutor = lazy(() => import("../executor-O4UP4M3C.js"));
 var SEP = " ";
 var keyOf = (op) => `${op.vaultName}${SEP}${op.collectionName}${SEP}${op.id}`;
 async function runDryRun(db, fn) {

package/dist/util/index.js

@@ -3,7 +3,7 @@ import {
 } from "../chunk-PY4KJPYU.js";
 import {
   FilenameSanitizationError
-} from "../chunk-CWM4GQD2.js";
+} from "../chunk-HKANJAOP.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/kernel/util/sanitize-filename.ts

package/dist/vault-head/index.js

@@ -6,19 +6,19 @@ import {
 import {
   buildRecordAad,
   openEnvelopeJson
-} from "../chunk-OHOKBMTM.js";
+} from "../chunk-FUE2KPKM.js";
 import {
   buildRecordEnvelope
 } from "../chunk-PENPHA45.js";
-import "../chunk-GQXFOAYZ.js";
-import "../chunk-KV6JM2IA.js";
-import "../chunk-TMBSPLUG.js";
+import "../chunk-OMXUQAZJ.js";
+import "../chunk-PUGHLCBW.js";
+import "../chunk-2LHPMFSR.js";
 import "../chunk-LP7BEXCT.js";
 import {
   encrypt
-} from "../chunk-AU3AUJIZ.js";
+} from "../chunk-RQQIB7CD.js";
 import "../chunk-IGNJOJEP.js";
-import "../chunk-CWM4GQD2.js";
+import "../chunk-HKANJAOP.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/with-commit/vault-head/head.ts

package/dist/{verify-6J2YLKSO.js → verify-5QI3DGO2.js}

@@ -2,10 +2,10 @@ import {
   blindedEqual,
   evaluateKofN,
   openVdigPayload
-} from "./chunk-GQXFOAYZ.js";
+} from "./chunk-OMXUQAZJ.js";
 import {
   dualReadSealedSlot
-} from "./chunk-KV6JM2IA.js";
+} from "./chunk-PUGHLCBW.js";
 import {
   VDIG_ITERATIONS,
   normalizeForVerify,
@@ -14,11 +14,11 @@ import {
 import {
   base64ToBuffer,
   generateSalt
-} from "./chunk-AU3AUJIZ.js";
+} from "./chunk-RQQIB7CD.js";
 import {
   ClassifiedConfigError,
   ClassifiedVerifyError
-} from "./chunk-CWM4GQD2.js";
+} from "./chunk-HKANJAOP.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/kernel/enclave/classify/verify.ts
@@ -137,4 +137,4 @@ export {
   verifyDigestField,
   verifyTextField
 };
-//# sourceMappingURL=verify-6J2YLKSO.js.map
+//# sourceMappingURL=verify-5QI3DGO2.js.map

package/dist/via/blob/index.d.ts

@@ -33,6 +33,9 @@ export { BLOB_COLLECTION, BLOB_INDEX_COLLECTION, BLOB_CHUNKS_COLLECTION, BLOB_SL
 export type { BlobObject, SlotRecord, SlotInfo, VersionRecord, BlobPutOptions, BlobResponseOptions, } from '../../kernel/types.js';
 export { detectMimeType, detectMagic, isPreCompressed } from '../../with-shape/blobs/mime-magic.js';
 export { runCompaction, BLOB_EVICTION_AUDIT_COLLECTION } from '../../with-shape/blobs/blob-compaction.js';
+export { reportOrphanBlobChunks } from '../../with-shape/blobs/orphan-report.js';
+export type { OrphanChunkReport } from '../../with-shape/blobs/orphan-report.js';
+export type { NoydbStore } from '../../kernel/types.js';
 export type { BlobFieldsConfig, BlobFieldPolicy, BlobEvictionEntry, CompactRunOptions, CompactionResult, CompactionContext, } from '../../with-shape/blobs/blob-compaction.js';
 export { createExportBlobsHandle, ExportBlobsAbortedError, EXPORT_AUDIT_COLLECTION, } from '../../with-shape/blobs/export-blobs.js';
 export type { ExportBlobsOptions, ExportedBlob, ExportBlobsHandle, ExportBlobsAuditEntry, } from '../../with-shape/blobs/export-blobs.js';

package/dist/walk-G5OAA3RE.js

@@ -0,0 +1,21 @@
+import {
+  dumpVaultSchema
+} from "./chunk-L374ZR75.js";
+import "./chunk-KHKKD62N.js";
+import "./chunk-2QN6NPV6.js";
+import "./chunk-Y2NBBT6K.js";
+import "./chunk-SZFNO7L4.js";
+import "./chunk-FUE2KPKM.js";
+import "./chunk-PENPHA45.js";
+import "./chunk-OMXUQAZJ.js";
+import "./chunk-PUGHLCBW.js";
+import "./chunk-2LHPMFSR.js";
+import "./chunk-LP7BEXCT.js";
+import "./chunk-RQQIB7CD.js";
+import "./chunk-IGNJOJEP.js";
+import "./chunk-HKANJAOP.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  dumpVaultSchema
+};
+//# sourceMappingURL=walk-G5OAA3RE.js.map

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-shape/blobs/blob-compaction.d.ts

@@ -30,6 +30,7 @@
  */
 import type { NoydbStore, SlotInfo } from '../../kernel/types.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type OrphanChunkReport } from './orphan-report.js';
 export interface BlobFieldPolicy<T = unknown> {
     /**
      * Via port brand marker — lets a `BlobFieldPolicy` satisfy the kernel's
@@ -145,6 +146,18 @@ export interface CompactionResult {
         records: number;
         evicted: number;
     }>;
+    /**
+     * #1133 — chunk rows in `_blob_chunks` with no surviving `_blob_index` entry.
+     * Pre-#1127 residue: unreachable by every reader AND by rotation, so for a
+     * legacy blob the bytes stay openable under a retired `_blob` DEK.
+     *
+     * REPORTED, never reclaimed — deciding "orphaned" means trusting the store's
+     * `list`, and a store that withholds one index row would have us destroy a
+     * LIVE blob's chunks. See `orphan-report.ts` for the full argument. A vault
+     * that has run `migrate()` has no legacy chunks to strand, and `chunks: 0`
+     * is the expected reading everywhere else.
+     */
+    readonly orphanBlobChunks: OrphanChunkReport;
 }
 export interface CompactRunOptions {
     /** Override "now" for deterministic testing. */