@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/backup-orchestrator/destination-policy.d.ts

@@ -1,88 +1,105 @@
-import { CollectionColumn, ISettingsStoreProvider } from '@camstack/types';
 /**
- * Per-`backups`-location policy. `locationId` is the foreign-key into
- * the storage orchestrator's `storage_locations` table.
- *
- * `enabled` gates whether scheduled / unspecified-target backups fan out
- * to this destination; operators can disable a destination temporarily
- * without deleting the underlying `StorageLocation`.
- *
- * `retentionCount` is independent per destination — destination A may
- * keep 3 archives while B keeps 30.
- *
- * `label` is an optional operator-defined display string. When omitted
- * the orchestrator falls back to the `StorageLocation.displayName`.
- */
+* Per-destination policy storage for the backup orchestrator
+* (Task 9 of the storage-unification refactor — backup arch carry-over).
+*
+* Each row is keyed by `locationId` (the `<type>:<slug>` id of a
+* `backups`-typed `StorageLocation`). The orchestrator now reads the
+* authoritative list of destinations from the storage cap
+* (`api.storage.listLocations({ type: 'backups' })`) and joins it with
+* this table to produce the wire-shape `BackupDestinationInfo` consumed
+* by the admin UI. There is no longer a `backup-destination` cap call
+* in the path.
+*
+* Contract mirror of `SqliteLocationStore` (storage-orchestrator): lazy
+* `declareCollection` so the constructor stays sync, and every read/write on
+* the `settings-store` collection surface. Callers obtain the provider via
+* `kernel.capabilityRegistry.getSingleton<ISettingsStoreProvider>('settings-store')`.
+*/
+import type { CollectionColumn, ISettingsStoreProvider } from "@camstack/types";
+/**
+* Per-`backups`-location policy. `locationId` is the foreign-key into
+* the storage orchestrator's `storage_locations` table.
+*
+* `enabled` gates whether scheduled / unspecified-target backups fan out
+* to this destination; operators can disable a destination temporarily
+* without deleting the underlying `StorageLocation`.
+*
+* `retentionCount` is independent per destination — destination A may
+* keep 3 archives while B keeps 30.
+*
+* `label` is an optional operator-defined display string. When omitted
+* the orchestrator falls back to the `StorageLocation.displayName`.
+*/
 export interface BackupDestinationPolicy {
-    readonly locationId: string;
-    readonly enabled: boolean;
-    readonly retentionCount: number;
-    readonly label?: string;
-    /**
-     * ms-epoch of the last time a run ATTEMPTED to write an archive here,
-     * whatever the outcome. Never a success stamp — `lastError` says whether
-     * the attempt landed, and the newest manifest entry says when one last
-     * did. Rows written before 2026-07-28 carry the old per-location
-     * scheduler's stamp, which had exactly this meaning.
-     */
-    readonly lastAttemptAt?: number;
-    /**
-     * Why the last attempt failed, verbatim from the provider. Cleared on the
-     * next attempt that lands. A destination that has never been written to
-     * has neither field, and that is REPORTED as never — D384.
-     */
-    readonly lastError?: string;
+	readonly locationId: string;
+	readonly enabled: boolean;
+	readonly retentionCount: number;
+	readonly label?: string;
+	/**
+	* ms-epoch of the last time a run ATTEMPTED to write an archive here,
+	* whatever the outcome. Never a success stamp — `lastError` says whether
+	* the attempt landed, and the newest manifest entry says when one last
+	* did. Rows written before 2026-07-28 carry the old per-location
+	* scheduler's stamp, which had exactly this meaning.
+	*/
+	readonly lastAttemptAt?: number;
+	/**
+	* Why the last attempt failed, verbatim from the provider. Cleared on the
+	* next attempt that lands. A destination that has never been written to
+	* has neither field, and that is REPORTED as never — D384.
+	*/
+	readonly lastError?: string;
 }
 export declare const BACKUP_DESTINATION_POLICIES_COLUMNS: readonly CollectionColumn[];
 export declare class BackupDestinationPolicyService {
-    private readonly store;
-    private declared;
-    constructor(store: ISettingsStoreProvider);
-    /**
-     * Lazy `declareCollection` — called from every read/write path.
-     * `declareCollection` is idempotent, so repeated calls collapse to a no-op
-     * after the first. This keeps the constructor synchronous and avoids a
-     * separate `initialize()` step that callers could forget.
-     */
-    initialize(): Promise<void>;
-    private ensureDeclared;
-    list(): Promise<readonly BackupDestinationPolicy[]>;
-    get(locationId: string): Promise<BackupDestinationPolicy | null>;
-    /**
-     * Replace-or-insert. Implemented as delete + insert, mirroring the
-     * `SqliteLocationStore` contract.
-     */
-    upsert(p: BackupDestinationPolicy): Promise<void>;
-    delete(locationId: string): Promise<void>;
-    /**
-     * Auto-create a default policy for a `backups` location seen for the
-     * first time (returns the existing policy unchanged when present).
-     * The orchestrator calls this lazily on the first `listDestinations`
-     * pass so newly-added storage locations are surfaced as enabled
-     * destinations without an explicit configuration step.
-     *
-     * Defaults are passed by the orchestrator (currently `retentionCount=7`).
-     * A fresh destination is enabled and keeps 7 archives; it gets NO cadence
-     * of its own — a destination runs when a schedule fans out to it, and
-     * seeding a cron here would advertise a nightly run nothing performs
-     * (D384).
-     */
-    ensureDefault(locationId: string, defaults: {
-        retentionCount: number;
-    }): Promise<BackupDestinationPolicy>;
-    /**
-     * Stamp the outcome of ONE attempted write to this destination.
-     *
-     * Read-modify-write on the policy row so the operator's `enabled`,
-     * `retentionCount` and `label` survive. A destination with no row yet
-     * gets one — an attempt on an unseen location must still be recorded, or
-     * the failure disappears with the process (which is exactly how a 03:00
-     * SMB refusal stayed invisible until the operator went looking).
-     */
-    recordAttempt(locationId: string, outcome: {
-        attemptAt: number;
-        error?: string;
-    }, defaults: {
-        retentionCount: number;
-    }): Promise<void>;
+	private readonly store;
+	private declared;
+	constructor(store: ISettingsStoreProvider);
+	/**
+	* Lazy `declareCollection` — called from every read/write path.
+	* `declareCollection` is idempotent, so repeated calls collapse to a no-op
+	* after the first. This keeps the constructor synchronous and avoids a
+	* separate `initialize()` step that callers could forget.
+	*/
+	initialize(): Promise<void>;
+	private ensureDeclared;
+	list(): Promise<readonly BackupDestinationPolicy[]>;
+	get(locationId: string): Promise<BackupDestinationPolicy | null>;
+	/**
+	* Replace-or-insert. Implemented as delete + insert, mirroring the
+	* `SqliteLocationStore` contract.
+	*/
+	upsert(p: BackupDestinationPolicy): Promise<void>;
+	delete(locationId: string): Promise<void>;
+	/**
+	* Auto-create a default policy for a `backups` location seen for the
+	* first time (returns the existing policy unchanged when present).
+	* The orchestrator calls this lazily on the first `listDestinations`
+	* pass so newly-added storage locations are surfaced as enabled
+	* destinations without an explicit configuration step.
+	*
+	* Defaults are passed by the orchestrator (currently `retentionCount=7`).
+	* A fresh destination is enabled and keeps 7 archives; it gets NO cadence
+	* of its own — a destination runs when a schedule fans out to it, and
+	* seeding a cron here would advertise a nightly run nothing performs
+	* (D384).
+	*/
+	ensureDefault(locationId: string, defaults: {
+		retentionCount: number;
+	}): Promise<BackupDestinationPolicy>;
+	/**
+	* Stamp the outcome of ONE attempted write to this destination.
+	*
+	* Read-modify-write on the policy row so the operator's `enabled`,
+	* `retentionCount` and `label` survive. A destination with no row yet
+	* gets one — an attempt on an unseen location must still be recorded, or
+	* the failure disappears with the process (which is exactly how a 03:00
+	* SMB refusal stayed invisible until the operator went looking).
+	*/
+	recordAttempt(locationId: string, outcome: {
+		attemptAt: number;
+		error?: string;
+	}, defaults: {
+		retentionCount: number;
+	}): Promise<void>;
 }

