@noy-db/hub 0.3.0-pre.10 → 0.3.0-pre.11

package/dist/port/by/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Kernel coordination port — the injected `CoordinationProvider` seam for the
+ * schema-fence drain-barrier.
+ *
+ * The kernel defines this port; `@noy-db/by-tabs` / `@noy-db/by-peer` implement
+ * it for real-time quorum, and an external orchestrator (`@klum-db/lobby`)
+ * drives it through the `Noydb` handle without ever naming a `by-*` package.
+ * The dependency arrow is `by-* → kernel ← klum`, the app at the apex.
+ *
+ * This module carries only the port TYPES plus two pure-ish helpers:
+ * {@link isQuorum} (a pure quorum predicate extracted from the legacy
+ * `activeQuiesced`) and {@link runDrainBarrier} (the reusable barrier protocol
+ * the migration cutover and klum both call).
+ *
+ * @module
+ */
+import type { Unsubscribe } from '../with/write-hooks.js';
+/** Vault fence state (the existing FenceDoc shape). */
+export interface FenceState {
+    readonly currentSchemaVersion: number;
+    readonly fenceState: 'normal' | 'draining' | 'migrating' | 'complete';
+}
+/** A writer's presence + ack, tagged with the session that owns it. */
+export interface WriterPresence {
+    /** = today's clientId (one per tab/peer). */
+    readonly writerId: string;
+    /** Groups one user's writers across vaults (consolidation is klum's job). */
+    readonly sessionId: string;
+    readonly lastSeen: number;
+    readonly quiescedAtVersion: number | null;
+}
+/** Session-addressable drain-barrier coordination transport. Per-vault ops. */
+export interface CoordinationProvider {
+    /** orchestrator → all writers */
+    setFence(vault: string, fence: FenceState): Promise<void>;
+    /**
+     * Fresh one-shot fence read for the write-path gate (`assertWritable`).
+     * A direct read (not a cached `observeFence` snapshot) avoids a staleness
+     * window and keeps the timing-sensitive cutover gate exact. The store
+     * default reads `_meta/schema-fence`; `by-*` return their last-pushed fence.
+     */
+    readFence(vault: string): Promise<FenceState>;
+    /** writer observes fence changes (default: poll-emit; by-*: push) */
+    observeFence(vault: string, onChange: (f: FenceState) => void): Unsubscribe;
+    /** writer → orchestrator: presence + ack (heartbeat + quiescedAtVersion) */
+    reportPresence(vault: string, p: WriterPresence): Promise<void>;
+    /** orchestrator observes presence changes (default: poll-emit; by-*: push) */
+    observePresence(vault: string, onChange: (writers: readonly WriterPresence[]) => void): Unsubscribe;
+    /** orchestrator one-shot snapshot of reachable writers (quorum input) */
+    reachableWriters(vault: string, o: {
+        staleMs: number;
+        now: number;
+    }): Promise<readonly WriterPresence[]>;
+}
+/**
+ * Pure quorum predicate: true when every writer (other than `excludeWriterId`)
+ * has acked at exactly `generation`. An empty set is trivially a quorum.
+ *
+ * Extracted from the legacy `activeQuiesced` store-polling check so the
+ * migration cutover, the store default provider, and `by-*` real-time
+ * providers all share one definition of "everyone has drained".
+ */
+export declare function isQuorum(writers: readonly WriterPresence[], generation: number, excludeWriterId?: string): boolean;
+/** Inputs for {@link runDrainBarrier}. */
+export interface DrainBarrierOptions {
+    readonly vault: string;
+    readonly generation: number;
+    readonly writerId: string;
+    readonly onFlush: () => Promise<void>;
+    readonly staleMs: number;
+    readonly quiesceTimeoutMs: number;
+    readonly now: () => number;
+    /** Optional seam (mainly for deterministic tests) run before each poll tick. */
+    readonly onPoll?: () => Promise<void>;
+}
+/**
+ * The reusable drain-barrier protocol shared by the migration cutover and klum:
+ *
+ *   drain self → setFence(draining) → await quorum (presence push + isQuorum,
+ *   polling as a fallback, or timeout) → run() → release-by-caller.
+ *
+ * Resolves once every reachable writer (excluding `writerId`) has quiesced at
+ * `generation`, at which point `run` is invoked exactly once. Rejects with
+ * {@link QuiesceTimeoutError} if `quiesceTimeoutMs` elapses first.
+ */
+export declare function runDrainBarrier(provider: CoordinationProvider, o: DrainBarrierOptions, run: () => Promise<void>): Promise<void>;

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

