@camstack/system 1.2.390 → 1.2.391

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

@@ -1,469 +1,450 @@
-import { IScopedLogger, IStorageProviderImpl, StorageAccess, StorageLocation, StorageLocationDeclaration, StorageLocationRef } from '@camstack/types';
-import { ResolveRoot } from './location-root-collision.js';
-import { ILocationStore } from './location-store.js';
+import type { IScopedLogger, IStorageProviderImpl, StorageAccess, StorageLocation, StorageLocationDeclaration, StorageLocationRef } from "@camstack/types";
+import type { ResolveRoot } from "./location-root-collision.js";
+import type { ILocationStore } from "./location-store.js";
 export interface ListLocationsFilter {
-    readonly type?: string;
+	readonly type?: string;
 }
 /**
- * Minimal structural shape the orchestrator needs from the kernel's
- * `StorageLocationRegistry` — the cardinality lookup plus the full
- * declaration list (the admin-UI Data screen renders one group per
- * declaration). Declared locally so core's builtins don't import the
- * kernel's registry type directly; the addon passes the real
- * `buildStorageLocationRegistry(...)` result, which structurally
- * satisfies this interface.
- */
+* Minimal structural shape the orchestrator needs from the kernel's
+* `StorageLocationRegistry` — the cardinality lookup plus the full
+* declaration list (the admin-UI Data screen renders one group per
+* declaration). Declared locally so core's builtins don't import the
+* kernel's registry type directly; the addon passes the real
+* `buildStorageLocationRegistry(...)` result, which structurally
+* satisfies this interface.
+*/
 export interface DeclarationSource {
-    cardinalityOf(id: string): 'single' | 'multi' | null;
-    /**
-     * Effective {@link StorageAccess} of a declared location kind — the
-     * constraint that decides which providers may back it. `null` = the kind
-     * was never declared. See `upsertLocation`'s remote-provider refusal.
-     */
-    accessOf(id: string): StorageAccess | null;
-    list(): readonly StorageLocationDeclaration[];
+	cardinalityOf(id: string): "single" | "multi" | null;
+	/**
+	* Effective {@link StorageAccess} of a declared location kind — the
+	* constraint that decides which providers may back it. `null` = the kind
+	* was never declared. See `upsertLocation`'s remote-provider refusal.
+	*/
+	accessOf(id: string): StorageAccess | null;
+	list(): readonly StorageLocationDeclaration[];
 }
 /**
- * Provider lookup callback. Returns the live set of `storage-provider`
- * registrants. Called per-dispatch (cheap registry scan) so newly
- * loaded addons surface immediately.
- */
+* Provider lookup callback. Returns the live set of `storage-provider`
+* registrants. Called per-dispatch (cheap registry scan) so newly
+* loaded addons surface immediately.
+*/
 export type StorageProviderLookup = () => readonly IStorageProviderImpl[];
 /**
- * Synchronous `providerId → nodeLocal` resolver, injected by the addon
- * from a cached snapshot of `storage-provider.getProviderInfo()` (the
- * `getProviderInfo` round-trip is async, so a sync cache keeps
- * `upsertLocation` synchronous — the contract its many callers rely on).
- *
- * Returns:
- *   - `true`  — node-local provider (filesystem): its locations bind to a
- *     single node, so a `nodeId` is required.
- *   - `false` — node-agnostic provider (S3/SFTP/WebDAV): `nodeId` optional.
- *   - `undefined` — provider not (yet) known. Treated as non-node-local:
- *     validation does not reject (the provider may register later / be
- *     remote), the safe default for the early-boot / in-memory path.
- */
+* Synchronous `providerId → nodeLocal` resolver, injected by the addon
+* from a cached snapshot of `storage-provider.getProviderInfo()` (the
+* `getProviderInfo` round-trip is async, so a sync cache keeps
+* `upsertLocation` synchronous — the contract its many callers rely on).
+*
+* Returns:
+*   - `true`  — node-local provider (filesystem): its locations bind to a
+*     single node, so a `nodeId` is required.
+*   - `false` — node-agnostic provider (S3/SFTP/WebDAV): `nodeId` optional.
+*   - `undefined` — provider not (yet) known. Treated as non-node-local:
+*     validation does not reject (the provider may register later / be
+*     remote), the safe default for the early-boot / in-memory path.
+*/
 export type NodeLocalResolver = (providerId: string) => boolean | undefined;
 /**
- * Whether a location still holds anything — the only question `deleteLocation`
- * is allowed to destroy a record on the answer to.
- *
- *  - `'occupied'` — something is there. Deleting the record now strands it.
- *  - `'empty'`    — the location was reached and holds nothing.
- *  - `'unknown'`  — it could not be reached at all: a remote provider, another
- *                   node's disk, an unmounted root. NOT "empty". A read that
- *                   fails must never authorise a destruction (D49).
- */
-export type LocationOccupancy = 'occupied' | 'empty' | 'unknown';
+* Whether a location still holds anything — the only question `deleteLocation`
+* is allowed to destroy a record on the answer to.
+*
+*  - `'occupied'` — something is there. Deleting the record now strands it.
+*  - `'empty'`    — the location was reached and holds nothing.
+*  - `'unknown'`  — it could not be reached at all: a remote provider, another
+*                   node's disk, an unmounted root. NOT "empty". A read that
+*                   fails must never authorise a destruction (D49).
+*/
+export type LocationOccupancy = "occupied" | "empty" | "unknown";
 export type LocationOccupancyProbe = (location: StorageLocation) => Promise<LocationOccupancy>;
 export interface DeleteLocationOptions {
-    /** Override an `occupied` or `unknown` verdict. See the cap docblock. */
-    readonly force?: boolean;
+	/** Override an `occupied` or `unknown` verdict. See the cap docblock. */
+	readonly force?: boolean;
 }
 /**
- * Where a single dispatch must execute: which `storage-provider`, on which
- * node. `providerId` alone is NOT a routing key — every node's filesystem
- * provider registers under the same id, so a target without its `nodeId`
- * silently resolves to whichever node asked (the hub).
- *
- * `nodeId` absent = node-agnostic (S3/SFTP/WebDAV): reachable from anywhere,
- * so the local provider runs it.
- */
+* Where a single dispatch must execute: which `storage-provider`, on which
+* node. `providerId` alone is NOT a routing key — every node's filesystem
+* provider registers under the same id, so a target without its `nodeId`
+* silently resolves to whichever node asked (the hub).
+*
+* `nodeId` absent = node-agnostic (S3/SFTP/WebDAV): reachable from anywhere,
+* so the local provider runs it.
+*/
 export interface StorageDispatchTarget {
-    readonly providerId: string;
-    readonly nodeId?: string;
+	readonly providerId: string;
+	readonly nodeId?: string;
 }
 /** The two chunked-I/O session families the orchestrator tracks. */
