@noy-db/hub 0.6.0-pre.9 → 0.7.0-pre.0

package/dist/kernel/enclave/record-keys/rekey.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Re-key one envelope from an old collection DEK to a new one (#1074).
+ *
+ * Lives in the enclave because it is envelope surgery: it reads and writes the
+ * protected body slots (`_iv`/`_data`/`_cek`), which `enclave-body-only`
+ * reserves to `kernel/enclave/**`. `rotateKeys` previously did this inline in
+ * `with-party/team/keyring.ts` and got it wrong in two ways that the guard
+ * would have caught had the code lived here.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../crypto.js';
+import type { EncryptedEnvelope } from '../../types.js';
+/**
+ * Produce the envelope `envelope` becomes once its collection's DEK rotates
+ * from `oldDek` to `newDek`.
+ *
+ * **Every slot is carried forward except `_bidx`.** The previous inline version
+ * built a fresh literal holding only `_noydb/_v/_ts/_iv/_data`, silently
+ * discarding `_by`, `_tier`, `_cek`, `_sealed`, `_vdig` and `_source`. Losing
+ * `_tier` was the worst of those: tier-0 reads treat elevated as missing, so an
+ * elevated record did not error after a rotation — it simply disappeared.
+ *
+ * `_bidx` is dropped deliberately. It is a DEK-rooted equality tag, so a tag
+ * carried across a DEK rotation can never be re-derived to match a query again
+ * while still leaking the old equality partition. Index coverage regrows
+ * per-record on the next `put()` under the new DEK.
+ *
+ * Two shapes, and picking the wrong one is why this needed a helper:
+ *
+ * - **per-record CEK** (`_cek` present) — the body is sealed under the CEK and
+ *   the CEK is wrapped under the collection DEK, so rotation re-wraps the CEK
+ *   and leaves the body **untouched**. The old inline code instead ran
+ *   `decrypt(body, oldDek)` on these, which throws: rotation could not complete
+ *   on a collection containing any CEK record.
+ * - **bare** — body sealed directly under the DEK, so decrypt and re-encrypt.
+ *
+ * Idempotence is the caller's problem, not this function's: it assumes
+ * `envelope` is still under `oldDek`. A resumable rotation must know which side
+ * of the migration each record is on before calling.
+ */
+export declare function rekeyEnvelopeToDek(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, oldDek: EnclaveKey, newDek: EnclaveKey): Promise<EncryptedEnvelope>;
+/**
+ * Resumable variant: returns the re-keyed envelope, or `null` when `envelope`
+ * is **already** under `newDek` and needs no work (#1074 part 2).
+ *
+ * A rotation interrupted mid-collection leaves records on both sides of the
+ * migration. Resuming means re-running the rotation with the *same* new DEK,
+ * which requires distinguishing "not yet moved" from "already moved" without
+ * the caller touching protected slots.
+ *
+ * Detection is by trial decryption under `oldDek`. There is no metadata that
+ * says which DEK sealed a record — deliberately, since such a marker would be
+ * store-writable and therefore a downgrade lever (the same reasoning that
+ * keeps the reader from branching on `_noydb`).
+ *
+ * A record that opens under *neither* key is genuinely damaged and rethrows,
+ * rather than being silently skipped: a rotation that quietly walked past
+ * unreadable records would convert a loud failure into permanent silent loss,
+ * which is the defect this whole issue is about.
+ */
+export declare function rekeyEnvelopeIfNeeded(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, oldDek: EnclaveKey, newDek: EnclaveKey): Promise<EncryptedEnvelope | null>;
+/**
+ * Does this envelope open under ANY of `keys`? A read-only probe — decrypts
+ * nothing into a caller-visible value and writes nothing.
+ *
+ * Exists so a rotation can tell *"this envelope belongs to a DIFFERENT DEK slot
+ * the caller also holds"* from *"this envelope is damaged"* (#1125). Those two
+ * look identical from a failed `rekeyEnvelopeIfNeeded`, and collapsing them
+ * either aborts a legitimate rotation or walks past unreadable data.
+ *
+ * **The question is deliberately asked of the KEY, not of the envelope's claimed
+ * `_tier`.** `_tier` is unencrypted — the store writes it — so routing a
+ * rotation on it would let a store mark a tier-0 record `_tier: 5` and have the
+ * rotation skip it, leaving a revoked member's DEK live on real data. That is
+ * #1115's defect wearing a different hat. A key either opens the body or it does
+ * not, and a store cannot forge that.
+ *
+ * Mirrors `rekeyBlobSet`'s `otherDeks` treatment, which asks the same question
+ * about the same kind of ambiguity.
+ */
+export declare function envelopeOpensUnderAny(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, keys: readonly EnclaveKey[]): Promise<boolean>;

package/dist/kernel/enclave/record-keys/tombstone.d.ts

@@ -16,6 +16,7 @@
  * vault; it calls into these.
  */
 import { type EncryptedEnvelope } from '../../types.js';
+import type { RecordRef } from '../record-aad.js';
 /**
  * Shape-only tombstone recognition for layers that have no per-collection
  * context (the sync engine, #590): a tombstone carries an empty `_data` and
@@ -45,7 +46,7 @@ export declare function isTombstone(envelope: EncryptedEnvelope, encrypted: bool
  * Deliberately omits `_iv`/`_data`/`_cek`/`_det` — that omission *is* the
  * erasure.
  */
-export declare function buildTombstone(version: number, actor: string): EncryptedEnvelope;
+export declare function buildTombstone(ref: RecordRef, version: number, actor: string): EncryptedEnvelope;
 /** #589: is this envelope an ordinary-delete marker (version-ordered, reads as absent)? */
 export declare function isDeleteMarker(envelope: EncryptedEnvelope): boolean;
 /**
@@ -54,4 +55,4 @@ export declare function isDeleteMarker(envelope: EncryptedEnvelope): boolean;
  * keeps the displaced `_v` — so it wins convergence over the pre-delete copy and a
  * re-create can still win over it at a higher version.
  */
-export declare function buildDeleteMarker(version: number, actor: string): EncryptedEnvelope;
+export declare function buildDeleteMarker(ref: RecordRef, version: number, actor: string): EncryptedEnvelope;

package/dist/kernel/errors.d.ts

@@ -10,7 +10,9 @@
  *       ├─ Crypto errors
  *       │    ├─ DecryptionError        — AES-GCM tag failure
  *       │    ├─ TamperedError          — ciphertext modified after write
- *       │    └─ InvalidKeyError        — wrong secret / corrupt keyring
+ *       │    ├─ InvalidKeyError        — wrong secret / corrupt keyring
+ *       │    ├─ KeyringCorruptError    — partial DEK corruption, KEK correct
+ *       │    └─ KeyringTamperedError   — keyring roster failed authentication (#1096)
  *       ├─ Access errors
  *       │    ├─ NoAccessError          — no DEK for this collection
  *       │    ├─ ReadOnlyError          — ro permission, write attempted
@@ -52,7 +54,7 @@
  *       │    ├─ BackupLedgerError      — hash-chain verification failed
  *       │    └─ BackupCorruptedError   — envelope hash mismatch in dump
  *       ├─ Bundle errors
- *       │    └─ BundleIntegrityError   — .noydb body sha256 mismatch
+ *       │    └─ PodIntegrityError   — .noydb body sha256 mismatch
  *       ├─ Session errors
  *       │    ├─ SessionExpiredError
  *       │    ├─ SessionNotFoundError
@@ -143,7 +145,23 @@ export declare class DecryptionError extends NoydbError {
  * Treat it as a security alert: the stored bytes are not what NOYDB wrote.
  */
 export declare class TamperedError extends NoydbError {
-    constructor(message?: string);
+    /**
+     * Why the tag check failed, when the enclave could tell (#1103).
+     *
+     * `'unbound-legacy-format'` — the body opens under an EMPTY AAD, so it was
+     * sealed before identity binding (#1041) and this is a format transition, not
+     * an attack. Positive evidence, not a guess: producing a body that decrypts
+     * under this DEK requires the DEK, which an untrusted store does not hold.
+     *
+     * Absent — no benign explanation was found. Treat as the security alert this
+     * error has always been.
+     *
+     * The field is additive and the throw is unchanged, so
+     * `catch (e) { if (e instanceof TamperedError) … }` keeps working; callers
+     * that want to tell a migration from a breach can now read this.
+     */
+    readonly reason?: 'unbound-legacy-format';
+    constructor(message?: string, reason?: 'unbound-legacy-format');
 }
 /**
  * Thrown when key unwrapping fails, typically because the secret is wrong
@@ -177,6 +195,86 @@ export declare class KeyringCorruptError extends NoydbError {
         message?: string;
     });
 }
+/**
+ * #1096 — the keyring's plaintext AUTHORITY half failed authentication.
+ *
+ * Thrown by `loadKeyring` when the canary is absent, when the reserved
+ * roster-key DEK entry is absent, or when the keys check out (KEK proven
+ * correct) but `roster_tag` is missing or does not match the file.
+ *
+ * Distinct from {@link KeyringCorruptError}: the KEYS are fine; the ROSTER —
+ * `role`, `permissions`, `granted_by`, the capability grants — is what cannot
+ * be trusted. A `_keyring` file is stored plaintext so admins can edit a
+ * member's authority without holding that member's credential, which left
+ * those fields authenticated by nothing; this error is what a hostile store
+ * editing them now produces.
+ *
+ * Deliberately raised only AFTER the key-unwrap epilogue, so a plain
+ * wrong-secret keeps reporting as `InvalidKeyError` and is never
+ * misannounced to the user as an attack.
+ */
+/**
+ * Why a `_keyring` file failed roster authentication (#1096).
+ *
+ * Named rather than inlined because a third consumer now reports it without
+ * throwing: `RotateResult.unverified` (#1114) lists the members a rotation
+ * skipped, and a union duplicated per call site drifts.
+ */
+export type KeyringTamperedReason = 'canary-missing' | 'roster-key-missing' | 'roster-tag-missing' | 'roster-tag-mismatch'
+/**
+ * The tag does not verify AND the file declares an older `_noydb_keyring`
+ * than this build writes (#1115) — a format transition, not an attack.
+ *
+ * Split out of `roster-tag-mismatch` deliberately. That label carries the one
+ * UNQUALIFIED accusation in this union, on the grounds that no released
+ * version ever wrote a mismatched tag. Widening what the tag covers makes
+ * that false for every vault written before the change, so without this the
+ * most common cause of a mismatch — you upgraded — would be reported as
+ * "the store has changed a member's role".
+ *
+ * CLASSIFICATION ONLY: the outcome is refusal either way, so a store that
+ * rewrites the plaintext version field changes the wording and nothing else.
+ */
+ | 'format-superseded'
+/**
+ * The file did not parse at all (#1121). Never thrown by
+ * `assertRosterAuthenticated` — which cannot reach a file it could not read —
+ * but reported by `verifyRoster` and accepted by `quarantineKeyring`, because
+ * truncation and bitrot produce the most literally unauthenticatable file
+ * there is and the tools for unauthenticatable files must not be the ones
+ * that choke on it.
+ */
+ | 'unparseable';
+export declare class KeyringTamperedError extends NoydbError {
+    readonly details: {
+        readonly userId: string;
+        readonly reason: KeyringTamperedReason;
+        /**
+         * The keyring format transition, when one is known: `from` is the version
+         * the FILE declares, `to` the version this build writes.
+         *
+         * Present so a reader can tell which version they hold and which one this
+         * build wants, without reverse-engineering it from the prose. The message
+         * said "an OLDER FORMAT" and never named either number, which is not
+         * enough to work out whether you are one release behind or five.
+         *
+         * Structured, not parsed out of the message: a consumer that translates
+         * the error never sees the English at all.
+         */
+        readonly format?: {
+            readonly from: number;
+            readonly to: number;
+        };
+    };
+    constructor(details: {
+        readonly userId: string;
+        readonly reason: KeyringTamperedReason;
+        readonly format?: {
+            readonly from: number;
+            readonly to: number;
+        };
+    });
+}
 /**
  * Thrown when the authenticated user does not have a DEK for the requested
  * collection — i.e. the collection is not in their keyring at all.
@@ -277,7 +375,7 @@ export declare class ExportCapabilityError extends NoydbError {
  * can show a precise "this bundle slot has expired" message instead
  * of the generic decryption-failure UX.
  *
- * Used predominantly on `BundleRecipient` slots produced by
+ * Used predominantly on `PodRecipient` slots produced by
  * `writePod({ recipients: [...] })` to time-box audit access.
  */
 export declare class KeyringExpiredError extends NoydbError {
@@ -759,10 +857,6 @@ export declare class PodVersionConflictError extends NoydbError {
     readonly remoteVersion: string;
     constructor(remoteVersion: string, message?: string);
 }
-/** @deprecated Use `PodVersionConflictError`. */
-export declare const BundleVersionConflictError: typeof PodVersionConflictError;
-/** @deprecated Use `PodVersionConflictError`. */
-export type BundleVersionConflictError = PodVersionConflictError;
 /**
  * Thrown when a sync operation (push or pull) fails due to a network error.
  *
@@ -1012,7 +1106,7 @@ export declare class FieldNotQueryableError extends NoydbError {
  * format violations like a missing magic prefix or malformed
  * header JSON) so consumers can pattern-match the corruption case
  * and handle it differently from a producer bug. A
- * `BundleIntegrityError` indicates "the bytes you got are not
+ * `PodIntegrityError` indicates "the bytes you got are not
  * what was written"; a plain `Error` from `parsePrefixAndHeader`
  * indicates "what was written wasn't a valid bundle in the first
  * place."
@@ -1022,7 +1116,7 @@ export declare class FieldNotQueryableError extends NoydbError {
  * written) but it surfaces with the same error class because the
  * end result is "the body cannot be turned back into a dump."
  */
-export declare class BundleIntegrityError extends NoydbError {
+export declare class PodIntegrityError extends NoydbError {
     constructor(message: string);
 }
 /**
@@ -1039,14 +1133,14 @@ export declare class PodHeaderVerificationError extends NoydbError {
 }
 /**
  * Thrown by `readPod` when the bundle carries
- * sealed per-user secrets but no supplied `SealingKeyProvider`
+ * sealed per-user secrets but no supplied `NoydbSealer`
  * has a `.id` (= `pid`) matching the sealed entry's `pid`.
  *
  * Carries the failing pid + the user id so the recipient can
  * surface an actionable prompt:
  *
  * ```
- * BundleSealMismatchError: bundle carries sealed secret for user "alice"
+ * PodSealMismatchError: bundle carries sealed secret for user "alice"
  *   under provider "macos-keychain:com.acme.app/alice@acme.example",
  *   but no registered provider matches that pid.
  * ```
@@ -1059,7 +1153,7 @@ export declare class PodHeaderVerificationError extends NoydbError {
  * 3. Inspect without unsealing — pass no `sealingProviders` to
  *    receive the sealed entries unmodified for offline analysis.
  */
-export declare class BundleSealMismatchError extends NoydbError {
+export declare class PodSealMismatchError extends NoydbError {
     readonly userId: string;
     readonly pid: string;
     constructor(userId: string, pid: string);
@@ -1565,6 +1659,32 @@ export declare class CrossJoinTooLargeError extends NoydbError {
         limit: number;
     });
 }
+/**
+ * Thrown by `.join()` when the field it is asked to follow carries no `ref()`
+ * declaration on the left collection (and is not a `dictKey` join field).
+ *
+ * A distinct class rather than a bare `Error` because the condition is
+ * legitimately TRANSIENT for one caller: a materialized view's `query()`
+ * callback is invoked during `openVault()`, before user code has had any
+ * opportunity to declare a collection's refs, so the MV registry defers that
+ * strategy's planning and retries instead of failing the vault open (#1139).
+ * Matching that condition on the message text would be the kind of proxy this
+ * codebase keeps getting bitten by; the class is the fact.
+ *
+ * For every other caller the meaning is unchanged and terminal: declare the
+ * ref, then retry. The message is identical to the one this replaced.
+ */
+export declare class RefNotDeclaredError extends NoydbError {
+    /** Collection the join was issued from. */
+    readonly collection: string;
+    /** Field the join tried to follow. */
+    readonly field: string;
+    constructor(opts: {
+        collection: string;
+        field: string;
+        message: string;
+    });
+}
 /**
  * Thrown at cross-join execution time when the target collection is not
  * reachable from the current vault. The left collection is included in the
@@ -1977,7 +2097,7 @@ export declare class RecoveryNotEnrolledError extends NoydbError {
  * STRONG recovery profile enrolled.
  *
  * Managed mode means the user never types a secret — the unlock
- * material lives in a `SealingKeyProvider` (`at-*` package). If that
+ * material lives in a `NoydbSealer` (`at-*` package). If that
  * provider's key is lost AND no strong recovery is enrolled, the
  * vault is irrecoverable. To prevent that footgun, managed-mode vaults
  * require at least one strong recovery profile (Shamir today;

package/dist/kernel/merge-authority.d.ts

@@ -0,0 +1,25 @@
+import type { MergeAuthority } from '../port/with/merge-authority.js';
+import type { EnclaveKey } from './enclave/index.js';
+/**
+ * ⚠️ **A client cannot verify what it cannot decrypt** — and that boundary is
+ * stated here rather than hidden.
+ *
+ * A record at a tier this caller holds no key for is accepted **unverified**.
+ * Rejecting it would break replication of data the peer legitimately holds but
+ * this client is not cleared to read, converting a confidentiality boundary
+ * into a replication failure. The residue is narrow: envelopes whose key the
+ * client lacks are pass-through, exactly as every envelope was before #1042.
+ *
+ * Closing that residue needs the vault head (#1044), which can detect absence
+ * and substitution without holding the key.
+ */
+export declare function buildMergeAuthority(
+/**
+ * Just the DEK map, not the whole keyring. `port-layering` refused a type
+ * import of `UnlockedKeyring` from `with-party` — correctly, and the narrower
+ * shape is better anyway: this needs to look up keys, not to know what a
+ * keyring is.
+ */
+keyring: {
+    readonly deks: ReadonlyMap<string, EnclaveKey>;
+}): MergeAuthority;

package/dist/kernel/noydb.d.ts

@@ -1,7 +1,7 @@
-import type { RotateResult } from '../with-party/team/keyring.js';
-import type { NoydbOptions, NoydbEventMap, GrantOptions, RevokeOptions, UpdateUserOptions, UserInfo, PushResult, PullResult, PushOptions, PullOptions, SyncStatus, SyncTargetInfo, NoydbStore, AccessibleVault, ListAccessibleVaultsOptions, QueryAcrossOptions, QueryAcrossResult, TranslatorAuditEntry, WriteConflict, UserApiFactory, ActiveTier, FactorProofBundle, GateName, VaultPolicy } from './types.js';
+import type { RotateResult, RosterVerifyResult, QuarantineResult } from '../with-party/team/keyring.js';
+import type { NoydbOptions, NoydbEventMap, GrantOptions, RevokeOptions, UpdateUserOptions, UserInfo, PushResult, PullResult, PushOptions, PullOptions, SyncStatus, SyncTargetInfo, SyncTargetStatus, NoydbStore, AccessibleVault, ListAccessibleVaultsOptions, QueryAcrossOptions, QueryAcrossResult, TranslatorAuditEntry, WriteConflict, UserApiFactory, ActiveTier, FactorProofBundle, GateName, VaultPolicy } from './types.js';
 import type { SecretPolicy } from './validation.js';
-import { type CoordinationProvider } from '../port/by/default-provider.js';
+import { type NoydbMesh } from '../port/by/default-provider.js';
 import type { Cover } from '../with-party/directory/cover/types.js';
 import type { SetCoverInput } from '../with-party/directory/cover/schema.js';
 import { Vault } from './vault.js';
@@ -36,8 +36,8 @@ export declare class Noydb {
     /** Session that owns this instance's writers (one user's writers across vaults). */
     private readonly sessionId;
     /** Drain-barrier coordination transport for the schema fence. */
-    private readonly coordinationProvider;
-    /** Pre-resolved `vault.user` API factory (mirrors `coordinationProvider` above). Public so `Vault` can call it. */
+    private readonly meshPort;
+    /** Pre-resolved `vault.user` API factory (mirrors `meshPort` above). Public so `Vault` can call it. */
     readonly userApiFactory: UserApiFactory;
     private readonly vaultCache;
     /**
@@ -96,7 +96,7 @@ export declare class Noydb {
     get custodyStrategy(): CustodyStrategy;
     private readonly snapshots;
     private readonly policyManager;
-    /** Pre-resolved policy-gate engine function (mirrors `coordinationProvider`/`userApiFactory` above). */
+    /** Pre-resolved policy-gate engine function (mirrors `meshPort`/`userApiFactory` above). */
     private readonly policyCheckGate;
     /**
      * Credential and multi-user operations — enrolment, secret rotation,
@@ -282,8 +282,8 @@ export declare class Noydb {
      * collection) pair that was dropped. Re-run `grant()` for those pairs, or
      * they stay locked out.
      *
-     * Unlike `revoke({ rotateKeys: true })`, this call does not REMOVE any
-     * user from the vault — they keep membership and their other collections.
+     * Unlike `revoke()`, this call does not REMOVE any user from the vault —
+     * they keep membership and their other collections.
      * This is the "just rotate" path; "revoke and rotate" lives in `revoke()`.
      *
      * Exposed on Noydb (rather than only on the lower-level keyring
@@ -292,6 +292,23 @@ export declare class Noydb {
      * Opt-in (#267): throws {@link TeamNotEnabledError} without `withTeam()`.
      */
     rotate(vault: string, collections: string[]): Promise<RotateResult>;
+    /**
+     * Verify every `_keyring` file in the vault. Read-only (#1121).
+     *
+     * Names each failing file and why, so the bad one need not be found by trial.
+     * Reports `checked` too: "nothing unverified" is equally true of a sweep that
+     * examined nothing.
+     */
+    verifyRoster(vault: string): Promise<RosterVerifyResult>;
+    /**
+     * Remove a `_keyring` file that cannot be authenticated, and re-key behind it
+     * (#1121). Owner-only; refuses a file that verifies (use {@link revoke}).
+     *
+     * `revoke` consults the target's own `role`, so it cannot act on a file it
+     * will not trust. This ignores every claim the file makes — which is exactly
+     * why it is restricted to files that already fail authentication.
+     */
+    quarantineKeyring(vault: string, userId: string, factors?: FactorProofBundle): Promise<QuarantineResult>;
     /** List all users with access to a vault. */
     listUsers(vault: string): Promise<UserInfo[]>;
     /**
@@ -549,6 +566,12 @@ export declare class Noydb {
     _clearActiveTxContext(ctx: TxContext): void;
     /** Get sync status for a vault. */
     syncStatus(vault: string): SyncStatus;
+    /**
+     * Per-target sync state for `vault` (#1034) — `syncStatus()` reads only the
+     * primary engine, so it cannot express "the LAN store is behind, the cloud
+     * is current". Registration order, primary first. See {@link SyncTargetStatus}.
+     */
+    syncTargetStatus(vault: string): SyncTargetStatus[];
     /**
      * Enumerate the sync targets wired for `vault` (#948) — the primary engine
      * (keyed by vault name) plus any additional targets (keyed `vault::label`
@@ -613,9 +636,9 @@ export declare class Noydb {
     /**
      * @internal Drain-barrier coordination transport for the schema fence.
      * The default store-backed provider reproduces today's fence behavior; a
-     * `by-*` real-time transport is injected via `coordinationStrategy`.
+     * `by-*` real-time transport is injected via `mesh`.
      */
-    get coordination(): CoordinationProvider;
+    get mesh(): NoydbMesh;
     /**
      * #693: true when multi-tab coordination is active at all — presence/election
      * alone (`propagateWrites: false`) or full write-propagation — a peer tab can

package/dist/kernel/query/builder.d.ts

@@ -270,6 +270,32 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      * carries the original `T` fields plus `result[as]` populated from every
      * right-side row (or the filtered subset when `on:` is supplied).
      *
+     * **⚠️ INNER-join semantics — an empty right subset DROPS the left row.**
+     * Each left row is emitted once per matching right row, so when `on:`
+     * yields nothing the row vanishes with no error, no warning and no count
+     * mismatch. This bites hardest on a reverse FK, where `.join()` (which is
+     * forward-only, and already a genuine LEFT outer join) does not apply and
+     * `.crossJoin()` is the only tool. To keep the row, return a one-element
+     * array holding `null`:
+     *
+     * ```ts
+     * .crossJoin('clients', { as: 'client', on: (b) => byEntity.get(b.entityId) ?? [null] })
+     * //                                                                          ^^^^^^^^
+     * //                                              the ONLY thing preserving the row
+     * ```
+     *
+     * **Prefer `outer: true`**, which does exactly this and types the alias as
+     * `TTarget | null`:
+     *
+     * ```ts
+     * .crossJoin('clients', { as: 'client', outer: true, on: (b) => byEntity.get(b.entityId) ?? [] })
+     * ```
+     *
+     * The `?? [null]` form remains valid and is what `outer` does internally, but
+     * it is invisible intent: it types the alias as non-null while the row can
+     * hold null, and a later "simplification" that drops it silently
+     * reintroduces the row loss.
+     *
      * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
      * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
      * where clause references the aliased fields).
@@ -286,14 +312,22 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
      *
      * Requires a JoinContext (constructed via `collection.query()`).
      */
-    crossJoin<TTarget = unknown, As extends string = string>(target: string, opts: {
+    crossJoin<TTarget = unknown, As extends string = string, TOuter extends boolean = false>(target: string, opts: {
         as: As;
         on?: ((left: T) => unknown[] | ((right: TTarget) => boolean)) | {
             readonly predicate: string;
         };
         maxRows?: number;
+        /**
+         * Keep the left row when its right side is empty, with `null` under
+         * `as`, instead of dropping it (#1130). Widens the alias to
+         * `TTarget | null` — which is why it is a type parameter rather than a
+         * plain boolean: `outer: false` must not pay for a null the row can
+         * never hold.
+         */
+        outer?: TOuter;
     }): Query<T & {
-        [K in As]: TTarget;
+        [K in As]: TOuter extends true ? TTarget | null : TTarget;
     }, S, Q, M>;
     /**
      * Execute the plan and return the matching records. When the plan
@@ -309,6 +343,12 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
     toArray(opts?: {
         locale?: string;
     }): T[];
+    /**
+     * Joins need a `JoinContext`. Unreachable in practice — `.join()` throws
+     * when one is missing — but belt-and-braces for a plan built through the
+     * raw `Query` constructor with joins pre-populated.
+     */
+    private requireJoinContext;
     /**
      * Decode this source's Via-covered fields on read (e.g. money: stored
      * scaled-int → canonical decimal), so `query().toArray()` agrees with
@@ -330,12 +370,19 @@ export declare class Query<T, S extends keyof T = never, Q extends keyof T & str
     }): T | null;
     /**
      * Return the number of matching records (after where/filter,
-     * before limit). **Joins are NOT applied** — count() reports the
-     * left-side cardinality, because joins in are projection-only
+     * before limit). **Joins are normally NOT applied** — count() reports the
+     * left-side cardinality, because joins are projection-only
      * (they attach an aliased field; they never filter). Running joins
      * here just to discard the aliases would be wasteful, and in strict
      * mode it could throw `DanglingReferenceError` for a call whose
      * intent is purely to count.
+     *
+     * The exception (#1030) is a `where` clause addressing a join alias. Then
+     * the legs must run, because the predicate is part of what is being
+     * counted — skipping them would report the unfiltered left cardinality.
+     * A strict-mode `DanglingReferenceError` becomes reachable from `count()`
+     * in exactly that case, which is acceptable: the caller asked to filter on
+     * the joined side, so they asked for the join.
      */
     count(): number;
     /**

package/dist/kernel/query/join.d.ts

@@ -45,6 +45,7 @@
  * including joined reads.
  */
 import type { RefDescriptor, RefMode } from '../refs.js';
+import type { Clause } from './predicate.js';
 /** Planner strategy for a single join leg. Auto-selected unless overridden. */
 export type JoinStrategy = 'hash' | 'nested';
 /** Default per-side row ceiling before `.join()` throws `JoinTooLargeError`. */
@@ -168,6 +169,32 @@ export interface JoinContext {
      */
     resolveDictSource?(field: string): JoinableSource | null;
 }
+/**
+ * Split a plan's clauses into those evaluable before the join legs run and
+ * those that need the joined shape (#1030).
+ *
+ * Join legs attach after `where` so the left set can be narrowed (and
+ * index-driven) first. That is the right default, but it silently broke any
+ * predicate addressing a joined alias: the field did not exist yet, so
+ * `readPath` returned `undefined`, nothing matched, and the query returned an
+ * empty result with no error.
+ *
+ * The split is deliberately narrow. When no clause addresses an alias — every
+ * query written against the previous behaviour — `postJoin` is empty and the
+ * caller takes its original path unchanged. The reordered pipeline therefore
+ * only ever runs for queries that match nothing today.
+ *
+ * KNOWN RESIDUAL: `.filter(r => r.client?.name === 'Ann')` cannot be
+ * classified (the predicate is a closure), so it still runs pre-join and still
+ * sees no alias. Prefer `.where()` for anything addressing a joined field.
+ *
+ * Shared by the eager `Query` and the streaming `ScanBuilder` so the two
+ * cannot drift on which side a clause belongs to.
+ */
+export declare function splitAroundJoins(clauses: readonly Clause[], joins: readonly JoinLeg[]): {
+    readonly preJoin: readonly Clause[];
+    readonly postJoin: readonly Clause[];
+};
 /**
  * Apply every join leg in the plan against a base set of left-side
  * rows. Called by the query executor after `where` / `orderBy` /

package/dist/kernel/query/live.d.ts

@@ -6,11 +6,18 @@
  * collection AND every right-side collection a join leg points at)
  * mutates.
  *
- * Framework-agnostic by design. The Vue layer wraps a `LiveQuery`
- * in a Vue `Ref<T[]>` by subscribing once and copying `value` into
- * the ref on every notification. React/Solid/Svelte adapters do the
- * same with their own primitives. Core never depends on a UI
- * framework.
+ * Framework-agnostic by design — core never depends on a UI
+ * framework. The binding that wraps a `LiveQuery` is
+ * `@noy-db/in-vue`'s `useLiveQuery(live)`: it subscribes once,
+ * mirrors `value` into a `ShallowRef`, re-reads `error` on every
+ * notification, and disposes via `onScopeDispose`.
+ * `@noy-db/in-pinia`'s `store.liveQuery(build)` delegates to it, so
+ * there is one implementation rather than two that drift (#1131).
+ *
+ * There is NO wrapper for `in-react`, `in-solid` or `in-svelte` — a
+ * consumer on those subscribes directly (see **Error semantics**
+ * below, which is the part a hand-rolled wrapper usually gets
+ * wrong). Do not describe those adapters as existing until one does.
  *
  * **Error semantics.** A `.live()` query may throw at re-run time —
  * a strict-mode `DanglingReferenceError` is the most common case
@@ -57,10 +64,25 @@
  */
 export interface LiveQuery<T> {
     /**
-     * Current snapshot of the query result. Updated in place on
-     * every upstream change. The reference returned is the same
-     * `readonly T[]` array — consumers that want change detection by
-     * reference should copy: `const arr = [...live.value]`.
+     * Current snapshot of the query result.
+     *
+     * **A FRESH ARRAY on every successful re-run** — `refresh()` assigns
+     * `this._value = this.recompute()`, and `recompute` is the query's own
+     * `toArray()`. So the reference CHANGES on each change, and reference
+     * identity is a valid change signal: a Vue `shallowRef`, a React
+     * `useState`, or any `Object.is` comparison detects an update without
+     * copying.
+     *
+     * The corollary is the part that bites: a consumer who reads `value`
+     * ONCE and holds the array gets a snapshot that never updates. Read it
+     * again after each notification — do not cache it.
+     *
+     * (An earlier version of this comment said the opposite — "updated in
+     * place… the reference returned is the same array" — and told callers to
+     * copy for change detection. Both halves were wrong, and the advice was
+     * backwards. Verified against `buildLiveQuery`: two reads across a
+     * notification are not `===`, and the first array still holds the old
+     * contents.)
      */
     readonly value: readonly T[];
     /**