@camstack/types 1.2.378 → 1.2.380

package/dist/interfaces/addon.d.ts

@@ -5,6 +5,7 @@ import type { PipelineSlot } from '../types/pipeline.js';
 import type { AddonDataPlane } from './addon-data-plane.js';
 import type { AddonPeerBytes } from './addon-peer-bytes.js';
 import type { SecretsAccess } from '../keychain/secrets-access.js';
+import type { RecordsAccess } from '../records/records-access.js';
 import type { CapabilityDeclaration } from './capability.js';
 import type { ConfigUISchemaWithValues, FieldProbeResult } from './config-ui.js';
 import type { IEventBus, ReadinessScope } from './event-bus.js';
@@ -733,6 +734,18 @@ export interface AddonContext<TConfig = Record<string, unknown>> {
      * kernel that predates the keychain.
      */
     readonly secrets?: SecretsAccess;
+    /**
+     * This addon's record kinds (D881): its own facts and documents - ledgers,
+     * audit rows, config documents, mirrors - read by key, by device, by device
+     * and time. The owner is the addon's own id, closed over by the kernel; a kind
+     * is readable and writable by its owner only. A field marked
+     * `.meta({ secret: true })` in a kind's schema is kept in the keychain
+     * automatically. See `docs/architecture/records.md`.
+     *
+     * Absent when the addon is loaded in isolation (tests, tooling) or on a
+     * kernel that predates records.
+     */
+    readonly records?: RecordsAccess;
     /**
      * Runtime accessor for the capability registry — exposed to addons that
      * need to enumerate peers of a collection cap (e.g. `turn-provider`) or

package/dist/interfaces/event-bus.d.ts

@@ -751,8 +751,21 @@ export interface TopologyNode {
  *  - `resumed`          — demand returned and the dial came back. The matching
  *    end of a `suspended`, and equally deliberate.
  *  - `broker-destroyed` — the stream was unpublished/released. Deliberate.
+ *
+ * A BATTERY camera sleeping is none of these: a sleep or a plain wake emits no
+ * `stream.offline` / `stream.online` at all (D883). It reaches an outage only
+ * through the three battery reasons below, each naming a real failure:
+ *
+ *  - `wake-timeout`       — a wake was DEMANDED (live viewer, recording,
+ *    explicit force) and no stream arrived inside its bound.
+ *  - `connection-error`   — the camera is reported awake and its stream is
+ *    gone.
+ *  - `battery-unreachable` — nothing heard from the camera past its battery
+ *    refresh window (`BATTERY_UNREACHABLE_AFTER_MS`, D847).
+ *
+ * Their `stream.online` is `recovered`, exactly as for `stale-timeout`.
  */
-export type StreamHealthReason = 'stale-timeout' | 'recovered' | 'first-packet' | 'suspended' | 'resumed' | 'broker-destroyed';
+export type StreamHealthReason = 'stale-timeout' | 'wake-timeout' | 'connection-error' | 'battery-unreachable' | 'recovered' | 'first-packet' | 'suspended' | 'resumed' | 'broker-destroyed';
 /** All known event categories with their typed payloads */
 /**
  * `keychain.changed` — a value was put or deleted. Never carries the value.
@@ -1556,21 +1569,37 @@ export interface EventCatalog {
      */
     'stream.online': {
         readonly deviceId: number;
-        readonly camStreamId: string;
+        /** Absent when a failed wake names no published stream (a sleeping camera after a restart). */
+        readonly camStreamId?: string;
         readonly profile: CamProfile | null;
         readonly brokerId: string;
         readonly sourceType: string;
         readonly lastPacketAt: number;
         readonly reason?: StreamHealthReason;
+        /**
+         * Every stream of the device this one transition covers. An outage and its
+         * recovery are DEVICE transitions (D883): main and sub dropping together is
+         * ONE event whose `camStreamId` / `profile` name the first and this list
+         * names them all. Absent on per-broker lazy-dial telemetry.
+         */
+        readonly camStreamIds?: readonly string[];
     };
     'stream.offline': {
         readonly deviceId: number;
-        readonly camStreamId: string;
+        /** Absent when a failed wake names no published stream (a sleeping camera after a restart). */
+        readonly camStreamId?: string;
         readonly profile: CamProfile | null;
         readonly brokerId: string;
         readonly sourceType: string;
         readonly lastPacketAt: number;
         readonly reason?: StreamHealthReason;
+        /**
+         * Every stream of the device this one transition covers. An outage and its
+         * recovery are DEVICE transitions (D883): main and sub dropping together is
+         * ONE event whose `camStreamId` / `profile` name the first and this list
+         * names them all. Absent on per-broker lazy-dial telemetry.
+         */
+        readonly camStreamIds?: readonly string[];
     };
     'retention.cleanup': {
         readonly deletedEvents?: number;

package/dist/interfaces/storage.d.ts

@@ -49,7 +49,7 @@ export interface IStorageProvider {
  * All named collections that the settings backend manages.
  * Each collection maps to a logical table/bucket in the backend.
  */
-export type SettingsCollection = 'system-settings' | 'addon-settings' | 'provider-settings' | 'device-settings' | 'detection-events' | 'audio-levels' | 'track-trails' | 'recording-segments' | 'recording-thumbnails' | 'recording-policies' | 'recording-storage-config' | 'recording-cleanup-queue' | 'known-faces' | (string & {});
+export type SettingsCollection = 'system-settings' | 'addon-settings' | 'detection-events' | 'audio-levels' | 'track-trails' | 'recording-segments' | 'recording-thumbnails' | 'recording-policies' | 'recording-storage-config' | 'recording-cleanup-queue' | 'known-faces' | (string & {});
 export interface SettingsGetInput {
     readonly namespace?: string;
     readonly collection: SettingsCollection;

package/dist/records/constants.d.ts

@@ -0,0 +1,23 @@
+/** Limits and names of `ctx.records` (D881). One authority; the engine and the facade read it. */
+/** The files a kind may live in. `history` is device-history's (D850), never records. */
+export declare const RECORD_DATABASES: readonly ['settings', 'events'];
+export type RecordDatabase = (typeof RECORD_DATABASES)[number];
+/** The classes of a kind: the `@durable` vocabulary, one authority (replaces the annotation). */
+export declare const RECORD_CLASSES: readonly ['config', 'ledger', 'audit', 'mirror', 'ephemeral'];
+export type RecordClass = (typeof RECORD_CLASSES)[number];
+export declare const RECORD_DEFAULT_MAX_DATA_BYTES: number;
+export declare const RECORD_MAX_DATA_BYTES: number;
+export declare const RECORD_ID_MAX_LENGTH = 256;
+export declare const RECORD_BATCH_MAX = 1000;
+export declare const RECORD_BATCH_MAX_BYTES: number;
+export declare const RECORD_QUERY_MAX = 1000;
+/** Rows one DELETE statement removes before the serving thread yields. */
+export declare const RECORD_DELETE_BATCH = 5000;
+/** A kind in the `settings` file may not bound itself above this (D447: high volume is `events`). */
+export declare const RECORD_SETTINGS_MAX_ROWS = 50000;
+export declare const RECORD_MAX_INDEXES = 8;
+export declare const RECORD_MAX_INDEX_FIELDS = 4;
+/** The engine's TTL sweep cadence. */
+export declare const RECORD_SWEEP_INTERVAL_MS: number;
+/** The `Column`-free proof prefix: a ref collection for a kind's secret fields. */
+export declare const RECORD_SECRET_COLLECTION_PREFIX = "records:";

package/dist/records/entry-kind.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Entry kinds (D881): every list of user-created entries (notification
+ * targets, brokers, LLM profiles) is ONE record kind with an id, a name and a
+ * kind-specific body, and the admin UI lists/adds/edits/deletes all of them
+ * through the `record-entries` capability with password fields derived from
+ * the schema (`.meta({ secret: true })`).
+ */
+import { z } from 'zod';
+import type { RecordIndex, DefinedRecordKind } from './record-kind.js';
+/** What an entry kind adds to a bare record kind. */
+export interface EntryKindSpec<S extends z.ZodType> {
+    /** The title the entries UI shows for the list. */
+    readonly title: string;
+    /** The body: a `name` field plus the kind's own. A discriminated union is fine. */
+    readonly schema: S;
+    readonly writeTrigger?: string;
+    readonly nameField?: string;
+    readonly database?: 'settings' | 'events';
+    readonly indexes?: readonly RecordIndex[];
+    readonly secretArrayKeys?: Readonly<Record<string, string>>;
+    readonly adoptsFrom?: string;
+}
+/** The body of a plain entry: a name and the fields the kind adds. */
+export declare function entryBody<Shape extends z.ZodRawShape>(shape: Shape): z.ZodObject<{
+    name: z.ZodString;
+} & Shape extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strip>;
+/**
+ * Declare one entry kind. An entry is configuration: never trimmed by the
+ * engine, never aged, belonging to no device.
+ */
+export declare function defineEntryKind<S extends z.ZodType>(name: string, spec: EntryKindSpec<S>): DefinedRecordKind<S>;

package/dist/records/errors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The named failures of `ctx.records` (D881).
+ *
+ * A records call crosses a worker thread, a UDS channel and a tRPC router, and
+ * an error class does not survive any of them - only its message does. So
+ * every message STARTS with a stable code, `records/<code>: <detail>`, and
+ * {@link recordsErrorFromMessage} rebuilds the typed class on the caller's side.
+ * A failed read is never `[]` or `undefined`: it throws one of these.
+ */
+/** Every code a records failure carries. */
+export declare const RECORDS_ERROR_CODES: readonly ['rev-conflict', 'too-large', 'unindexed-filter', 'filter-required', 'unknown-kind', 'not-found', 'unique-violation', 'plaintext-secret', 'foreign-marker', 'secret-unavailable', 'invalid-record', 'declaration-refused', 'adoption-pending', 'no-caller', 'batch-too-large'];
+export type RecordsErrorCode = (typeof RECORDS_ERROR_CODES)[number];
+/** The base of every records failure. `detail` is the human part of the message. */
+export declare class RecordsError extends Error {
+    readonly code: RecordsErrorCode;
+    readonly detail: string;
+    constructor(code: RecordsErrorCode, detail: string);
+}
+/** A write guarded by `ifRev` found another revision (or an existing row for `ifRev: 0`). */
+export declare class RevConflictError extends RecordsError {
+    constructor(detail: string);
+}
+/** `data` exceeds the kind's `maxDataBytes`. Bytes are never record fields (D613). */
+export declare class RecordTooLargeError extends RecordsError {
+    constructor(detail: string);
+}
+/** A filter, order or aggregate names a field no declared index serves. */
+export declare class UnindexedFilterError extends RecordsError {
+    constructor(detail: string);
+}
+/** A bulk delete with no predicate at all. */
+export declare class FilterRequiredError extends RecordsError {
+    constructor(detail: string);
+}
+/** The caller declared no such kind (another addon's kind is indistinguishable from none). */
+export declare class UnknownRecordKindError extends RecordsError {
+    constructor(detail: string);
+}
+export declare class RecordNotFoundError extends RecordsError {
+    constructor(detail: string);
+}
+/** A unique index refused the write. */
+export declare class RecordUniqueViolationError extends RecordsError {
+    constructor(detail: string);
+}
+/** A secret field held a plain string where only a keychain marker may be stored. */
+export declare class PlaintextSecretError extends RecordsError {
+    constructor(detail: string);
+}
+/** A marker whose ref is not the row's own (the D878 rule). */
+export declare class ForeignSecretMarkerError extends RecordsError {
+    constructor(detail: string);
+}
+/** The keychain could not store or serve a value: explicit, never an empty string. */
+export declare class RecordSecretUnavailableError extends RecordsError {
+    constructor(detail: string);
+}
+export declare class InvalidRecordError extends RecordsError {
+    constructor(detail: string);
+}
+/** A kind declaration the engine refuses (non-additive change, bad shape, wrong file). */
+export declare class DeclarationRefusedError extends RecordsError {
+    constructor(detail: string);
+}
+/** A kind is empty while the legacy table it adopts from still holds rows. */
+export declare class AdoptionPendingError extends RecordsError {
+    constructor(detail: string);
+}
+export declare class NoCallerError extends RecordsError {
+    constructor(detail: string);
+}
+export declare class BatchTooLargeError extends RecordsError {
+    constructor(detail: string);
+}
+/**
+ * Rebuild the typed error from a message that crossed a wire; `null` when the
+ * message is not a records failure.
+ */
+export declare function recordsErrorFromMessage(message: string): RecordsError | null;
+/** The records failure inside any thrown value (a wrapped tRPC error included), or the value. */
+export declare function asRecordsError(err: unknown): unknown;

package/dist/records/index.d.ts

@@ -0,0 +1,6 @@
+export * from './constants.js';
+export * from './errors.js';
+export * from './record-kind.js';
+export * from './secret-paths.js';
+export * from './records-access.js';
+export * from './entry-kind.js';

package/dist/records/record-kind.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Record kinds (D881): the declaration an addon makes of one kind of fact, the
+ * Zod row schema that describes it, and the helper that turns the two into the
+ * JSON the engine stores.
+ *
+ * A kind is declared ONCE, next to the code that owns it, and the engine's
+ * reconciler creates its indexes - nothing creates DDL at runtime from a write.
+ * Everything the generic machinery needs (secret fields, the entry descriptor)
+ * is DERIVED from the Zod schema: `.meta({ secret: true })` marks a credential,
+ * never a field name (D879).
+ */
+import { z } from 'zod';
+import { RECORD_CLASSES, RECORD_DATABASES } from './constants.js';
+/** A JSON field path: `trackId`, `auth.accessToken`. Charset-restricted: it is rendered into DDL. */
+export declare const RecordFieldPathSchema: z.ZodString;
+export declare const RecordIndexSchema: z.ZodObject<{
+    name: z.ZodString;
+    fields: z.ZodArray<z.ZodString>;
+    unique: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type RecordIndex = z.infer<typeof RecordIndexSchema>;
+export declare const RecordRetentionSchema: z.ZodUnion<readonly [z.ZodObject<{
+    ttlMs: z.ZodNumber;
+    from: z.ZodEnum<{
+        at: "at";
+        write: "write";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    maxRows: z.ZodOptional<z.ZodNumber>;
+    maxRowsPerDevice: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    owner: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    none: z.ZodString;
+}, z.core.$strict>]>;
+export type RecordRetention = z.infer<typeof RecordRetentionSchema>;
+/** The descriptor a generic entries UI reads (D881 "generic entries"). */
+export declare const EntryDescriptorSchema: z.ZodObject<{
+    title: z.ZodString;
+    nameField: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type EntryDescriptor = z.infer<typeof EntryDescriptorSchema>;
+/** What crosses the wire and sits in the engine's catalog: JSON only, no Zod. */
+export declare const RecordKindDeclarationSchema: z.ZodObject<{
+    database: z.ZodDefault<z.ZodEnum<{
+        events: "events";
+        settings: "settings";
+    }>>;
+    class: z.ZodEnum<{
+        audit: "audit";
+        config: "config";
+        ephemeral: "ephemeral";
+        ledger: "ledger";
+        mirror: "mirror";
+    }>;
+    writeTrigger: z.ZodString;
+    device: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        optional: "optional";
+        required: "required";
+    }>>;
+    at: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        required: "required";
+    }>>;
+    indexes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        fields: z.ZodArray<z.ZodString>;
+        unique: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    retention: z.ZodUnion<readonly [z.ZodObject<{
+        ttlMs: z.ZodNumber;
+        from: z.ZodEnum<{
+            at: "at";
+            write: "write";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        maxRows: z.ZodOptional<z.ZodNumber>;
+        maxRowsPerDevice: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        owner: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        none: z.ZodString;
+    }, z.core.$strict>]>;
+    deviceRemoval: z.ZodDefault<z.ZodEnum<{
+        delete: "delete";
+        none: "none";
+    }>>;
+    maxDataBytes: z.ZodDefault<z.ZodNumber>;
+    secretPaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    secretArrayKeys: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    adoptsFrom: z.ZodOptional<z.ZodString>;
+    transactFamily: z.ZodOptional<z.ZodString>;
+    entry: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        nameField: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RecordKindDeclaration = z.infer<typeof RecordKindDeclarationSchema>;
+/** The kind names: lower-case, dash separated, short enough for an index name. */
+export declare const RecordKindNameSchema: z.ZodString;
+/** Cross-field rules a declaration must satisfy. Throws {@link DeclarationRefusedError}. */
+export declare function assertValidDeclaration(name: string, decl: RecordKindDeclaration): void;
+/** The input of {@link defineRecordKinds} for one kind. */
+export interface RecordKindSpec<S extends z.ZodType = z.ZodType> {
+    readonly schema: S;
+    readonly database?: (typeof RECORD_DATABASES)[number];
+    readonly class: (typeof RECORD_CLASSES)[number];
+    readonly writeTrigger: string;
+    readonly device?: 'required' | 'optional' | 'none';
+    readonly at?: 'required' | 'none';
+    readonly indexes?: readonly RecordIndex[];
+    readonly retention: RecordRetention;
+    readonly deviceRemoval?: 'delete' | 'none';
+    readonly maxDataBytes?: number;
+    readonly secretArrayKeys?: Readonly<Record<string, string>>;
+    readonly adoptsFrom?: string;
+    readonly transactFamily?: string;
+    /** Makes this an ENTRY kind: it gets the generic list/add/edit/delete UI. */
+    readonly entry?: {
+        readonly title: string;
+        readonly nameField?: string;
+    };
+}
+/** A declared kind: its name, the row schema and the JSON the engine stores. */
+export interface DefinedRecordKind<S extends z.ZodType = z.ZodType> {
+    readonly name: string;
+    readonly schema: S;
+    readonly declaration: RecordKindDeclaration;
+}
+/**
+ * Declare the kinds of a package. The keys are the kind names. The result is
+ * what `ctx.records.declare` sends to the engine and what `ctx.records.kind`
+ * types its handle from.
+ */
+export declare function defineRecordKinds<const T extends Readonly<Record<string, RecordKindSpec>>>(specs: T): {
+    readonly [K in keyof T & string]: DefinedRecordKind<T[K]['schema']>;
+};
+/** The wire form of a package's kinds: name -> declaration. */
+export declare function declarationsOf(kinds: Readonly<Record<string, DefinedRecordKind>>): Readonly<Record<string, RecordKindDeclaration>>;

package/dist/records/records-access.d.ts

@@ -0,0 +1,153 @@
+/**
+ * `ctx.records` - an addon's handle on its OWN record kinds (D881).
+ *
+ * The owner is closed over at construction (the addon id) and the transport
+ * decides how it is proven: a hub in-process caller states it, a forked or
+ * agent addon sends the bare input and the parent stamps who is calling - the
+ * `ctx.secrets` model. Nothing a caller passes can change it.
+ *
+ * ## Secrets are a feature of the kind
+ *
+ * A field of the kind's Zod schema marked `.meta({ secret: true })` is stored
+ * as a keychain MARKER bound to the row's own ref and never as a value:
+ *
+ *  - **write**: a non-empty string goes to the keychain FIRST, then the row is
+ *    written holding the marker. The redaction token (or an empty/absent
+ *    value on a `patch`) keeps what is stored; `put` is a full replace, so a
+ *    secret field it omits is removed - and so is its keychain value. A locked
+ *    keychain refuses the whole write (`records/secret-unavailable`):
+ *    plaintext is never stored, never logged, never in an error message.
+ *  - **read**: every read shows the redaction token for a set secret. The
+ *    owner that needs the value asks for it (`getResolved`, `query` with
+ *    `resolveSecrets`); the keychain answering `unavailable` or `missing`
+ *    THROWS - a locked keychain is never read as an empty password.
+ *  - **delete**: the keychain values of the removed rows go with them.
+ */
+import type { z } from 'zod';
+import type { DeclareKindResult, IRecordsProvider, RecordQueryInput, RecordWhere } from '../capabilities/records.cap.js';
+import type { SecretsAccess } from '../keychain/secrets-access.js';
+import { type DefinedRecordKind } from './record-kind.js';
+import { collectSecretLeaves } from './secret-paths.js';
+/** The wire: the `records` provider's methods. The owner is never an argument. */
+export type RecordsTransport = IRecordsProvider;
+/** A row as the owner sees it. Secret fields hold the redaction token unless resolved. */
+export interface RecordRow<T> {
+    readonly id: string;
+    readonly deviceId: number | null;
+    readonly at: number | null;
+    readonly expiresAt: number | null;
+    readonly rev: number;
+    readonly updatedAt: number;
+    readonly data: T;
+}
+export interface RecordPut<T> {
+    readonly id: string;
+    readonly deviceId?: number;
+    readonly at?: number;
+    readonly expiresAt?: number;
+    readonly data: T;
+}
+export interface RecordsLogger {
+    warn(message: string, extras?: {
+        readonly meta?: Record<string, unknown>;
+    }): void;
+}
+export interface RecordsAccessOptions {
+    readonly owner: string;
+    readonly transport: RecordsTransport;
+    /** The owner's keychain handle; `null` where there is none (a kind with secrets then refuses). */
+    readonly secrets: SecretsAccess | null;
+    readonly logger?: RecordsLogger;
+    /** Builds the transport for another owner - in-process system builtins only. */
+    readonly transportForOwner?: (owner: string) => RecordsTransport;
+}
+export interface RecordQueryOptions {
+    /** Resolve the secret fields of the page in ONE keychain call. A failure throws. */
+    readonly resolveSecrets?: boolean;
+}
+export interface RecordKindHandle<T> {
+    readonly name: string;
+    get(id: string): Promise<RecordRow<T> | null>;
+    getMany(ids: readonly string[]): Promise<readonly RecordRow<T>[]>;
+    /** `get` with the secret fields resolved from the keychain. */
+    getResolved(id: string): Promise<RecordRow<T> | null>;
+    put(input: RecordPut<T>, opts?: {
+        readonly ifRev?: number;
+    }): Promise<{
+        readonly rev: number;
+    }>;
+    putMany(inputs: readonly RecordPut<T>[]): Promise<{
+        readonly count: number;
+    }>;
+    /** RFC 7396 merge in one statement. `null` removes a field. */
+    patch(id: string, partial: Readonly<Record<string, unknown>>, opts?: {
+        readonly ifRev?: number;
+        readonly at?: number | null;
+        readonly expiresAt?: number | null;
+    }): Promise<{
+        readonly rev: number;
+    }>;
+    delete(id: string): Promise<boolean>;
+    deleteMany(ids: readonly string[]): Promise<number>;
+    query(q: Omit<RecordQueryInput, 'kind' | 'limit'> & {
+        readonly limit?: number;
+    }, opts?: RecordQueryOptions): Promise<{
+        readonly records: readonly RecordRow<T>[];
+        readonly nextCursor: string | null;
+    }>;
+    count(q: {
+        readonly deviceId?: number;
+        readonly atFrom?: number;
+        readonly atTo?: number;
+        readonly where?: RecordWhere;
+    }): Promise<number>;
+    histogram(q: {
+        readonly deviceId?: number;
+        readonly from: number;
+        readonly to: number;
+        readonly bucketMs: number;
+    }): Promise<readonly {
+        readonly bucketStart: number;
+        readonly count: number;
+    }[]>;
+    aggregate(q: {
+        readonly op: 'sum' | 'min' | 'max' | 'count';
+        readonly field?: string;
+        readonly groupBy?: string;
+        readonly where?: RecordWhere;
+    }): Promise<readonly {
+        readonly group: string | number | null;
+        readonly value: number | null;
+    }[]>;
+    deleteWhere(q: {
+        readonly deviceId?: number;
+        readonly atBefore?: number;
+        readonly where?: RecordWhere;
+    }): Promise<number>;
+    allocateId(): Promise<number>;
+}
+export interface RecordsAccess {
+    readonly owner: string;
+    /**
+     * Reconcile this addon's kinds (the engine creates the indexes; additive
+     * only). THROWS {@link AdoptionPendingError} while a kind is empty and the
+     * legacy table it adopts from still holds rows - the boot guard (D853: no
+     * migration code in the product).
+     */
+    declare(kinds: Readonly<Record<string, DefinedRecordKind>>): Promise<Readonly<Record<string, DeclareKindResult>>>;
+    kind<S extends z.ZodType>(definition: DefinedRecordKind<S>): RecordKindHandle<z.infer<S>>;
+    /**
+     * In-process SYSTEM builtins only (the entries service): act as the door of
+     * another owner. `null` everywhere else - a forked addon has no way to state
+     * an identity the transport would accept.
+     */
+    readonly forOwner: ((owner: string) => RecordsAccess) | null;
+    /** The D865 hook body: delete the device's rows from every kind declared `deviceRemoval: 'delete'`. */
+    deleteDevice(deviceId: number, opts?: {
+        readonly kinds?: readonly string[];
+    }): Promise<Readonly<Record<string, number>>>;
+}
+/** Build the owner's records handle. */
+export declare function createRecordsAccess(options: RecordsAccessOptions): RecordsAccess;
+/** Re-exported so adoption tooling builds the same concrete paths the facade does. */
+export { collectSecretLeaves };

package/dist/records/secret-paths.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Secret fields of a record, addressed the way a Zod schema declares them
+ * (`collectZodSecretPaths`): dotted keys, `[]` for "each element of this array"
+ * (`auth.accessToken`, `headers[].value`).
+ *
+ * Array elements are matched by a DECLARED id key (`secretArrayKeys`:
+ * `{ headers: 'name' }`), never by index, so reordering a list keeps every
+ * keychain ref (the same rule as `arrayItemFieldPath`). The concrete path of a
+ * leaf names its element: `headers[X-Api].value`.
+ *
+ * Pure and browser-safe. Nothing here mutates: every transform returns a new value.
+ */
+import { arrayItemFieldPath } from '../keychain/secret-ref.js';
+/** One segment of a declared path. */
+export interface SecretPathSegment {
+    readonly key: string;
+    /** `true` when the key holds an array and the path continues into each element. */
+    readonly each: boolean;
+}
+/** The array prefixes (declared form, e.g. `headers` or `a.headers`) of a path. */
+export declare function parseSecretPath(path: string): readonly SecretPathSegment[];
+/** The declared array prefixes of `path` that need an id key (`headers`, `a.rows`). */
+export declare function secretArrayPrefixes(path: string): readonly string[];
+/** One secret leaf found in a record body. */
+export interface SecretLeaf {
+    /** The declared path it matched (`headers[].value`). */
+    readonly declared: string;
+    /** Its concrete path, naming array elements by id (`headers[X-Api].value`). */
+    readonly concrete: string;
+    readonly value: unknown;
+}
+/**
+ * Visit every secret leaf PRESENT in `data` (an absent branch has nothing to
+ * visit). `replace` returns the new leaf value, or {@link REMOVE_LEAF}; the
+ * result is a new body, `data` is untouched.
+ */
+export declare const REMOVE_LEAF: unique symbol;
+export type LeafReplacement = unknown | typeof REMOVE_LEAF;
+/** Replace/remove every present secret leaf; returns a NEW body. */
+export declare function mapSecretLeaves(data: unknown, paths: readonly string[], arrayKeys: Readonly<Record<string, string>>, visit: (leaf: SecretLeaf) => LeafReplacement): unknown;
+/** Every present secret leaf, read-only. */
+export declare function collectSecretLeaves(data: unknown, paths: readonly string[], arrayKeys: Readonly<Record<string, string>>): readonly SecretLeaf[];
+/**
+ * The keychain collection name a kind's secrets live under. Prefixed so a
+ * record's refs never collide with the refs a legacy collection of the same name
+ * already holds during an adoption.
+ */
+export declare function recordSecretCollection(kind: string): string;
+/** The ONE ref a row's secret field may carry: the engine and the facade both build it here. */
+export declare function recordSecretRef(owner: string, kind: string, rowId: string, concretePath: string): string;
+/** A concrete path built from a flat array item, re-exported for adoption tooling. */
+export declare const recordArrayItemPath: typeof arrayItemFieldPath;