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

package/dist/with-shape/blobs/export-blobs.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `vault.exportBlobs()` — bulk blob extraction primitive.
+ *
+ * Async-iterable handle over every blob attached to records in a
+ * vault, optionally filtered by collection allowlist and per-record
+ * predicate. Emits tuples of `{ blobId, recordRef, bytes, meta }` so
+ * the consumer can pipe into any sink (zip stream, S3 multipart, USB
+ * copy, cold-storage tape) without pulling the whole export into
+ * memory.
+ *
+ * ## Auth + audit
+ *
+ * - Capability check runs **once** at handle creation via
+ *   `Vault.assertCanExport('plaintext', 'blob')`. An operator whose
+ *   keyring lacks that bit fails before a single byte of ciphertext
+ *   is decrypted.
+ * - Audit entry lands in `_export_audit` at handle creation: the
+ *   actor, start timestamp, target collections, predicate presence,
+ *   and batch mechanism. **No content hashes** — per the spec
+ *   non-correlation invariant.
+ *
+ * ## Abort + resume
+ *
+ * - `handle.abort()` flips the internal signal; the next iteration
+ *   boundary throws `AbortError`. Consumers already in `for await`
+ *   can catch and exit cleanly.
+ * - Restart after a partial failure with `{ afterBlobId }` — the
+ *   iterator skips tuples up to (and including) that blob id before
+ *   yielding again. Combined with a blob-count ceiling it supports
+ *   idempotent batch re-runs.
+ *
+ * @module
+ */
+import type { Collection } from '../../kernel/collection.js';
+export interface ExportBlobsOptions {
+    /**
+     * Collection allowlist. Omit to export blobs from every collection
+     * the caller has read access to.
+     */
+    readonly collections?: readonly string[];
+    /**
+     * Per-record predicate. Called on the decrypted record BEFORE any
+     * blob bytes are read for that record — returning false skips the
+     * record and all its slots without touching their chunks.
+     */
+    readonly where?: (record: unknown, context: {
+        collection: string;
+        id: string;
+    }) => boolean;
+    /**
+     * Resume after a specific blob id. The iterator skips tuples up to
+     * and including this id, then yields. Format of the id is the same
+     * as `ExportedBlob.blobId` (the HMAC-keyed eTag).
+     */
+    readonly afterBlobId?: string;
+    /**
+     * External abort signal. When fired, the next iterator tick throws
+     * `ExportBlobsAbortedError`. Honored alongside `handle.abort()`.
+     */
+    readonly signal?: AbortSignal;
+}
+export interface ExportedBlob {
+    /** Opaque blob identifier — HMAC-keyed eTag, stable across vaults. */
+    readonly blobId: string;
+    /** Where this blob came from in the vault. */
+    readonly recordRef: {
+        readonly collection: string;
+        readonly id: string;
+        readonly slot: string;
+    };
+    /** Decrypted plaintext bytes. */
+    readonly bytes: Uint8Array;
+    /** Best-effort metadata (from the blob slot record). */
+    readonly meta: {
+        readonly size: number;
+        /**
+         * User-visible filename stored on the slot. Often equal to the
+         * slot name; differs when the caller supplied an explicit
+         * `filename` to `BlobSet.put()`.
+         */
+        readonly filename: string;
+        readonly mimeType?: string;
+        readonly createdAt?: string;
+    };
+}
+export interface ExportBlobsHandle extends AsyncIterable<ExportedBlob> {
+    /** Abort the export. Safe to call multiple times. */
+    abort(): void;
+    /** True once `abort()` has fired or the external signal aborted. */
+    readonly aborted: boolean;
+}
+export declare class ExportBlobsAbortedError extends Error {
+    constructor(reason: string);
+}
+export declare const EXPORT_AUDIT_COLLECTION = "_export_audit";
+export interface ExportBlobsAuditEntry {
+    readonly id: string;
+    readonly mechanism: 'exportBlobs';
+    readonly actor: string;
+    readonly startedAt: string;
+    readonly collections: readonly string[] | null;
+    readonly predicate: boolean;
+    readonly afterBlobId: string | null;
+}
+/**
+ * Build the handle. Factored out of `Vault.exportBlobs` so the
+ * implementation can be unit-tested without going through the
+ * compartment lifecycle.
+ */
+export declare function createExportBlobsHandle(actor: string, listAccessibleCollections: () => Promise<string[]>, getCollection: <T>(name: string) => Collection<T>, writeAudit: (entry: ExportBlobsAuditEntry) => Promise<void>, options: ExportBlobsOptions): ExportBlobsHandle;

