@camstack/types 1.2.162 → 1.2.163

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

@@ -354,6 +354,24 @@ export interface PipelineAudioInferenceResultPayload {
     readonly nodeId: string;
     readonly [key: string]: unknown;
 }
+/** Why the storage location set changed. */
+export type StorageLocationsChangedReason = 'upsert' | 'delete';
+/**
+ * One change to the SET of storage locations (`EventCategory.StorageLocationsChanged`).
+ *
+ * Deliberately thin: it names WHICH location moved and WHAT kind of change it
+ * was, and nothing about the row itself. A consumer re-reads
+ * `storage.listLocations` — the event is a doorbell, and a payload carrying the
+ * row would be a second, staler authority for it.
+ *
+ * A bulk edit rings this once per row, so every consumer coalesces.
+ */
+export interface StorageLocationsChangedPayload {
+    readonly locationId: string;
+    readonly locationType: string;
+    readonly reason: StorageLocationsChangedReason;
+    readonly [key: string]: unknown;
+}
 /**
  * Camera assignment lifecycle payload emitted by `addon-pipeline-orchestrator`
  * when a camera is assigned to or unassigned from an agent runner. Used by
@@ -840,6 +858,7 @@ export interface EventCatalog {
     'process.restarted': {
         processId: string;
     };
+    'storage.locations-changed': StorageLocationsChangedPayload;
     'recording.started': {
         deviceId: number;
         streamId?: string;

package/dist/interfaces/storage-location-mode.d.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+/**
+ * The storage-location STATE MODEL (D385) — one typed state, one policy module.
+ *
+ * A location's state used to be split across two authorities: the typed
+ * `enabled` field (THE write switch since D383) and an untyped `config.readOnly`
+ * key. They did not mean the same thing — `enabled: false` was still evicted
+ * under disk pressure while `config.readOnly` was deliberately excluded — and
+ * neither name said which. Every consumer re-derived the difference, and the
+ * three questions that actually matter were answered in six places.
+ *
+ * This module is the ONLY place in the repo allowed to interpret the state. It
+ * answers three questions and nothing else:
+ *
+ *   - may this location be WRITTEN to?   {@link modeMayWrite}
+ *   - may this location be READ?          {@link modeMayRead}
+ *   - what is its eviction policy?        {@link evictionPolicyForMode}
+ *
+ * | mode       | write | read | eviction                       |
+ * | ---------- | ----- | ---- | ------------------------------ |
+ * | `active`   | yes   | yes  | `normal` (pressure + usage cap) |
+ * | `readonly` | no    | yes  | `never`                        |
+ * | `drain`    | no    | yes  | `drain` (paced, until empty)   |
+ * | `disabled` | no    | no   | `never`                        |
+ *
+ * `scripts/check-storage-location-mode-single-owner.ts` fails the build when
+ * anything outside this module reads `config['readOnly']` or compares `enabled`
+ * directly. A rule nothing checks has already been broken somewhere.
+ */
+export declare const STORAGE_LOCATION_MODES: readonly ["active", "readonly", "drain", "disabled"];
+/**
+ * The one typed state of a storage location. Authoritative Zod schema — the TS
+ * alias below is `z.infer<>` of it, never a second spelling.
+ */
+export declare const StorageLocationModeSchema: z.ZodEnum<{
+    readonly: "readonly";
+    active: "active";
+    drain: "drain";
+    disabled: "disabled";
+}>;
+export type StorageLocationMode = z.infer<typeof StorageLocationModeSchema>;
+/**
+ * What disk-pressure and usage-cap relief may do to a location.
+ *
+ * - `normal` — the existing behaviour: free-percent guard plus `maxUsedGb`.
+ * - `never`  — excluded entirely. A retiring disk the operator is copying off
+ *              must not race the relocate mover, and a disabled one is not the
+ *              system's to erase.
+ * - `drain`  — a monotonically descending effective usage cap, paced to what
+ *              the ACTIVE locations of the same class gained (D386). This is
+ *              the only policy that shrinks a location the system is not
+ *              writing to.
+ */
+export declare const StorageEvictionPolicySchema: z.ZodEnum<{
+    never: "never";
+    drain: "drain";
+    normal: "normal";
+}>;
+export type StorageEvictionPolicy = z.infer<typeof StorageEvictionPolicySchema>;
+/**
+ * The legacy untyped drain key. Named ONCE, here, so the guard has exactly one
+ * sanctioned reader and the string never appears anywhere else.
+ */
+export declare const LEGACY_READ_ONLY_CONFIG_KEY = "readOnly";
+/**
+ * The shape this module needs off a location row. Structural rather than
+ * `StorageLocation` so the recorder's own resolved-location type, the admin
+ * UI's row and a persisted row can all be asked the same three questions
+ * without importing each other.
+ */
+export interface StorageLocationStateSource {
+    /** The typed state, once stamped. Absent on a row written before D385. */
+    readonly mode?: StorageLocationMode;
+    /** The retired write switch (D383). Read ONLY by the legacy fold below. */
+    readonly enabled?: boolean;
+    /** The provider-facing config blob, which carried the retired drain key. */
+    readonly config: Readonly<Record<string, unknown>>;
+}
+/** Is this mode a write target? Only `active` is. */
+export declare function modeMayWrite(mode: StorageLocationMode): boolean;
+/** May this mode be read (playback, timeline, scrub, relocate source)? */
+export declare function modeMayRead(mode: StorageLocationMode): boolean;
+/** What eviction may do here. See {@link StorageEvictionPolicy}. */
+export declare function evictionPolicyForMode(mode: StorageLocationMode): StorageEvictionPolicy;
+/**
+ * The mode a LEGACY row implies, or `null` when it implies nothing — the row is
+ * already stamped, or it carried neither flag.
+ *
+ * Both legacy flags fold to `readonly`, which is the CONSERVATIVE direction: a
+ * state change must never start deleting footage on its own, and it must never
+ * make footage that was still being served disappear. `enabled: false` used to
+ * leave the location evictable under pressure; folding it to `readonly` stops
+ * that, which is a strictly safer answer than the one it replaces.
+ */
+export declare function legacyModeOf(location: StorageLocationStateSource): StorageLocationMode | null;
+/**
+ * The state of a location, stamped or folded. THE one interpretation: a row
+ * that predates D385 is never ambiguous, and a stamped `mode` always wins over
+ * whatever the legacy pair still says.
+ */
+export declare function resolveLocationMode(location: StorageLocationStateSource): StorageLocationMode;
+/** Is this one of the four states? The stamped value crosses a wire, and a
+ *  value nobody defined must not be rendered as if it were a state. */
+export declare function isStorageLocationMode(value: unknown): value is StorageLocationMode;
+/** May this location be written to? */
+export declare function mayWriteToLocation(location: StorageLocationStateSource): boolean;
+/** May this location be read? A `disabled` one may not — and that is an
+ *  operator CHOICE, which callers must report as unavailable rather than as an
+ *  unknown-location fault. */
+export declare function mayReadLocation(location: StorageLocationStateSource): boolean;
+/** What eviction may do to this location. */
+export declare function evictionPolicyOfLocation(location: StorageLocationStateSource): StorageEvictionPolicy;
+/**
+ * The config blob with the retired drain key removed. Returns the SAME object
+ * when there was nothing to strip, so a caller can tell "changed" from
+ * "unchanged" by identity and skip a pointless persist.
+ */
+export declare function strippedOfLegacyReadOnly(config: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+/** The subset of a location row {@link withLocationMode} rewrites. */
+export interface StorageLocationModePatch {
+    readonly mode: StorageLocationMode;
+    readonly enabled: boolean;
+    readonly config: Readonly<Record<string, unknown>>;
+}
+/**
+ * Set a location's mode, and with it everything that must agree with it.
+ *
+ * `enabled` stays readable for one release as a DERIVED value (`mode ===
+ * 'active'`) so consumers that have not moved yet keep working, and the legacy
+ * `config.readOnly` key is DELETED. This function is the only way to write
+ * either, which is what makes it impossible for the two to disagree.
+ *
+ * Returns a new object — the input is never mutated.
+ */
+export declare function withLocationMode<T extends StorageLocationStateSource>(location: T, mode: StorageLocationMode): T & StorageLocationModePatch;

package/dist/interfaces/storage-location.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { StorageLocationMode } from './storage-location-mode.js';
 /**
  * `StorageLocationType` — an addon-declared id that identifies the *kind* of
  * storage a location serves. Defined here (not in `capabilities/storage.cap.ts`)
@@ -50,10 +51,20 @@ export declare const StorageLocationSchema: z.ZodObject<{
     nodeId: z.ZodOptional<z.ZodString>;
     isSystem: z.ZodDefault<z.ZodBoolean>;
     enabled: z.ZodOptional<z.ZodBoolean>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        readonly: "readonly";
+        active: "active";
+        drain: "drain";
+        disabled: "disabled";
+    }>>;
     capacity: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         totalBytes: z.ZodNumber;
         availableBytes: z.ZodNumber;
     }, z.core.$strip>>>;
+    owned: z.ZodOptional<z.ZodObject<{
+        bytes: z.ZodNumber;
+        measuredAtMs: z.ZodNumber;
+    }, z.core.$strip>>;
     createdAt: z.ZodNumber;
     updatedAt: z.ZodNumber;
 }, z.core.$strip>;
@@ -74,14 +85,51 @@ export declare const LegacyStorageLocationDefaultSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type LegacyStorageLocationDefault = z.infer<typeof LegacyStorageLocationDefaultSchema>;
 /**
- * Is this location a write target? THE one place that decides what an absent
- * `enabled` means on a persisted row — legacy rows predate the flag and were
- * active, so absence is enabled. Every consumer asks here rather than spelling
- * `enabled !== false` again, so the tri-state has exactly one interpretation.
+ * Is this location a write target?
+ *
+ * A THIN delegate to the policy module (D385) — `mode` is the state, and
+ * `mayWriteToLocation` is the only thing that interprets it (folding the legacy
+ * `enabled` / `config.readOnly` pair for rows that predate the stamp). Kept for
+ * one release because the name is spelled in a dozen call sites; new code asks
+ * `mayWriteToLocation` directly.
  */
-export declare function isLocationEnabled(location: {
+export interface LocationWriteTargetQuery {
+    readonly mode?: StorageLocationMode;
     readonly enabled?: boolean;
-}): boolean;
+    readonly config?: Readonly<Record<string, unknown>>;
+}
+export declare function isLocationEnabled(location: LocationWriteTargetQuery): boolean;
+/**
+ * Bytes in one GB, for every storage figure an operator types.
+ *
+ * BINARY (1024³), everywhere. The repo had both: the orchestrator's
+ * `maxUsedGb` → bytes conversion used 1024³ while the recorder's placement
+ * headroom used 10⁹ for the SAME stored key, so a location with a cap set was
+ * silently 7.4% off depending on which side of the pipe asked. The persisted
+ * values were entered against the binary unit and the admin UI reads it, so
+ * that is the one that stays. Every GB knob — `maxUsedGb`, `minFreeGb` —
+ * converts through {@link gbToBytes} and nowhere else.
+ */
+export declare const STORAGE_BYTES_PER_GB: number;
+/** GB → bytes, binary. Fractional GB is admitted and floored. */
+export declare function gbToBytes(gb: number): number;
+/**
+ * How far a `drain` has got (D386) — the read a UI renders, and nothing more.
+ *
+ * `estimatedEmptyAtMs` is derived from the growth the ratchet has actually
+ * OBSERVED and is `null` when it has observed none. Never a fabricated date: a
+ * drain with no observed growth has no honest ETA, and inventing one is how an
+ * operator learns not to believe the screen.
+ */
+export declare const StorageDrainProgressSchema: z.ZodObject<{
+    locationId: z.ZodString;
+    startedAtMs: z.ZodNumber;
+    startBytes: z.ZodNumber;
+    bytesRemaining: z.ZodNumber;
+    drained: z.ZodBoolean;
+    estimatedEmptyAtMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type StorageDrainProgress = z.infer<typeof StorageDrainProgressSchema>;
 /**
  * Reference accepted by consumer-facing `api.storage.*` calls.
  * Either:

package/dist/node.d.ts

@@ -1,18 +1,20 @@
-export { ensureBinary, downloadBinary, findInPath, getPlatformInfo, buildBinaryPath, } from './deps/binary-downloader.js';
 export type { PlatformInfo } from './deps/binary-downloader.js';
+export { buildBinaryPath, downloadBinary, ensureBinary, findInPath, getPlatformInfo, } from './deps/binary-downloader.js';
 export { ensureFfmpeg, getFfmpegDownloadUrl } from './deps/ffmpeg-downloader.js';
-export { ensurePython, installPythonPackages, installPythonRequirements, getPythonDownloadUrl, PYTHON_VERSION, } from './deps/python-downloader.js';
-export { ChildCostRegistry, NO_COST_CLAIM, nodeProcStatReader, parseProcCpuSeconds, parseProcRssBytes, readProcessCost, } from './process/child-cost-registry.js';
+export { ensurePython, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, PYTHON_VERSION, } from './deps/python-downloader.js';
+export type { Fmp4FragmentChildArgs, Fmp4FragmentChildDeps, } from './ffmpeg/fmp4-fragment-child.js';
+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 { ChildCostClaimHandle, ChildCostClaimInput, ProcStatReader, } from './process/child-cost-registry.js';
+export { ChildCostRegistry, NO_COST_CLAIM, nodeProcStatReader, parseProcCpuSeconds, parseProcRssBytes, readProcessCost, } from './process/child-cost-registry.js';
 export { FilesystemStorageProvider } from './storage/filesystem-storage-provider.js';
+export type { PhysicalRoot, RealpathSync } from './storage/physical-root.js';
+export { containsOrEquals, physicalRootOf } from './storage/physical-root.js';
 export { canonicalHash } from './utils/canonical-hash.js';
-export { signExpiringUrl, verifyExpiringUrl } from './utils/expiring-url-signature.js';
 export type { VerifyExpiringUrlInput } from './utils/expiring-url-signature.js';
-export { canonicalDeviceFingerprint, diffExportTargets, resolveExportFingerprint, } from './utils/export-reconciler.js';
+export { signExpiringUrl, verifyExpiringUrl } from './utils/expiring-url-signature.js';
 export type { DeviceExportShape, ExportDelta, ExportTargetEntry, } from './utils/export-reconciler.js';
-export { FfmpegProcess } from './ffmpeg/process.js';
-export type { FfmpegProcessOptions, FfmpegExit, FfmpegExitClass } from './ffmpeg/process.js';
-export { Fmp4FragmentPlane } from './ffmpeg/fmp4-fragment-plane.js';
-export type { Fmp4CloseReason, Fmp4Packet, Fmp4PrebufferOptions, Fmp4PrebufferStats, Fmp4SubscribeInput, Fmp4SubscriberInfo, Fmp4Subscription, } from './ffmpeg/fmp4-fragment-plane.js';
-export { Fmp4FragmentChild } from './ffmpeg/fmp4-fragment-child.js';
-export type { Fmp4FragmentChildArgs, Fmp4FragmentChildDeps, } from './ffmpeg/fmp4-fragment-child.js';
+export { canonicalDeviceFingerprint, diffExportTargets, resolveExportFingerprint, } from './utils/export-reconciler.js';