package/dist/builtins/backup-orchestrator/download-helpers.d.ts

@@ -1,12 +1,12 @@
-import { IScopedLogger } from '@camstack/types';
-import { ChunkedDownloadApi } from './manifest-store.js';
+import type { IScopedLogger } from "@camstack/types";
+import type { ChunkedDownloadApi } from "./manifest-store.js";
 export interface DownloadArchiveInput {
-    readonly api: ChunkedDownloadApi;
-    readonly locationId: string;
-    readonly filename: string;
-    readonly cachePath: string;
-    /** Per-chunk byte budget. Matches the upload helper's 8 MiB. */
-    readonly chunkBytes: number;
-    readonly logger: IScopedLogger;
+	readonly api: ChunkedDownloadApi;
+	readonly locationId: string;
+	readonly filename: string;
+	readonly cachePath: string;
+	/** Per-chunk byte budget. Matches the upload helper's 8 MiB. */
+	readonly chunkBytes: number;
+	readonly logger: IScopedLogger;
 }
 export declare function downloadArchiveToCache(input: DownloadArchiveInput): Promise<void>;

package/dist/builtins/backup-orchestrator/encryption-key-store.d.ts

@@ -1,36 +1,47 @@
-import { ISettingsStoreProvider } from '@camstack/types';
 /**
- * @durable class=config owner=backup-orchestrator
- *   write="`setupEncryption` inserts one row per generated key and retires the
- *     previous active row; `disableEncryption` retires the active row"
- *   retention="none — one small row per key ever generated; a retired row
- *     names the key older archives need"
- */
+* The backup encryption setting (operator decision 2026-10-09): which backup
+* PUBLIC key new archives are encrypted to, and the keys used before.
+*
+* The secret key is never here — it is shown once at setup and kept by the
+* operator (see `system-backup/backup-encryption.ts` for why). A retired key
+* stays listed so the Backup page can say which key an older archive needs.
+*
+* A read that fails THROWS: a backup run must never take "could not read the
+* setting" for "encryption is off" and ship a plain archive.
+*/
+import type { ISettingsStoreProvider } from "@camstack/types";
+/**
+* @durable class=config owner=backup-orchestrator
+*   write="`setupEncryption` inserts one row per generated key and retires the
+*     previous active row; `disableEncryption` retires the active row"
+*   retention="none — one small row per key ever generated; a retired row
+*     names the key older archives need"
+*/
 export declare const BACKUP_ENCRYPTION_KEYS_COLLECTION = "backup_encryption_keys";
 export interface BackupEncryptionKeyRecord {
-    readonly keyId: string;
-    readonly publicKey: string;
-    readonly createdAt: number;
-    readonly retiredAt: number | null;
+	readonly keyId: string;
+	readonly publicKey: string;
+	readonly createdAt: number;
+	readonly retiredAt: number | null;
 }
