@camstack/system 1.2.201 → 1.2.203

package/dist/builtins/storage-orchestrator/location-occupancy-slice.d.ts

@@ -0,0 +1,47 @@
+import { IScopedLogger, IStorageOccupancyProvider } from '@camstack/types';
+/** What one location's owners hold there, merged. */
+export interface LocationOwnedBytes {
+    readonly bytes: number;
+    /** The OLDEST contributing measurement — honest about the whole figure
+     *  rather than about its freshest part. */
+    readonly measuredAtMs: number;
+}
+export interface OccupancySliceDeps {
+    readonly logger: IScopedLogger;
+    /** Registered `storage-occupancy` providers (cross-process proxies). */
+    readonly getProviders: () => readonly IStorageOccupancyProvider[];
+    /** Every location worth asking about, at refresh time. */
+    readonly locationIds: () => readonly string[];
+    readonly now: () => number;
+    /** How long a figure stays servable before a refresh is kicked. */
+    readonly staleAfterMs?: number;
+}
+export declare class LocationOccupancySlice {
+    private readonly deps;
+    private slice;
+    private refreshing;
+    private lastRefreshMs;
+    constructor(deps: OccupancySliceDeps);
+    /**
+     * What the last completed refresh saw for this location, or `undefined` when
+     * nothing has reported for it. There is deliberately no fallback: unknown is
+     * the truth about a location nobody owns bytes on.
+     */
+    ownedFor(locationId: string): LocationOwnedBytes | undefined;
+    /**
+     * Serve-and-revalidate. Called by every read: it returns immediately, and
+     * kicks a background refresh when the slice is older than the window. A read
+     * never awaits, and never joins a refresh already in flight (D224).
+     */
+    serveAndRevalidate(): void;
+    /**
+     * Ask every provider once and replace the slice.
+     *
+     * A provider that throws contributes NOTHING and is logged — it does not
+     * contribute a zero, and it does not take the other providers' answers down
+     * with it. A location that ends up with no contribution at all simply stays
+     * out of the slice, which is what makes it read back as unknown.
+     */
+    refresh(): Promise<void>;
+    private runRefresh;
+}

package/dist/builtins/storage-orchestrator/location-protection.d.ts

@@ -0,0 +1,20 @@
+/** statfs of the location's volume, when this node could take it. */
+export interface LocationVolumeCapacity {
+    readonly totalBytes: number;
+    readonly availableBytes: number;
+}
+/** One line, at most once per location per process. */
+export type ProtectionNotice = (message: string, meta: Record<string, unknown>) => void;
+/**
+ * The free-space percentage the guard enforces for one location.
+ *
+ * Order:
+ *   1. `config.minFreeGb`, converted against the volume total — the operator's
+ *      criterion in the unit they set it in.
+ *   2. `config.minFreePercent` — the legacy per-location override, and the
+ *      fallback when `minFreeGb` cannot be converted (no volume total: a
+ *      remote-node or unstattable location). Falling back is the right
+ *      direction — the alternative is a location with no guard at all.
+ *   3. the provider's declared default.
+ */
+export declare function resolveMinFreePercent(config: Readonly<Record<string, unknown>>, providerDefaultPercent: number, capacity: LocationVolumeCapacity | null, notice: ProtectionNotice): number;

package/dist/builtins/storage-orchestrator/location-root-collision.d.ts

@@ -0,0 +1,44 @@
+import { PhysicalRoot } from '@camstack/types/node';
+/** The minimum a row must expose for this check. */
+export interface RootCollisionCandidate {
+    readonly id: string;
+    readonly type: string;
+    /** Which node the path lives on. Two locations on DIFFERENT nodes can never
+     *  collide, however identical their paths look. */
+    readonly nodeId?: string;
+    readonly config: Readonly<Record<string, unknown>>;
+}
+/** How this location's physical root was derived, or that it could not be. */
+export type ResolveRoot = (basePath: string) => PhysicalRoot;
+/** A same-type root collision, with everything the message needs to name it. */
+export interface RootCollision {
+    readonly otherId: string;
+    readonly type: string;
+    readonly sharedRoot: string;
+    /** `equal` — the same directory. `nested` — one inside the other's tree. */
+    readonly kind: 'equal' | 'nested';
+}
+/** Why the check could not be made. Never a refusal — the caller warns. */
+export interface RootCollisionUnknown {
+    readonly reason: 'no-base-path' | 'unresolvable';
+    readonly detail: string;
+}
+export type RootCollisionVerdict = {
+    readonly outcome: 'clear';
+} | {
+    readonly outcome: 'collides';
+    readonly collision: RootCollision;
+} | {
+    readonly outcome: 'unknown';
+    readonly unknown: RootCollisionUnknown;
+};
+/**
+ * Does `next` collide with anything already stored?
+ *
+ * `existing` is every other location; the row being EDITED is excluded by id,
+ * so re-saving a location without moving its root never refuses itself.
+ */
+export declare function findRootCollision(next: RootCollisionCandidate, existing: Iterable<RootCollisionCandidate>, resolveRoot: ResolveRoot, storedSelf?: RootCollisionCandidate): RootCollisionVerdict;
+/** The operator-facing refusal. Names the location it collides with and the
+ *  shared root — a refusal that says only "conflict" makes the operator hunt. */
+export declare function rootCollisionMessage(id: string, collision: RootCollision): string;

