@noy-db/hub 0.1.0-pre.8 → 0.2.0-pre.1

package/dist/{index-DJTf9yxn.d.ts → index-CmVgTkqk.d.cts}

@@ -1,5 +1,5 @@
-import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-SBHmi6D0.js';
-import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery } from './strategy-D-SrOLCl.js';
+import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-Dnu81tsS.cjs';
+import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery, h as GroupedQueryN } from './strategy-DSTrsZ8t.cjs';
 
 /**
  * All NOYDB error classes — a single import surface for `catch` blocks and
@@ -116,6 +116,26 @@ declare class TamperedError extends NoydbError {
 declare class InvalidKeyError extends NoydbError {
     constructor(message?: string);
 }
+/**
+ * Thrown when a keyring's wrapped-DEK set unwraps partially — at least
+ * one DEK succeeds (proving the KEK is correct) but at least one fails.
+ * The passphrase is right; the failed entries are corrupted.
+ *
+ * This is distinct from {@link InvalidKeyError} so that
+ * `NoydbOptions.onInvalidKey: 'reset'` does NOT fire — resetting on
+ * partial corruption would destroy the still-valid DEKs and the data
+ * they protect, which is silent data loss in response to a feature
+ * designed for stale-credential recovery.
+ */
+declare class KeyringCorruptError extends NoydbError {
+    readonly failedCollections: readonly string[];
+    readonly intactCount: number;
+    constructor(opts: {
+        failedCollections: readonly string[];
+        intactCount: number;
+        message?: string;
+    });
+}
 /**
  * Thrown when the authenticated user does not have a DEK for the requested
  * collection — i.e. the collection is not in their keyring at all.
@@ -229,7 +249,7 @@ declare class KeyringExpiredError extends NoydbError {
 }
 /**
  * Thrown when an `@noy-db/as-*` import is attempted but the invoking
- * keyring lacks the required import-capability bit (issue ).
+ * keyring lacks the required import-capability bit.
  *
  * - `tier: 'plaintext'` — a plaintext-tier import (`as-csv`, `as-json`,
  *   `as-ndjson`, `as-zip`, …) was attempted but the keyring's
@@ -327,6 +347,64 @@ declare class PeriodClosedError extends NoydbError {
     readonly recordTs: string;
     constructor(periodName: string, endDate: string, recordTs: string);
 }
+/**
+ * Thrown when a `put()` or `delete()` is rejected by a guard's `check`
+ * function. The `reason` is the message the guard supplied — typically a
+ * short business description (e.g. "invoice is issued"). The full
+ * collection + id are surfaced so audit UIs can link back to the record.
+ */
+declare class RecordLockedError extends NoydbError {
+    readonly collection: string;
+    readonly id: string;
+    readonly reason: string;
+    constructor(collection: string, id: string, reason: string);
+}
+/**
+ * Thrown when a `put()` changes one or more fields that are frozen by a
+ * `frozenFields` guard. The `fields` list contains the specific paths
+ * that were detected as changed.
+ */
+declare class FieldFrozenError extends NoydbError {
+    readonly collection: string;
+    readonly id: string;
+    readonly fields: readonly string[];
+    constructor(collection: string, id: string, fields: readonly string[]);
+}
+/**
+ * Thrown by an amendment invariant when the proposed change-set violates
+ * the declared business rule (e.g. disbursement total not preserved).
+ * Triggers a full transaction rollback via the existing revert pass.
+ */
+declare class InvariantError extends NoydbError {
+    constructor(message: string);
+}
+/**
+ * Thrown at `withTransactions({ amendment: true })` open if the caller's
+ * role is not in the guard's allowed amendment roles. Fail-fast: thrown
+ * before any writes are attempted.
+ */
+declare class AmendmentForbiddenError extends NoydbError {
+    readonly userId: string;
+    readonly role: string;
+    constructor(userId: string, role: string);
+}
+/**
+ * Thrown by `listUsersWithEnvelopes` when the vault's user directory
+ * has been disabled (via `db.setDirectoryEnabled(vault, false)`) and
+ * the caller's role is neither `owner` nor `admin`. Owner/admin can
+ * still enumerate users — the toggle is a UX privacy switch, not a
+ * security boundary.
+ *
+ * Honest caveat: this is a UX flag, not a privacy guarantee. The
+ * envelope ciphertext is still in the store, the keyring file is
+ * still listed at `_keyring/*`, and anyone with direct store read
+ * access can count keyrings without going through the hub. See
+ * `docs/subsystems/user-envelope.md` → "Directory visibility".
+ */
+declare class DirectoryDisabledError extends NoydbError {
+    readonly vault: string;
+    constructor(vault: string);
+}
 /**
  * Thrown when a user tries to act at a tier they are not cleared for.
  *
@@ -584,6 +662,33 @@ declare class IndexWriteFailureError extends NoydbError {
 declare class BundleIntegrityError extends NoydbError {
     constructor(message: string);
 }
+/**
+ * Thrown by `readNoydbBundle` (#197) when the bundle carries
+ * sealed per-user passphrases but no supplied `SealingKeyProvider`
+ * has a `.id` (= `pid`) matching the sealed entry's `pid`.
+ *
+ * Carries the failing pid + the user id so the recipient can
+ * surface an actionable prompt:
+ *
+ * ```
+ * BundleSealMismatchError: bundle carries sealed passphrase for user "alice"
+ *   under provider "macos-keychain:com.acme.app/alice@acme.example",
+ *   but no registered provider matches that pid.
+ * ```
+ *
+ * Three resolution paths the message names (per foundation §11.9.4):
+ *
+ * 1. Configure a provider matching the pid and retry import.
+ * 2. Pass `attemptUnsealAcrossProviders: true` to try each
+ *    registered provider regardless of pid.
+ * 3. Inspect without unsealing — pass no `sealingProviders` to
+ *    receive the sealed entries unmodified for offline analysis.
+ */
+declare class BundleSealMismatchError extends NoydbError {
+    readonly userId: string;
+    readonly pid: string;
+    constructor(userId: string, pid: string);
+}
 /**
  * Thrown when `vault.collection()` is called with a name that is
  * reserved for NOYDB internal use (any name starting with `_dict_`).
@@ -830,6 +935,156 @@ declare class PathEscapeError extends NoydbError {
         targetDir: string;
     });
 }
+/**
+ * Thrown at vault open if the derivation graph contains a cycle.
+ * `path` is the offending chain (e.g. `['a', 'b', 'c', 'a']`).
+ */
+declare class DerivationCycleError extends NoydbError {
+    readonly path: readonly string[];
+    constructor(path: readonly string[]);
+}
+/**
+ * Thrown when a cascade of source → output → source → … exceeds the
+ * configured `maxDepth` (default 5).
+ */
+declare class DerivationDepthError extends NoydbError {
+    readonly limit: number;
+    readonly attempted: number;
+    constructor(limit: number, attempted: number);
+}
+/**
+ * Thrown at registration if a `withDerivation` strategy references an
+ * output `collection` that isn't otherwise declared (no schema, no use
+ * elsewhere). Surfacing this early catches typos in collection names.
+ */
+declare class DerivationOutputUnknownError extends NoydbError {
+    readonly collection: string;
+    constructor(collection: string);
+}
+/**
+ * Thrown when the user's `derive` function returns a value that doesn't
+ * match the declared output spec (e.g. wrong shape, wrong key set).
+ */
+declare class DerivationOutputShapeError extends NoydbError {
+    readonly outputKey: string;
+    constructor(outputKey: string, detail: string);
+}
+/**
+ * Thrown by array-shape derivations (#200) when the `derive` function
+ * returns more rows than the output's `maxFanout` cap. The cap exists
+ * to keep dispatch cost bounded — without it a single source-row
+ * update could fan out to thousands of derived rows, dominating the
+ * write path.
+ *
+ * Defaults to `maxFanout: 64`. Raise on the output spec for
+ * carry-forward expansion cases (e.g. monthly rows across multi-year
+ * contracts).
+ */
+declare class DerivationCapExceededError extends NoydbError {
+    readonly outputKey: string;
+    readonly returned: number;
+    readonly maxFanout: number;
+    constructor(outputKey: string, returned: number, maxFanout: number);
+}
+/**
+ * Thrown at vault open if the materialized-view graph contains a
+ * cycle. `path` is the offending chain (e.g. `['a-mv', 'b-mv', 'a-mv']`).
+ * Detected by the same shared DFS that catches `DerivationCycleError`;
+ * surfaces with a distinct error type so consumers can disambiguate.
+ */
+declare class MaterializedViewCycleError extends NoydbError {
+    readonly path: readonly string[];
+    constructor(path: readonly string[]);
+}
+/**
+ * Thrown at MV registration if the query references a source
+ * collection that isn't declared on the vault. Surfacing this early
+ * catches typos in collection names.
+ */
+declare class MaterializedViewSourceUnknownError extends NoydbError {
+    readonly mvName: string;
+    readonly collection: string;
+    constructor(mvName: string, collection: string);
+}
+/**
+ * Thrown by the MV executor when a refresh produces more rows than
+ * the configured ceiling. Default ceiling is 100k rows; override
+ * per-MV via `maxRows`. Mirrors `JoinTooLargeError` /
+ * `GroupCardinalityError` from the query DSL — the explosion is
+ * detected BEFORE writes hit the store, so the source-write
+ * transaction can roll back cleanly via strict-mode.
+ */
+declare class MaterializedViewTooLargeError extends NoydbError {
+    readonly mvName: string;
+    readonly expected: number;
+    readonly limit: number;
+    constructor(mvName: string, expected: number, limit: number);
+}
+/**
+ * Thrown by `withMaterializedView()` at registration time when the
+ * strategy is structurally malformed. Distinct from
+ * `MaterializedViewSourceUnknownError` (the source list is well-formed
+ * but names a collection the vault doesn't know) and
+ * `MaterializedViewCycleError` (the source graph has a cycle): this
+ * error fires before either check, at the moment the spec is being
+ * normalized.
+ *
+ * Today the trigger cases are all about the `query` / `unionSources`
+ * dichotomy introduced by #165:
+ *   - both `query` and `unionSources` were set (mutually exclusive),
+ *   - neither `query` nor `unionSources` was set,
+ *   - `unionSources` has fewer than 2 arms,
+ *   - two arms in `unionSources` reference the same `collection`.
+ *
+ * The error message is prefixed with `[noy-db] withMaterializedView:`
+ * so it's grep-friendly in logs and looks consistent with the existing
+ * `ValidationError` messages from the same factory.
+ */
+declare class MaterializedViewConfigError extends NoydbError {
+    constructor(message: string);
+}
+/**
+ * Thrown at vault open when a `withOverlayedView` declaration uses
+ * another virtual-overlay name as its `base`. Multi-overlay stacking
+ * is a v2 non-goal — the shallow expansion in
+ * `QueryDependencyAnalyzer` would truncate at the inner overlay
+ * name, leaving downstream MVs silently stale.
+ */
+declare class OverlayBaseIsVirtualError extends NoydbError {
+    readonly overlayName: string;
+    readonly base: string;
+    constructor(overlayName: string, base: string);
+}
+/**
+ * Thrown at vault open when a `withOverlayedView`'s `overlay`
+ * references an unknown collection or an MV-owned collection. The
+ * overlay collection is user-writable; MV-owned collections aren't.
+ */
+declare class OverlayCollectionUnavailableError extends NoydbError {
+    readonly overlayName: string;
+    readonly overlay: string;
+    constructor(overlayName: string, overlay: string);
+}
+/**
+ * Thrown at vault open when a `withOverlayedView`'s virtual `name`
+ * collides with an MV output or a concrete source collection.
+ */
+declare class OverlayNameCollisionError extends NoydbError {
+    readonly overlayName: string;
+    constructor(overlayName: string);
+}
+/**
+ * Thrown by the virtual overlay's `put(id, record)` when the
+ * consumer-supplied `id` doesn't match `rowKey(record)`. Catches
+ * fat-finger separator typos that would otherwise silently produce
+ * orphaned overlay rows. Direct writes to the underlying overlay
+ * collection (bypass the virtual layer) skip this validation.
+ */
+declare class OverlayIdMismatchError extends NoydbError {
+    readonly actual: string;
+    readonly expected: string;
+    constructor(actual: string, expected: string);
+}
 
 /**
  * Foreign-key references — the soft-FK mechanism.
@@ -1361,12 +1616,54 @@ interface QuerySource<T> {
  * joinContext, and calling `.join()` on it throws with an actionable
  * error. See `query/join.ts` for the full design.
  */
