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

package/dist/port/with/i18n-strategy.d.ts

@@ -0,0 +1,175 @@
+/**
+ * i18n strategy seam (#623 Task 7 — moved out of `via/i18n/strategy.ts`
+ * and `via/i18n/dictionary.ts`, precedent: `port/with/lazy-strategy.ts`).
+ * Lives on the `/with` port (the one seam the kernel spine may import
+ * statically) so `Collection`/`Vault` can hold the `NO_I18N` default and the
+ * two reserved-name/brand predicates without a spine→service static import.
+ *
+ * Core imports `I18nStrategy` type-only + `NO_I18N` stub; real
+ * `applyI18nLocale` / `validateI18nTextValue` / `DictionaryHandle` are only
+ * reachable via `withI18n()` in `via/i18n/active.ts`.
+ *
+ * Solo apps that don't use `i18nText()` fields, don't declare `dictKey()`
+ * fields, and don't open a `vault.dictionary(...)` handle ship none of the
+ * ~854 LOC behind this seam.
+ *
+ * Behavior under NO_I18N:
+ *
+ * - **applyI18nLocale** — returns the record unchanged. Apps without
+ *   any i18n descriptors never observe a difference; apps that
+ *   *did* declare i18nText/dictKey fields without opting into the
+ *   strategy still get raw values back (locale resolution silently
+ *   skipped). The validators below ensure the misconfiguration is
+ *   caught at write time instead.
+ * - **validateI18nTextValue** — throws when called. Only fires when
+ *   a collection declared `i18nFields`; if you declared the field,
+ *   you must opt in.
+ * - **buildDictionaryHandle** — throws when called. Only fires when
+ *   user code calls `vault.dictionary(...)`.
+ *
+ * #650 Task 1 (via-lookup extraction, phase D): the real
+ * `buildDictionaryHandle` (in `via/i18n/active.ts`) now delegates to
+ * `withLookup().buildLookupHandle` (`via/lookup/active.ts`) — same
+ * handle (`LookupHandle`, aliased as `DictionaryHandle`), new home. This
+ * interface's shape is unchanged.
+ *
+ * @internal
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
+import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+import type { I18nTextDescriptor } from '../../via/i18n/core.js';
+import type { Layer } from '../../via/i18n/policy.js';
+import type { ScriptWarning } from '../../via/i18n/script.js';
+import type { DictKeyDescriptor, DictionaryHandle, DictionaryOptions, StaticDictDescriptor } from '../../via/i18n/dictionary.js';
+import type { ViaCryptoCtx } from '../../kernel/via/index.js';
+import type { EncryptedEnvelope } from '../../kernel/types.js';
+/**
+ * Options accepted by `I18nStrategy.buildDictionaryHandle`. Mirrors
+ * the `DictionaryHandle` constructor verbatim — kept here so core
+ * code never imports the dictionary module at runtime.
+ *
+ * @internal
+ */
+export interface BuildDictionaryHandleOptions<Keys extends string = string> {
+    adapter: NoydbStore;
+    compartmentName: string;
+    dictionaryName: string;
+    keyring: UnlockedKeyring;
+    /**
+     * The `reservedEnvelopes('_dict_')` capability (#629 Task 4) — DictionaryHandle's
+     * sanctioned crypto door onto its `_dict_<name>` collection. Bound by the
+     * Vault to its own `getDEK`, the same per-collection-name DEK resolver
+     * every other collection uses.
+     */
+    reservedEnvelopes: ReturnType<ViaCryptoCtx['reservedEnvelopes']>;
+    encrypted: boolean;
+    ledger: LedgerStore | undefined;
+    options: DictionaryOptions;
+    findAndUpdateReferences: ((dictionaryName: string, oldKey: string, newKey: string) => Promise<void>) | undefined;
+    emitter: NoydbEventEmitter;
+    /**
+     * Used by the active strategy to satisfy the generic-key parameter
+     * on the returned handle. The NO_I18N stub never reads it.
+     */
+    _keyMarker?: Keys;
+    /** #650 Task 4 (#647) — choke-point participation hooks, passed through to `buildLookupHandle`. */
+    onDirty?: ((collection: string, id: string, action: 'put' | 'delete', version: number) => Promise<void>) | undefined;
+    onRecordMutated?: ((collection: string, id: string, action: 'put' | 'delete', version: number) => Promise<void>) | undefined;
+    /**
+     * #647 fix wave 1 — mints a version-ordered delete-marker envelope, passed through to
+     * `buildLookupHandle`. See `port/with/lookup-strategy.ts`'s `BuildLookupHandleOptions` doc
+     * comment for why this is injected rather than imported by the handle itself.
+     */
+    buildDeleteMarker: (version: number, actor: string) => EncryptedEnvelope;
+    /** #650 Task 5 (#648) — the real reference check, passed through to `buildLookupHandle`. */
+    checkReferencesOnDelete?: ((key: string) => Promise<unknown>) | undefined;
+}
+/**
+ * @internal
+ */
+export interface I18nStrategy {
+    /**
+     * Resolve `i18nText` fields on a record to the requested locale and
+     * return a new object. Returns the input unchanged under
+     * `NO_I18N`.
+     */
+    applyI18nLocale(record: Record<string, unknown>, fields: Record<string, I18nTextDescriptor>, locale: string, fallback?: string | readonly string[], layer?: Layer): Record<string, unknown>;
+    /**
+     * Validate that an i18nText field's value satisfies its descriptor
+     * (required locales present, etc.). Throws under `NO_I18N` —
+     * declaring i18nFields without opting in is a misconfiguration.
+     */
+    validateI18nTextValue(value: unknown, field: string, descriptor: I18nTextDescriptor): void;
+    /**
+     * Enforce per-locale script constraints over an i18nText value map
+     * (write-time). Returns the (possibly filtered) value plus any
+     * non-fatal warnings. Returns the value unchanged when the field has
+     * no `script` option, or under `NO_I18N`.
+     */
+    enforceScript(value: Record<string, unknown>, field: string, descriptor: I18nTextDescriptor, exempt?: ReadonlySet<string>): {
+        value: Record<string, unknown>;
+        warnings: ScriptWarning[];
+    };
+    /**
+     * Per-field locales that are unchanged round-tripped densify fills (exempt
+     * from write-time script enforcement). Empty under NO_I18N.
+     */
+    computeExemptFills(prior: Record<string, unknown> | undefined, incoming: Record<string, unknown>, fields: Record<string, I18nTextDescriptor>): Map<string, Set<string>>;
+    /**
+     * Eager-fill empty i18n slots from each field's substitute chain and record
+     * provenance in `record['_i18nFilled']`. Mutates `record`. No-op under
+     * NO_I18N.
+     */
+    densify(record: Record<string, unknown>, prior: Record<string, unknown> | undefined, fields: Record<string, I18nTextDescriptor>): void;
+    /**
+     * Construct a typed `DictionaryHandle` for the named dictionary.
+     * Throws under `NO_I18N`.
+     */
+    buildDictionaryHandle<Keys extends string = string>(opts: BuildDictionaryHandleOptions<Keys>): DictionaryHandle<Keys>;
+}
+/**
+ * No-i18n stub. Locale resolution is the identity; validation and
+ * dictionary construction throw with an actionable pointer.
+ *
+ * @internal
+ */
+export declare const NO_I18N: I18nStrategy;
+/**
+ * Return true when a collection name is a reserved dictionary collection
+ * (the `_dict_*` prefix). Mirrors `DICT_COLLECTION_PREFIX` — now on
+ * `via/lookup/handle.ts` (#650 Task 1), re-exported from
+ * `via/i18n/dictionary.ts` for compat — duplicated here (not
+ * imported) so this port has no VALUE dependency back on the feature; keep
+ * the two in sync if the prefix ever changes.
+ */
+export declare function isDictCollectionName(name: string): boolean;
+/** Runtime predicate for detecting a StaticDictDescriptor. */
+export declare function isStaticDictDescriptor(x: unknown): x is StaticDictDescriptor;
+/**
+ * Runtime predicate for detecting an I18nTextDescriptor. Pure tag check —
+ * moved here (#623 Task 11) alongside `isStaticDictDescriptor` so
+ * `kernel/via/compose.ts` (`mergeViaFields`'s descriptor-shape classification)
+ * can reach it through the port instead of importing `via/i18n/core.js`
+ * directly. Re-exported from that module for compat with existing importers.
+ */
+export declare function isI18nTextDescriptor(x: unknown): x is I18nTextDescriptor;
+/**
+ * Runtime predicate for detecting a DictKeyDescriptor. Pure tag check —
+ * moved here (#623 Task 11) for the same reason as `isI18nTextDescriptor`
+ * above. Re-exported from `via/i18n/dictionary.js` for compat with
+ * existing importers.
+ */
+export declare function isDictKeyDescriptor(x: unknown): x is DictKeyDescriptor;
+/**
+ * Type-only re-exports (#623 Task 8) — the kernel spine (collection.ts,
+ * collection-config.ts, vault.ts, types.ts) imports these descriptor/handle
+ * types through the port instead of reaching into `via/i18n/*`
+ * directly, so `src/kernel/**` carries no via-i18n specifier at all.
+ * `isolatedModules: true` erases these at build time — no runtime coupling.
+ */
+export type { I18nTextDescriptor } from '../../via/i18n/core.js';
+export type { DictKeyDescriptor, DictionaryHandle, DictionaryOptions, StaticDictDescriptor } from '../../via/i18n/dictionary.js';
+export type { Layer } from '../../via/i18n/policy.js';
+export type { ScriptWarning } from '../../via/i18n/script.js';