-type Store = Pick<ISettingsStoreProvider, 'declareCollection' | 'query' | 'insert' | 'deleteWhere'>;
+type Store = Pick<ISettingsStoreProvider, "declareCollection" | "query" | "insert" | "deleteWhere">;
 export declare class BackupEncryptionKeyStore {
-    private readonly store;
-    private readonly now;
-    private declared;
-    constructor(store: Store, now?: () => number);
-    private ensureDeclared;
-    /** Every key, newest first. */
-    list(): Promise<readonly BackupEncryptionKeyRecord[]>;
-    /** The key new archives are encrypted to; `null` = encryption off. */
-    active(): Promise<BackupEncryptionKeyRecord | null>;
-    /** Make `publicKey` the active key; the previous one is retired, kept listed. */
-    activate(input: {
-        readonly publicKey: string;
-    }): Promise<BackupEncryptionKeyRecord>;
-    /** Encryption off: the active key is retired. Archives already made keep needing it. */
-    disable(): Promise<void>;
-    private retireActive;
-    private write;
+	private readonly store;
+	private readonly now;
+	private declared;
+	constructor(store: Store, now?: () => number);
+	private ensureDeclared;
+	/** Every key, newest first. */
+	list(): Promise<readonly BackupEncryptionKeyRecord[]>;
+	/** The key new archives are encrypted to; `null` = encryption off. */
+	active(): Promise<BackupEncryptionKeyRecord | null>;
+	/** Make `publicKey` the active key; the previous one is retired, kept listed. */
+	activate(input: {
+		readonly publicKey: string;
+	}): Promise<BackupEncryptionKeyRecord>;
+	/** Encryption off: the active key is retired. Archives already made keep needing it. */
+	disable(): Promise<void>;
+	private retireActive;
+	private write;
 }
 export {};

