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

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

@@ -0,0 +1,62 @@
+/**
+ * Read / write the pod-wide `_manifest/schema` envelope.
+ *
+ * Mirrors `with-shape/persisted-schemas/storage.ts`'s shape: the same
+ * standard noy-db record envelope, AES-GCM encrypted with a collection DEK
+ * (here, the `_manifest` collection's own DEK — the manifest INDEX
+ * discloses collection names + hashes + generations + field ids, metadata
+ * rather than schema bodies, so it gets the same encryption grain as
+ * `_schemas` itself).
+ *
+ * Storage layout:
+ *
+ *   <vault>/_manifest/schema   →   EncryptedEnvelope
+ *
+ * Unlike `persisted-schemas/storage.ts` (which takes an already-resolved
+ * `EnclaveKey`), these functions take a `getDEK` resolver and call
+ * `getDEK(MANIFEST_COLLECTION)` themselves — there is exactly one manifest
+ * record per pod, so there is no per-collection DEK the caller needs to
+ * pick; resolving it here keeps every manifest call-site symmetric.
+ *
+ * @module
+ */
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import { type SchemaManifest, type SchemaManifestEntry } from './types.js';
+/** A resolver for a collection's DEK — the same shape as `Vault`'s internal `getDEK`. */
+export type GetManifestDEK = (collectionName: string) => Promise<EnclaveKey>;
+/**
+ * A decrypted schema-manifest read paired with the wrapping envelope's `_v`
+ * — the optimistic-concurrency token. Pass `version` back to
+ * {@link saveSchemaManifest} (via `writeSchemaManifest`'s `expectedVersion`)
+ * to make the write a strict CAS.
+ */
+export interface LoadedSchemaManifest {
+    /** Wrapping envelope `_v`. */
+    readonly version: number;
+    /** Decrypted schema manifest. */
+    readonly manifest: SchemaManifest;
+}
+/**
+ * Read the `_manifest/schema` envelope together with its wrapping `_v`.
+ * Returns `undefined` when no manifest has ever been written, when the
+ * envelope fails to decrypt (wrong DEK), or when it doesn't parse as a
+ * `v: 1, kind: 'schema'` manifest.
+ */
+export declare function loadSchemaManifestEntry(store: NoydbStore, vault: string, getDEK: GetManifestDEK): Promise<LoadedSchemaManifest | undefined>;
+/**
+ * Encrypt and persist the schema manifest as a strict CAS write:
+ * `expectedVersion` must match the stored envelope's `_v` (0 when no
+ * envelope exists yet) or `store.put` throws `ConflictError` — surfaced by
+ * `writer.ts`'s `writeSchemaManifest` as `ManifestConflictError` rather than
+ * retried.
+ */
+export declare function saveSchemaManifest(store: NoydbStore, vault: string, manifest: SchemaManifest, expectedVersion: number, getDEK: GetManifestDEK): Promise<void>;
+/**
+ * `sha256Hex(canonicalJson(collections))` — the pod-wide content binding
+ * over a schema manifest's per-collection index. Canonical JSON sorts
+ * object keys at every depth, so the result is independent of the map's
+ * key insertion order. Shared by the writer's tests and (#941 Task 3) the
+ * derivation path, so the hash is computed identically everywhere.
+ */
+export declare function computeAggregateHash(collections: Record<string, SchemaManifestEntry>): Promise<string>;

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

