@camstack/system 1.2.202 → 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/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;
     /**