package/dist/builtins/backup-orchestrator/index.d.ts

@@ -1,2 +1,2 @@
-export { BackupOrchestratorAddon } from './backup-orchestrator.addon.js';
-export { BackupOrchestratorAddon as default } from './backup-orchestrator.addon.js';
+export { BackupOrchestratorAddon } from "./backup-orchestrator.addon.js";
+export { BackupOrchestratorAddon as default } from "./backup-orchestrator.addon.js";

package/dist/builtins/backup-orchestrator/manifest-store.d.ts

@@ -1,95 +1,114 @@
-import { AddonApi } from '@camstack/types';
-import { ArchiveManifest } from '../system-backup/system-backup.service.js';
+/**
+* Per-location backup manifest persistence (Task 10 of the storage-
+* unification refactor).
+*
+* Each `backups`-typed `StorageLocation` carries a single
+* `manifests.json` file at its root. The orchestrator reads/appends/
+* writes this file via the consumer-facing `storage` cap — there is
+* no on-disk path coupling, the storage provider (filesystem, SFTP,
+* S3, …) handles dispatch.
+*
+* Concurrency: the orchestrator serializes per-location reads/writes
+* through `withLocationLock` so a fan-out of N parallel destination
+* uploads can't interleave manifest mutations within the same
+* location. Across locations, mutations run in parallel.
+*
+* Wire shape mirrors the spec: each archive entry carries an inline
+* snapshot of the embedded `ArchiveManifest` so `getEntries` can
+* serve the contents preview without re-reading the tarball.
+*/
+import type { AddonApi } from "@camstack/types";
+import type { ArchiveManifest } from "../system-backup/system-backup.service.js";
 /** File path (relative to the location root) where the index lives. */
 export declare const MANIFESTS_FILENAME = "manifests.json";
 export interface ManifestArchiveEntry {
-    readonly id: string;
-    /** Filename inside the location (e.g. `<id>.tar.gz`). */
-    readonly filename: string;
-    readonly createdAt: number;
-    readonly sizeBytes: number;
-    readonly label?: string;
-    /**
-     * Snapshot of the embedded `.camstack-backup-manifest.json`. For an
-     * ENCRYPTED archive only its outline (locations, totals, no file list): the
-     * destination holds this index in clear, and the file list stays inside the
-     * ciphertext.
-     */
-    readonly manifest: ArchiveManifest;
-    /** Present when the archive is encrypted to a backup key. */
-    readonly encryption?: ManifestArchiveEncryption;
+	readonly id: string;
+	/** Filename inside the location (e.g. `<id>.tar.gz`). */
+	readonly filename: string;
+	readonly createdAt: number;
+	readonly sizeBytes: number;
+	readonly label?: string;
+	/**
+	* Snapshot of the embedded `.camstack-backup-manifest.json`. For an
+	* ENCRYPTED archive only its outline (locations, totals, no file list): the
+	* destination holds this index in clear, and the file list stays inside the
+	* ciphertext.
+	*/
+	readonly manifest: ArchiveManifest;
+	/** Present when the archive is encrypted to a backup key. */
+	readonly encryption?: ManifestArchiveEncryption;
 }
 export interface ManifestArchiveEncryption {
-    readonly scheme: string;
-    readonly keyId: string;
+	readonly scheme: string;
+	readonly keyId: string;
 }
 export interface LocationBackupManifest {
-    readonly version: 1;
-    readonly archives: readonly ManifestArchiveEntry[];
+	readonly version: 1;
+	readonly archives: readonly ManifestArchiveEntry[];
 }
 /** Subset of `AddonApi['storage']` the manifest store consumes. */