package/dist/with-shape/blobs/import-external.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Import / bootstrap (reverse projection) — walk an existing bucket/prefix in an
+ * {@link ObjectProjection} and build a master collection where each record
+ * anchors one object, restoring the record-anchoring invariant for objects that
+ * pre-date noy-db (or were written by another system). See as-aws-s3 §3.8.
+ *
+ * Idempotent: re-running re-adopts the same objects under the same record ids.
+ */
+import type { ObjectProjection } from './object-projection.js';
+/** Minimal collection surface this utility needs (avoids importing the kernel). */
+export interface ImportableCollection {
+    get(id: string): Promise<unknown>;
+    put(id: string, record: unknown): Promise<unknown>;
+    blob(id: string): {
+        adoptExternal(slot: string, ref: {
+            key: string;
+            size?: number;
+            contentType?: string;
+            public?: boolean;
+            backlink?: string;
+        }): Promise<void>;
+    };
+}
+export interface ImportExternalOptions {
+    /** Only consider objects under this key prefix. Default `''` (all). */
+    prefix?: string;
+    /**
+     * Derive the record id for an object key. Default: the path segment before
+     * the last — i.e. `{collection}/{recordId}/{field}` → `recordId`. Return
+     * `null` to skip the object.
+     */
+    deriveRecordId?: (key: string) => string | null;
+    /** Build the anchor record for a new id. Default `{ id }`. */
+    makeRecord?: (id: string) => unknown;
+}
+export interface ImportExternalResult {
+    imported: number;
+    skipped: number;
+    recordIds: string[];
+}
+/**
+ * Build/extend `collection` from the objects under `prefix` in `objectStore`,
+ * adopting each as the `field` blob on its derived record.
+ */
+export declare function importExternalObjects(args: {
+    collection: ImportableCollection;
+    objectStore: ObjectProjection;
+    field: string;
+    options?: ImportExternalOptions;
+}): Promise<ImportExternalResult>;

package/dist/with-shape/blobs/mime-magic.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Lightweight MIME type detection from magic bytes (file signatures).
+ *
+ * Designed for the blob store's auto-detection feature. Operates on the first 16 bytes of
+ * plaintext — no filesystem access, no filename guessing.
+ *
+ * ## Detection strategies
+ *
+ * 1. **Prefix match** — magic bytes at offset 0 (most formats).
+ * 2. **Offset match** — magic bytes at a fixed offset > 0 (ISOBMFF: offset 4).
+ * 3. **Compound match** — two separate byte sequences at different offsets
+ *    (RIFF-based: bytes 0-3 + bytes 8-11).
+ *
+ * ## Formats excluded (require offset > 16 bytes)
+ *
+ * - TAR (`ustar` at offset 257)
+ * - ISO 9660 (`CD001` at offset 32769)
+ *
+ * @module
+ */
+/**
+ * Detect MIME type from the first bytes of a file.
+ *
+ * @param header - The first 16 bytes (or more) of the plaintext. Passing
+ *   fewer than 16 bytes may miss compound and offset-based matches.
+ * @returns Detected MIME type, or `'application/octet-stream'` if unknown.
+ */
+export declare function detectMimeType(header: Uint8Array): string;
+/**
+ * Detect MIME type and whether the format is already compressed.
+ *
+ * Used by `BlobSet.put()` to decide whether to skip gzip compression.
+ *
+ * @param header - The first 16 bytes (or more) of the plaintext.
+ * @returns `{ mime, preCompressed }` or `null` if no match.
+ */
+export declare function detectMagic(header: Uint8Array): {
+    mime: string;
+    format: string;
+    preCompressed: boolean;
+} | null;
+/**
+ * Check whether a format is already compressed (should skip gzip).
+ *
+ * @param mimeType - A MIME type string.
+ * @returns `true` if the format is known to be pre-compressed.
+ */
+export declare function isPreCompressed(mimeType: string): boolean;

