@camstack/types 1.2.397 → 1.2.398

package/dist/interfaces/auth.d.ts

@@ -1,4 +1,4 @@
-export { type UserRecord, type ApiKeyRecord, type TokenScope } from '../schemas/auth-records.js';
+export { type UserRecord, type TokenScope } from '../schemas/auth-records.js';
 import type { TokenScope } from '../schemas/auth-records.js';
 export interface UserPermissions {
     isAdmin: boolean;

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

@@ -484,6 +484,15 @@ export interface StorageLocationsChangedPayload {
  * when a camera is assigned to or unassigned from an agent runner. Used by
  * the UI / metrics dashboard. No frame data.
  */
+export type PipelineMotionNoisePayload = {
+    readonly deviceId: number;
+    /** The rolling window the figures are over, in ms. */
+    readonly windowMs: number;
+    /** Share of the window with a detection session open, whole percent. */
+    readonly dutyPct: number;
+    /** Sessions opened in the window. */
+    readonly sessions: number;
+};
 export interface PipelineCameraAssignmentPayload {
     readonly deviceId: number;
     readonly agentNodeId: string;
@@ -1270,15 +1279,25 @@ export interface EventCatalog {
         /** The enabled device keys the live probe did not report. */
         readonly unavailableDeviceKeys: readonly string[];
     };
-    /** A camera with an open detection session that has detected nothing for
-     *  longer than the blind threshold. */
+    /** A camera that MOVED (enough session time over enough sessions), was
+     *  analysed, and whose detector produced no raw output at all (D907). */
     'pipeline.detection-blind': {
         readonly deviceId: number;
-        /** How long it has been blind, in ms. */
+        /** Wall time since its last detection, in ms — context, not the gate. */
         readonly blindForMs: number;
-        /** The threshold that was crossed, in ms. */
+        /** The motion bar that was crossed, in ms. */
         readonly thresholdMs: number;
-    };
+        /** Session-open time since the detector last produced anything, in ms. */
+        readonly motionMs: number;
+        /** Sessions opened in that time. */
+        readonly sessions: number;
+        /** Frames since the last detection where candidates fell under the floor. */
+        readonly belowFloor: number;
+    };
+    /** A camera whose motion has been constant with no detection (D907). */
+    'pipeline.motion-noisy': PipelineMotionNoisePayload;
+    /** The camera's motion fell back, or a detection arrived (D907). */
+    'pipeline.motion-calm': PipelineMotionNoisePayload;
     /** Per-camera pipeline config changed — orchestrator hot-reloads the assigned runner. */
     'pipeline.camera-updated': {
         readonly deviceId: number;

package/dist/notification/alert-episode.d.ts

@@ -59,4 +59,11 @@ export declare function alertNodeId(alert: Pick<Alert, 'source' | 'metadata'>):
  * (an `error` episode announces its opening only).
  */
 export declare function alertEpisodeKind(severity: AlertSeverity, phase: AlertEpisodePhase): NcSystemEventKind | null;
+/**
+ * The kind of a CRITICAL episode edge about a DEVICE (D911): the alert's source
+ * is `device`, so it is announced in the devices family as
+ * `device-attention-required` / `-resolved` INSTEAD of `alert-critical`. One
+ * alert notifies once, through one family. `null` for any other severity.
+ */
+export declare function deviceAttentionKind(severity: AlertSeverity, phase: AlertEpisodePhase): NcSystemEventKind | null;
 export declare function alertEpisodePayload(alert: Alert, phase: AlertEpisodePhase, at: number): AlertEpisodePayload;

package/dist/records/errors.d.ts

@@ -8,7 +8,7 @@
  * 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', 'no-caller', 'batch-too-large'];
+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', 'no-caller', 'batch-too-large', 'transact-refused'];
 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 {
@@ -68,6 +68,14 @@ export declare class NoCallerError extends RecordsError {
 export declare class BatchTooLargeError extends RecordsError {
     constructor(detail: string);
 }
+/**
+ * A `transact` the engine refuses before touching a row: an op on a kind the
+ * caller did not declare in ONE file and ONE `transactFamily`. The detail names
+ * which rule (`cross-file`, `cross-family`, `no-family`); it is never a silent split.
+ */
+export declare class TransactRefusedError 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.

package/dist/records/index.d.ts

@@ -2,6 +2,7 @@ export * from './constants.js';
 export * from './errors.js';
 export * from './record-kind.js';
 export * from './secret-paths.js';
+export * from './transact-rules.js';
 export * from './records-access.js';
 export * from './entry-kind.js';
 export { makeInMemoryRecords, type InMemoryRecords, type InMemoryRecordsOptions, type InMemorySeedRow, type InMemoryStoredRow, } from './in-memory-records.js';

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

@@ -42,7 +42,7 @@ export declare const EntryDescriptorSchema: z.ZodObject<{
     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. */
+/** What crosses the wire from an addon: JSON only, no Zod. An unknown key is refused. */
 export declare const RecordKindDeclarationSchema: z.ZodObject<{
     database: z.ZodDefault<z.ZodEnum<{
         events: "events";
@@ -92,7 +92,6 @@ export declare const RecordKindDeclarationSchema: z.ZodObject<{
     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;
@@ -100,6 +99,67 @@ export declare const RecordKindDeclarationSchema: z.ZodObject<{
         fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/**
+ * A declaration as the engine's catalog stored it: an unknown key is DROPPED,
+ * because a row written by an older engine must never stop records from
+ * starting. Only for rows read back from the catalog, never for input.
+ */
+export declare const StoredRecordKindDeclarationSchema: 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>>;
+    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.$strip>;
 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;

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

@@ -24,7 +24,7 @@
  *  - **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 { DeclareKindResult, IRecordsProvider, RecordQueryInput, RecordTransactOp, RecordWhere } from '../capabilities/records.cap.js';
 import type { SecretsAccess } from '../keychain/secrets-access.js';
 import { type DefinedRecordKind } from './record-kind.js';
 /** The wire: the `records` provider's methods. The owner is never an argument. */
@@ -64,8 +64,36 @@ export interface RecordQueryOptions {
     /** Resolve the secret fields of the page in ONE keychain call. A failure throws. */
     readonly resolveSecrets?: boolean;
 }
+/**
+ * One write prepared for {@link RecordsAccess.transact}: the wire op plus the
+ * undo of the keychain writes made for it (a refused transaction puts the
+ * previous secret values back). Build it with the kind handle's `txPut`,
+ * `txPatch` and `txDelete`, which run the same validation and secret handling
+ * as the single `put` / `patch` / `delete`.
+ */
+export interface PreparedTransactOp {
+    readonly wire: RecordTransactOp;
+    readonly rollback: () => Promise<void>;
+}
+/** What one op of a transaction did, in op order. `rev` is `null` for a delete. */
+export interface TransactOpResult {
+    readonly rev: number | null;
+    readonly deleted: boolean;
+}
 export interface RecordKindHandle<T> {
     readonly name: string;
+    /** `put` as an op of {@link RecordsAccess.transact}. */
+    txPut(input: RecordPut<T>, opts?: {
+        readonly ifRev?: number;
+    }): Promise<PreparedTransactOp>;
+    /** `patch` as an op of {@link RecordsAccess.transact}. */
+    txPatch(id: string, partial: Readonly<Record<string, unknown>>, opts?: {
+        readonly ifRev?: number;
+        readonly at?: number | null;
+        readonly expiresAt?: number | null;
+    }): Promise<PreparedTransactOp>;
+    /** `delete` as an op of {@link RecordsAccess.transact}. */
+    txDelete(id: string): PreparedTransactOp;
     get(id: string): Promise<RecordRow<T> | null>;
     getMany(ids: readonly string[]): Promise<readonly RecordRow<T>[]>;
     /** `get` with the secret fields resolved from the keychain. */
@@ -133,6 +161,13 @@ export interface RecordsAccess {
      */
     declare(kinds: Readonly<Record<string, DefinedRecordKind>>): Promise<Readonly<Record<string, DeclareKindResult>>>;
     kind<S extends z.ZodType>(definition: DefinedRecordKind<S>): RecordKindHandle<z.infer<S>>;
+    /**
+     * Several writes in ONE transaction: all land or none does. Every op's kind
+     * must be declared by this owner in ONE database file under ONE
+     * `transactFamily`; anything else throws `records/transact-refused` before a
+     * row is touched. Results are in op order.
+     */
+    transact(ops: readonly PreparedTransactOp[]): Promise<readonly TransactOpResult[]>;
     /**
      * 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

package/dist/records/transact-rules.d.ts

@@ -0,0 +1,7 @@
+import type { RecordKindDeclaration } from './record-kind.js';
+export interface TransactMember {
+    readonly kind: string;
+    readonly declaration: Pick<RecordKindDeclaration, 'database' | 'transactFamily'>;
+}
+/** Throws {@link TransactRefusedError} unless the kinds may share one transaction. */
+export declare function assertTransactScope(members: readonly TransactMember[]): void;

package/dist/schemas/auth-records.d.ts

@@ -202,18 +202,6 @@ export declare const UserRecordSchema: z.ZodObject<{
     updatedAt: z.ZodNumber;
 }, z.core.$strip>;
 export type UserRecord = z.infer<typeof UserRecordSchema>;
-export declare const ApiKeyRecordSchema: z.ZodObject<{
-    id: z.ZodString;
-    label: z.ZodString;
-    isAdmin: z.ZodDefault<z.ZodBoolean>;
-    allowedProviders: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>;
-    allowedDevices: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>;
-    tokenHash: z.ZodString;
-    tokenPrefix: z.ZodString;
-    createdAt: z.ZodNumber;
-    lastUsedAt: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export type ApiKeyRecord = z.infer<typeof ApiKeyRecordSchema>;
 export declare const ScopedTokenSchema: z.ZodObject<{
     id: z.ZodString;
     userId: z.ZodString;