-export type ManifestStorageApi = Pick<AddonApi['storage'], 'read' | 'write' | 'exists'>;
+export type ManifestStorageApi = Pick<AddonApi["storage"], "read" | "write" | "exists">;
 /**
- * Subset of `AddonApi['storage']` consumed by the chunked-download
- * helper. Sourced from the same generated type so the contract stays
- * in lockstep with the live cap surface.
- */
-export type ChunkedDownloadApi = Pick<AddonApi['storage'], 'beginDownload' | 'readChunk' | 'endDownload'>;
+* Subset of `AddonApi['storage']` consumed by the chunked-download
+* helper. Sourced from the same generated type so the contract stays
+* in lockstep with the live cap surface.
+*/
+export type ChunkedDownloadApi = Pick<AddonApi["storage"], "beginDownload" | "readChunk" | "endDownload">;
 /**
- * Read the per-location manifest. Returns an empty manifest on first
- * use (when `manifests.json` doesn't exist) or when the file is
- * unreadable / corrupt — operators see destination state degrade
- * gracefully rather than the orchestrator crashing.
- */
+* Read the per-location manifest. Returns an empty manifest on first
+* use (when `manifests.json` doesn't exist) or when the file is
+* unreadable / corrupt — operators see destination state degrade
+* gracefully rather than the orchestrator crashing.
+*/
 export declare function readLocationManifest(api: ManifestStorageApi, locationId: string): Promise<LocationBackupManifest>;
 export declare function writeLocationManifest(api: ManifestStorageApi, locationId: string, manifest: LocationBackupManifest): Promise<void>;
 /**
- * Decode the raw bytes of `manifests.json`. Falls back to an empty
- * manifest on JSON-parse / shape-validation failure — same defensive
- * stance as the legacy `LocalBackupService.ensureManifestsLoaded`.
- */
+* Decode the raw bytes of `manifests.json`. Falls back to an empty
+* manifest on JSON-parse / shape-validation failure — same defensive
+* stance as the legacy `LocalBackupService.ensureManifestsLoaded`.
+*/
 export declare function parseManifestBytes(bytes: Uint8Array): LocationBackupManifest;
 /**
- * What the destination's clear-text index may say about an encrypted archive:
- * the outline a restore needs (locations, sizes, the snapshot promise) — not
- * the list of files, which stays inside the ciphertext.
- */
+* What the destination's clear-text index may say about an encrypted archive:
+* the outline a restore needs (locations, sizes, the snapshot promise) — not
+* the list of files, which stays inside the ciphertext.
+*/
 export declare function outlineOfManifest(manifest: ArchiveManifest): ArchiveManifest;
 /**
- * Build a `ManifestArchiveEntry` from the raw inputs collected during
- * a successful upload. Pure transform — no I/O — kept here so the
- * triggerBackup path stays terse.
- */
+* Build a `ManifestArchiveEntry` from the raw inputs collected during
+* a successful upload. Pure transform — no I/O — kept here so the
+* triggerBackup path stays terse.
+*/
 export declare function buildArchiveEntry(input: {
-    id: string;
-    filename: string;
-    createdAt: number;
-    sizeBytes: number;
-    label?: string;
-    manifest: ArchiveManifest;
-    encryption?: ManifestArchiveEncryption;
+	id: string;
+	filename: string;
+	createdAt: number;
+	sizeBytes: number;
+	label?: string;
+	manifest: ArchiveManifest;
+	encryption?: ManifestArchiveEncryption;
 }): ManifestArchiveEntry;
 /**
- * Pure retention split: given an archive list and the operator's
- * `retentionCount`, return `{ keep, drop }` where `keep` is the most-
- * recent N archives (newest first) and `drop` is the older overflow.
- *
- * `retentionCount <= 0` is treated as "no pruning" — defensive against
- * a config value that would otherwise wipe every archive on the next
- * write.
- */
+* Pure retention split: given an archive list and the operator's
+* `retentionCount`, return `{ keep, drop }` where `keep` is the most-
+* recent N archives (newest first) and `drop` is the older overflow.
+*
+* `retentionCount <= 0` is treated as "no pruning" — defensive against
+* a config value that would otherwise wipe every archive on the next
+* write.
+*/
 export declare function applyRetention(archives: readonly ManifestArchiveEntry[], retentionCount: number): {
-    readonly keep: readonly ManifestArchiveEntry[];
-    readonly drop: readonly ManifestArchiveEntry[];
+	readonly keep: readonly ManifestArchiveEntry[];
+	readonly drop: readonly ManifestArchiveEntry[];
 };
 /**
- * Per-location async mutex. The orchestrator owns one instance and
- * funnels every read-modify-write of `manifests.json` through it so
- * parallel destination uploads (within the same location) commit in
- * arrival order. Across locations the operations run in parallel —
- * each location keys its own promise chain.
- */
+* Per-location async mutex. The orchestrator owns one instance and
+* funnels every read-modify-write of `manifests.json` through it so
+* parallel destination uploads (within the same location) commit in
+* arrival order. Across locations the operations run in parallel —
+* each location keys its own promise chain.
+*/
 export declare class LocationManifestLock {
-    private readonly chains;
-    run<T>(locationId: string, fn: () => Promise<T>): Promise<T>;
+	private readonly chains;
+	run<T>(locationId: string, fn: () => Promise<T>): Promise<T>;
 }

package/dist/builtins/backup-orchestrator/restore-archive.d.ts

@@ -1,24 +1,24 @@
 /** An encrypted backup was asked to restore without its key. */
 export declare class BackupKeyRequiredError extends Error {
-    readonly keyId: string;
-    constructor(keyId: string);
+	readonly keyId: string;
+	constructor(keyId: string);
 }
 /**
- * Before downloading gigabytes: does the operator's key fit what the
- * destination's manifest says the archive needs? `archiveKeyId` undefined =
- * the manifest records no encryption (the header check after the download
- * remains the authority).
- */
+* Before downloading gigabytes: does the operator's key fit what the
+* destination's manifest says the archive needs? `archiveKeyId` undefined =
+* the manifest records no encryption (the header check after the download
+* remains the authority).
+*/
 export declare function precheckRestoreKey(archiveKeyId: string | undefined, secretKey: string | undefined): void;
 export interface PrepareRestoreInput {
-    /** The archive as downloaded from the destination. Consumed (deleted or renamed). */
-    readonly downloaded: string;
-    /** Where the restore marker will point: a plain `.tar.gz`. */
-    readonly target: string;
-    readonly secretKey?: string;
+	/** The archive as downloaded from the destination. Consumed (deleted or renamed). */
+	readonly downloaded: string;
+	/** Where the restore marker will point: a plain `.tar.gz`. */
+	readonly target: string;
+	readonly secretKey?: string;
 }
 export interface PreparedRestore {
-    readonly encrypted: boolean;
-    readonly keyId?: string;
+	readonly encrypted: boolean;
+	readonly keyId?: string;
 }
 export declare function prepareRestoreArchive(input: PrepareRestoreInput): Promise<PreparedRestore>;