package/dist/with-shape/blobs/object-projection.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `ObjectProjection` — the capability an `as-*` projection store implements to
+ * hold blob bytes as native, directly-consumable objects (e.g. servable S3
+ * objects) rather than the encrypted-envelope chunks a `NoydbStore` holds.
+ *
+ * This is the shared seam behind **direct-serve blobs** and the
+ * **debug raw-object path**: "write these bytes as one real object and
+ * give me a URL to it." See the as-aws-s3 design spec.
+ *
+ * Unlike `NoydbStore` (ciphertext in / ciphertext out), an `ObjectProjection`
+ * sees **raw bytes** — it is `as-*`, not `to-*`, and lives **outside** the
+ * zero-knowledge guarantee. Wiring it up is a deliberate, per-field opt-in.
+ */
+/** Metadata about a stored object, without its body. */
+export interface ObjectMeta {
+    readonly size: number;
+    readonly contentType?: string;
+    readonly etag?: string;
+    readonly lastModified?: string;
+    /** S3-style user metadata (`x-amz-meta-*`). Small; see the design's
+     *  plain / encrypted / opaque-token modes. */
+    readonly userMeta?: Record<string, string>;
+}
+export interface PutObjectOptions {
+    readonly contentType: string;
+    /** World-readable object (CDN origin) vs private (presigned-only). Default false. */
+    readonly public?: boolean;
+    /** User metadata mirrored onto the object (the "secondary store"). */
+    readonly userMeta?: Record<string, string>;
+}
+export interface ObjectUrlOptions {
+    /** TTL for a presigned URL (ignored for a public object). */
+    readonly expiresInSeconds?: number;
+}
+export interface PutUrlOptions {
+    readonly contentType: string;
+    readonly expiresInSeconds?: number;
+}
+/** One entry returned by {@link ObjectProjection.listPrefix}. */
+export interface ObjectListEntry {
+    readonly key: string;
+    readonly meta: ObjectMeta;
+}
+export interface ObjectProjection {
+    /** Diagnostic name (e.g. `'aws-s3'`, `'memory'`). */
+    readonly name?: string;
+    /** Write raw bytes as a single native object with a real content type. */
+    putObject(key: string, bytes: Uint8Array, opts: PutObjectOptions): Promise<void>;
+    /** Read the raw bytes back; `null` if absent. */
+    getObject(key: string): Promise<Uint8Array | null>;
+    /** Delete the object. Idempotent — absent is not an error. */
+    deleteObject(key: string): Promise<void>;
+    /** Object metadata without the body; `null` if absent. */
+    headObject(key: string): Promise<ObjectMeta | null>;
+    /** A URL to GET the object — presigned (time-limited) or stable public. */
+    objectUrl(key: string, opts?: ObjectUrlOptions): Promise<string>;
+    /** A presigned URL the client PUTs bytes to directly (large-file upload,
+     *  bytes bypass the hub). */
+    putUrl(key: string, opts: PutUrlOptions): Promise<string>;
+    /** List objects under a key prefix — for import / reconcile. */
+    listPrefix(prefix: string): Promise<ObjectListEntry[]>;
+}
+/**
+ * In-memory {@link ObjectProjection} — a reference implementation for tests,
+ * local development, and the hub's blob-wiring conformance. Holds bytes in a
+ * `Map`; URLs are synthetic (`memory://…`). Not for production.
+ */
+export declare function memoryObjectProjection(opts?: {
+    baseUrl?: string;
+}): ObjectProjection;

package/dist/with-shape/introspection/describe.d.ts