+/**
+ * Declared deterministic predicate (#153). Carries the consumer's
+ * stable `hash` (for function-body identity), the function itself,
+ * and is keyed by name when registered on a `Query<T>` via
+ * `_withPredicates()`.
+ */
+interface DeclaredPredicate {
+    hash: string;
+    fn: (record: unknown, ctx?: unknown) => boolean;
+}
 declare class Query<T> {
     private readonly source;
     private readonly plan;
     private readonly joinContext;
     private readonly aggregateStrategy;
-    constructor(source: QuerySource<T>, plan?: QueryPlan, joinContext?: JoinContext, aggregateStrategy?: AggregateStrategy);
+    private readonly predicates;
+    constructor(source: QuerySource<T>, plan?: QueryPlan, joinContext?: JoinContext, aggregateStrategy?: AggregateStrategy, predicates?: ReadonlyMap<string, DeclaredPredicate>);
+    /**
+     * @internal — accessor for the materialized-view dependency
+     * analyzer. Not part of the public API; consumers should use the
+     * builder methods, not inspect the plan directly.
+     */
+    _plan(): QueryPlan;
+    /**
+     * @internal — accessor for the materialized-view dependency
+     * analyzer. Returns the join resolution context (or `undefined` for
+     * queries constructed without a Collection backing).
+     */
+    _joinContext(): JoinContext | undefined;
+    /**
+     * @internal — clone this Query with a declared-predicate map
+     * attached. Used by the materialized-view registry to enable
+     * `.wherePredicate(name, ctx?)` for the MV's query callback (#153).
+     * Consumers don't call this directly.
+     */
+    _withPredicates(predicates: ReadonlyMap<string, DeclaredPredicate>): Query<T>;
+    /**
+     * Filter by a registered deterministic predicate (#153). Requires
+     * the Query to have been augmented with a predicates map (typically
+     * via the materialized-view registry — bare Queries constructed
+     * outside an MV throw on `.wherePredicate()`).
+     *
+     * `ctx` is an optional opaque value passed verbatim to the predicate
+     * function. Both `predicateHash` (from the registration) and a
+     * canonical-JSON hash of `ctx` fold into the MV's `queryHash`, so
+     * either changing forces refresh on next visit.
+     */
+    wherePredicate(name: string, ctx?: unknown): Query<T>;
     /** Add a field comparison. Multiple where() calls are AND-combined. */
     where(field: string, op: Operator, value: unknown): Query<T>;
     /**
@@ -1558,6 +1855,7 @@ declare class Query<T> {
      * per record and can't be index-accelerated.
      */
     groupBy<F extends string>(field: F): GroupedQuery<T, F>;
+    groupBy<F extends readonly [string, string, ...string[]]>(...fields: F): GroupedQueryN<T, F>;
     /**
      * Re-run the query whenever the source notifies of changes.
      * Returns an unsubscribe function. The callback receives the latest result.
@@ -1937,4 +2235,4 @@ declare class ScanBuilder<T> implements AsyncIterable<T> {
     private recordMatches;
 }
 
-export { ScanBuilder as $, AlreadyElevatedError as A, BackupCorruptedError as B, ConflictError as C, DEFAULT_JOIN_MAX_ROWS as D, ElevationExpiredError as E, FilenameSanitizationError as F, GroupCardinalityError as G, type QuerySource as H, ImportCapabilityError as I, type JoinContext as J, KeyringExpiredError as K, LedgerContentionError as L, MissingTranslationError as M, NoydbError as N, type OrderBy as O, PathEscapeError as P, Query as Q, ReadOnlyAtInstantError as R, ReadOnlyError as S, ReadOnlyFrameError as T, type RefDescriptor as U, RefIntegrityError as V, type RefMode as W, RefRegistry as X, RefScopeError as Y, type RefViolation as Z, ReservedCollectionNameError as _, BackupLedgerError as a, type ScanPageProvider as a0, SchemaValidationError as a1, SessionExpiredError as a2, SessionNotFoundError as a3, SessionPolicyError as a4, StoreCapabilityError as a5, TamperedError as a6, TierDemoteDeniedError as a7, TierNotGrantedError as a8, TranslatorNotConfiguredError as a9, ValidationError as aa, applyJoins as ab, buildLiveQuery as ac, executePlan as ad, ref as ae, resetJoinWarnings as af, BundleIntegrityError as b, BundleVersionConflictError as c, DanglingReferenceError as d, DecryptionError as e, DelegationTargetMissingError as f, DictKeyInUseError as g, DictKeyMissingError as h, ExportCapabilityError as i, IndexRequiredError as j, IndexWriteFailureError as k, InvalidKeyError as l, type JoinLeg as m, type JoinStrategy as n, JoinTooLargeError as o, type JoinableSource as p, type LiveQuery as q, type LiveUpstream as r, LocaleNotSpecifiedError as s, NetworkError as t, NoAccessError as u, NotFoundError as v, PeriodClosedError as w, PermissionDeniedError as x, PrivilegeEscalationError as y, type QueryPlan as z };
+export { KeyringCorruptError as $, AmendmentForbiddenError as A, BackupCorruptedError as B, ConflictError as C, DictKeyInUseError as D, ElevationExpiredError as E, FieldFrozenError as F, ExportCapabilityError as G, FilenameSanitizationError as H, InvariantError as I, GroupCardinalityError as J, ImportCapabilityError as K, LocaleNotSpecifiedError as L, MissingTranslationError as M, NoydbError as N, OverlayBaseIsVirtualError as O, IndexRequiredError as P, Query as Q, ReservedCollectionNameError as R, SessionExpiredError as S, TranslatorNotConfiguredError as T, IndexWriteFailureError as U, InvalidKeyError as V, type JoinContext as W, type JoinLeg as X, type JoinStrategy as Y, JoinTooLargeError as Z, type JoinableSource as _, DictKeyMissingError as a, KeyringExpiredError as a0, LedgerContentionError as a1, type LiveQuery as a2, type LiveUpstream as a3, NetworkError as a4, NoAccessError as a5, NotFoundError as a6, type OrderBy as a7, PathEscapeError as a8, PeriodClosedError as a9, PermissionDeniedError as aa, PrivilegeEscalationError as ab, type QueryPlan as ac, type QuerySource as ad, ReadOnlyAtInstantError as ae, ReadOnlyError as af, ReadOnlyFrameError as ag, type RefDescriptor as ah, RefIntegrityError as ai, type RefMode as aj, RefRegistry as ak, RefScopeError as al, type RefViolation as am, ScanBuilder as an, type ScanPageProvider as ao, SchemaValidationError as ap, StoreCapabilityError as aq, TamperedError as ar, TierDemoteDeniedError as as, TierNotGrantedError as at, ValidationError as au, applyJoins as av, buildLiveQuery as aw, executePlan as ax, ref as ay, resetJoinWarnings as az, SessionNotFoundError as b, SessionPolicyError as c, RecordLockedError as d, DerivationCapExceededError as e, DerivationCycleError as f, DerivationDepthError as g, DerivationOutputShapeError as h, DerivationOutputUnknownError as i, OverlayCollectionUnavailableError as j, OverlayIdMismatchError as k, OverlayNameCollisionError as l, MaterializedViewConfigError as m, MaterializedViewCycleError as n, MaterializedViewSourceUnknownError as o, MaterializedViewTooLargeError as p, AlreadyElevatedError as q, BackupLedgerError as r, BundleIntegrityError as s, BundleSealMismatchError as t, BundleVersionConflictError as u, DEFAULT_JOIN_MAX_ROWS as v, DanglingReferenceError as w, DecryptionError as x, DelegationTargetMissingError as y, DirectoryDisabledError as z };

package/dist/{index-DsVbTDZI.d.cts → index-hdFvZkBP.d.cts}

@@ -1,4 +1,5 @@
-import { aS as PublicEnvelope, b0 as BundleRecipient, aY as Vault } from './types-arFMsCtn.cjs';
+import { bh as PublicEnvelope, dj as SealingKeyProvider, bu as BundleRecipient, bq as Vault } from './types-C4lwMKKF.cjs';
+import './index-CmVgTkqk.cjs';
 
 /**
  * `.noydb` container format — byte layout, header schema, validators.
@@ -123,6 +124,22 @@ interface NoydbBundleHeader {
      * other unknown header key still rejects at parse time.
      */
     readonly publicEnvelope?: PublicEnvelope;
+    /**
+     * Auto-unlock material indicator (#197). When present, the bundle
+     * body wraps the dump JSON in a structure carrying per-user
+     * passphrases — either plaintext (`'unsealed'`, public-by-design)
+     * or sealed under a `SealingKeyProvider` (`'sealed'`, requires
+     * matching provider on the recipient side).
+     *
+     * Visible pre-decompression so cloud listing UIs can warn before
+     * download: "this bundle opens itself for anyone holding the file"
+     * (unsealed) or "this bundle is sealed for a specific provider"
+     * (sealed).
+     *
+     * Absent → the body is a raw `vault.dump()` JSON string (the
+     * pre-#197 shape; back-compatible).
+     */
+    readonly autoUnlock?: 'unsealed' | 'sealed';
 }
 /**
  * Validate a parsed bundle header. Throws on any deviation from
@@ -188,6 +205,26 @@ declare function hasNoydbBundleMagic(bytes: Uint8Array): boolean;
  * archive utilities that don't care about decryption.
  */
 