package/dist/builtins/storage-orchestrator/location-store.d.ts

@@ -1,4 +1,11 @@
-import { ISettingsStoreProvider, StorageLocation } from '@camstack/types';
+import { ISettingsStoreProvider, LegacyStorageLocationDefault, StorageLocation } from '@camstack/types';
+/**
+ * A location as it comes back OFF DISK: the live record plus the retired
+ * `isDefault` column, which exists only so the orchestrator's boot migration
+ * can turn an old default into the enabled write set and say which row it came
+ * from. No other reader may take this type.
+ */
+export type PersistedStorageLocation = StorageLocation & LegacyStorageLocationDefault;
 /**
  * Abstract storage interface for `StorageLocation` records. Methods are
  * async because production-side implementations hit SQLite — but the
@@ -6,8 +13,10 @@ import { ISettingsStoreProvider, StorageLocation } from '@camstack/types';
  * disk doesn't block the cap surface.
  */
 export interface ILocationStore {
-    /** Read every persisted location. Called once at boot. */
-    loadAll(): Promise<readonly StorageLocation[]>;
+    /** Read every persisted location. Called once at boot. Rows carry the
+     *  RETIRED `isDefault` column when it was set, for the one reader allowed to
+     *  see it: the orchestrator's boot migration onto the `enabled` write set. */
+    loadAll(): Promise<readonly PersistedStorageLocation[]>;
     /** Insert or replace a single location by id. */
     upsert(loc: StorageLocation): Promise<void>;
     /** Remove a location by id. */

package/dist/builtins/storage-orchestrator/storage-migration-coordinator.d.ts

@@ -125,7 +125,7 @@ export declare class StorageMigrationCoordinator {
      * remaining" action.
      *
      * A class appears here only when something is (or might be) left on a
-     * location that is not its default. An empty result therefore means exactly
+     * location outside its write set. An empty result therefore means exactly
      * "there is nothing to drain", which is what lets the UI offer the action
      * only when it is true, and what lets {@link drain} refuse rather than start
      * a job that would move nothing and report `done` — the failure mode D295
@@ -137,12 +137,12 @@ export declare class StorageMigrationCoordinator {
      */
     residue(): Promise<readonly StorageMigrationResidue[]>;
     /**
-     * Run the DRAIN half alone, against classes whose default has already moved.
+     * Run the DRAIN half alone, against classes whose write set has already moved.
      *
      * ## Why this is a second verb rather than a looser `start`
      *
-     * `start` refuses a destination that is already the class's default
-     * (`"recordingsLow:ssd" is already the "recordingsLow" default`). That refusal
+     * `start` refuses a destination that is already the class's only write target
+     * (`"recordingsLow:ssd" is already the only write target for "recordingsLow"`). That refusal
      * is correct and it is load-bearing: there is genuinely nothing left to
      * repoint, and an operator must never be able to re-repoint a migrated class
      * by accident. Making `start` idempotent — "an already-repointed class
@@ -151,7 +151,7 @@ export declare class StorageMigrationCoordinator {
      * operator reads ("pauses the writers…") would be a lie half the time.
      *
      * `drain` instead cannot repoint AT ALL: it never touches
-     * `setDefaultLocations`, and its job starts in `draining` with `repointed`
+     * `setWriteTargets`, and its job starts in `draining` with `repointed`
      * already true, so the `repointing` / `refreshing` / `resuming` blocks of
      * {@link run} are behind it and unreachable. The two verbs are disjoint, and
      * `start`'s refusal keeps meaning exactly what it meant.
@@ -161,7 +161,7 @@ export declare class StorageMigrationCoordinator {
      * The finished job is the audit of what happened; re-opening it destroys
      * that. And a drain is needed in cases where no migration job ever existed
      * (a mover armed by hand, footage stranded on a location an operator added
-     * and then un-defaulted). One job = one operation, and the work list comes
+     * and then disabled again). One job = one operation, and the work list comes
      * from {@link residue} — the archive — not from what a previous job believed.
      */
     drain(input: StorageMigrationDrainInput): Promise<string>;
@@ -217,9 +217,9 @@ export declare class StorageMigrationCoordinator {
     private waitForSeal;
     private verifyMoves;
     /**
-     * After a from→to copy whose source was NOT the class default: stop new
-     * writes to `from`. The default is unchanged (that is the whole point of
-     * naming a non-default source). A location that is already disabled is
+     * After a from→to copy whose source was NOT a write target: stop new writes
+     * to `from`. The rest of the write set is unchanged (that is the whole point
+     * of naming a source outside it). A location that is already disabled is
      * left alone.
      */
     private freezeDrainedSources;

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.d.ts

@@ -4,6 +4,15 @@ interface StorageOrchestratorConfig extends Record<string, unknown> {
 export declare class StorageOrchestratorAddon extends BaseAddon<StorageOrchestratorConfig> {
     private service;
     private pressureManager;
+    /**
+     * How much of each location CamStack itself holds (D388).
+     *
+     * Built on first use rather than in a field initializer: `this.ctx` does not
+     * exist until `initialize()` runs, and a field initializer touching it throws
+     * in the constructor.
+     */
+    private occupancySlice;
+    private get occupancy();
     private pressureTimer;
     private pressureSweepInFlight;
     private migration;
@@ -98,6 +107,25 @@ export declare class StorageOrchestratorAddon extends BaseAddon<StorageOrchestra
      * the recorder so disk-pressure is a single core concern.
      */
     private resolveLocationThresholds;
+    /** Location ids that have already logged the `minFreeGb` / `minFreePercent`
+     *  redundancy. The pressure sweep runs on a timer; the notice is worth
+     *  exactly one line per location per process, not one per minute. */
+    private readonly minFreeRedundancyLogged;
+    private logMinFreeRedundancyOnce;
+    /**
+     * The draining locations and the ACTIVE peers of their class whose growth
+     * paces them (D386). Rebuilt every sweep from the live mode of every
+     * location, so this is also what STOPS a drain: a location the operator
+     * switched back simply stops appearing.
+     */
+    private drainStore;
+    /** The drain ratchet's durable home, once a data-store engine exists. Same
+     *  late-wiring window as the location table — on an agent it is never. */
+    private resolveDrainStore;
+    private drainPlanRefusalLogged;
+    private resolveDrainPlan;
+    /** Drain progress for every draining location, as of the last sweep. */
+    private drainProgress;
     /**
      * What the provider's own schema declared secret, or `undefined` when this
      * node has never heard from that provider. The distinction is the whole
@@ -106,6 +134,25 @@ export declare class StorageOrchestratorAddon extends BaseAddon<StorageOrchestra
     private declaredSecretKeys;
     /** Which keys of a given stored config must never leave this process. */
     private secretKeysFor;
+    /**
+     * Ring the doorbell: the SET of storage locations changed (D387).
+     *
+     * A consumer that resolves locations at boot had no way to learn that the
+     * operator added, edited or removed one — the recorder kept writing to the
+     * disk set it resolved hours ago, and an operator who added a second
+     * recordings disk in the admin UI got nothing until something unrelated
+     * happened to re-resolve.
+     *
+     * Telemetry, and deliberately so (D8/D11): it carries no row, it is allowed
+     * to be dropped, and every consumer re-reads `listLocations` for itself and
+     * converges on its own periodic path anyway. A bulk edit rings it once per
+     * row — coalescing is the consumer's job, not this one's.
+     *
+     * Never throws into the mutation that produced it: the location IS saved,
+     * and a bus that will not take a telemetry event must not turn that into a
+     * failed upsert.
+     */
+    private announceLocationsChanged;
     /** A location with its provider's declared secrets replaced by the sentinel. */
     private redacted;
     /**