@@ -0,0 +1,237 @@
+/**
+ * `buildDescription` — pure assembler that merges collection config
+ * (moneyFields / dictKeyFields / refs / computed / fieldMeta) with an
+ * optional validator-derived `zodFields` map into a normalised
+ * {@link CollectionDescription}.
+ *
+ * The sync path (`collection.describe()`) passes `zodFields: undefined`.
+ * The async path supplies a populated map and validator-derived type
+ * strings.
+ *
+ * @module
+ */
+import type { FieldMeta } from './field-meta.js';
+import { FieldMetaUnknownFieldError } from './field-meta.js';
+import type { CollectionMeta } from './meta.js';
+import type { ViaDescriptor, ViaPosture } from '../../kernel/via/index.js';
+import type { DictKeyDescriptor, StaticDictDescriptor } from '../../via/i18n/dictionary.js';
+import type { LookupDescriptor } from '../../via/lookup/descriptor.js';
+import type { I18nTextDescriptor } from '../../via/i18n/core.js';
+import type { ComputedFields } from '../../with-formula/computed/index.js';
+import type { RefDescriptor } from '../../kernel/refs.js';
+import type { ClassifiedFieldSpec } from '../../via/classified/descriptor.js';
+export interface DescribedField {
+    readonly key: string;
+    /** Sync: inferred from config ('number'|'enum'|'string'|'array'|'unknown'). Async (Task 4): validator-derived. */
+    readonly type: string;
+    readonly optional: boolean;
+    readonly constraints?: Record<string, unknown>;
+    readonly label: string;
+    readonly description?: string;
+    /** Card/section grouping hint for detail & form layouts. From fieldMeta/zod .meta(). */
+    readonly group?: string;
+    /** Relative ordering hint within and across groups. Lower renders first. */
+    readonly order?: number;
+    readonly semanticType?: string;
+    readonly unit?: string;
+    readonly sensitivity?: 'public' | 'pii' | 'secret';
+    readonly aggregate?: 'sum' | 'count' | 'distinct' | 'none';
+    readonly aliases?: readonly string[];
+    readonly ref?: {
+        target: string;
+        mode: string;
+        isArray?: true;
+    };
+    readonly displayFor?: string;
+    readonly money?: {
+        mode: 'fixed' | 'multi';
+        currency?: string;
+        scale?: number;
+        rounding?: string;
+    };
+    readonly dict?: {
+        name: string;
+        static: boolean;
+        values?: readonly {
+            value: string;
+            label?: string;
+        }[];
+    };
+    /**
+     * Normalized lookup metadata (#650 Task 7 — the first-ever
+     * `ViaBinding.describeFragment` consumer; sourced from the `'lookup'`
+     * binding's fragment, NOT from config directly — see `buildDescription`).
+     * Present for every `lookup()`/`enumOf()`/`dict()` field, ALONGSIDE the
+     * pre-existing `dict` block above (kept byte-stable for the
+     * `dictKey()`/`staticDict()` alias — this is additive, not a replacement).
+     * `dimension` is omitted for a bare `enumOf()` (no backing store, no
+     * dimension name — the #650 Task 2 `dimension:''` sentinel resolved).
+     * `keys` is the statically-known closed-vocabulary key set (declared
+     * `keys`, or a static table's own keys) — omitted when membership lives
+     * only in the backing collection/dictionary.
+     */
+    readonly lookup?: {
+        readonly dimension?: string;
+        readonly backing: 'static' | 'reserved' | 'collection';
+        readonly vocabulary: 'open' | 'closed';
+        readonly key: string;
+        readonly altKeys?: readonly string[];
+        readonly present?: {
+            readonly label: string;
+            readonly by?: string;
+        };
+        readonly sortBy?: string;
+        readonly onDelete: 'restrict' | 'cascade' | 'nullify';
+        readonly keys?: readonly string[];
+    };
+    readonly computed?: true;
+    /** i18n metadata for fields declared with i18nText(). Present only when the field is i18n-enabled. */
+    readonly i18n?: {
+        readonly locales?: readonly string[];
+        readonly densify?: boolean;
+    };
+    /** Widget hint derived from semanticType+type, overridable via fieldMeta.widget. */
+    readonly widget: string;
+    /** Whether the field is user-editable. False for computed, id, and provenance-stamped fields. */
+    readonly editable: boolean;
+    /** Present when the field is classified. Serialized read-projection contract. */
+    readonly classified?: {
+        readonly preset: string;
+        readonly storage: 'recoverable' | 'never' | 'digest-only';
+        readonly list: 'omit' | {
+            readonly mask: string;
+        } | {
+            readonly rider: string;
+        };
+        /**
+         * Present (and `true`) only when the field opted into the equatable blind
+         * index. Additive metadata — emitted UNGATED (no `withClassified()` needed;
+         * `toJSONSchema()` carries it too), so it advertises *that* the field is
+         * equatable beyond the DEK-consent boundary. Intended: it's a structural
+         * property a schema consumer legitimately needs and discloses no value. A
+         * deployment wanting it gated can gate this behind its value-bearing door.
+         */
+        readonly equatable?: true;
+    };
+    /**
+     * Present only for a field declared via `blobFields` (#657) — out-of-band
+     * attachment storage (`collection.blob(id)`), never a sealed or plaintext
+     * record field. `queryable` mirrors the binding's fixed `ViaPosture`
+     * (blob content is never indexed — always `'none'`); the rest mirrors the
+     * declared `blobFields[field]` policy verbatim (scalars) or as a presence
+     * flag (predicate knobs — a predicate has no serializable form). Sourced
+     * from the `'blob'` binding's `describeFragment()`, the same
+     * `viaFragments` door the `lookup` block above is sourced from.
+     */
+    readonly blob?: {
+        readonly retainDays?: number;
+        readonly evictWhen?: true;
+        readonly legalHold?: true;
+        readonly retainUntil?: true;
+        readonly external?: true;
+        readonly public?: true;
+        readonly backlink?: string;
+        readonly queryable: 'none';
+    };
+    /**
+     * Present only for a graph-tainted derived field (#638 Task 3 — computed/
+     * derivation output whose effective posture was forced away from the
+     * plain baseline by a source's posture, e.g. a computed field reading a
+     * classified field). `forcedBy` names the immediate declared source
+     * field(s) responsible.
+     */
+    readonly taint?: {
+        readonly posture: ViaPosture;
+        readonly forcedBy: readonly string[];
+    };
+}
+export interface CollectionDescription {
+    readonly collection: string;
+    readonly fields: readonly DescribedField[];
+    /** Collection-level descriptive metadata; label falls back to the humanized collection name. */
+    readonly meta: CollectionMeta;
+}
+/** Options for the async describe(opts) overload. */
+export interface DescribeOptions {
+    /**
+     * When true, resolve dynamic-dict labels from vault.dictionary(name).list()
+     * and populate dict.values[].label for dynamic dictKey fields.
+     */
+    readonly resolveDictLabels?: boolean;
+}
+export interface ZodFieldSlot {
+    readonly type?: string;
+    readonly optional?: boolean;
+    readonly constraints?: Record<string, unknown>;
+    readonly meta?: Partial<FieldMeta>;
+}
+/**
+ * Derive per-field slots from a Standard Schema validator.
+ * - Calls `derivePersistedSchema` to get the JSON Schema.
+ * - Falls back to `{}` for non-Zod or unknown validators.
+ * - For zod-4 schemas: reads recognized `.meta()` keys from inline property annotations.
+ * - Returns: `Record<fieldKey, { type, optional, constraints?, meta? }>`.
+ *
+ * No static zod import — all zod access is lazy via derivePersistedSchema.
+ */
+export declare function deriveZodFields(schema: unknown): Promise<Record<string, ZodFieldSlot>>;
+export interface BuildDescriptionInput {
+    readonly collection: string;
+    readonly fieldMeta: Record<string, FieldMeta> | undefined;
+    /**
+     * Kernel-visible collections only carry the opaque {@link ViaDescriptor}
+     * marker (the kernel never inspects a Via feature's concrete descriptor
+     * shape). Every entry here is actually a {@link MoneyDescriptor} — only
+     * `money()` constructs them — narrowed locally below where its
+     * mode/currency/scale are read for the describe() output.
+     */
+    readonly moneyFields: Record<string, ViaDescriptor> | undefined;
+    readonly dictKeyFields: Record<string, DictKeyDescriptor | StaticDictDescriptor> | undefined;
+    /** Native lookup()/enumOf()/dict() fields (#650 Task 2) — declared only via `viaFields`/`via()`, no sugar key. */
+    readonly lookupFields?: Record<string, LookupDescriptor> | undefined;
+    readonly computed: ComputedFields | undefined;
+    readonly refs: Record<string, RefDescriptor>;
+    /** Async path fills this; sync path passes `undefined`. */
+    readonly zodFields: Record<string, ZodFieldSlot> | undefined;
+    /**
+     * Async path: when `resolveDictLabels` was true, this map holds
+     * `{ dictName -> { value -> label } }` for dynamic dictKey fields.
+     * Used to populate `dict.values[].label`.
+     */
+    readonly dictLabels?: Record<string, Record<string, string>> | undefined;
+    /** Collection-level descriptive metadata. Label falls back to humanized collection name. */
+    readonly meta?: CollectionMeta | undefined;
+    /**
+     * Map of field name → I18nTextDescriptor for fields declared with i18nText().
+     * When present, describe() surfaces an `i18n` block on matching DescribedField entries.
+     */
+    readonly i18nFields?: Record<string, I18nTextDescriptor> | undefined;
+    /** Per-field classified specs (already resolved/flattened). */
+    readonly classified?: Record<string, ClassifiedFieldSpec> | undefined;
+    /** Graph-computed taint overlay (#638 Task 3) — `Collection.via?.taint`. */
+    readonly taint?: {
+        readonly postures: ReadonlyMap<string, ViaPosture>;
+        readonly provenance?: ReadonlyMap<string, readonly string[]>;
+    } | undefined;
+    /**
+     * Per-binding `describeFragment()` output, keyed by binding brand (#650
+     * Task 7 — first-ever consumer of `ViaBinding.describeFragment`,
+     * `via/index.ts:136`). `Collection.describe()`/`describeAsync()` build this
+     * from `this.via?.describeFragments()`. The `'lookup'` brand's fragment
+     * feeds the `lookup` block below; `'blob'`'s feeds the `blob` block
+     * (#657, the second consumer). Other brands' fragments ride along unread
+     * until they gain a consumer too.
+     */
+    readonly viaFragments?: Record<string, Record<string, unknown>> | undefined;
+}
+export { FieldMetaUnknownFieldError };
+/**
+ * Pure assembler: no I/O, no side effects.
+ * Builds a {@link CollectionDescription} from the collection's in-memory config.
+ *
+ * When `zodFields` is supplied (async path), validates that every `fieldMeta` key
+ * refers to a known field (config ∪ zodFields). Throws `FieldMetaUnknownFieldError`
+ * on the first unknown key — this is the real validation that the vault.ts no-op
+ * couldn't do (schema fields weren't knowable synchronously).
+ */
+export declare function buildDescription(input: BuildDescriptionInput): CollectionDescription;