+/**
+ * The credential kinds that can be bundled for auto-unlock.
+ * WebAuthn is intentionally excluded — it is hardware-bound and
+ * cannot be embedded as a portable credential.
+ */
+type AutoCredentialKind = 'passphrase' | 'password' | 'pin';
+/**
+ * A typed credential for auto-unlock. Carries the credential `kind`
+ * alongside the plaintext `value`, so consumers can dispatch the
+ * correct login/prefill path rather than treating all credentials
+ * as passphrases.
+ *
+ * `bundle.ts` is a pure format layer — it carries the credential
+ * without interpreting it. The consumer is responsible for
+ * dispatching on `kind`.
+ */
+interface AutoCredential {
+    readonly kind: AutoCredentialKind;
+    readonly value: string;
+}
 /**
  * Options accepted by `writeNoydbBundle`.
  *
@@ -258,6 +295,96 @@ interface WriteNoydbBundleOptions {
      * suited to personal backup-and-restore).
      */
     readonly recipients?: readonly BundleRecipient[];
+    /**
+     * Auto-unlock — unsealed per-user credentials (#215).
+     *
+     * Generalises `autoPassphrases` to support any bundleable credential
+     * kind (`passphrase` | `password` | `pin`).
+     *
+     * Public-by-design: anyone holding the bundle bytes can read these
+     * plaintext credentials. Use for demo data, sample vaults,
+     * prospect onboarding.
+     *
+     * The `policy: 'public-by-design'` discriminant is mandatory. A
+     * bare `{ perUser }` without it is rejected at write time — the
+     * safety net against a careless call against a production vault.
+     *
+     * Mutually exclusive with `sealedCredentials`, `autoPassphrases`,
+     * and `sealedPassphrases`.
+     */
+    readonly autoCredentials?: {
+        readonly policy: 'public-by-design';
+        readonly perUser: Record<string, AutoCredential>;
+    };
+    /**
+     * Auto-unlock — per-user credentials sealed under a
+     * {@link SealingKeyProvider} (#215).
+     *
+     * Generalises `sealedPassphrases` to support any bundleable
+     * credential kind (`passphrase` | `password` | `pin`).
+     *
+     * The hub seals each user's plaintext credential under `provider`
+     * and embeds the resulting sealed envelopes in the bundle. The
+     * recipient must hold a provider with a matching `pid` (i.e.,
+     * `provider.id`) to auto-unseal on import.
+     *
+     * `mode: 'self-target'` is the only supported mode — sender and
+     * recipient share the same provider identity (same iCloud Keychain
+     * entry, same MDM-provisioned bundle id, same KMS account, etc.).
+     *
+     * Mutually exclusive with `autoCredentials`, `autoPassphrases`,
+     * and `sealedPassphrases`.
+     */
+    readonly sealedCredentials?: {
+        readonly mode: 'self-target';
+        readonly provider: SealingKeyProvider;
+        readonly perUser: Record<string, AutoCredential>;
+    };
+    /**
+     * @deprecated Use `autoCredentials` instead (#215).
+     *
+     * Auto-unlock — unsealed per-user passphrases (#197 slice 1).
+     *
+     * Public-by-design: anyone holding the bundle bytes can read these
+     * plaintext credentials. Use for demo data, sample vaults,
+     * prospect onboarding.
+     *
+     * The `policy: 'public-by-design'` discriminant is mandatory. A
+     * bare `{ perUser }` without it is rejected at write time — the
+     * safety net against a careless call against a production vault.
+     *
+     * Mutually exclusive with `autoCredentials`, `sealedCredentials`,
+     * and `sealedPassphrases`.
+     */
+    readonly autoPassphrases?: {
+        readonly policy: 'public-by-design';
+        readonly perUser: Record<string, string>;
+    };
+    /**
+     * @deprecated Use `sealedCredentials` instead (#215).
+     *
+     * Auto-unlock — per-user passphrases sealed under a
+     * {@link SealingKeyProvider} (#197 slice 1, self-target only).
+     *
+     * The hub seals each user's plaintext passphrase under `provider`
+     * and embeds the resulting sealed envelopes in the bundle. The
+     * recipient must hold a provider with a matching `pid` (i.e.,
+     * `provider.id`) to auto-unseal on import.
+     *
+     * `mode: 'self-target'` is the only mode in slice 1 — sender and
+     * recipient share the same provider identity (same iCloud Keychain
+     * entry, same MDM-provisioned bundle id, same KMS account, etc.).
+     * Recipient-target sealing via the `RecipientSealer` interface
+     * (foundation §11.4) is deferred to a follow-up slice.
+     *
+     * Mutually exclusive with `autoCredentials`, `sealedCredentials`,
+     * and `autoPassphrases`.
+     */
+    readonly sealedPassphrases?: {
+        readonly mode: 'self-target';
+        readonly provider: SealingKeyProvider;
+        readonly perUser: Record<string, string>;
+    };
 }
 /**
  * Result returned by `readNoydbBundle`. The caller is expected to
@@ -268,6 +395,50 @@ interface WriteNoydbBundleOptions {
 interface NoydbBundleReadResult {
     readonly header: NoydbBundleHeader;
     readonly dumpJson: string;
+    /**
+     * Auto-unlock material (#197, widened in #215). Present only when
+     * the header's `autoUnlock` flag is set AND the body's wrapped
+     * structure survived parsing. Values are typed credentials — either
+     * delivered plain (`kind: 'unsealed'`) or unsealed at read time
+     * using one of the supplied `sealingProviders` (`kind: 'sealed'`).
+     *
+     * Consumers dispatch on `cred.kind` to choose the correct login /
+     * prefill path. Pre-0.2 bundles (bare string entries) are coerced
+     * to `{ kind: 'passphrase', value }` on read for back-compat.
+     *
+     * For `kind: 'sealed'` bundles read without `sealingProviders`, the
+     * `value` field is the raw base64 sealed bytes — opaque to the
+     * consumer until unsealed elsewhere.
+     */
+    readonly autoUnlock?: {
+        readonly kind: 'unsealed' | 'sealed';
+        readonly perUser: Record<string, AutoCredential>;
+    };
+}
+/**
+ * Options accepted by {@link readNoydbBundle} for the #197
+ * auto-unlock paths. Without these the reader behaves exactly as
+ * pre-#197 (header parsed; body returned as `dumpJson`).
+ */
+interface ReadNoydbBundleOptions {
+    /**
+     * Recipient-side sealing providers used to unseal entries from
+     * `sealedPassphrases`. The reader picks the one whose `.id`
+     * matches each entry's `pid`. Multiple providers may be supplied
+     * (different users may seal under different identities).
+     *
+     * When unset and the bundle carries sealed envelopes, the
+     * `autoUnlock.perUser` map remains the SEALED entries unmodified
+     * — callers can inspect them or unseal elsewhere.
+     */
+    readonly sealingProviders?: readonly SealingKeyProvider[];
+    /**
+     * Opt-in trial mode for unsealing — when an entry's `pid` doesn't
+     * match a registered provider, try each provider whose alg
+     * matches. Default `false` (strict-pid dispatch per foundation
+     * §11.9.2). Surfaces extra credential prompts; use deliberately.
+     */
+    readonly attemptUnsealAcrossProviders?: boolean;
 }
 /** Test-only: reset the brotli detection cache between tests. */
 declare function resetBrotliSupportCache(): void;