@@ -0,0 +1,135 @@
+/**
+ * Keep the persisted `_manifest/schema` record in sync with the
+ * per-collection `_schemas/<collection>` source of truth (#941 Task 3).
+ *
+ * Called from `persisted-schemas/register.ts`'s `persistSchemaIfNeeded`
+ * right after a `_schemas/<collection>` write succeeds.
+ *
+ * ## Reconciling strict-CAS-refuse with the derived nature of the manifest
+ *
+ * `writer.ts`'s `writeSchemaManifest` is deliberately strict-CAS: a
+ * concurrent *direct* edit to the manifest is refused, never retried (AC
+ * #1). But this call site is not a direct edit — it is a re-derivation
+ * from the source of truth, triggered as a side effect of a `_schemas`
+ * write that has ALREADY succeeded. When N collections are declared
+ * together (one `openVault()` call registering several `persistJsonSchema:
+ * true` collections), their `persistSchemaIfNeeded` calls run CONCURRENTLY
+ * — each one's own `_schemas/<collection>` write lands independently, and
+ * each then calls this function. A single derive-then-write with no
+ * feedback loop is NOT enough here: a call whose `deriveSchemaManifest`
+ * snapshot ran before a sibling's `_schemas` write landed would persist a
+ * manifest that's missing that sibling forever (nothing re-triggers it) —
+ * this was a REAL bug (not a test-isolation artifact — reproduced with 0
+ * shared state, purely from concurrent `_schemas` writes racing the derive
+ * snapshot; see #941 flake fix commit). `syncSchemaManifest` therefore
+ * loops (bounded by {@link MAX_SYNC_ATTEMPTS}):
+ *
+ *   1. Derive fresh, compare to what's persisted. Already converged → done.
+ *   2. Write via strict-CAS. `ManifestConflictError` (another writer moved
+ *      the manifest first) → loop: re-derive against the NEW state and
+ *      retry, exactly like a normal optimistic-CAS retry.
+ *   3. On a successful write, derive ONE more time. If a sibling's
+ *      `_schemas` write landed while we were deriving/writing, the state
+ *      has already moved past what we just wrote — loop again to catch it
+ *      up. If the re-derive matches what we wrote, we're the last writer
+ *      and the manifest is provably converged: return.
+ *
+ * This guarantees that whichever collection's `_schemas` write is the LAST
+ * to land (in real wall-clock order — there is always exactly one, even
+ * though no single caller knows which) ends up running a sync whose own
+ * derive sees every sibling's write already committed, and whose
+ * recheck-after-write confirms nothing moved further — so it converges the
+ * manifest deterministically, regardless of interleaving. If attempts are
+ * exhausted under pathological contention, the loop gives up — with a
+ * `console.warn` (see cap-exhaustion note below), not silently — leaving
+ * the last successful write in place; the manifest is a derivable cache
+ * (not a correctness invariant), so a next schema write or `open()`'s
+ * re-derive still converges it, matching how `persistSchemaIfNeeded`
+ * already treats its own write failures.
+ * Any error OTHER than `ManifestConflictError` (store failure, DEK
+ * resolution failure, etc.) is NOT swallowed — it propagates to the
+ * caller immediately, matching how `persistSchemaIfNeeded` already treats
+ * its own write failures as a visible (not silently discarded) fingerprint
+ * failure.
+ *
+ * ## CRITICAL fix (#941 review): a scoped principal must never write a
+ * partial manifest
+ *
+ * `deriveSchemaManifest` returns `undecodableCollections` for any
+ * `_schemas/<collection>` entry this principal's `lookupDEK` couldn't
+ * resolve — e.g. a member `grant()`-scoped to one collection can decrypt
+ * `_manifest` itself (system-prefixed DEKs propagate to every role) but
+ * NOT a sibling data collection's `_schemas/<sibling>` entry. Before this
+ * fix, `deriveSchemaManifest` silently treated "can't decrypt" the same as
+ * "no derivable content" and omitted the sibling — so a scoped member's
+ * OWN schema declare would derive a manifest missing every collection they
+ * can't see, load the real (complete) persisted manifest as a valid CAS
+ * token, observe a hash mismatch, and OVERWRITE it — permanently dropping
+ * the siblings, silently, ledger-audited as a legitimate migration. The
+ * converging recheck loop above made this WORSE, not better: re-deriving
+ * from the same restricted view just re-confirms the same partial result
+ * and declares it "stable."
+ *
+ * Fix: if `undecodableCollections` is non-empty, `syncSchemaManifest`
+ * `SKIP`s entirely — no read-compare, no write, no audit, no loop. It does
+ * NOT try to merge-preserve the undecodable entries from what's currently
+ * persisted: an `aggregateHash` computed over entries this principal can't
+ * verify would be a hash asserting something it never actually checked,
+ * which is worse than not writing at all. This is safe because:
+ *
+ *   - The source of truth, `_schemas/<their-collection>`, was ALREADY
+ *     updated by their declare — nothing about their own change is lost.
+ *   - The pod-wide `_manifest` cache simply isn't rewritten by a principal
+ *     who'd corrupt it by omission — it stays whatever a full-visibility
+ *     principal (owner/admin/custodian) last wrote.
+ *   - `open()` re-derives from `_schemas` directly (not from the cached
+ *     manifest) for whoever opens it, so a stale cache is never load-bearing.
+ *   - The NEXT full-visibility principal's declare (or any subsequent sync
+ *     by someone with complete access) naturally refreshes the cache,
+ *     including the scoped member's own just-landed change.
+ *
+ * ## Ledger audit (AC #5)
+ *
+ * Schema-generation transitions are not ledger-audited anywhere else today
+ * (neither the `_schemas/<collection>` write in `register.ts` nor the fence
+ * bump in `schema-update/fence-controller.ts#runCutover`). This is the
+ * first ledger-audited signal for a schema change: every manifest write
+ * that actually happens (i.e. every time the derived manifest differs from
+ * what's stored) appends an `op: 'migration'` entry via the optional
+ * `getLedgerOrNull` callback — `null`/absent when the history strategy
+ * isn't opted in, matching every other optional-ledger call site
+ * (`vault._getLedgerOrNull()?.append(...)`, see `liberate.ts`,
+ * `with-audit/periods/vault-facade.ts`). No audit fires on the no-op path
+ * (derived manifest unchanged), on a swallowed conflict (the winning
+ * writer's own sync already audits its write), or on the scoped-principal
+ * SKIP path above (nothing was written).
+ *
+ * @module
+ */
+import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import { type LookupDEK } from './derive.js';
+import { type GetManifestDEK } from './storage.js';
+export interface ManifestSyncDeps {
+    /** Resolver for `_manifest`'s OWN DEK — mints if absent (this principal's declare is about to write it). */
+    readonly getDEK: GetManifestDEK;
+    /**
+     * NON-MINTING lookup for every OTHER (sibling data) collection's DEK,
+     * used by `deriveSchemaManifest` to build the index — see `derive.ts`'s
+     * `LookupDEK` doc for why minting here would be actively harmful.
+     */
+    readonly lookupDEK: LookupDEK;
+    /** Optional ledger handle — absent when the history strategy isn't opted in (no-op audit). */
+    readonly getLedgerOrNull?: () => LedgerStore | null;
+}
+/**
+ * Re-derive the schema manifest and write it if it changed, looping until
+ * the write is provably stable against concurrent sibling `_schemas`
+ * writes (see module doc). SKIPS entirely (no write, no audit) when this
+ * principal's view is incomplete (`undecodableCollections` non-empty) —
+ * see the module doc's CRITICAL fix section. Swallows a
+ * {@link ManifestConflictError} by retrying against the fresher state; any
+ * other error propagates. Ledger-audits (`op: 'migration'`) once per
+ * successful write.
+ */
+export declare function syncSchemaManifest(store: NoydbStore, vault: string, deps: ManifestSyncDeps): Promise<void>;

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