package/dist/with-shape/introspection/field-meta.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Consumer-neutral, data-relatable field descriptors — the canonical,
+ * validator-agnostic authoring channel. Merged by `collection.describe()`.
+ *
+ * Descriptive, never prescriptive: label/semanticType/unit/sensitivity/
+ * aggregate/aliases/displayFor only. Layout, styling, and active-locale
+ * selection stay app-side.
+ *
+ * @module
+ */
+/** Known semantic types; the union is open — unknown strings pass through. */
+export type SemanticType = 'date' | 'datetime' | 'email' | 'url' | 'currency' | 'percent' | 'country' | 'vat' | 'iban' | 'entity' | (string & {});
+export interface FieldMeta {
+    /** Human label for any displayable field. Required. */
+    label: string;
+    description?: string;
+    semanticType?: SemanticType;
+    /** Display unit, e.g. '€', '%', 'kg'. */
+    unit?: string;
+    /** Data classification driving redaction/inspector masking. */
+    sensitivity?: 'public' | 'pii' | 'secret';
+    /** Default aggregation for this field. */
+    aggregate?: 'sum' | 'count' | 'distinct' | 'none';
+    /** Canonical search synonyms (data vocabulary, not UI). */
+    aliases?: readonly string[];
+    /** Entity pairing: the field holding the human label for this id (buyerId → buyerName). */
+    displayFor?: string;
+    /**
+     * Override the widget hint derived from semanticType/type.
+     * e.g. 'textarea', 'date', 'money', 'select', 'checkbox', 'number', 'text'.
+     * When absent, the widget is derived automatically by buildDescription.
+     */
+    widget?: string;
+    /**
+     * Card/section grouping hint for detail & form layouts (e.g. 'Identity',
+     * 'Amounts'). Purely descriptive metadata — consumers group; describe()
+     * keeps emitting fields alphabetically.
+     */
+    group?: string;
+    /** Relative ordering hint within (and across) groups. Lower renders first. */
+    order?: number;
+}
+export declare class FieldMetaUnknownFieldError extends Error {
+    readonly collection: string;
+    readonly key: string;
+    constructor(collection: string, key: string);
+}
+/** Reject fieldMeta keys that are not known fields (typo guard), fail-loud. */
+export declare function validateFieldMetaKeys(collection: string, fieldMeta: Record<string, FieldMeta>, knownFields: ReadonlySet<string>): void;
+export interface MergeInputs {
+    channel?: FieldMeta;
+    zodMeta?: Partial<FieldMeta>;
+    inferred?: Partial<FieldMeta>;
+}
+export interface ResolvedMeta extends Partial<FieldMeta> {
+    label: string;
+}
+/** camelCase / snake_case → Title Case words. */
+export declare function humanizeFieldKey(key: string): string;
+/** Merge one field's metadata: channel > zodMeta > inferred; label always present. */
+export declare function resolveFieldMeta(key: string, inputs: MergeInputs): ResolvedMeta;