@@ -0,0 +1,21 @@
+/**
+ * @noy-db/hub/in — the in-* framework family port (types only).
+ *
+ * A framework binding (`in-react`, `in-nuxt`, `in-vue`, `in-pinia`,
+ * `in-tanstack-query`, `in-ai`, …) binds ONLY to this subpath: the handle
+ * types it wraps (`Noydb`, `Vault`, `Collection`, `Query`, `LiveQuery`) plus
+ * the change-event shape it observes (`ChangeEvent`). Type-only — a
+ * framework binding always receives a live instance from `createNoydb()`/
+ * `openVault()`/`collection()` via the root barrel or `@noy-db/hub/cargo`;
+ * this port exists so its wrapper types can name the shapes without
+ * importing the whole hub surface.
+ *
+ * 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 { Noydb } from '../../kernel/noydb.js';
+export type { Vault } from '../../kernel/vault.js';
+export type { Collection } from '../../kernel/collection.js';
+export type { Query } from '../../kernel/query/builder.js';
+export type { LiveQuery } from '../../kernel/query/live.js';
+export type { ChangeEvent } from '../../kernel/types.js';

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

@@ -0,0 +1,27 @@
+/**
+ * @noy-db/hub/on — the on-* unlock family port.
+ *
+ * An unlock / auth primitive (`on-password`, `on-webauthn`, `on-oidc`,
+ * `on-totp`, `on-shamir`, `on-recovery`, …) binds ONLY to this subpath: the
+ * paper-recovery mint primitive plus the keyring/role/permission/rewrap/
+ * enroll shapes those packages read and write. `on-recovery` already
+ * consumes `mintPaperRecoveryEntry`/`PaperRecoveryEntry` from the root
+ * barrel (`@noy-db/hub`); this subpath is the stable, named port onto the
+ * same values, mirroring `@noy-db/hub/cargo`.
+ *
+ * NOTE: these primitives are implemented in `with-party/team/*` (the
+ * multi-user keyring service), not in the kernel spine proper — same
+ * precedent as `@noy-db/hub/ui` re-exporting from `with-shape/introspection`.
+ * The port-layering check only restricts kernel *spine* files (and
+ * port-to-port imports) from reaching into a `with-*` service statically;
+ * a port itself may.
+ *
+ * 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 { mintPaperRecoveryEntry } from '../../with-party/team/recovery.js';
+export type { PaperRecoveryEntry } from '../../with-party/team/recovery.js';
+export type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+export type { Role, Permissions } from '../../kernel/types.js';
+export type { SlotRewrapContext } from '../../with-party/team/rotate-recover.js';
+export type { EnrollAuthenticatorOptions } from '../../with-party/team/authenticators.js';

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

@@ -0,0 +1,19 @@
+/**
+ * @noy-db/hub/to — the stable store-adapter contract (the `to-*` family port).
+ *
+ * A storage backend (a `to-*` package) binds ONLY to this subpath: the
+ * ciphertext-facing slice of the hub. It carries the 6-method `NoydbStore`
+ * contract (plus its optional extension methods), the envelope / snapshot / op
+ * types a store passes through, the store-facing error classes, and the
+ * `NoydbPodStore` contract (plus `PodVersionConflictError`) for pod stores
+ * such as `to-drive` and `to-icloud`. Mirrors the `@noy-db/hub/cargo` seam
+ * used by klum-db and the `by-*` transports.
+ *
+ * Supersedes `@noy-db/hub/adapter`, which has been retired (coordinated
+ * removal; consumers migrated to this subpath).
+ *
+ * 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 { NoydbStore, NoydbBundleStore, NoydbPodStore, EncryptedEnvelope, VaultSnapshot, TxOp, StoreCapabilities, StoreCredentials, StoreCredentialSource, StoreTime, ListPageResult, } from '../../kernel/types.js';
+export { ConflictError, NetworkError, StoreCapabilityError, BundleVersionConflictError, PodVersionConflictError, } from '../../kernel/errors.js';

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

@@ -0,0 +1,21 @@
+/**
+ * **@noy-db/hub/ui** — the narrow, stable seam for the `collection.describe()`
+ * output contract that `@noy-db/ui` (and `@noy-db/ui-nuxt`) bind to *instead of* the
+ * whole `@noy-db/hub` root barrel.
+ *
+ * It re-exports ONLY the describe()-output type contract: the `CollectionDescription`
+ * envelope, its `DescribedField` element, the async `DescribeOptions`, and the
+ * descriptive-metadata building blocks (`CollectionMeta`, `FieldMeta`, `SemanticType`).
+ * Type-only — `describe()` itself is a method on `Collection`, reached via the root
+ * barrel / `/cargo`. These same names also remain exported from the root barrel
+ * (this subpath is purely additive); ui can migrate to the narrow seam on its own
+ * schedule. Treat it as a contract — additive changes only; removals are breaking.
+ *
+ * The pre-existing `./describe` subpath has been retired (coordinated removal;
+ * consumers migrated to `/ui`).
+ *
+ * @packageDocumentation
+ */
+export type { CollectionDescription, DescribedField, DescribeOptions, } from '../../with-shape/introspection/describe.js';
+export type { CollectionMeta } from '../../with-shape/introspection/meta.js';
+export type { FieldMeta, SemanticType } from '../../with-shape/introspection/field-meta.js';

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