@@ -0,0 +1,49 @@
+/**
+ * The pod-wide **schema manifest** record type (#941).
+ *
+ * This is an INDEX, not a full-inline manifest: `SchemaManifest.collections`
+ * carries per-collection *metadata* (generation / content hash / field ids),
+ * never the JSON Schema body itself. The JSON Schema stays the source of
+ * truth at `_schemas/<collection>`, encrypted under that collection's own
+ * DEK (see `with-shape/persisted-schemas`). Inlining full schemas into one
+ * pod-wide manifest record would either leak every collection's schema to a
+ * principal scoped to a single collection, or force the manifest itself
+ * onto a collection-DEK it has no business holding — the index preserves
+ * per-collection DEK isolation while still giving a single place to answer
+ * "what schema generation is this pod at, and does collection X's stored
+ * schema match its declared content hash."
+ *
+ * `aggregateHash` binds the whole per-collection index's content: it is
+ * `sha256Hex(canonicalJson(collections))`, so any change to any collection's
+ * entry (a new generation, a changed hash, added/renamed field ids) changes
+ * `aggregateHash` too. Canonical JSON (sorted object keys, no whitespace)
+ * makes the hash independent of the map's key insertion order.
+ *
+ * @module
+ */
+/** Per-collection entry inside a {@link SchemaManifest}'s `collections` index. */
+export interface SchemaManifestEntry {
+    /** The vault-wide schema-fence generation this collection's schema was last written at. */
+    readonly generation: number;
+    /** SHA-256 (hex) of the collection's canonicalised JSON Schema (see `persisted-schemas/derive.ts`). */
+    readonly contentHash: string;
+    /** Stable per-field ids (#946), keyed by the field's current name. Absent when the collection has none. */
+    readonly fieldIds?: Record<string, string>;
+}
+/**
+ * The pod-wide schema manifest — one record per pod, stored at
+ * `_manifest/schema` (see `storage.ts`). An INDEX over the per-collection
+ * `_schemas/<collection>` entries, not the schemas themselves.
+ */
+export interface SchemaManifest {
+    readonly v: 1;
+    readonly kind: 'schema';
+    /** Pod-wide schema-fence generation (`FenceDoc.currentSchemaVersion`) as of this manifest's derivation. */
+    readonly generation: number;
+    /** Per-collection index: collection name → its manifest entry. */
+    readonly collections: Record<string, SchemaManifestEntry>;
+    /** `sha256Hex(canonicalJson(collections))` — the pod-wide content binding over the index. */
+    readonly aggregateHash: string;
+}
+/** The record id the schema manifest is stored under inside `_manifest`. */
+export declare const MANIFEST_SCHEMA_RECORD_ID: "schema";

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