package/dist/port/with/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @noy-db/hub/with — the seam `with*()` services hook into.
+ *
+ * Carries the three primitives every opt-in service is built on top of: the
+ * `ServiceBus` (observe/gate lifecycle bus; `SubsystemBus` is a deprecated
+ * alias kept for source compat), the `WriteHookRegistry`
+ * (before/after write hooks), and the export/import capability gate
+ * (`assertCanExport`/`assertCanImport`/`canExport`/`canImport`). This subpath
+ * is the stable, named port onto them.
+ *
+ * Named re-exports only (no `export *`) so the published surface is explicit and
+ * tsup's per-entry bundling keeps class identity stable across subpaths.
+ */
+export type { WriteEvent, WriteHook, Unsubscribe, } from './write-hooks.js';
+export { WriteHookRegistry } from './write-hooks.js';
+export type { LifecycleEventMap, LifecyclePoint, BusHandler, GatePutEvent, GateDeleteEvent, GateEventMap, GatePoint, GateHandler, } from './service-bus.js';
+export { ServiceBus, SubsystemBus } from './service-bus.js';
+export { assertCanExport, assertCanImport, canExport, canImport, } from './capabilities.js';

package/dist/port/with/lazy-strategy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Lazy-mode capability contract (#267 Track A tail — lazy-mode promoted out
+ * of `routing` into its own `lazy` service). Lives on the `/with` port (the
+ * one seam the kernel spine may import statically) so `Collection` can hold
+ * the back-compat default without a spine→service static import.
+ *
+ * Lazy mode (`prefetch: false`) skips bulk hydration: reads go per-id
+ * against the store and land in a bounded LRU working set. The strategy owns
+ * constructing that LRU:
+ *
+ *  - `withLazy()` (`with-store/lazy/active.ts`, subpath `@noy-db/hub/lazy`)
+ *    is the explicit catalog opt-in — silent, forward-stable.
+ *  - {@link IMPLICIT_LAZY} is the floor default reached when a collection
+ *    declares `prefetch: false` WITHOUT `lazyStrategy: withLazy()`. It keeps
+ *    the pre-#267 behavior byte-for-byte (back-compat delegation, pre-1.0)
+ *    but emits a one-time deprecation warn outside test env. It will become
+ *    a throwing stub at 1.0, letting the LRU leave the floor bundle
+ *    entirely once the per-record-CEK cache stops pinning `Lru` there.
+ *
+ * The on-demand read/write branches themselves stay kernel-resident (they
+ * are `if (this.lazy)` forks on the hot get/put/scan paths); the service
+ * seam owns cache construction + budget validation, which is where the
+ * opt-in and the future tree-shake win live.
+ * @internal
+ */
+import { Lru } from '../../kernel/cache/index.js';
+import type { CacheOptions } from '../../kernel/collection.js';
+export interface LazyStrategy {
+    /**
+     * Build the bounded LRU working-set cache for a lazy collection.
+     * MUST throw when `cache` declares neither `maxRecords` nor `maxBytes` —
+     * an unbounded lazy cache defeats the purpose.
+     */
+    createCache<V>(collection: string, cache: CacheOptions | undefined): Lru<string, V>;
+}
+/**
+ * Shared budget validation + LRU construction — the one implementation both
+ * {@link IMPLICIT_LAZY} and `withLazy()` run, so the two paths cannot drift.
+ * @internal
+ */
+export declare function buildLazyCache<V>(collection: string, cache: CacheOptions | undefined): Lru<string, V>;
+/**
+ * Back-compat default (deprecated): `prefetch: false` without
+ * `lazyStrategy: withLazy()`. Identical behavior to the explicit opt-in,
+ * plus a one-time deprecation warn (suppressed under NODE_ENV=test,
+ * mirroring the listPage fallback warn). @internal
+ */
+export declare const IMPLICIT_LAZY: LazyStrategy;