@@ -0,0 +1,81 @@
+/**
+ * Strategy seam between core Collection and the optional blob service
+ * (#629 Task 7 — moved out of `with-shape/blobs/strategy.ts`, precedent:
+ * `port/with/classified-strategy.ts`/`i18n-strategy.ts`). Lives on the
+ * `/with` port (the one seam the kernel spine may import statically) so
+ * `Collection`/`Vault` can hold the `NO_BLOBS` default without a
+ * spine→service static import.
+ *
+ * Core imports `BlobStrategy` as a TYPE-ONLY symbol and `NO_BLOBS` as a
+ * minimal runtime stub. Neither pulls in the heavy `BlobSet` / chunk /
+ * MIME machinery — those only arrive when the consumer explicitly
+ * imports `@noy-db/hub/blobs` (see `via/blob/index.ts` →
+ * `withBlobs()` factory).
+ *
+ * This file is intentionally tiny so the bundler keeps it in the graph
+ * without dragging everything else in.
+ *
+ * @internal
+ */
+import type { BlobSet } from '../../with-shape/blobs/blob-set.js';
+import type { NoydbStore } from '../../kernel/types.js';
+import type { ObjectProjection } from '../../with-shape/blobs/object-projection.js';
+import type { BlobFieldsConfig } from '../../with-shape/blobs/blob-compaction.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * Args forwarded by `Collection.blob(id)` to the active strategy's
+ * `openSlot`. The strategy is responsible for returning a live
+ * `BlobSet` bound to the given record.
+ *
+ * @internal
+ */
+export interface BlobStrategyOpenArgs {
+    readonly store: NoydbStore;
+    readonly vault: string;
+    readonly collection: string;
+    readonly recordId: string;
+    readonly getDEK: (collectionName: string) => Promise<EnclaveKey>;
+    readonly encrypted: boolean;
+    readonly userId: string;
+    /**
+     * Collection opts into per-record keys (`perRecordKeys`), so its blobs are
+     * erasable: new uploads mint a per-blob content CEK (crypto-shreddable at
+     * `refCount → 0`). Off → legacy shared-`_blob`-DEK chunks. See the per-blob
+     * CEK design spec.
+     */
+    readonly erasableBlobs?: boolean;
+    /**
+     * Vault is in debug-plaintext mode (`encrypt: false` + `debugPlaintext: true`).
+     * Blobs are then written as a single un-gzipped object (one base64 chunk) so
+     * the stored object is directly recoverable with native tools (`base64 -d`),
+     * matching the directly-inspectable record layout. Dev-only — see the
+     * plaintext/debug-store-mode design.
+     */
+    readonly debugPlaintext?: boolean;
+    /**
+     * Object projection for `external` blob fields (`createNoydb({ objectStore })`).
+     * When present, fields declared `external` in `blobFields` route their raw
+     * bytes here instead of the encrypted-chunk path.
+     */
+    readonly objectStore?: ObjectProjection;
+    /** Per-collection blob field policies — used to resolve `external` / `public`. */
+    readonly blobFields?: BlobFieldsConfig;
+}
+/**
+ * The seam interface. `@internal` — do not build public APIs on this
+ * shape; it can evolve freely until blobs are extracted into their
+ * own package, at which point it will be promoted to public.
+ *
+ * @internal
+ */
+export interface BlobStrategy {
+    openSlot(args: BlobStrategyOpenArgs): BlobSet;
+}
+/**
+ * Default strategy for collections that did not opt into blob storage.
+ * Every operation surfaces an actionable error that points the caller
+ * at the opt-in path.
+ *
+ * @internal
+ */
+export declare const NO_BLOBS: BlobStrategy;

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