@@ -0,0 +1,32 @@
+/**
+ * Strict-CAS schema-manifest writer (#941, AC #1).
+ *
+ * Every other reserved-collection writer in the hub (`persisted-schemas`'s
+ * `savePersistedSchema` callers, the classified/satellite marker writers)
+ * retries on a CAS conflict: re-read, re-apply, try again. The schema
+ * manifest deliberately does NOT — two concurrent *direct* edits to the
+ * manifest must be refused and surfaced, never silently merged or
+ * retry-resolved, because a manifest write encodes a specific point-in-time
+ * claim about the pod's schema generation/content-hash set. A caller that
+ * lost the race must re-derive against the fresh state and decide what to
+ * do, not have its stale write quietly re-applied on top of someone else's.
+ *
+ * Ledger audit: this writer does not have a `LedgerStore` handle at this
+ * seam (mirroring `persisted-schemas`, whose `_schemas/<collection>` writes
+ * are likewise not ledger-audited today). Wiring `LedgerStore.append({ op:
+ * 'migration', ... })` around a manifest write belongs at the call site
+ * where a ledger handle is already in scope (the open/write integration —
+ * #941 Task 3/4), not here.
+ *
+ * @module
+ */
+import { type GetManifestDEK } from './storage.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { SchemaManifest } from './types.js';
+/**
+ * Write the schema manifest as a strict CAS: `expectedVersion` must match
+ * the stored envelope's `_v` (0 when no manifest exists yet). On a
+ * conflict, throws {@link ManifestConflictError} — this function never
+ * retries.
+ */
+export declare function writeSchemaManifest(store: NoydbStore, vault: string, manifest: SchemaManifest, expectedVersion: number, getDEK: GetManifestDEK): Promise<void>;