-export type StorageSessionKind = 'upload' | 'download';
+export type StorageSessionKind = "upload" | "download";
 export declare class StorageOrchestratorService {
-    private readonly logger;
-    private readonly getProviders;
-    /**
-     * Optional persistence backend. When supplied, `initialize()`
-     * hydrates the in-memory map from the store, and every mutation
-     * (upsert/delete) mirrors to it. When `null` / `undefined`, the
-     * service is in-memory only — the contract used by the existing
-     * routing tests, where re-creating the service deliberately
-     * forgets every location.
-     *
-     * Mutable because production boot wires it late: the `settings-store`
-     * cap often isn't registered when the orchestrator initializes, so the
-     * service starts store-less and the addon calls {@link attachStore} once
-     * the provider appears. See {@link attachStore}.
-     */
-    private locationStore;
-    /** Cross-node provider resolver (hub wiring: a node-routed capability
-     *  proxy over `storage-provider`). Absent → remote locations error. */
-    private readonly getRemoteProvider?;
-    private readonly locations;
-    /**
-     * Declaration-driven cardinality source, injected by the addon after
-     * the kernel aggregates `storageLocations` declarations. `null` until
-     * `setRegistry` runs — `upsertLocation` then treats every type as
-     * `'multi'` (no singleton enforcement), the safe default for the
-     * in-memory-only / early-boot path.
-     */
-    private registry;
-    /**
-     * Injected `providerId → nodeLocal` resolver (see {@link NodeLocalResolver}).
-     * `null` until {@link setNodeLocalResolver} runs — `upsertLocation` then
-     * skips the node-local requirement check entirely (every provider is
-     * treated as node-agnostic), the safe default for the in-memory-only /
-     * early-boot path that predates the resolver wiring.
-     */
-    private nodeLocalResolver;
-    /**
-     * Injected occupancy probe (see {@link LocationOccupancyProbe}). `null` until
-     * {@link setOccupancyProbe} runs, and a `null` probe answers `unknown` — so a
-     * service with no probe REFUSES an unforced delete rather than performing one
-     * it could not check. The check is the point; a check that defaults to
-     * "permit" is a paragraph, not a guard.
-     */
-    private occupancyProbe;
-    /** `localNodeId` with any forked-child `/addon` suffix stripped. */
-    private readonly localNode;
-    /**
-     * `<kind>:<sessionId>` → the dispatch target that OPENED the session.
-     * Chunked I/O carries no `StorageLocation` after the first hop, so without
-     * this the follow-up chunks fall back to a `providerId`-only lookup — which
-     * on a multi-node cluster means the hub's filesystem, not the agent's.
-     */
-    private readonly sessionTargets;
-    constructor(logger: IScopedLogger, getProviders: StorageProviderLookup, 
-    /**
-     * Optional persistence backend. When supplied, `initialize()`
-     * hydrates the in-memory map from the store, and every mutation
-     * (upsert/delete) mirrors to it. When `null` / `undefined`, the
-     * service is in-memory only — the contract used by the existing
-     * routing tests, where re-creating the service deliberately
-     * forgets every location.
-     *
-     * Mutable because production boot wires it late: the `settings-store`
-     * cap often isn't registered when the orchestrator initializes, so the
-     * service starts store-less and the addon calls {@link attachStore} once
-     * the provider appears. See {@link attachStore}.
-     */
-    locationStore?: ILocationStore | null, 
-    /** This node's id — locations pinned to OTHER nodes dispatch remotely. */
-    localNodeId?: string, 
-    /** Cross-node provider resolver (hub wiring: a node-routed capability
-     *  proxy over `storage-provider`). Absent → remote locations error. */
-    getRemoteProvider?: ((nodeId: string) => IStorageProviderImpl | null) | undefined);
-    /**
-     * The node this orchestrator runs on, with any forked-child `/addon`
-     * suffix stripped. A location whose `nodeId` differs is NOT this node's
-     * to touch — its bytes, and its free space, live elsewhere.
-     */
-    getLocalNodeId(): string;
-    /** True once a persistence store is wired (constructor or {@link attachStore}). */
-    hasStore(): boolean;
-    /**
-     * Late-bind the persistence store (production boot: the `settings-store`
-     * cap registers after the orchestrator initializes, so the service runs
-     * in-memory-only until then). Idempotent — a second call once a store is
-     * wired is a no-op.
-     *
-     * Reconciles both directions so operator edits survive a reboot:
-     *   1. hydrate — DB rows win over any early in-memory seed (restores
-     *      operator config like `minFreePercent` that the pre-store boot
-     *      can't see);
-     *   2. backfill — in-memory locations the DB doesn't have yet (the
-     *      pre-store seed defaults on a fresh install) are persisted, so the
-     *      store becomes the durable source of truth from here on.
-     *
-     * **The re-entry guard latches on a SUCCESSFUL hydrate, not on the attempt** —
-     * `loadAll()` is awaited BEFORE `this.locationStore` is assigned, and the
-     * order is load-bearing. Latching first meant one transient read error
-     * answered `hasStore()` true forever, so the addon's `ensureStoreWired` gate
-     * skipped every retry; the service then ran the whole process lifetime on
-     * pre-store seed defaults while `upsert` mirrored them onto rows it had never
-     * read, silently replacing the operator's persisted `minFreePercent`. Failing
-     * back to store-less is the safe direction: an in-memory-only service writes
-     * nothing over what is on disk, and the next `capability:provider-registered`
-     * event tries again. Held by
-     * `__tests__/storage-orchestrator-persistence.spec.ts`.
-     */
-    attachStore(store: ILocationStore): Promise<void>;
-    /**
-     * ONE explicit migration onto the four-state model (D385), run once per boot
-     * against the rows that came off disk. Idempotent: the second boot finds
-     * nothing to do.
-     *
-     * Two steps, in order, and each one is a WRITE — the point is that "absent"
-     * stops existing rather than being re-interpreted on every read forever:
-     *
-     *   1. A row with no `mode` is stamped with the mode its legacy flags imply
-     *      (`legacyModeOf`): `config.readOnly === true` → `readonly` and the
-     *      config key is DELETED; `enabled === false` → `readonly` (the
-     *      CONSERVATIVE direction — a state change must never start deleting
-     *      footage on its own); everything else → `active`. `withLocationMode`
-     *      derives `enabled` from the mode, so the two can never disagree, and
-     *      this subsumes the D383 pass that stamped flagless rows `enabled: true`.
-     *   2. A type left with NO write target — only reachable from a hand-edited
-     *      store or a row an older build wrote — gets one made `active`, chosen as
-     *      the row the RETIRED default flag named, else the `:default`-slugged
-     *      row, else the lexicographically first. Loudly: a class with no write
-     *      target records nowhere, and refusing to repair it here would leave the
-     *      hub silently unable to write with no operator action pending.
-     *
-     * An operator's explicit `readonly`/`drain`/`disabled` is never reversed by
-     * step 1 — only step 2 touches it, and only when the alternative is a class
-     * that cannot write at all.
-     *
-     * On the live hub every location is enabled with no `readOnly`, so step 1 is
-     * a no-op that stamps `active` and nothing else changes.
-     */
-    private migrateOntoTheWriteSet;
-    /** Apply one migrated row in memory and mirror it to the store. */
-    private persistMigrated;
-    /**
-     * Inject the declaration-driven cardinality source. Called once by the
-     * addon after the kernel aggregates every addon's `storageLocations`
-     * declarations into a `StorageLocationRegistry`.
-     */
-    setRegistry(registry: DeclarationSource | null): void;
-    /**
-     * Inject the synchronous `providerId → nodeLocal` resolver (SP1). Called
-     * by the addon from a cached snapshot of every `storage-provider`'s
-     * `getProviderInfo().nodeLocal`, refreshed when the provider collection
-     * changes. Powers the node-local upsert guard and the boot backfill.
-     */
-    setNodeLocalResolver(resolver: NodeLocalResolver | null): void;
-    /**
-     * Inject the "does this location still hold anything" probe read by
-     * {@link deleteLocation}. Absent → every delete sees `unknown` and therefore
-     * REFUSES without `force`, which is the safe direction for a service wired
-     * without one.
-     */
-    setOccupancyProbe(probe: LocationOccupancyProbe | null): void;
-    /**
-     * The full set of addon-declared storage locations, as aggregated by
-     * the kernel and injected via {@link setRegistry}. Powers the admin-UI
-     * Data screen's per-declaration grouping. Empty until the registry is
-     * injected (early-boot / in-memory-only path).
-     */
-    listDeclarations(): readonly StorageLocationDeclaration[];
-    /**
-     * Hydrate the in-memory map from the persistence layer. Called once
-     * by the addon during `onInitialize`, before the eager seed pass.
-     * Idempotent — running it twice with the same store contents
-     * produces the same map. No-op when the service was constructed
-     * without a store.
-     *
-     * Errors loading individual rows are tolerated: the bad row is
-     * skipped and logged so a single corrupted record doesn't lock the
-     * whole orchestrator out of boot. (The store-side validation pass
-     * before insert means only schema-invalid SQL state can produce
-     * such a row.)
-     */
-    initialize(): Promise<void>;
-    /**
-     * Boot backfill (SP1): stamp `nodeId` on every persisted node-local
-     * location that lacks one. Single-node deployments seeded their
-     * filesystem locations before `nodeId` existed — they live on `hubNodeId`
-     * (the hub). Node-agnostic (remote) locations are left untouched: their
-     * absent `nodeId` is correct (reachable from any node).
-     *
-     * Idempotent — a location that already carries a `nodeId` (any value) is
-     * never re-touched, so re-running on a populated map (or a re-boot) is a
-     * no-op. A plain local update, not versioned-migration machinery: only
-     * the rows missing `nodeId` are mutated + persisted.
-     *
-     * No-op until the node-local resolver is wired (it classifies which
-     * providers are node-local).
-     */
-    backfillNodeIds(hubNodeId: string): Promise<void>;
-    listLocations(filter?: ListLocationsFilter): readonly StorageLocation[];
-    /**
-     * The WRITE SET of a type: every enabled location of it, in stable id order.
-     * This replaced `getDefaultLocation` (D383) — a type does not have one write
-     * target any more, it has a pool, and every consumer that must pick one picks
-     * from here by its own rule (the recorder by headroom, a drain by an operator
-     * -named destination).
-     */
-    writeTargets(type: string): readonly StorageLocation[];
-    /**
-     * Change the WRITE SET as one compensated commit: each named location is
-     * enabled (it joins the pool) or disabled (it becomes read-only — still read,
-     * still played back, still age-swept, still drained).
-     *
-     * This is the cutover verb, and its only caller is the migration coordinator,
-     * which persists its `repointing` phase BEFORE calling so a crash mid-write
-     * is recovered by replaying the same idempotent set before writers resume.
-     *
-     * It moves ONLY the locations it is given: a cutover from A to C on a class
-     * that also writes to B leaves B in the pool, because the operator's pool is
-     * the authority and a migration is not a licence to shrink it. The commit is
-     * refused when it would leave a write-serving type with nothing enabled —
-     * the same refusal `upsertLocation` applies, judged on the RESULT so an
-     * enable and a disable in one commit are weighed together.
-     */
-    setWriteTargets(enabledByLocationId: ReadonlyMap<string, boolean>): Promise<void>;
-    /**
-     * Insert or update a location.
-     *
-     * When a persistence store is wired (Task 6), the record is mirrored to it;
-     * the mirror is fire-and-forget and its errors reach the logger.
-     */
-    /**
-     * Refuse a `(location kind, provider)` pair the kind cannot use.
-     *
-     * The rule, in one line: a `'local-path'` kind requires a provider whose
-     * `getProviderInfo().nodeLocal` is `true`.
-     *
-     * `nodeLocal` is the honest name for "this provider's `resolve` returns a
-     * path on the filesystem of the node that resolved it". The
-     * `storage-provider` cap's own discriminated union already forces every
-     * provider to declare it, and all four remote providers declare `false`, so
-     * no new cap surface is needed to ask the question.
-     *
-     * Three-valued on purpose. Only a POSITIVE `false` refuses:
-     *  - `true`      → node-local, always fine.
-     *  - `false`     → the provider is known and known to be remote. REFUSE.
-     *  - `undefined` → the provider has not registered yet (early boot, an addon
-     *    still loading). That is "unknown", not "remote", and a read that could
-     *    not be made must never destroy work (D49) — the system seed runs
-     *    through this path before any provider registers. Allowed, and logged,
-     *    so the allowance is never silent.
-     *
-     * The DECLARATION side is read the same way. A kind the registry does not
-     * know is `local-path` (fail-closed: an unknown kind is not a permissive
-     * one), but NO REGISTRY AT ALL is a different statement — nothing has been
-     * loaded, so nothing can be concluded about any kind. The addon injects the
-     * registry inside `onInitialize`, before the `storage` cap is mounted, so
-     * there is no window in which an operator upsert sees this branch; a service
-     * constructed without one is the in-memory/early-boot path.
-     */
-    private refuseIncompatibleProvider;
-    upsertLocation(input: Omit<StorageLocation, 'createdAt' | 'updatedAt'>): StorageLocation;
-    /**
-     * Remove a location. Refuses the last location of a type and the last
-     * enabled location of a type. `isSystem` is informational — a frozen
-     * recordings `:default` is deletable once a sibling is live. Occupancy still
-     * refuses unless `force` is set; force never overrides uniqueness /
-     * last-enabled.
-     */
-    deleteLocation(id: string, options?: DeleteLocationOptions): Promise<void>;
-    /**
-     * Run the injected occupancy probe, converting "no probe" and "the probe
-     * threw" into `unknown` rather than into a permit.
-     */
-    private probeOccupancy;
-    /**
-     * Remove seed-shaped locations (`<type>:default`) whose type is no longer
-     * declared by any addon (stale defaults from a removed location type).
-     * Operator-added locations of an undeclared type are KEPT but warned.
-     *
-     * FAIL-SAFE: if the registry is EMPTY (no addon declared any location), we
-     * refuse to prune anything. An empty registry almost always means
-     * declarations failed to load (boot ordering, a stale install) — pruning
-     * "everything undeclared" in that state would wipe every seeded location
-     * (data/logs/recordings/…). Better to keep stale rows than destroy live ones.
-     */
-    pruneUndeclaredSystemLocations(): void;
-    /**
-     * Resolve a `StorageLocationRef` to a concrete `StorageLocation`.
-     *  - bare type (e.g. `'backups'`) → default location of that type
-     *  - fully-qualified id (e.g. `'backups:nas-01'`) → that exact instance
-     *
-     * Throws an actionable error when nothing matches — every consumer of
-     * the singleton `storage` cap funnels through here, so the error
-     * message is what operators see when the orchestrator's view of the
-     * world doesn't match expectations.
-     */
-    resolveRef(ref: StorageLocationRef): StorageLocation;
-    /**
-     * Find the storage-provider that backs a given location — the entry point
-     * every consumer-facing `storage` cap method funnels through.
-     *
-     * Routing key is `(providerId, nodeId)`, never `providerId` alone: every
-     * node's FilesystemStorageProvider registers under the SAME providerId, so
-     * a providerId-only match resolves to whichever node asked. That is how a
-     * location created on an agent ended up writing to the HUB's filesystem
-     * (root-caused 2026-07-29).
-     */
-    getProviderFor(location: StorageLocation): Promise<IStorageProviderImpl>;
-    /**
-     * Resolve one dispatch target to the provider that must execute it.
-     *
-     * `descriptor` is the operator-facing subject of the error message
-     * (`location "recordings:disk"`, `uploadId "u-42"`); `locationId` is the
-     * structured tag for the log line when there is a location behind the
-     * dispatch (chunked sessions carry only the session id).
-     *
-     * Both failure branches LOG before throwing, and NEITHER falls back to the
-     * local provider — a silent fallback is the bug this method exists to fix.
-     */
-    private getProviderForTarget;
-    /**
-     * Remember which provider — and on which NODE — opened a chunked session.
-     * `beginUpload` / `beginDownload` carry a `StorageLocation`; every later
-     * chunk carries only the session id, and a session id issued by an agent
-     * means nothing to the hub's provider.
-     */
-    rememberSession(kind: StorageSessionKind, sessionId: string, location: StorageLocation): void;
-    /** Drop a session's routing entry (finalize / abort / end). */
-    forgetSession(kind: StorageSessionKind, sessionId: string): void;
-    /** Drop every session entry (addon shutdown). */
-    clearSessions(): void;
-    /**
-     * Resolve the provider that owns an in-flight chunked session, on the node
-     * that opened it. Throws when the orchestrator has no record of the open
-     * call (provider gone, or a chunk for a session it never issued).
-     */
-    getProviderForSession(kind: StorageSessionKind, sessionId: string): Promise<IStorageProviderImpl>;
-    /** Convenience: lookup by id (returns `undefined` if not found). */
-    getLocationById(id: string): StorageLocation | undefined;
-    /**
-     * Seed one default `StorageLocation` per addon-declared location that
-     * doesn't already have one. Idempotent — re-running with the same
-     * declarations on a populated map is a no-op (each declared `id`
-     * already resolves to an existing `<id>:default`).
-     *
-     * The seeded row is born ENABLED — a fresh install must be able to write the
-     * moment it boots, and `enabled` is the only write switch there is (D383).
-     * The `:default` suffix is a NAME kept for idempotency across existing
-     * installs, not a flag: the stored `id` is `'recordings:default'` so it
-     * satisfies the
-     * `^[a-z][a-z0-9-]*:[a-z0-9-]+$` regex on `StorageLocationSchema.id`.
-     *
-     * `basePath` is the storage root (e.g. `<CAMSTACK_DATA>`). Each
-     * location's `config.basePath` is `<basePath>/<id>`, except when the
-     * declaration sets `defaultsTo` — then it inherits the resolved root of
-     * the referenced location's default instance (sharing the same root
-     * directory for derivative slots like `recordingsLow` → `recordings`).
-     */
-    seedDefaults(input: {
-        readonly providerId: string;
-        readonly basePath: string;
-        /**
-         * Root for declarations marked `defaultRoot: 'media'` (the dedicated media
-         * volume, `CAMSTACK_MEDIA_ROOT`). Absent → media declarations fall back to
-         * `basePath` like everything else.
-         */
-        readonly mediaBasePath?: string;
-        /**
-         * Root for declarations marked `defaultRoot: 'backup'` (the dedicated
-         * backup volume, `CAMSTACK_BACKUP_ROOT`, default `/backups`). Absent →
-         * backup declarations fall back to `basePath`.
-         */
-        readonly backupBasePath?: string;
-        readonly declarations: readonly StorageLocationDeclaration[];
-    }): void;
-    /**
-     * The same-type physical-root refusal (D389).
-     *
-     * An unresolvable root — another node's disk, a remote provider, a path that
-     * does not exist yet — WARNS and lets the write through. Refusing on a read
-     * that could not be taken blocks the operator on a doubt, and the recorder's
-     * demotion still catches what slips past (D49's spirit).
-     */
-    private refuseSameTypeRootCollision;
-    /** Injectable so a test can drive symlinks and unresolvable paths without
-     *  touching a real filesystem. Production takes the shared derivation. */
-    private resolveRoot;
-    /** Test seam for {@link refuseSameTypeRootCollision}. */
-    setRootResolver(resolveRoot: ResolveRoot): void;
-    /** Internal: check whether any location of the given type exists. */
-    private hasAnyLocationOfType;
+	private readonly logger;
+	private readonly getProviders;
+	/**
+	* Optional persistence backend. When supplied, `initialize()`
+	* hydrates the in-memory map from the store, and every mutation
+	* (upsert/delete) mirrors to it. When `null` / `undefined`, the
+	* service is in-memory only — the contract used by the existing
+	* routing tests, where re-creating the service deliberately
+	* forgets every location.
+	*
+	* Mutable because production boot wires it late: the `settings-store`
+	* cap often isn't registered when the orchestrator initializes, so the
+	* service starts store-less and the addon calls {@link attachStore} once
+	* the provider appears. See {@link attachStore}.
+	*/
+	private locationStore;
+	/** Cross-node provider resolver (hub wiring: a node-routed capability
+	*  proxy over `storage-provider`). Absent → remote locations error. */
+	private readonly getRemoteProvider?;
+	private readonly locations;
+	/**
+	* Declaration-driven cardinality source, injected by the addon after
+	* the kernel aggregates `storageLocations` declarations. `null` until
+	* `setRegistry` runs — `upsertLocation` then treats every type as
+	* `'multi'` (no singleton enforcement), the safe default for the
+	* in-memory-only / early-boot path.
+	*/
+	private registry;
+	/**
+	* Injected `providerId → nodeLocal` resolver (see {@link NodeLocalResolver}).
+	* `null` until {@link setNodeLocalResolver} runs — `upsertLocation` then
+	* skips the node-local requirement check entirely (every provider is
+	* treated as node-agnostic), the safe default for the in-memory-only /
+	* early-boot path that predates the resolver wiring.
+	*/
+	private nodeLocalResolver;
+	/**
+	* Injected occupancy probe (see {@link LocationOccupancyProbe}). `null` until
+	* {@link setOccupancyProbe} runs, and a `null` probe answers `unknown` — so a
+	* service with no probe REFUSES an unforced delete rather than performing one
+	* it could not check. The check is the point; a check that defaults to
+	* "permit" is a paragraph, not a guard.
+	*/
+	private occupancyProbe;
+	/** `localNodeId` with any forked-child `/addon` suffix stripped. */
+	private readonly localNode;
+	/**
+	* `<kind>:<sessionId>` → the dispatch target that OPENED the session.
+	* Chunked I/O carries no `StorageLocation` after the first hop, so without
+	* this the follow-up chunks fall back to a `providerId`-only lookup — which
+	* on a multi-node cluster means the hub's filesystem, not the agent's.
+	*/
+	private readonly sessionTargets;
+	constructor(logger: IScopedLogger, getProviders: StorageProviderLookup, locationStore?: ILocationStore | null, localNodeId?: string, getRemoteProvider?: ((nodeId: string) => IStorageProviderImpl | null) | undefined);
+	/**
+	* The node this orchestrator runs on, with any forked-child `/addon`
+	* suffix stripped. A location whose `nodeId` differs is NOT this node's
+	* to touch — its bytes, and its free space, live elsewhere.
+	*/
+	getLocalNodeId(): string;
+	/** True once a persistence store is wired (constructor or {@link attachStore}). */
+	hasStore(): boolean;
+	/**
+	* Late-bind the persistence store (production boot: the `settings-store`
+	* cap registers after the orchestrator initializes, so the service runs
+	* in-memory-only until then). Idempotent — a second call once a store is
+	* wired is a no-op.
+	*
+	* Reconciles both directions so operator edits survive a reboot:
+	*   1. hydrate — DB rows win over any early in-memory seed (restores
+	*      operator config like `minFreePercent` that the pre-store boot
+	*      can't see);
+	*   2. backfill — in-memory locations the DB doesn't have yet (the
+	*      pre-store seed defaults on a fresh install) are persisted, so the
+	*      store becomes the durable source of truth from here on.
+	*
+	* **The re-entry guard latches on a SUCCESSFUL hydrate, not on the attempt** —
+	* `loadAll()` is awaited BEFORE `this.locationStore` is assigned, and the
+	* order is load-bearing. Latching first meant one transient read error
+	* answered `hasStore()` true forever, so the addon's `ensureStoreWired` gate
+	* skipped every retry; the service then ran the whole process lifetime on
+	* pre-store seed defaults while `upsert` mirrored them onto rows it had never
+	* read, silently replacing the operator's persisted `minFreePercent`. Failing
+	* back to store-less is the safe direction: an in-memory-only service writes
+	* nothing over what is on disk, and the next `capability:provider-registered`
+	* event tries again. Held by
+	* `__tests__/storage-orchestrator-persistence.spec.ts`.
+	*/
+	attachStore(store: ILocationStore): Promise<void>;
+	/**
+	* ONE explicit migration onto the four-state model (D385), run once per boot
+	* against the rows that came off disk. Idempotent: the second boot finds
+	* nothing to do.
+	*
+	* Two steps, in order, and each one is a WRITE — the point is that "absent"
+	* stops existing rather than being re-interpreted on every read forever:
+	*
+	*   1. A row with no `mode` is stamped with the mode its legacy flags imply
+	*      (`legacyModeOf`): `config.readOnly === true` → `readonly` and the
+	*      config key is DELETED; `enabled === false` → `readonly` (the
+	*      CONSERVATIVE direction — a state change must never start deleting
+	*      footage on its own); everything else → `active`. `withLocationMode`
+	*      derives `enabled` from the mode, so the two can never disagree, and
+	*      this subsumes the D383 pass that stamped flagless rows `enabled: true`.
+	*   2. A type left with NO write target — only reachable from a hand-edited
+	*      store or a row an older build wrote — gets one made `active`, chosen as
+	*      the row the RETIRED default flag named, else the `:default`-slugged
+	*      row, else the lexicographically first. Loudly: a class with no write
+	*      target records nowhere, and refusing to repair it here would leave the
+	*      hub silently unable to write with no operator action pending.
+	*
+	* An operator's explicit `readonly`/`drain`/`disabled` is never reversed by
+	* step 1 — only step 2 touches it, and only when the alternative is a class
+	* that cannot write at all.
+	*
+	* On the live hub every location is enabled with no `readOnly`, so step 1 is
+	* a no-op that stamps `active` and nothing else changes.
+	*/
+	private migrateOntoTheWriteSet;
+	/** Apply one migrated row in memory and mirror it to the store. */
+	private persistMigrated;
+	/**
+	* Inject the declaration-driven cardinality source. Called once by the
+	* addon after the kernel aggregates every addon's `storageLocations`
+	* declarations into a `StorageLocationRegistry`.
+	*/
+	setRegistry(registry: DeclarationSource | null): void;
+	/**
+	* Inject the synchronous `providerId → nodeLocal` resolver (SP1). Called
+	* by the addon from a cached snapshot of every `storage-provider`'s
+	* `getProviderInfo().nodeLocal`, refreshed when the provider collection
+	* changes. Powers the node-local upsert guard and the boot backfill.
+	*/
+	setNodeLocalResolver(resolver: NodeLocalResolver | null): void;
+	/**
+	* Inject the "does this location still hold anything" probe read by
+	* {@link deleteLocation}. Absent → every delete sees `unknown` and therefore
+	* REFUSES without `force`, which is the safe direction for a service wired
+	* without one.
+	*/
+	setOccupancyProbe(probe: LocationOccupancyProbe | null): void;
+	/**
+	* The full set of addon-declared storage locations, as aggregated by
+	* the kernel and injected via {@link setRegistry}. Powers the admin-UI
+	* Data screen's per-declaration grouping. Empty until the registry is
+	* injected (early-boot / in-memory-only path).
+	*/
+	listDeclarations(): readonly StorageLocationDeclaration[];
+	/**
+	* Hydrate the in-memory map from the persistence layer. Called once
+	* by the addon during `onInitialize`, before the eager seed pass.
+	* Idempotent — running it twice with the same store contents
+	* produces the same map. No-op when the service was constructed
+	* without a store.
+	*
+	* Errors loading individual rows are tolerated: the bad row is
+	* skipped and logged so a single corrupted record doesn't lock the
+	* whole orchestrator out of boot. (The store-side validation pass
+	* before insert means only schema-invalid SQL state can produce
+	* such a row.)
+	*/
+	initialize(): Promise<void>;
+	/**
+	* Boot backfill (SP1): stamp `nodeId` on every persisted node-local
+	* location that lacks one. Single-node deployments seeded their
+	* filesystem locations before `nodeId` existed — they live on `hubNodeId`
+	* (the hub). Node-agnostic (remote) locations are left untouched: their
+	* absent `nodeId` is correct (reachable from any node).
+	*
+	* Idempotent — a location that already carries a `nodeId` (any value) is
+	* never re-touched, so re-running on a populated map (or a re-boot) is a
+	* no-op. A plain local update, not versioned-migration machinery: only
+	* the rows missing `nodeId` are mutated + persisted.
+	*
+	* No-op until the node-local resolver is wired (it classifies which
+	* providers are node-local).
+	*/
+	backfillNodeIds(hubNodeId: string): Promise<void>;
+	listLocations(filter?: ListLocationsFilter): readonly StorageLocation[];
+	/**
+	* The WRITE SET of a type: every enabled location of it, in stable id order.
+	* This replaced `getDefaultLocation` (D383) — a type does not have one write
+	* target any more, it has a pool, and every consumer that must pick one picks
+	* from here by its own rule (the recorder by headroom, a drain by an operator
+	* -named destination).
+	*/
+	writeTargets(type: string): readonly StorageLocation[];
+	/**
+	* Change the WRITE SET as one compensated commit: each named location is
+	* enabled (it joins the pool) or disabled (it becomes read-only — still read,
+	* still played back, still age-swept, still drained).
+	*
+	* This is the cutover verb, and its only caller is the migration coordinator,
+	* which persists its `repointing` phase BEFORE calling so a crash mid-write
+	* is recovered by replaying the same idempotent set before writers resume.
+	*
+	* It moves ONLY the locations it is given: a cutover from A to C on a class
+	* that also writes to B leaves B in the pool, because the operator's pool is
+	* the authority and a migration is not a licence to shrink it. The commit is
+	* refused when it would leave a write-serving type with nothing enabled —
+	* the same refusal `upsertLocation` applies, judged on the RESULT so an
+	* enable and a disable in one commit are weighed together.
+	*/
+	setWriteTargets(enabledByLocationId: ReadonlyMap<string, boolean>): Promise<void>;
+	/**
+	* Insert or update a location.
+	*
+	* When a persistence store is wired (Task 6), the record is mirrored to it;
+	* the mirror is fire-and-forget and its errors reach the logger.
+	*/
+	/**
+	* Refuse a `(location kind, provider)` pair the kind cannot use.
+	*
+	* The rule, in one line: a `'local-path'` kind requires a provider whose
+	* `getProviderInfo().nodeLocal` is `true`.
+	*
+	* `nodeLocal` is the honest name for "this provider's `resolve` returns a
+	* path on the filesystem of the node that resolved it". The
+	* `storage-provider` cap's own discriminated union already forces every
+	* provider to declare it, and all four remote providers declare `false`, so
+	* no new cap surface is needed to ask the question.
+	*
+	* Three-valued on purpose. Only a POSITIVE `false` refuses:
+	*  - `true`      → node-local, always fine.
+	*  - `false`     → the provider is known and known to be remote. REFUSE.
+	*  - `undefined` → the provider has not registered yet (early boot, an addon
+	*    still loading). That is "unknown", not "remote", and a read that could
+	*    not be made must never destroy work (D49) — the system seed runs
+	*    through this path before any provider registers. Allowed, and logged,
+	*    so the allowance is never silent.
+	*
+	* The DECLARATION side is read the same way. A kind the registry does not
+	* know is `local-path` (fail-closed: an unknown kind is not a permissive
+	* one), but NO REGISTRY AT ALL is a different statement — nothing has been
+	* loaded, so nothing can be concluded about any kind. The addon injects the
+	* registry inside `onInitialize`, before the `storage` cap is mounted, so
+	* there is no window in which an operator upsert sees this branch; a service
+	* constructed without one is the in-memory/early-boot path.
+	*/
+	private refuseIncompatibleProvider;
+	upsertLocation(input: Omit<StorageLocation, "createdAt" | "updatedAt">): StorageLocation;
+	/**
+	* Remove a location. Refuses the last location of a type and the last
+	* enabled location of a type. `isSystem` is informational — a frozen
+	* recordings `:default` is deletable once a sibling is live. Occupancy still
+	* refuses unless `force` is set; force never overrides uniqueness /
+	* last-enabled.
+	*/
+	deleteLocation(id: string, options?: DeleteLocationOptions): Promise<void>;
+	/**
+	* Run the injected occupancy probe, converting "no probe" and "the probe
+	* threw" into `unknown` rather than into a permit.
+	*/
+	private probeOccupancy;
+	/**
+	* Remove seed-shaped locations (`<type>:default`) whose type is no longer
+	* declared by any addon (stale defaults from a removed location type).
+	* Operator-added locations of an undeclared type are KEPT but warned.
+	*
+	* FAIL-SAFE: if the registry is EMPTY (no addon declared any location), we
+	* refuse to prune anything. An empty registry almost always means
+	* declarations failed to load (boot ordering, a stale install) — pruning
+	* "everything undeclared" in that state would wipe every seeded location
+	* (data/logs/recordings/…). Better to keep stale rows than destroy live ones.
+	*/
+	pruneUndeclaredSystemLocations(): void;
+	/**
+	* Resolve a `StorageLocationRef` to a concrete `StorageLocation`.
+	*  - bare type (e.g. `'backups'`) → default location of that type
+	*  - fully-qualified id (e.g. `'backups:nas-01'`) → that exact instance
+	*
+	* Throws an actionable error when nothing matches — every consumer of
+	* the singleton `storage` cap funnels through here, so the error
+	* message is what operators see when the orchestrator's view of the
+	* world doesn't match expectations.
+	*/
+	resolveRef(ref: StorageLocationRef): StorageLocation;
+	/**
+	* Find the storage-provider that backs a given location — the entry point
+	* every consumer-facing `storage` cap method funnels through.
+	*
+	* Routing key is `(providerId, nodeId)`, never `providerId` alone: every
+	* node's FilesystemStorageProvider registers under the SAME providerId, so
+	* a providerId-only match resolves to whichever node asked. That is how a
+	* location created on an agent ended up writing to the HUB's filesystem
+	* (root-caused 2026-07-29).
+	*/
+	getProviderFor(location: StorageLocation): Promise<IStorageProviderImpl>;
+	/**
+	* Resolve one dispatch target to the provider that must execute it.
+	*
+	* `descriptor` is the operator-facing subject of the error message
+	* (`location "recordings:disk"`, `uploadId "u-42"`); `locationId` is the
+	* structured tag for the log line when there is a location behind the
+	* dispatch (chunked sessions carry only the session id).
+	*
+	* Both failure branches LOG before throwing, and NEITHER falls back to the
+	* local provider — a silent fallback is the bug this method exists to fix.
+	*/
+	private getProviderForTarget;
+	/**
+	* Remember which provider — and on which NODE — opened a chunked session.
+	* `beginUpload` / `beginDownload` carry a `StorageLocation`; every later
+	* chunk carries only the session id, and a session id issued by an agent
+	* means nothing to the hub's provider.
+	*/
+	rememberSession(kind: StorageSessionKind, sessionId: string, location: StorageLocation): void;
+	/** Drop a session's routing entry (finalize / abort / end). */
+	forgetSession(kind: StorageSessionKind, sessionId: string): void;
+	/** Drop every session entry (addon shutdown). */
+	clearSessions(): void;
+	/**
+	* Resolve the provider that owns an in-flight chunked session, on the node
+	* that opened it. Throws when the orchestrator has no record of the open
+	* call (provider gone, or a chunk for a session it never issued).
+	*/
+	getProviderForSession(kind: StorageSessionKind, sessionId: string): Promise<IStorageProviderImpl>;
+	/** Convenience: lookup by id (returns `undefined` if not found). */
+	getLocationById(id: string): StorageLocation | undefined;
+	/**
+	* Seed one default `StorageLocation` per addon-declared location that
+	* doesn't already have one. Idempotent — re-running with the same
+	* declarations on a populated map is a no-op (each declared `id`
+	* already resolves to an existing `<id>:default`).
+	*
+	* The seeded row is born ENABLED — a fresh install must be able to write the
+	* moment it boots, and `enabled` is the only write switch there is (D383).
+	* The `:default` suffix is a NAME kept for idempotency across existing
+	* installs, not a flag: the stored `id` is `'recordings:default'` so it
+	* satisfies the
+	* `^[a-z][a-z0-9-]*:[a-z0-9-]+$` regex on `StorageLocationSchema.id`.
+	*
+	* `basePath` is the storage root (e.g. `<CAMSTACK_DATA>`). Each
+	* location's `config.basePath` is `<basePath>/<id>`, except when the
+	* declaration sets `defaultsTo` — then it inherits the resolved root of
+	* the referenced location's default instance (sharing the same root
+	* directory for derivative slots like `recordingsLow` → `recordings`).
+	*/
+	seedDefaults(input: {
+		readonly providerId: string;
+		readonly basePath: string;
+		/**
+		* Root for declarations marked `defaultRoot: 'media'` (the dedicated media
+		* volume, `CAMSTACK_MEDIA_ROOT`). Absent → media declarations fall back to
+		* `basePath` like everything else.
+		*/
+		readonly mediaBasePath?: string;
+		/**
+		* Root for declarations marked `defaultRoot: 'backup'` (the dedicated
+		* backup volume, `CAMSTACK_BACKUP_ROOT`, default `/backups`). Absent →
+		* backup declarations fall back to `basePath`.
+		*/
+		readonly backupBasePath?: string;
+		readonly declarations: readonly StorageLocationDeclaration[];
+	}): void;
+	/**
+	* The same-type physical-root refusal (D389).
+	*
+	* An unresolvable root — another node's disk, a remote provider, a path that
+	* does not exist yet — WARNS and lets the write through. Refusing on a read
+	* that could not be taken blocks the operator on a doubt, and the recorder's
+	* demotion still catches what slips past (D49's spirit).
+	*/
+	private refuseSameTypeRootCollision;
+	/** Injectable so a test can drive symlinks and unresolvable paths without
+	*  touching a real filesystem. Production takes the shared derivation. */
+	private resolveRoot;
+	/** Test seam for {@link refuseSameTypeRootCollision}. */
+	setRootResolver(resolveRoot: ResolveRoot): void;
+	/** Internal: check whether any location of the given type exists. */
+	private hasAnyLocationOfType;
 }