@@ -0,0 +1,84 @@
+/**
+ * Credential-broker strategy seam (#479, credential-broker spec §5). Lives
+ * on the `/with` port (the one seam the kernel spine may import statically)
+ * so `Vault` can hold the `NO_BROKER` floor default without a spine→service
+ * static import — the same idiom as `port/with/team-strategy.ts`.
+ *
+ * `BrokerCtx` bundles what the `_broker` seed lifecycle needs (`store`/
+ * `vault`/`keyring`) into one argument, so `BrokerStrategy`'s three methods
+ * stay uniform. The `BrokerConfig` a strategy was built with is NOT part of
+ * this port-level ctx — `withBroker(config)` (`with-party/broker/active.ts`)
+ * keeps it in its own closure and injects it into the richer
+ * {@link BrokerSeedCtx} it passes to the `_broker` seed ops
+ * (`enrollSeed`/`rotateSeed`/`mintStoreCredentials`). `NO_BROKER` (the floor
+ * default) never builds a ctx — every method throws first.
+ * @internal
+ */
+import type { NoydbStore, StoreCredentialSource } from '../../kernel/types.js';
+import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+/** Construction-time options for `withBroker(config)` (spec §5 client surface). */
+export interface BrokerConfig {
+    /**
+     * Stable id; part of the HKDF info tag AND the proof canonical. MUST be
+     * globally-unique / endpoint-derived (spec F4) — reusing one `brokerId`
+     * across two endpoints enables a cross-endpoint relay.
+     */
+    readonly brokerId: string;
+    /** https broker base URL; its origin is bound into the proof MAC (F4). */
+    readonly endpoint: string;
+    /** Dev-backend session token for `/enroll` (spec decision 1). */
+    readonly attestation?: (() => string | Promise<string>) | undefined;
+    /** DI for tests / non-window runtimes. */
+    readonly fetch?: typeof fetch | undefined;
+    /** Refresh margin in ms, default 60_000. */
+    readonly skewMs?: number | undefined;
+}
+/**
+ * Per-call context a {@link BrokerStrategy} method needs: the seed API's
+ * `store`/`vault`/`keyring`.
+ */
+export interface BrokerCtx {
+    readonly store: NoydbStore;
+    readonly vault: string;
+    readonly keyring: UnlockedKeyring;
+}
+/**
+ * {@link BrokerCtx} augmented with the `BrokerConfig` the `_broker` seed ops
+ * (`enrollSeed`/`rotateSeed`/`mintStoreCredentials`) need. `withBroker(config)`
+ * (`with-party/broker/active.ts`) builds this by injecting its closed-over
+ * `config` into the port-level `BrokerCtx` it receives — the port interface
+ * itself never carries `config`.
+ */
+export interface BrokerSeedCtx extends BrokerCtx {
+    readonly config: BrokerConfig;
+}
+/** The vault-bound handle `vault.broker()` returns (spec §5). */
+export interface CredentialBrokerHandle {
+    /** Generate+persist the `_broker` seed (idempotent), register its proof key. */
+    enroll(): Promise<void>;
+    /** Rotate the seed + re-register (revokes the old proof key after a grace window). */
+    rotate(): Promise<void>;
+    /** Single-flight, per-profile cache of a `StoreCredentialSource`. */
+    credentialSource(profile?: string): StoreCredentialSource;
+}
+/** The opt-in strategy contract `withBroker(config)` implements. */
+export interface BrokerStrategy {
+    enroll(ctx: BrokerCtx): Promise<void>;
+    rotate(ctx: BrokerCtx): Promise<void>;
+    credentialSource(ctx: BrokerCtx, profile?: string): StoreCredentialSource;
+}
+/**
+ * No-op stub — the floor default. Every broker operation throws
+ * {@link BrokerNotEnabledError}; opt in with `brokerStrategy: withBroker(config)`
+ * (from `@noy-db/hub/broker`) in `createNoydb()`.
+ * @internal
+ */
+export declare const NO_BROKER: BrokerStrategy;
+/**
+ * Build the vault-bound {@link CredentialBrokerHandle} `vault.broker()`
+ * returns — factored out of `kernel/vault.ts` to keep that file's footprint
+ * to a single accessor line (the kernel-surface ceiling). `getKeyring` is a
+ * thunk, not a snapshot: the active keyring can change after `vault.load()`,
+ * so each handle method re-reads it fresh at call time.
+ */
+export declare function buildCredentialBrokerHandle(strategy: BrokerStrategy, store: NoydbStore, vault: string, getKeyring: () => UnlockedKeyring): CredentialBrokerHandle;

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