package/dist/with-shape/persisted-schemas/field-ids.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stable field-identifier minting (#946).
+ *
+ * A field's `id` is opaque and permanent — minted once, from randomness
+ * only, with no timestamp and no name-derivation. A name-derived id would
+ * change when the field is renamed, defeating the whole point (identity
+ * must survive a rename). See `PersistedSchemaEnvelope.fieldIds`.
+ *
+ * @module
+ */
+/**
+ * Resolve the `fieldIds` map for a freshly-derived schema against the
+ * previously-stored envelope's map (if any). Existing ids are preserved by
+ * name — a field keeps its id across re-derivation as long as its name is
+ * unchanged; a genuinely new field name mints a fresh id. Returns
+ * `undefined` when the fresh schema has no derivable top-level field set
+ * (e.g. a stub envelope, or a non-object root schema).
+ *
+ * `renamed` (#946 Task 2) — unambiguous rename pairs from
+ * `computeSchemaDelta`'s `SchemaDelta.renamed`. When the fresh name is a
+ * rename target (`to`), the id is looked up under its OLD name (`from`)
+ * instead of the fresh name itself — the whole point of a stable field id
+ * is that it survives exactly this case; without it, a rename would mint a
+ * fresh id for the new name and silently drop the old one.
+ */
+export declare function resolveFieldIds(freshJsonSchema: object | null, priorFieldIds: Record<string, string> | undefined, renamed?: readonly {
+    readonly from: string;
+    readonly to: string;
+}[]): Record<string, string> | undefined;

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

@@ -13,6 +13,7 @@
  *
  * @module
  */
+import { type ManifestSyncDeps } from '../manifest/sync.js';
 import type { SchemaUpdateStrategy, UpdateDecision } from '../schema-update/types.js';
 import type { NoydbStore, ClassifiedMarker } from '../../kernel/types.js';
 import type { PersistedSchemaEnvelope } from './types.js';
@@ -35,6 +36,8 @@ export declare function persistSchemaIfNeeded(opts: {
     readonly validator: unknown;
     readonly dek: EnclaveKey;
     readonly strategies?: readonly SchemaUpdateStrategy[];
+    /** #941 Task 3: re-derive + sync the `_manifest/schema` INDEX after a write. Omitted → no sync (e.g. tests that don't care). */
+    readonly manifestSync?: ManifestSyncDeps;
 }): Promise<PersistSchemaResult>;
 /**
  * Persist (or refresh) the C-A / R10 classified marker into the collection's

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

@@ -51,4 +51,21 @@ export interface PersistedSchemaEnvelope {
      * the satellite-pair analogue of {@link classified}'s config-drift guard.
      */
     readonly satellite?: PairingMarker;
+    /**
+     * Stable per-field identifiers (#946), keyed by the field's current name
+     * (top-level JSON Schema `properties` key) and mapping to an opaque,
+     * permanent id minted once via `mintFieldId()`. IDs are preserved by name
+     * across re-derivation (a field keeps its id as long as its name is
+     * unchanged) so a field's identity survives a rename — the name is a
+     * label, the id is the stable key. Absent on a legacy (pre-#946) envelope
+     * and on a stub envelope with no derivable field set (`jsonSchema === null`).
+     */
+    readonly fieldIds?: Record<string, string>;
+    /**
+     * The vault-wide schema-fence generation (`FenceDoc.currentSchemaVersion`)
+     * as of this envelope's most recent write. Together with
+     * `FenceDoc.schemaHash`, answers "generation N = which schema content
+     * hash" (#946). Absent on a legacy (pre-#946) envelope.
+     */
+    readonly generation?: number;
 }

package/dist/with-shape/schema-update/fence-controller.d.ts

@@ -17,6 +17,37 @@ import type { TransformFn } from './types.js';
 import { type CoordinationProvider } from '../../port/by/index.js';
 /** Runs one collection's transform; supplied by the Vault (binds to a Collection). */
 export type RunTransform = (collection: string, transform: TransformFn) => Promise<void>;