package/dist/with-shape/introspection/fields.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Map a JSON Schema (Draft 2020-12 produced by `zod-to-json-schema`) into
+ * the {@link FieldDescriptor} map consumed by {@link VaultSchemaSnapshot}.
+ *
+ * Used by both the persisted-schema path (decrypted envelope body) and the
+ * live-validator path (in-process derivation).
+ *
+ * @module
+ */
+import type { FieldDescriptor, FieldSource } from './types.js';
+export declare function jsonSchemaToFields(jsonSchema: unknown, source: FieldSource, refs?: Record<string, {
+    target: string;
+    mode: string;
+}>): Record<string, FieldDescriptor>;

package/dist/with-shape/introspection/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Introspection — `Vault.dumpSchema()` produces a structured
+ * {@link VaultSchemaSnapshot} describing the vault's shape and (optional)
+ * stats. Consumed by `noydb describe` for human-readable audit output.
+ *
+ * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md
+ *
+ * @module
+ */
+export type { VaultSchemaSnapshot, DumpSchemaOptions, CollectionDescriptor, CollectionConfig, CollectionStats, FieldDescriptor, FieldSource, MaterializedViewDescriptor, OverlayViewDescriptor, DerivationDescriptor, InternalCollectionStats, } from './types.js';
+export { dumpVaultSchema } from './walk.js';
+export { jsonSchemaToFields } from './fields.js';

