@camstack/types 1.2.379 → 1.2.381

package/dist/interfaces/addon-peer-bytes.d.ts

@@ -62,7 +62,7 @@
  * handle. A caller that minted an offer per frame would exhaust the outstanding
  * bound inside a second and be refused by name.
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { IncomingMessage } from 'node:http';
 import type { Readable } from 'node:stream';
 import { z } from 'zod';
 /**
@@ -145,7 +145,23 @@ export interface PeerBytesOfferOptions {
     readonly declaredBytes?: number;
     readonly ttlMs?: number;
 }
-export type PeerBytesHandler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+type PeerBytesResponseEvent = 'close' | 'drain' | 'data';
+/** Minimal `ServerResponse` surface peer-bytes producers write through. */
+export interface PeerBytesHandlerResponse {
+    readonly headersSent: boolean;
+    readonly writable: boolean;
+    readonly destroyed: boolean;
+    readonly writableEnded: boolean;
+    writeHead(statusCode: number, statusMessage?: string, headers?: Record<string, string>): this;
+    writeHead(statusCode: number, headers?: Record<string, string>): this;
+    write(chunk: Uint8Array | string): boolean;
+    end(cb?: () => void): this;
+    destroy(err?: Error): this;
+    on(event: PeerBytesResponseEvent, listener: (...args: readonly unknown[]) => void): this;
+    once(event: 'close' | 'drain', listener: () => void): this;
+    off(event: 'close' | 'drain', listener: () => void): this;
+}
+export type PeerBytesHandler = (req: IncomingMessage, res: PeerBytesHandlerResponse) => void | Promise<void>;
 /** A buffer the producer already holds, written out in bounded chunks. */
 export interface PeerBytesBufferOffer {
     readonly bytes: Buffer;
@@ -242,3 +258,4 @@ export interface AddonPeerBytes {
     offerFile(options: PeerBytesFileOffer): Promise<PeerBytesOfferResult>;
     open(ticket: PeerBytesTicket): Promise<PeerBytesOpenResult>;
 }
+export {};

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/config-ui.d.ts

@@ -1144,3 +1144,7 @@ export interface HydrateSchemaOptions {
     readonly inlineSecretsAsViews?: boolean;
 }
 export declare function hydrateSchema(schema: ConfigUISchema, values: Record<string, unknown>, options?: HydrateSchemaOptions): ConfigUISchemaWithValues;
+/** Strip inline `value` from a hydrated field for schema-only round-trips. */
+export declare function dehydrateConfigField(field: ConfigFieldWithValue): ConfigField;
+/** Inverse of {@link hydrateSchema} — drops resolved values from every leaf field. */
+export declare function dehydrateSchema(schema: ConfigUISchemaWithValues): ConfigUISchema;

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/node.d.ts

@@ -10,8 +10,8 @@ export type { Fmp4FragmentChildArgs, Fmp4FragmentChildDeps, } from './ffmpeg/fmp
 export { Fmp4FragmentChild } from './ffmpeg/fmp4-fragment-child.js';
 export type { Fmp4CloseReason, Fmp4Packet, Fmp4PrebufferOptions, Fmp4PrebufferStats, Fmp4SubscribeInput, Fmp4SubscriberInfo, Fmp4Subscription, } from './ffmpeg/fmp4-fragment-plane.js';
 export { Fmp4FragmentPlane } from './ffmpeg/fmp4-fragment-plane.js';
-export type { FfmpegExit, FfmpegExitClass, FfmpegProcessOptions } from './ffmpeg/process.js';
-export { FfmpegProcess } from './ffmpeg/process.js';
+export type { FfmpegExit, FfmpegExitClass, FfmpegProcessOptions, FfmpegSpawnFn, SpawnedFfmpegProcess, } from './ffmpeg/process.js';
+export { defaultFfmpegSpawn, FfmpegProcess } from './ffmpeg/process.js';
 export type { FfmpegArgvSpawn, PinnedFfmpegSpawnAnswer } from './ffmpeg/pinned-spawn.js';
 export { NO_PINNED_FFMPEG_DETAIL, pinnedFfmpegSpawner, resolvePinnedFfmpegSpawner, } from './ffmpeg/pinned-spawn.js';
 export type { ChildCostClaimHandle, ChildCostClaimInput, ProcStatReader, } from './process/child-cost-registry.js';

package/dist/node.js

@@ -1410,6 +1410,9 @@ var Fmp4FragmentPlane = class {
 * that also owned the bytes would need a mode per consumer, which is the same
 * mistake as one builder per consumer.
 */
+function defaultFfmpegSpawn(command, args, options) {
+	return (0, node_child_process.spawn)(command, args, options ?? {});
+}
 var DEFAULT_FIRST_DATA_TIMEOUT_MS = 8e3;
 var DEFAULT_RESTART_DELAY_MS = 1e3;
 var DEFAULT_STABLE_RUN_MS = 3e4;
@@ -2285,6 +2288,7 @@ exports.canonicalDeviceFingerprint = canonicalDeviceFingerprint;
 exports.canonicalHash = require_composition.canonicalHash;
 exports.containsOrEquals = containsOrEquals;
 exports.customizationBlockName = customizationBlockName;
+exports.defaultFfmpegSpawn = defaultFfmpegSpawn;
 exports.diffExportTargets = diffExportTargets;
 exports.downloadBinary = downloadBinary;
 exports.ensureBinary = ensureBinary;

package/dist/node.mjs

@@ -1387,6 +1387,9 @@ var Fmp4FragmentPlane = class {
 * that also owned the bytes would need a mode per consumer, which is the same
 * mistake as one builder per consumer.
 */
+function defaultFfmpegSpawn(command, args, options) {
+	return spawn(command, args, options ?? {});
+}
 var DEFAULT_FIRST_DATA_TIMEOUT_MS = 8e3;
 var DEFAULT_RESTART_DELAY_MS = 1e3;
 var DEFAULT_STABLE_RUN_MS = 3e4;
@@ -2247,4 +2250,4 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
-export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, NO_PINNED_FFMPEG_DETAIL, OwnerOnlyError, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, customizationBlockName, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, icaclsArgs, installPythonPackages, installPythonRequirements, mkdirOwnerOnlySync, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, pinnedFfmpegSpawner, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, resolvePinnedFfmpegSpawner, restrictDirToOwnerSync, restrictFileToOwnerSync, signExpiringUrl, verifyExpiringUrl, writeFileAtomic, writeOwnerOnlyFileSync };
+export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, NO_PINNED_FFMPEG_DETAIL, OwnerOnlyError, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, customizationBlockName, defaultFfmpegSpawn, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, icaclsArgs, installPythonPackages, installPythonRequirements, mkdirOwnerOnlySync, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, pinnedFfmpegSpawner, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, resolvePinnedFfmpegSpawner, restrictDirToOwnerSync, restrictFileToOwnerSync, signExpiringUrl, verifyExpiringUrl, writeFileAtomic, writeOwnerOnlyFileSync };

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/in-memory-records.d.ts

@@ -0,0 +1,21 @@
+import { type RecordsAccess } from './records-access.js';
+interface StoredRow {
+    readonly id: string;
+    readonly at: number | null;
+    readonly rev: number;
+    readonly updatedAt: number;
+    readonly data: Record<string, unknown>;
+}
+export interface InMemoryRecords {
+    readonly records: RecordsAccess;
+    readonly tables: ReadonlyMap<string, ReadonlyMap<string, StoredRow>>;
+    seed(kind: string, row: {
+        id: string;
+        at?: number;
+        data: Record<string, unknown>;
+    }): void;
+    failWrites(on: boolean): void;
+    failReads(on: boolean): void;
+}
+export declare function makeInMemoryRecords(owner?: string): InMemoryRecords;
+export {};

package/dist/records/index.d.ts

@@ -0,0 +1,9 @@
+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';
+export * from './settings-brokers-adopts-from.js';
+export * from './settings-array-adopts-from.js';
+export { makeInMemoryRecords, type InMemoryRecords } from './in-memory-records.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>>;