+/** Structural (no static import — kernel-spine port-layering carve-out, same rationale as
+ *  `kernel/via/dispatch.ts`'s `AuditLedgerLike`) shape of the with-history `LedgerStore.append`
+ *  seam {@link schemaBumpAuditHook} needs. */
+interface AuditLedgerLike {
+    append(input: {
+        readonly op: 'lifecycle';
+        readonly collection: string;
+        readonly id: string;
+        readonly version: number;
+        readonly actor: string;
+        readonly payloadHash: string;
+        readonly reason?: string;
+    }): Promise<unknown>;
+}
+/**
+ * #965 — a bare `runCutover` generation bump (no re-declare, no per-record
+ * migrations) otherwise leaves zero ledger evidence: per-record `migration`
+ * entries only fire from `applyCutoverTransform` when records + a transform
+ * exist. Mirrors `ledgerAuditHook` (`kernel/via/dispatch.ts`): encoded as a
+ * `'lifecycle'` entry (no ciphertext to hash, `payloadHash: ''`), distinct
+ * from the per-record `op: 'migration'` entries via its
+ * `reason: 'schema:generation-bump=<n>'`. Fires once per successful bump,
+ * always — even when the same cutover also produced per-record entries —
+ * so "one bump entry per generation bump" stays a simple, unconditional
+ * invariant to audit against.
+ *
+ * `getLedger` is called lazily (at bump time, not at wiring time) — same
+ * lazy-init contract as `Vault.getLedgerOrNull`; calling it eagerly during
+ * `Vault` construction (before `this.strategies` is assigned) would throw.
+ */
+export declare function schemaBumpAuditHook(getLedger: () => AuditLedgerLike | null, actor: string): (generation: number) => Promise<void>;
 export declare class SchemaFenceController {
     #private;
     constructor(opts: {
@@ -38,6 +69,8 @@ export declare class SchemaFenceController {
             currentSchemaVersion: number;
             fenceState: FenceState;
         }) => void;
+        /** #965 — best-effort ledger audit for a bare (no-record) generation bump. See {@link schemaBumpAuditHook}. */
+        auditBump?: ((generation: number) => Promise<void>) | undefined;
     });
     /** Capture the generation snapshot at vault-open. */
     init(): Promise<void>;
@@ -60,3 +93,4 @@ export declare class SchemaFenceController {
     /** Recover a stuck drain: reset fenceState to normal at the current version (no bump). */
     abort(): Promise<void>;
 }
+export {};

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

@@ -8,6 +8,15 @@ export type FenceState = 'normal' | 'draining' | 'migrating' | 'complete';
 export interface FenceDoc {
     readonly currentSchemaVersion: number;
     readonly fenceState: FenceState;
+    /**
+     * Content hash (`PersistedSchemaEnvelope.hash`) of the schema most
+     * recently persisted while the vault sat at `currentSchemaVersion` —
+     * binds "generation N" to a concrete schema-content hash (#946), so
+     * "which schema is generation N" is answerable from `schemaFenceState()`
+     * alone. Optional: absent on a fresh vault (generation 0, nothing
+     * persisted yet) and on a fence document written before #946.
+     */
+    readonly schemaHash?: string;
 }
 export declare const FENCE_RECORD_ID = "schema-fence";
 export declare const DEFAULT_FENCE: FenceDoc;

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

@@ -1,11 +1,27 @@
 import type { SchemaUpdateStrategy } from './types.js';
 /** Allow any schema change. Explicit blind / back-compat. */
 export declare function blindUpdate(): SchemaUpdateStrategy;