@@ -0,0 +1,31 @@
+import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+import type { ExportFormat } from '../../kernel/types.js';
+/**
+ * Authorize an `@noy-db/as-*` export against the keyring's `exportCapability`.
+ * Throws `ExportCapabilityError` if the keyring is not authorised.
+ *
+ * - plaintext tier requires a `format`; defaults to empty for every role.
+ * - bundle tier defaults to on for owner/admin, off for others.
+ */
+export declare function assertCanExport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): void;
+/**
+ * Authorize an `@noy-db/as-*` import against the keyring's `importCapability`.
+ * Throws `ImportCapabilityError` if the keyring is not authorised.
+ *
+ * - plaintext tier requires a `format`; default-closed for every role.
+ * - bundle tier is default-closed for every role, including owner — import is
+ *   more dangerous than export (corrupts vs leaks).
+ */
+export declare function assertCanImport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): void;
+/**
+ * Read-only accessor for the keyring's export capability, with role-based
+ * defaults resolved. Useful for UI affordances (grey out the export button if
+ * no capability) without throwing.
+ */
+export declare function canExport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): boolean;
+/**
+ * Read-only accessor for the keyring's import capability. UI affordance —
+ * returns false in every default-closed case (every role with no explicit
+ * `importCapability` grant).
+ */
+export declare function canImport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): boolean;

package/dist/port/with/classified-marker.d.ts

@@ -0,0 +1,9 @@
+/**
+ * C-A/R10 config-drift marker store I/O — re-exported here (not
+ * `via/classified/config-drift.js` directly) so `Collection`'s
+ * dynamic `import()` in `_ensureClassifiedMarker`/`_classifiedMarkerDigestOnly`
+ * stays lazy while satisfying via-layering (#629 Task 6: the kernel spine
+ * may not name a `via/classified/*` path, not even inside a dynamic
+ * import specifier).
+ */
+export { persistClassifiedMarkerForFields, readClassifiedMarkerDigestOnly } from '../../via/classified/config-drift.js';

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