@@ -344,7 +515,7 @@ declare function readNoydbBundlePublicEnvelope(bytes: Uint8Array, opts?: {
  * free of crypto concerns and lets the same code feed format
  * inspectors that never decrypt anything.
  */
-declare function readNoydbBundle(bytes: Uint8Array): Promise<NoydbBundleReadResult>;
+declare function readNoydbBundle(bytes: Uint8Array, opts?: ReadNoydbBundleOptions): Promise<NoydbBundleReadResult>;
 
 /**
  * Minimal ULID generator — zero dependencies, Web Crypto API only.
@@ -411,4 +582,4 @@ declare function generateULID(): string;
  */
 declare function isULID(value: string): boolean;
 
-export { type CompressionAlgo as C, FLAG_COMPRESSED as F, NOYDB_BUNDLE_FORMAT_VERSION as N, type WriteNoydbBundleOptions as W, NOYDB_BUNDLE_MAGIC as a, NOYDB_BUNDLE_PREFIX_BYTES as b, type NoydbBundleHeader as c, type NoydbBundleReadResult as d, readNoydbBundleHeader as e, readNoydbBundlePublicEnvelope as f, generateULID as g, hasNoydbBundleMagic as h, isULID as i, resetBrotliSupportCache as j, COMPRESSION_BROTLI as k, COMPRESSION_GZIP as l, COMPRESSION_NONE as m, FLAG_HAS_INTEGRITY_HASH as n, encodeBundleHeader as o, readNoydbBundle as r, validateBundleHeader as v, writeNoydbBundle as w };
+export { type AutoCredential as A, type CompressionAlgo as C, FLAG_COMPRESSED as F, NOYDB_BUNDLE_FORMAT_VERSION as N, type ReadNoydbBundleOptions as R, type WriteNoydbBundleOptions as W, type AutoCredentialKind as a, NOYDB_BUNDLE_MAGIC as b, NOYDB_BUNDLE_PREFIX_BYTES as c, type NoydbBundleHeader as d, type NoydbBundleReadResult as e, readNoydbBundleHeader as f, generateULID as g, hasNoydbBundleMagic as h, isULID as i, readNoydbBundlePublicEnvelope as j, resetBrotliSupportCache as k, COMPRESSION_BROTLI as l, COMPRESSION_GZIP as m, COMPRESSION_NONE as n, FLAG_HAS_INTEGRITY_HASH as o, encodeBundleHeader as p, readNoydbBundle as r, validateBundleHeader as v, writeNoydbBundle as w };