-/** Allow additive changes; reject non-additive ones. The safety backstop. */
+/**
+ * Allow additive changes; reject non-additive ones. The safety backstop.
+ *
+ * #946: a `renamed` pair is NOT additive-safe *for this gate* — the delta
+ * itself carries no data migration, so an allowed rename would orphan
+ * existing record values under the old key. `computeSchemaDelta` classifies
+ * a pure rename as `kind: 'additive'` (it IS additive-safe as far as the
+ * name-change itself is concerned, and the id-carry through `SchemaDelta.
+ * renamed` is real), but a guard whose whole job is "don't admit anything
+ * that isn't a mechanical additive write" must still block it — the same as
+ * it blocks any other non-additive change — forcing a `coordinatedCutover()`
+ * (or `blindUpdate()`) to actually move the data.
+ */
 export declare function additiveOnly(): SchemaUpdateStrategy;
 /**
  * Reject schema changes. With `fields`, reject only when one of those
- * fields is added/removed/changed; otherwise reject any non-`none` delta.
+ * fields is added/removed/changed/renamed; otherwise reject any non-`none`
+ * delta. #946: a `renamed` pair's `from` AND `to` both count as touching a
+ * locked field — a rename away from a locked name (or onto one) still
+ * violates the lock, and a blanket `lockSchema()` (no `fields`) already
+ * blocks any rename since a pure rename's `kind` is never `'none'`.
  */
 export declare function lockSchema(opts?: {
     readonly fields?: readonly string[];

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

@@ -23,6 +23,17 @@ export interface SchemaDelta {
     readonly removed: readonly string[];
     /** Top-level properties present in both but altered. */
     readonly changed: readonly FieldChange[];
+    /**
+     * Unambiguous rename pairs detected by shape-matching a removed name
+     * against an added name (#946) — same field, new label. Present only
+     * when at least one pairing was found; the paired names are excluded
+     * from `added`/`removed` (a pure rename is additive-safe, not a
+     * drop+add). See `computeSchemaDelta`'s doc comment for the pairing rule.
+     */
+    readonly renamed?: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[];
 }
 /** Context handed to a strategy alongside the delta. */
 export interface UpdateContext {

package/dist/with-sync/engine.d.ts

@@ -19,6 +19,10 @@ export declare class SyncEngine {
     private readonly vault;
     readonly role: SyncTargetRole;
     readonly label: string | undefined;
+    /** #948: the resolved policy this engine was constructed with, retained for
+     *  introspection (`Noydb.listSyncTargets()`) — otherwise lost once consumed
+     *  into the scheduler below. */
+    readonly policy: SyncPolicy | undefined;
     private dirty;
     private lastPush;
     private lastPull;
@@ -158,6 +162,19 @@ export declare class SyncEngine {
      *  ordinary put. `isTombstoneShape` covers a forgotten-elsewhere record arriving as a shred;
      *  `isDeleteMarker` covers an ordinary (#589) delete — both route to the SAME 'delete' action
      *  (sync delete ≠ forget: freshness only, no shred/residue channel on the receiving side). */
+    /**
+     * #936 — a local-wins resolution write must SUPERSEDE the remote, never
+     * overwrite it in place: when the winner's `_v` does not already exceed
+     * the remote's (the same-`_v` push tie), re-stamp it at `remote._v + 1`.
+     * Without this the loser's next pull sees no delta (`_v`-based
+     * detection) and the peers stay silently diverged at the same version.
+     * `_v` is envelope metadata — AEAD-unbound, and `_vdig` is deliberately
+     * `_v`-independent — so the engine may restamp ciphertext. Callers must
+     * mirror the advanced envelope locally (`applyRemote`) so both sides
+     * agree. The 'merged' branch needs none of this: resolver output is
+     * already stamped `max(local, remote) + 1`.
+     */
+    private advancePastRemote;
     private applyRemote;
     /** Record + emit a tombstone enforcement (#590). */
     private reportErasure;

package/dist/with-sync/presence.d.ts

@@ -26,7 +26,14 @@ export interface PresenceHandleOpts {
     vault: string;
     /** Collection name — used as HKDF `info` and channel suffix. */
     collectionName: string;
-    /** Calling user's ID, embedded unencrypted in storage records. */
+    /**
+     * Calling user's ID. In encrypted mode it is encrypted inside the
+     * storage-poll record's `data` field — the record id is an
+     * adapter-opaque HMAC tag, not the userId, so the adapter never learns
+     * peer identities. Unencrypted vaults have no key to tag or encrypt
+     * with, so the userId is used as the record id in cleartext (dev posture
+     * only — identity privacy requires encryption).
+     */
     userId: string;
     /** Whether encryption is active. When false, presence payloads are stored as JSON. */
     encrypted: boolean;
@@ -51,6 +58,7 @@ export declare class PresenceHandle<P> {
     private readonly channel;
     private readonly storageCollection;
     private presenceKey;
+    private presenceTagKey;
     private subscribers;
     private unsubscribePubSub;
     private pollTimer;
@@ -71,6 +79,28 @@ export declare class PresenceHandle<P> {
     /** Stop all listening and clear resources. */
     stop(): void;
     private getPresenceKey;
+    /**
+     * Derive (and cache) the presence-tag key — a non-extractable, sign-only
+     * HMAC-SHA256 key HKDF-derived from the collection DEK, domain-separated
+     * from the presence payload key by {@link PRESENCE_TAG_KEY_DOMAIN}.
+     * Mirrors `deriveClassifyIndexKey` (kernel/enclave/classify/bidx.ts). No
+     * PBKDF2 stretch — the adapter never holds this key, so a plain keyed HMAC
+     * tag is sufficient and deterministic. Returns `null` when unencrypted
+     * (no DEK to derive from).
+     */
+    private getPresenceTagKey;
+    /**
+     * Deterministic, adapter-opaque tag for `userId` — used as the
+     * storage-poll record id in encrypted mode so the adapter never sees the
+     * userId. Falls back to the raw `userId` when unencrypted (no key exists
+     * to tag with — see {@link PresenceHandleOpts.userId}).
+     *
+     * Signs directly via `subtle.sign` (like `bidx.ts`'s `mintAt`) rather than
+     * the barrel's `hmacSha256Hex` helper: that helper re-exports its key
+     * argument's raw bytes internally, which only works for extractable keys
+     * (e.g. an AES-GCM DEK) — `presenceTagKey` is deliberately non-extractable.
+     */
+    private presenceTag;
     private getPubSubAdapter;
     private startListening;
     private stopListening;

package/dist/withdraw-accessible-JSDQHXHE.js

@@ -0,0 +1,28 @@
+import {
+  FROZEN_SNAPSHOTS_COLLECTION,
+  freezeAndDeleteClosure,
+  freezeSnapshotOnly,
+  randomId,
+  withdrawAccessibleData
+} from "./chunk-JSRU5W2M.js";
+import "./chunk-4MQDV3HZ.js";
+import "./chunk-EK7DT5BT.js";
+import "./chunk-CYQOUTMY.js";
+import "./chunk-FY343IZR.js";
+import "./chunk-NQRJ5AJO.js";
+import "./chunk-HXGUIPQB.js";
+import "./chunk-AR2JDFAE.js";
+import "./chunk-747LRSOO.js";
+import "./chunk-LP7BEXCT.js";
+import "./chunk-VCETL77O.js";
+import "./chunk-24ZLWWEO.js";
+import "./chunk-HNGSV2YC.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  FROZEN_SNAPSHOTS_COLLECTION,
+  freezeAndDeleteClosure,
+  freezeSnapshotOnly,
+  randomId,
+  withdrawAccessibleData
+};
+//# sourceMappingURL=withdraw-accessible-JSDQHXHE.js.map

package/dist/withdraw-accessible-JSDQHXHE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/hub",
-  "version": "0.4.0",
+  "version": "0.6.0-pre.0",
   "description": "Zero-knowledge, offline-first, encrypted document store — core library with AES-256-GCM, PBKDF2, multi-user keyring, and sync engine",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -208,14 +208,14 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@noy-db/attestation": "0.4.0"
+    "@noy-db/attestation": "0.6.0-pre.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "esbuild": "^0.25.0",
     "zod": "^4.0.0",
     "zod-to-json-schema": "^3.25.2",
-    "@noy-db/on-shamir": "0.4.0"
+    "@noy-db/on-shamir": "0.6.0-pre.0"
   },
   "peerDependencies": {
     "zod-to-json-schema": "^3.25.0"

package/dist/api-SI2IVBQO.js

@@ -1,20 +0,0 @@
-import {
-  UserApi,
-  createUserApi
-} from "./chunk-SF2ZIRD6.js";
-import "./chunk-2BET5QTS.js";
-import "./chunk-SU6SGWXM.js";
-import "./chunk-EFJAAFBW.js";
-import "./chunk-35NMVJ7I.js";
-import "./chunk-NFZGZ4AK.js";
-import "./chunk-QJNCB5SK.js";
-import "./chunk-LP7BEXCT.js";
-import "./chunk-AKKRXT23.js";
-import "./chunk-77AEMXFA.js";
-import "./chunk-QZWTRENR.js";
-import "./chunk-PZ5AY32C.js";
-export {
-  UserApi,
-  createUserApi
-};
-//# sourceMappingURL=api-SI2IVBQO.js.map