@camstack/system 1.0.2

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

@@ -0,0 +1,49 @@
+import { ISettingsBackend, StorageLocation } from '@camstack/types';
+/**
+ * Abstract storage interface for `StorageLocation` records. Methods are
+ * async because production-side implementations hit SQLite — but the
+ * orchestrator's mutation paths fire-and-forget the writes so a slow
+ * disk doesn't block the cap surface.
+ */
+export interface ILocationStore {
+    /** Read every persisted location. Called once at boot. */
+    loadAll(): Promise<readonly StorageLocation[]>;
+    /** Insert or replace a single location by id. */
+    upsert(loc: StorageLocation): Promise<void>;
+    /** Remove a location by id. */
+    delete(id: string): Promise<void>;
+}
+/**
+ * SQLite-backed implementation of `ILocationStore` — uses the
+ * `settings-store` cap's structured-table surface (`ensureTable` /
+ * `tableInsert` / `tableUpdate` / `tableDelete` / `tableQuery`). Wired
+ * to the live `ISettingsBackend` provider obtained from
+ * `kernel.capabilityRegistry.getSingleton('settings-store')`.
+ *
+ * The cap-router surface (`ctx.api.settingsStore.*`) does NOT expose
+ * the `tableXxx` methods — they're only on the raw `ISettingsBackend`.
+ * Same constraint that drives `IntegrationRegistry` to take a direct
+ * provider reference instead of going through the cap.
+ */
+export declare class SqliteLocationStore implements ILocationStore {
+    private readonly backend;
+    private tableEnsured;
+    constructor(backend: ISettingsBackend);
+    /**
+     * Lazy `ensureTable` — keeps the constructor cheap and async-free.
+     * Called from every mutation/read path; the backend's `ensureTable`
+     * is itself idempotent (additive migration), so repeated calls are
+     * effectively no-ops after the first.
+     */
+    private ensureTable;
+    loadAll(): Promise<readonly StorageLocation[]>;
+    /**
+     * Replace-or-insert. Implemented as `delete` + `insert` rather than
+     * the conditional `tableUpdate` path because the orchestrator
+     * serializes every mutation through the in-memory map before
+     * dispatching to the store — there's no contention to lose, and the
+     * delete-then-insert path is unconditionally simpler.
+     */
+    upsert(loc: StorageLocation): Promise<void>;
+    delete(id: string): Promise<void>;
+}

package/dist/builtins/storage-orchestrator/provider-discovery.d.ts

@@ -0,0 +1,10 @@
+import { IStorageProviderImpl, IStorageCapProvider } from '@camstack/types';
+/** One entry of the `storage.listProviders` output array. */
+export type StorageProviderListEntry = Awaited<ReturnType<IStorageCapProvider['listProviders']>>[number];
+/**
+ * Callback invoked when a provider's `getProviderInfo()` throws. The array
+ * `index` is passed so the orchestrator can identify which provider failed —
+ * `getProviderInfo()` itself threw, so there is no static id to log otherwise.
+ */
+export type ProviderInfoErrorHandler = (provider: IStorageProviderImpl, error: unknown, index: number) => void;
+export declare function collectProviderInfos(providers: readonly IStorageProviderImpl[], onError: ProviderInfoErrorHandler): Promise<StorageProviderListEntry[]>;

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