package/dist/port/with/lookup-strategy.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Lookup strategy seam (#650 Task 1 — via-lookup extraction, phase D of the
+ * Via port; precedent: `port/with/i18n-strategy.ts`). Lives on the `/with`
+ * port (the one seam the kernel spine may import statically) so `Vault` can
+ * reach the dict-registry pure helpers and the `LookupHandle`/`NO_LOOKUP`
+ * types without a spine→`via/` static import (Check 14 via-layering bans
+ * that; `port/with/` is always allowed, Check 9's sanctioned exception).
+ *
+ * `kernel/vault.ts` imports ONLY this module for lookup — never
+ * `via/lookup/*` directly.
+ *
+ * This task (#650 Task 1) is a pure move: `Vault.dictionary()` still
+ * constructs its handle through `i18nStrategy.buildDictionaryHandle`
+ * (`port/with/i18n-strategy.ts`), which now internally delegates to
+ * `withLookup().buildLookupHandle` (same handle, new home). `LookupStrategy`
+ * / `NO_LOOKUP` / `isLookupCollectionName` here are the seam later phase-D
+ * tasks bind `vault.collection()`'s lookup fields onto — unused by Task 1's
+ * wiring, but their exact shapes are frozen now so later tasks don't
+ * re-litigate them.
+ */
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
+import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+import type { ViaCryptoCtx } from '../../kernel/via/index.js';
+import type { LookupHandle, DictionaryOptions } from '../../via/lookup/handle.js';
+import { enforceStaticDictOnPut, resolveDictSource, updateReferencingRecords, resolveLabelFromMap, collectLookupDictCompat, lookupToStaticDictCompat, reservedDictDepsOf, materializeBackingTable, checkLookupMembership, buildLookupAltIndex, registerLookupRefEdges, buildLookupSnapshotRows, coerceLookupKey, resolveBackingRowKey, matchesReferencingValue, type DictReferencingCollection, type LookupDictCompat, type MaterializedBacking } from '../../via/lookup/registry.js';
+import { buildPresentForJoin } from '../../via/lookup/snapshot.js';
+import type { LookupDescriptor } from '../../via/lookup/descriptor.js';
+/**
+ * Backing options for `LookupStrategy.buildLookupHandle` — same shape as
+ * `DictionaryOptions` (kept as a distinct alias since the "lookup" name is
+ * the forward-looking one; `DictionaryOptions` stays the dict-tier name).
+ */
+export type LookupBackingOptions = DictionaryOptions;
+/**
+ * Options accepted by `LookupStrategy.buildLookupHandle`. Mirrors the
+ * `LookupHandle` constructor verbatim, plus the two choke-point
+ * participation hooks (`onDirty`/`onRecordMutated`) #647 (Task 4) wires —
+ * both `undefined` in this task (pure move, no new call sites).
+ */
+export interface BuildLookupHandleOptions<Keys extends string = string> {
+    readonly adapter: NoydbStore;
+    readonly compartmentName: string;
+    readonly dimensionName: string;
+    readonly keyring: UnlockedKeyring;
+    /**
+     * The `reservedEnvelopes('_dict_')` capability (#629 Task 4) — the
+     * handle's sanctioned crypto door onto its `_dict_<name>` collection.
+     * Bound by the Vault to its own `getDEK`, the same per-collection-name
+     * DEK resolver every other collection uses.
+     */
+    readonly reservedEnvelopes: ReturnType<ViaCryptoCtx['reservedEnvelopes']>;
+    readonly encrypted: boolean;
+    readonly ledger: LedgerStore | undefined;
+    readonly options: LookupBackingOptions;
+    readonly findAndUpdateReferences: ((dimension: string, oldKey: string, newKey: string) => Promise<void>) | undefined;
+    readonly emitter: NoydbEventEmitter;
+    /**
+     * #647 fix wave 1 — mints a version-ordered delete-marker envelope. Bound by the Vault to the
+     * real `kernel/enclave` `buildDeleteMarker` function — `LookupHandle` (`via/lookup/**`)
+     * may not import `kernel/enclave/` itself (Check 11/15), so this capability is injected the
+     * same way `reservedEnvelopes` above is.
+     */
+    readonly buildDeleteMarker: (version: number, actor: string) => EncryptedEnvelope;
+    /** #650 Task 4 (#647) — choke-point participation hooks. */
+    readonly onDirty?: ((collection: string, id: string, action: 'put' | 'delete', version: number) => Promise<void>) | undefined;
+    readonly onRecordMutated?: ((collection: string, id: string, action: 'put' | 'delete', version: number) => Promise<void>) | undefined;
+    /**
+     * #650 Task 5 (#648) — the real reference check `LookupHandle.delete()`'s strict branch calls:
+     * restrict throws `DictKeyInUseError` naming the referencing collection, cascade/nullify apply
+     * their propagation. Bound by the Vault (never a `Collection`/keyring/DEK reach-around); a
+     * no-op when the dimension has no declared lookup-referencing edges (today's dangling behavior
+     * for undeclared refs is unaffected). Return value is discarded by the handle — callers who
+     * need cascade/nullify counts (forget) go through `VaultLinks` directly.
+     */
+    readonly checkReferencesOnDelete?: ((key: string) => Promise<unknown>) | undefined;
+    /**
+     * Used by the active strategy to satisfy the generic-key parameter on the
+     * returned handle. The NO_LOOKUP stub never reads it. Mirrors
+     * `BuildDictionaryHandleOptions._keyMarker` (`port/with/i18n-strategy.ts`).
+     */
+    _keyMarker?: Keys;
+}
+export interface LookupStrategy {
+    /**
+     * Construct a typed `LookupHandle` for the named dimension. Throws under
+     * `NO_LOOKUP`.
+     */
+    buildLookupHandle<Keys extends string = string>(opts: BuildLookupHandleOptions<Keys>): LookupHandle<Keys>;
+}
+/**
+ * No-lookup stub. Mirrors `NO_I18N.buildDictionaryHandle`'s shape, but unlike `NO_I18N` (wired as
+ * `vault.ts`'s `opts.i18nStrategy ?? NO_I18N` default), nothing selects this stub today — there is
+ * no `lookupStrategy` option on `createNoydb()`; `vault.dictionary()`'s only construction path
+ * (`Vault.i18nStrategy.buildDictionaryHandle` → `withLookup().buildLookupHandle`) never reaches
+ * here. Kept as forward scaffolding for a later task that wires an independent lookup opt-in.
+ */
+export declare const NO_LOOKUP: LookupStrategy;
+/** `_dict_*` (legacy dict tier) and `_lookup_*` (the phase-D reserved backing). */
+export declare const LOOKUP_COLLECTION_PREFIXES: readonly ["_dict_", "_lookup_"];
+/** Return true when a collection name is a reserved lookup-backing collection. */
+export declare function isLookupCollectionName(name: string): boolean;
+export { enforceStaticDictOnPut, resolveDictSource, updateReferencingRecords };
+export type { DictReferencingCollection };
+export { dictCollectionName } from '../../via/lookup/handle.js';
+export { resolveLabelFromMap, collectLookupDictCompat, lookupToStaticDictCompat };
+export type { LookupDictCompat };
+export { reservedDictDepsOf };
+export { materializeBackingTable, checkLookupMembership, buildLookupAltIndex };
+export type { MaterializedBacking };
+export { registerLookupRefEdges };
+export { buildLookupSnapshotRows, buildPresentForJoin };
+export type { LookupSnapshot } from '../../via/lookup/snapshot.js';
+export { coerceLookupKey, resolveBackingRowKey, matchesReferencingValue };
+/** Runtime predicate for detecting a `LookupDescriptor` (any of the three tiers). */
+export declare function isLookupDescriptor(x: unknown): x is LookupDescriptor;
+/** Runtime predicate for the bare enum tier (`backing:'static'`, no in-code `table` — no label source). */
+export declare function isEnumDescriptor(x: unknown): x is LookupDescriptor;
+/**
+ * Type-only re-exports — the kernel spine imports these descriptor/handle
+ * types through the port instead of reaching into `via/lookup/*` or
+ * `via/i18n/*` directly. `isolatedModules: true` erases these at
+ * build time — no runtime coupling.
+ */
+export type { LookupHandle, DictEntry, DictionaryOptions } from '../../via/lookup/handle.js';
+export type { LookupDescriptor, Vocabulary, LookupBacking, OnDelete } from '../../via/lookup/descriptor.js';
+export type { LookupViaConfig } from '../../via/lookup/binding.js';
+export type { DictKeyDescriptor, StaticDictDescriptor } from '../../via/i18n/dictionary.js';

package/dist/port/with/service-bus.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Generic per-instance **observe** bus. Observe-class
+ * services (devtools inspector, audit, sync-dirty notification) register
+ * handlers against named lifecycle points instead of the kernel naming each
+ * service. Mirrors the registry pattern of {@link WriteHookRegistry} but is
+ * internal and keyed by lifecycle point.
+ *
+ * OBSERVE SEMANTICS: handlers react to a write that already happened. A
+ * handler throw is warned, not propagated — it can never abort a write. Write-
+ * *gating* services (guards, periods) need a throw-propagating gate bus.
+ * Add observe points by extending {@link LifecycleEventMap}. Write-*gating*
+ * services use the sibling gate API on this same class
+ * (`registerGate`/`dispatchGate`, throw-propagating); see {@link GateEventMap}.
+ *
+ * @module
+ */
+import type { WriteEvent } from './write-hooks.js';
+import type { Role } from '../../kernel/types.js';
+/** Typed map of OBSERVE lifecycle point → event payload. Extend by adding keys. */
+export interface LifecycleEventMap {
+    afterPut: WriteEvent;
+    afterDelete: WriteEvent;
+}
+export type LifecyclePoint = keyof LifecycleEventMap;
+export type BusHandler<P extends LifecyclePoint> = (event: LifecycleEventMap[P]) => void | Promise<void>;
+export type Unsubscribe = () => void;
+/** Payload for a `beforePut` gate — carries the data guards and periods need to validate or reject a write. */
+export interface GatePutEvent {
+    readonly op: 'create' | 'update';
+    readonly vault: string;
+    readonly collection: string;
+    readonly docId: string;
+    /**
+     * The record about to be written (pre schema-validation). Money fields
+     * are presented in their canonical decoded form — equal on both
+     * sides for an unchanged value, regardless of how the caller wrote them.
+     */
+    readonly incoming: unknown;
+    /**
+     * Decrypted prior record, or null on create / when prior is unreadable.
+     * Money fields are decoded to the canonical decimal `get()` shape, NOT
+     * the stored scaled-int — `incoming[f] === existing[f]` holds
+     * for an unchanged money field.
+     */
+    readonly existing: unknown;
+    /** Prior envelope version, or 0 when none. */
+    readonly existingVersion: number;
+    /** Prior envelope timestamp (`_ts` ISO string), or undefined when none — periods compares against this. */
+    readonly existingTs: string | undefined;
+    readonly userId: string;
+    readonly role: Role;
+    /**
+     * Names of fields whose values are schema-owned computed fields for this
+     * collection. Gate handlers (e.g. `frozenFields`) must skip these: the
+     * incoming record is the raw user input (computed fields not yet evaluated),
+     * so comparing `existing[computedField]` vs `incoming[computedField]`
+     * would always see a change even when the computed result is unchanged.
+     */
+    readonly computedFieldNames?: ReadonlySet<string>;
+}
+/** Payload for a `beforeDelete` gate. Like {@link GatePutEvent} without `incoming`. */
+export interface GateDeleteEvent {
+    readonly vault: string;
+    readonly collection: string;
+    readonly docId: string;
+    /** True for system-internal (housekeeping) deletes — handlers branch on this. */
+    readonly internal: boolean;
+    /** Decrypted prior record; money fields decoded to the canonical `get()` shape. */
+    readonly existing: unknown;
+    readonly existingVersion: number;
+    readonly existingTs: string | undefined;
+    readonly userId: string;
+    readonly role: Role;
+}
+/** Typed map of GATE lifecycle point → event payload. Extend by adding keys. */
+export interface GateEventMap {
+    beforePut: GatePutEvent;
+    beforeDelete: GateDeleteEvent;
+}
+export type GatePoint = keyof GateEventMap;
+export type GateHandler<P extends GatePoint> = (event: GateEventMap[P]) => void | Promise<void>;
+/**
+ * Registration options for a gate handler.
+ *
+ * `needsPrior` (default `true`) declares whether the handler reads the
+ * prior-derived event fields — `existing`, `existingVersion`, `existingTs`,
+ * and (on `beforePut`) `op`. When EVERY handler registered at a point set
+ * `needsPrior: false`, the write path skips the prior-read (store get +
+ * decrypt) entirely and dispatches the event with `existing: null`,
+ * `existingVersion: 0`, `existingTs: undefined` (and `op: 'create'` on
+ * `beforePut`; a `beforeDelete` gate then also fires for delete-of-absent).
+ * A handler that opts out MUST NOT rely on those fields. (#267 prior-read
+ * elision — pure perf; one prior-needing handler restores the old behavior
+ * for the whole point.)
+ */
+export interface GateRegisterOptions {
+    readonly needsPrior?: boolean;
+}
+export declare class ServiceBus {
+    #private;
+    /** Register a handler for an observe point. Returns an unsubscribe fn. */
+    register<P extends LifecyclePoint>(point: P, handler: BusHandler<P>): Unsubscribe;
+    /** Cheap gate for the write path — true when any handler is registered for the point. */
+    hasHandlers(point: LifecyclePoint): boolean;
+    /**
+     * True while one or more dispatches are in flight. Backed by a depth counter
+     * so that two concurrent async dispatches (`Promise.all([put('a'), put('b')])`
+     * each captured `busAfterPut=true` at their respective put() tops while depth
+     * was 0) both proceed independently — the counter stays > 0 until BOTH finish,
+     * so any nested write attempted by a handler still sees `dispatching === true`
+     * and is suppressed by the write-path gate in `collection.ts`
+     * (`busAfterPut = hasHandlers('afterPut') && !dispatching`). Re-entrancy
+     * suppression lives exclusively on that write-path gate; concurrent independent
+     * dispatches must not drop each other's events.
+     */
+    get dispatching(): boolean;
+    /**
+     * Dispatch in registration order, awaited. Per-handler errors are warned, not
+     * thrown — an observe handler must never abort a completed write. A
+     * re-entrancy guard suppresses nested firing so a handler that itself writes
+     * cannot loop (same rationale as WriteHookRegistry.#suppressed).
+     */
+    dispatch<P extends LifecyclePoint>(point: P, event: LifecycleEventMap[P]): Promise<void>;
+    /**
+     * Register a write-gating handler. A throw from the handler ABORTS the
+     * write. Returns an unsubscribe fn. See {@link GateRegisterOptions} for
+     * the `needsPrior` prior-read declaration (#267).
+     */
+    registerGate<P extends GatePoint>(point: P, handler: GateHandler<P>, opts?: GateRegisterOptions): Unsubscribe;
+    /** Cheap gate for the write path — true when any gate handler is registered for the point. */
+    hasGateHandlers(point: GatePoint): boolean;
+    /**
+     * True when at least one gate handler at `point` needs the prior record
+     * (the default). False when the point has no handlers or every handler
+     * registered with `needsPrior: false` — the write path then skips the
+     * prior-read before dispatching (#267 prior-read elision).
+     */
+    gateNeedsPrior(point: GatePoint): boolean;
+    /**
+     * Run gate handlers in registration order, awaited. Unlike `dispatch`
+     * (observe), a handler throw is NOT swallowed — it PROPAGATES, aborting the
+     * write before it reaches the store. The first throw stops the remaining
+     * handlers (fail-fast). This is the seam guards/periods migrate onto.
+     *
+     * Note: gate handlers are validators that read, not write. A gate handler
+     * that writes back into the same collection would re-enter the write path
+     * and re-dispatch this point; loop-suppression for that case is deferred to
+     * the migration slice (contract: gate handlers must not perform writes that
+     * re-trigger their own point).
+     */
+    dispatchGate<P extends GatePoint>(point: P, event: GateEventMap[P]): Promise<void>;
+}
+/** @deprecated Use ServiceBus. */
+export declare const SubsystemBus: typeof ServiceBus;
+/** @deprecated Use ServiceBus. */
+export type SubsystemBus = ServiceBus;

package/dist/port/with/team-strategy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Multi-user team capability contract (#267 Track A tail — the
+ * keyring-grant → team split). Lives on the `/with` port (the one seam the
+ * kernel spine may import statically) so `Noydb` can hold the `NO_TEAM`
+ * floor default without a spine→service static import.
+ *
+ * The active engine (`withTeam()` in `with-party/team/active.ts`)
+ * statically links the grant/revoke/rotate keyring engines from
+ * `keyring.ts` — bundle-charged to consumers of the `@noy-db/hub/team`
+ * subpath, never to the single-user floor. {@link NO_TEAM} (the floor
+ * default) throws {@link TeamNotEnabledError}.
+ *
+ * `Noydb.grant` / `Noydb.revoke` / `Noydb.rotate` delegate here, passing
+ * their `TeamFacade` — the facade owns the policy-gate + keyring plumbing
+ * (`runGrant` / `runRevoke` / `runRotate`) and receives the engine as an
+ * argument from the strategy.
+ *
+ * Deliberately NOT gated (single-user primitives): owner keyring creation,
+ * unlock, `listUsers`, `updateUser`, passphrase rotate/recover, and the
+ * `createDeedOwner` free function (no createNoydb instance to gate against —
+ * the same carve-out as `liberateVault`).
+ * @internal
+ */
+import type { GrantOptions, RevokeOptions, FactorProofBundle } from '../../kernel/types.js';
+import type { TeamFacade } from '../../with-party/team/noydb-facade.js';
+export interface TeamStrategy {
+    grant(team: TeamFacade, vault: string, options: GrantOptions, factors?: FactorProofBundle): Promise<void>;
+    revoke(team: TeamFacade, vault: string, options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
+    rotate(team: TeamFacade, vault: string, collections: string[]): Promise<void>;
+}
+/**
+ * No-op stub — the floor default. Every multi-user team operation throws
+ * {@link TeamNotEnabledError}; opt in with `teamStrategy: withTeam()` in
+ * createNoydb. @internal
+ */
+export declare const NO_TEAM: TeamStrategy;

package/dist/port/with/write-hooks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hub-level write lifecycle hooks. `onBeforeWrite` may abort (throw);
+ * `onAfterWrite` is awaited and its errors are warned, not thrown. A
+ * re-entrancy flag suppresses nested firing so a handler that writes can't
+ * loop. Held on the Noydb instance, threaded into every Collection.
+ */
+export interface WriteEvent {
+    readonly op: 'create' | 'update' | 'delete';
+    readonly vault: string;
+    readonly collection: string;
+    readonly docId: string;
+    readonly before: unknown;
+    readonly after: unknown;
+    readonly baseVersion: number;
+    readonly version: number;
+    readonly userId: string;
+    readonly timestamp: number;
+    readonly txId: string;
+}
+export type WriteHook = (event: WriteEvent) => void | Promise<void>;
+export type Unsubscribe = () => void;
+export declare class WriteHookRegistry {
+    #private;
+    /** True while handlers are running — used by the write path to skip nested firing. */
+    get suppressed(): boolean;
+    /** True when any hook is registered (cheap gate for the write path). */
+    get hasHandlers(): boolean;
+    onBeforeWrite(handler: WriteHook): Unsubscribe;
+    onAfterWrite(handler: WriteHook): Unsubscribe;
+    /** Run before-hooks (awaited, in order). A throw propagates and aborts the write. */
+    runBefore(event: WriteEvent): Promise<void>;
+    /** Run after-hooks (awaited, in order). Per-handler errors are warned, not thrown. */
+    runAfter(event: WriteEvent): Promise<void>;
+}

package/dist/portability/index.js

@@ -1,36 +1,36 @@
 import {
   NO_PORTABILITY
-} from "../chunk-II6DLDZM.js";
+} from "../chunk-K5IMOGHB.js";
 import {
   PortabilityNotEnabledError
-} from "../chunk-OJ64XMPJ.js";
+} from "../chunk-BIOUI4HL.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/with-audit/portability/active.ts
 function withPortability() {
   return {
     async exportAccessibleData(vault, opts) {
-      const { exportAccessibleData } = await import("../export-accessible-Z3NSZZHN.js");
+      const { exportAccessibleData } = await import("../export-accessible-PCMXSUZS.js");
       return exportAccessibleData(vault, opts);
     },
     async withdrawAccessibleData(vault, opts) {
-      const { withdrawAccessibleData } = await import("../withdraw-accessible-Q7BULAN5.js");
+      const { withdrawAccessibleData } = await import("../withdraw-accessible-WZIEVWSR.js");
       return withdrawAccessibleData(vault, opts);
     },
     async requestWithdrawal(vault, opts) {
-      const { requestWithdrawal } = await import("../request-withdrawal-GU4XS2R5.js");
+      const { requestWithdrawal } = await import("../request-withdrawal-TI3A5WPS.js");
       return requestWithdrawal(vault, opts);
     },
     async listWithdrawalRequests(vault, opts) {
-      const { listWithdrawalRequests } = await import("../request-withdrawal-GU4XS2R5.js");
+      const { listWithdrawalRequests } = await import("../request-withdrawal-TI3A5WPS.js");
       return listWithdrawalRequests(vault, opts);
     },
     async approveWithdrawal(vault, requestId, opts) {
-      const { approveWithdrawal } = await import("../request-withdrawal-GU4XS2R5.js");
+      const { approveWithdrawal } = await import("../request-withdrawal-TI3A5WPS.js");
       return approveWithdrawal(vault, requestId, opts);
     },
     async rejectWithdrawal(vault, requestId, opts) {
-      const { rejectWithdrawal } = await import("../request-withdrawal-GU4XS2R5.js");
+      const { rejectWithdrawal } = await import("../request-withdrawal-TI3A5WPS.js");
       return rejectWithdrawal(vault, requestId, opts);
     }
   };