@@ -0,0 +1,62 @@
+/**
+ * Classified strategy seam (#629 Task 5 — moved out of
+ * `via/classified/strategy.ts`, precedent: `port/with/i18n-strategy.ts`).
+ * Lives on the `/with` port (the one seam the kernel spine may import
+ * statically) so `Collection`/`Vault` can hold the `NO_CLASSIFIED` default
+ * without a spine→service static import.
+ *
+ * This file (unlike `via/classified/**`) is NOT subject to the
+ * `via-enclave-isolation` architecture guard — it may import `EnclaveKey`
+ * from the enclave barrel freely, the same way `port/with/i18n-strategy.ts`
+ * did before #629 Task 4's DictionaryHandle cutover.
+ *
+ * The ② capability seam for classified read-egress ops (stage 1: reveal;
+ * stage 2: verify).
+ *
+ * @internal
+ */
+import type { ClassifiedFieldSpec } from '../../via/classified/descriptor.js';
+import type { EncryptedEnvelope } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+export type { ClassifiedViaConfig } from '../../via/classified/binding.js';
+export type { ClassifiedVerdict } from '../../kernel/types.js';
+import type { ClassifiedVerdict } from '../../kernel/types.js';
+export { resolveClassifiedFields, type ClassifiedEntry, type ResolvedClassified } from '../../via/classified/resolve.js';
+export { guardClassifiedCompat, type ClassifiedGuardCtx } from '../../via/classified/guards.js';
+export type { ClassifiedFieldSpec };
+export interface ClassifiedRevealCtx {
+    readonly collection: string;
+    readonly spec: ClassifiedFieldSpec;
+    /** True on an encrypted collection — false selects the plaintext-body read. */
+    readonly encrypted: boolean;
+    readonly getEnvelope: (id: string) => Promise<EncryptedEnvelope | null>;
+    readonly resolveCek: (env: EncryptedEnvelope) => Promise<EnclaveKey | undefined>;
+    readonly getDEK: () => Promise<EnclaveKey>;
+    readonly onAccess?: ((op: 'reveal', id: string) => Promise<void>) | undefined;
+}
+export interface ClassifiedVerifyCtx {
+    readonly collection: string;
+    readonly spec: ClassifiedFieldSpec;
+    readonly getEnvelope: (id: string) => Promise<EncryptedEnvelope | null>;
+    readonly resolveCek: (env: EncryptedEnvelope) => Promise<EnclaveKey | undefined>;
+    readonly getDEK: () => Promise<EnclaveKey>;
+    readonly now: () => number;
+    /** Group members resolved by the collection (matchGroup only). */
+    readonly groupMembers?: ReadonlyArray<{
+        readonly field: string;
+        readonly spec: ClassifiedFieldSpec;
+    }>;
+    readonly onAccess?: ((op: 'verify' | 'find', id: string) => Promise<void>) | undefined;
+}
+export interface ClassifiedStrategy {
+    reveal(ctx: ClassifiedRevealCtx, id: string, field: string): Promise<unknown>;
+    verify(ctx: ClassifiedVerifyCtx, id: string, field: string, candidate: string): Promise<ClassifiedVerdict>;
+    verifyText(ctx: ClassifiedVerifyCtx, id: string, field: string, candidate: string): Promise<ClassifiedVerdict>;
+    matchGroup(ctx: ClassifiedVerifyCtx, id: string, answers: Record<string, string>, opts: {
+        readonly min: number;
+    }): Promise<{
+        readonly passed: boolean;
+    }>;
+    computeTarget(ctx: ClassifiedVerifyCtx, field: string, candidate: string, costByte?: number): Promise<string | null>;
+}
+export declare const NO_CLASSIFIED: ClassifiedStrategy;

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

@@ -0,0 +1,19 @@
+/**
+ * computed strategy seam (#638 Task 7 — mirrors `port/with/{classified,blob}-strategy.ts`).
+ * Lives on the `/with` port (the one seam the kernel spine may import statically) so
+ * `kernel/via/compose.ts`/`kernel/collection-config.ts` can read a `via(computed(...))`
+ * descriptor's shape without a spine→`src/via/**` static import (via-layering, Check 14).
+ *
+ * Installs the computed via-binder EAGERLY — the classified/blob precedent, not money/
+ * i18n's lazy-in-factory pattern: a `computed: { field: { fn, deps, mode: 'virtual' } }`
+ * sugar entry never calls the `computed()` declaration factory at all, so lazy linking
+ * (money/i18n's `installViaBinder` call inside their own factory) would leave
+ * `viaBinder('computed')` unresolved for that path. This port module is already
+ * unconditionally imported by the kernel spine (`collection-config.ts`), so linking here
+ * guarantees the binder is installed before `compileViaBindings` ever needs it, regardless
+ * of which surface (sugar object-form or `via(computed(...))`) declared the virtual field.
+ *
+ * @internal
+ */
+import type { ComputedDescriptor } from '../../via/computed/descriptor.js';
+export type { ComputedDescriptor };

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';