@@ -0,0 +1,103 @@
+import { BaseAddon, ProviderRegistration } from '@camstack/types';
+interface StorageOrchestratorConfig extends Record<string, unknown> {
+}
+export declare class StorageOrchestratorAddon extends BaseAddon<StorageOrchestratorConfig> {
+    private service;
+    private pressureManager;
+    private pressureTimer;
+    private pressureSweepInFlight;
+    /**
+     * `uploadId` → providerId. Populated on `beginUpload`, consulted on
+     * every subsequent `writeChunk` / `finalizeUpload` / `abortUpload`,
+     * cleared on terminal calls. The provider holds the actual session
+     * state (open file descriptor, buffered offsets, …) — we just
+     * remember which provider owns it.
+     */
+    private readonly uploadOwners;
+    /** Symmetric to `uploadOwners` for download sessions. */
+    private readonly downloadOwners;
+    /**
+     * Cached `providerId → nodeLocal` snapshot (SP1). Backs the orchestrator's
+     * synchronous `NodeLocalResolver` — `getProviderInfo()` is async, so we
+     * keep a sync cache and refresh it whenever the provider collection
+     * changes (alongside the seed pass). Absent providerId → resolver returns
+     * `undefined` (treated as node-agnostic).
+     */
+    private readonly nodeLocalByProvider;
+    /**
+     * Disposers run on `onShutdown` — currently the eventBus subscription
+     * for `capability:provider-registered` events used by the lazy seed
+     * fallback. Stored separately from the `BaseAddon` disposer chain so
+     * it can be inspected in tests.
+     */
+    private readonly seedSubscriptionDisposers;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    /**
+     * Resolve the live `ISettingsBackend` from the capability registry
+     * and wrap it in a `SqliteLocationStore`. Returns `null` when the
+     * settings-store cap isn't registered yet — the service falls back
+     * to in-memory only. Production boot order (sqlite-settings runs
+     * before the orchestrator) makes this the rare path.
+     */
+    private resolveLocationStore;
+    /**
+     * Late-wire the persistence store once the `settings-store` cap registers.
+     * Production boot order means the store is usually absent at
+     * `onInitialize`; this runs on every `capability:provider-registered`
+     * event until it succeeds. Single-flighted + idempotent (the service
+     * ignores a second attach). Without this, operator edits (e.g. a
+     * location's `minFreePercent`) live only in memory and are wiped on every
+     * restart — the service never hydrates from / persists to SQLite.
+     */
+    private storeWireInFlight;
+    private ensureStoreWired;
+    private storageProviders;
+    /** Single-flighted pressure sweep — never overlaps a slow eviction round. */
+    private runPressureSweep;
+    /**
+     * locationId → resolved `minFreePercent`. The policy is intrinsic to the
+     * location's provider (`shouldSaveDiskSpace` gates the guard, `minFreePercent`
+     * is the default), overridable per-location via `config.minFreePercent`.
+     * Locations with the guard off (or threshold 0) are omitted. Moved here from
+     * the recorder so disk-pressure is a single core concern.
+     */
+    private resolveLocationThresholds;
+    private locationBasePath;
+    /** Free capacity (%) on a location's volume via `statfs`; 100 (guard inert) when unstattable. */
+    private locationFreePercent;
+    /** Total bytes on a location's volume via `statfs`; 0 when unstattable. */
+    private locationVolumeTotalBytes;
+    /**
+     * Seed default storage locations from the addon-declared
+     * `storageLocations`, aggregated by the kernel into a
+     * `StorageLocationRegistry`. Idempotent — re-running on a populated
+     * map is a no-op (each declared id's `<id>:default` is already in the
+     * service's map).
+     *
+     * `basePath` is the filesystem storage root, falling back to
+     * `process.env.CAMSTACK_DATA ?? path.resolve(process.cwd(), 'camstack-data')`.
+     * Every declared default is attributed to the `filesystem-storage`
+     * provider; operators repoint individual locations (or add remote
+     * SFTP/S3/WebDAV instances) through the admin UI afterwards.
+     */
+    private seedFromDeclarations;
+    /**
+     * Rebuild the `providerId → nodeLocal` cache from every registered
+     * `storage-provider`'s `getProviderInfo()`. Cheap registry scan; runs on
+     * boot and on every provider-registered reconcile. Failed probes are
+     * skipped (the provider stays absent → treated as node-agnostic).
+     */
+    private refreshNodeLocalCache;
+    private resolveByUploadId;
+    private resolveByDownloadId;
+    /**
+     * Look up a `storage-provider` by `providerId` only — used for
+     * upload / download dispatch where the original `StorageLocation` is
+     * no longer in scope. Throws if the provider has gone away (e.g.
+     * addon unloaded mid-session).
+     */
+    private providerByProviderId;
+}
+export default StorageOrchestratorAddon;