package/dist/with-shape/introspection/json-schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `buildJsonSchema` — pure overlay that merges describe() metadata onto a
+ * base JSON Schema (from derivePersistedSchema) as `x-` extension keys.
+ *
+ * When no base JSON Schema is available (non-zod / unknown validator),
+ * builds a minimal `{ type:'object', properties }` from describe()'s field
+ * type tags. No static `import 'zod'` — validator derivation stays lazy.
+ *
+ * @module
+ */
+import type { CollectionDescription } from './describe.js';
+/** Overlay describe() metadata onto a base JSON Schema (or build a minimal one). */
+export declare function buildJsonSchema(desc: CollectionDescription, base?: Record<string, unknown> | null): object;

package/dist/with-shape/introspection/meta.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Descriptive metadata for the collection and vault levels of the metadata
+ * ladder (field level = FieldMeta). Identity, not structure: label /
+ * description / icon only. Descriptive, never prescriptive.
+ * @module
+ */
+/** A collection's own descriptive metadata. */
+export interface CollectionMeta {
+    /** Friendly name; falls back to the humanized collection name. */
+    label?: string;
+    description?: string;
+    /** Semantic icon NAME (e.g. a Lucide key), not styling. */
+    icon?: string;
+    /** Plural form for list headers ("Invoice" → "Invoices"). */
+    pluralLabel?: string;
+}
+/** A vault's own descriptive metadata. */
+export interface VaultMeta {
+    label?: string;
+    description?: string;
+    icon?: string;
+}

package/dist/with-shape/introspection/projection.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `applyListProjection` — the ONE vetted read-projection for lists/exports.
+ * Replaces classified field values with their declared projection (omit /
+ * mask / rider) so no consumer re-implements redaction. Pure, non-mutating.
+ * Consumed by as-* exporters (#489) and available to any list renderer.
+ * @module
+ */
+import type { CollectionDescription } from './describe.js';
+export interface ListProjectionOptions {
+    /** Also handle fields carrying only a plain sensitivity tag (pii/secret). */
+    readonly sensitivity?: 'omit' | 'mask';
+}
+export declare function applyListProjection(desc: CollectionDescription, record: Record<string, unknown>, opts?: ListProjectionOptions): Record<string, unknown>;