@camstack/core 0.1.15 → 0.1.17

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-orchestrator.addon.mjs","names":[],"sources":["../../../src/builtins/storage-orchestrator/storage-orchestrator.service.ts","../../../src/builtins/storage-orchestrator/location-store.ts","../../../src/builtins/storage-orchestrator/storage-orchestrator.addon.ts"],"sourcesContent":["/**\n * Routing core for the `storage-orchestrator` builtin.\n *\n * Owns the in-memory `locationId → StorageLocation` map and the\n * `providerId → IStorageProviderImpl` lookup. Every consumer-facing\n * `storage` cap call lands here:\n *   1. `resolveRef(ref)` — bare type or fully-qualified id → concrete location\n *   2. `getProviderFor(location)` — match `location.providerId` against the\n *      live set of `storage-provider` collection providers\n *\n * The provider lookup is injected (`getProviders`) so unit tests can\n * pass fixtures without booting a real CapabilityRegistry. The addon\n * wires the production lookup to\n * `ctx.kernel.capabilityRegistry?.getCollection<IStorageProviderImpl>('storage-provider')`.\n *\n * Task 5 adds first-boot seeding of default locations from each\n * `storage-provider`'s `getProviderInfo().supportedLocationTypes`.\n * Task 6 adds an optional `ILocationStore` for SQLite persistence —\n * `initialize()` hydrates the in-memory map from the store, and every\n * `upsertLocation` / `deleteLocation` mirrors the change to the store.\n * Tests pass `null` (or a fake `ILocationStore`) for in-memory-only\n * operation; production wires `SqliteLocationStore`.\n */\nimport type {\n  IScopedLogger,\n  IStorageProviderImpl,\n  StorageLocation,\n  StorageLocationRef,\n  StorageLocationType,\n} from '@camstack/types'\nimport {\n  StorageLocationTypeSchema,\n  DEFAULT_LOCATION_SUBDIRS,\n  STORAGE_LOCATION_CARDINALITY,\n} from '@camstack/types'\nimport * as path from 'node:path'\nimport type { ILocationStore } from './location-store.js'\n\nexport interface ListLocationsFilter {\n  readonly type?: StorageLocationType\n}\n\n/**\n * Provider lookup callback. Returns the live set of `storage-provider`\n * registrants. Called per-dispatch (cheap registry scan) so newly\n * loaded addons surface immediately.\n */\nexport type StorageProviderLookup = () => readonly IStorageProviderImpl[]\n\nexport class StorageOrchestratorService {\n  private readonly locations: Map<string, StorageLocation> = new Map()\n\n  constructor(\n    private readonly logger: IScopedLogger,\n    private readonly getProviders: StorageProviderLookup,\n    /**\n     * Optional persistence backend. When supplied, `initialize()`\n     * hydrates the in-memory map from the store, and every mutation\n     * (upsert/delete) mirrors to it. When `null` / `undefined`, the\n     * service is in-memory only — the contract used by the existing\n     * routing tests, where re-creating the service deliberately\n     * forgets every location.\n     */\n    private readonly locationStore: ILocationStore | null = null,\n  ) {}\n\n  /**\n   * Hydrate the in-memory map from the persistence layer. Called once\n   * by the addon during `onInitialize`, before the eager seed pass.\n   * Idempotent — running it twice with the same store contents\n   * produces the same map. No-op when the service was constructed\n   * without a store.\n   *\n   * Errors loading individual rows are tolerated: the bad row is\n   * skipped and logged so a single corrupted record doesn't lock the\n   * whole orchestrator out of boot. (The store-side validation pass\n   * before insert means only schema-invalid SQL state can produce\n   * such a row.)\n   */\n  async initialize(): Promise<void> {\n    if (!this.locationStore) return\n    const rows = await this.locationStore.loadAll()\n    let upgraded = 0\n    for (const loc of rows) {\n      // One-shot upgrade for legacy rows seeded before the `isSystem`\n      // column existed: seed-shaped ids (`<type>:default`) are always\n      // system-protected. Without this, a fresh-from-old-DB boot would\n      // expose the bootstrap defaults to operator deletion.\n      if (!loc.isSystem && loc.id === `${loc.type}:default`) {\n        const upgradedLoc: StorageLocation = { ...loc, isSystem: true }\n        this.locations.set(upgradedLoc.id, upgradedLoc)\n        // Persist the upgrade so subsequent boots skip the rewrite.\n        const store = this.locationStore\n        void store.upsert(upgradedLoc).catch((err) => {\n          this.logger.warn('storage-orchestrator: isSystem upgrade persist failed', {\n            meta: { id: upgradedLoc.id, error: err instanceof Error ? err.message : String(err) },\n          })\n        })\n        upgraded++\n      } else {\n        this.locations.set(loc.id, loc)\n      }\n    }\n    this.logger.info('storage-orchestrator: hydrated locations from store', {\n      meta: { loaded: this.locations.size, isSystemUpgraded: upgraded },\n    })\n  }\n\n  // ── Location CRUD ─────────────────────────────────────────────────────\n\n  listLocations(filter?: ListLocationsFilter): readonly StorageLocation[] {\n    const all = [...this.locations.values()]\n    return filter?.type ? all.filter(l => l.type === filter.type) : all\n  }\n\n  getDefaultLocation(type: StorageLocationType): StorageLocation | null {\n    for (const loc of this.locations.values()) {\n      if (loc.type === type && loc.isDefault) return loc\n    }\n    return null\n  }\n\n  /**\n   * Insert or update a location. If `isDefault: true`, atomically\n   * demotes any other default for the same type — operators always see\n   * exactly one default per type.\n   *\n   * When a persistence store is wired (Task 6), the new record AND any\n   * implicitly-demoted siblings are persisted before the in-memory map\n   * mutation returns. Persistence errors propagate to the caller.\n   */\n  upsertLocation(input: Omit<StorageLocation, 'createdAt' | 'updatedAt'>): StorageLocation {\n    const now = Date.now()\n    const existing = this.locations.get(input.id)\n\n    // Cardinality guard — singleton types reject \"Add\" attempts (an\n    // upsert with no matching `id` already in the map). Editing the\n    // existing singleton is fine; adding a parallel one would split\n    // state in a way consumers can't reconcile (two `addons-data`\n    // roots, two `data` paths for sqlite, …).\n    if (!existing) {\n      const cardinality = STORAGE_LOCATION_CARDINALITY[input.type]\n      if (cardinality === 'singleton') {\n        const already = [...this.locations.values()].find(l => l.type === input.type)\n        if (already) {\n          throw new Error(\n            `Storage type \"${input.type}\" is singleton — only one location allowed (existing: \"${already.id}\"). Edit it instead of adding a new one.`,\n          )\n        }\n      }\n    }\n    // System-protected fields cannot be flipped by the operator. Once\n    // a location is seeded as `isSystem: true`, edits preserve that\n    // flag — the addon owns the lifecycle, not the operator.\n    if (existing?.isSystem === true) {\n      input = { ...input, isSystem: true }\n    }\n\n    const next: StorageLocation = {\n      ...input,\n      createdAt: existing?.createdAt ?? now,\n      updatedAt: now,\n    }\n    const demoted: StorageLocation[] = []\n    if (next.isDefault) {\n      for (const [otherId, otherLoc] of this.locations) {\n        if (otherLoc.type === next.type && otherLoc.id !== next.id && otherLoc.isDefault) {\n          const updated: StorageLocation = { ...otherLoc, isDefault: false, updatedAt: now }\n          this.locations.set(otherId, updated)\n          demoted.push(updated)\n        }\n      }\n    }\n    this.locations.set(next.id, next)\n    this.logger.debug('storage-orchestrator: upsertLocation', {\n      meta: { id: next.id, type: next.type, providerId: next.providerId, isDefault: next.isDefault },\n    })\n    // Persistence is best-effort fire-and-forget on the upsert path —\n    // the service stays sync (the cap surface awaits provider methods,\n    // not the orchestrator's own writes). Errors are surfaced to the\n    // logger so an SQLite hiccup doesn't silently desync.\n    if (this.locationStore) {\n      const store = this.locationStore\n      void (async () => {\n        try {\n          for (const d of demoted) await store.upsert(d)\n          await store.upsert(next)\n        } catch (err) {\n          this.logger.error('storage-orchestrator: upsert persistence failed', {\n            meta: { id: next.id, error: err instanceof Error ? err.message : String(err) },\n          })\n        }\n      })()\n    }\n    return next\n  }\n\n  /**\n   * Remove a location. Refuses to remove the default of a type unless a\n   * sibling default exists (defensive — `upsertLocation` already ensures\n   * at most one default per type, but the logic guards against future\n   * bypass paths e.g. SQLite migration that imports two defaults).\n   *\n   * Persistence (Task 6) mirrors the delete asynchronously, with errors\n   * routed to the logger — see `upsertLocation` for the rationale.\n   */\n  deleteLocation(id: string): void {\n    const loc = this.locations.get(id)\n    if (!loc) {\n      throw new Error(`Storage location \"${id}\" not found`)\n    }\n    if (loc.isSystem) {\n      throw new Error(\n        `Storage location \"${id}\" is system-managed and cannot be deleted. Edit its config (path / providerId) instead.`,\n      )\n    }\n    if (loc.isDefault) {\n      const otherDefault = [...this.locations.values()].find(\n        l => l.type === loc.type && l.id !== id && l.isDefault,\n      )\n      if (!otherDefault) {\n        throw new Error(\n          `Cannot delete default location \"${id}\" for type \"${loc.type}\" — promote another location to default first`,\n        )\n      }\n    }\n    this.locations.delete(id)\n    if (this.locationStore) {\n      const store = this.locationStore\n      void store.delete(id).catch((err) => {\n        this.logger.error('storage-orchestrator: delete persistence failed', {\n          meta: { id, error: err instanceof Error ? err.message : String(err) },\n        })\n      })\n    }\n  }\n\n  // ── Ref resolution ────────────────────────────────────────────────────\n\n  /**\n   * Resolve a `StorageLocationRef` to a concrete `StorageLocation`.\n   *  - bare type (e.g. `'backups'`) → default location of that type\n   *  - fully-qualified id (e.g. `'backups:nas-01'`) → that exact instance\n   *\n   * Throws an actionable error when nothing matches — every consumer of\n   * the singleton `storage` cap funnels through here, so the error\n   * message is what operators see when the orchestrator's view of the\n   * world doesn't match expectations.\n   */\n  resolveRef(ref: StorageLocationRef): StorageLocation {\n    if (ref.includes(':')) {\n      const loc = this.locations.get(ref)\n      if (!loc) {\n        throw new Error(`Storage location \"${ref}\" not found`)\n      }\n      return loc\n    }\n    // Bare-type form — must match one of the closed enum values.\n    const parsed = StorageLocationTypeSchema.safeParse(ref)\n    if (!parsed.success) {\n      throw new Error(\n        `Invalid storage location ref \"${ref}\" — expected a StorageLocationType or a fully-qualified id (\\`<type>:<slug>\\`)`,\n      )\n    }\n    const def = this.getDefaultLocation(parsed.data)\n    if (!def) {\n      throw new Error(\n        `No default storage location configured for type \"${parsed.data}\" — register one or pass a fully-qualified id (\\`<type>:<slug>\\`)`,\n      )\n    }\n    return def\n  }\n\n  // ── Provider lookup ───────────────────────────────────────────────────\n\n  /**\n   * Find the storage-provider that backs a given location. Lookup is by\n   * `location.providerId` against `getProviderInfo().providerId` from\n   * each registered collection provider. Throws with both the missing\n   * providerId and the offending location id so the operator can pick\n   * the right place to fix the config.\n   */\n  async getProviderFor(location: StorageLocation): Promise<IStorageProviderImpl> {\n    const providers = this.getProviders()\n    for (const p of providers) {\n      const info = await p.getProviderInfo()\n      if (info.providerId === location.providerId) return p\n    }\n    throw new Error(\n      `No storage-provider registered for providerId \"${location.providerId}\" (location \"${location.id}\")`,\n    )\n  }\n\n  /** Convenience: lookup by id (returns `undefined` if not found). */\n  getLocationById(id: string): StorageLocation | undefined {\n    return this.locations.get(id)\n  }\n\n  // ── First-boot seeding (Task 5) ───────────────────────────────────────\n\n  /**\n   * Seed one default `StorageLocation` per `supportedTypes` entry that\n   * doesn't already have one. Idempotent — re-running with the same\n   * provider info on a populated map is a no-op (each entry already\n   * resolves on `id === <type>:default`).\n   *\n   * Convention: the bare-type ref `'backups'` resolves via\n   * `getDefaultLocation('backups')` (walks `isDefault === true`); the\n   * actual stored `id` is `'backups:default'` so it satisfies the\n   * `^[a-z][a-z0-9-]*:[a-z0-9-]+$` regex on `StorageLocationSchema.id`.\n   *\n   * `basePath` is the provider's storage root (e.g. the filesystem\n   * provider's `<CAMSTACK_DATA>` dir). Each location's `config.basePath`\n   * is set to `<basePath>/<DEFAULT_LOCATION_SUBDIRS[type]>` — except\n   * when the subdir is already absolute (today only `cache` →\n   * `/tmp/camstack-cache`), in which case it's used verbatim. The\n   * filesystem provider re-derives the same path on its own — this\n   * config field is purely an operator-visible record of what was\n   * provisioned. Task 7 will refactor providers to honour the\n   * location's `config.basePath` directly.\n   */\n  seedDefaults(input: {\n    readonly providerId: string\n    readonly supportedTypes: readonly StorageLocationType[]\n    readonly basePath: string\n  }): void {\n    let added = 0\n    for (const type of input.supportedTypes) {\n      // Skip types already covered for any provider — first wins.\n      if (this.hasAnyLocationOfType(type)) continue\n      const subdir = DEFAULT_LOCATION_SUBDIRS[type]\n      const fullPath = path.isAbsolute(subdir) ? subdir : path.join(input.basePath, subdir)\n      const id = `${type}:default`\n      this.upsertLocation({\n        id,\n        type,\n        displayName: DEFAULT_DISPLAY_NAMES[type],\n        providerId: input.providerId,\n        config: { basePath: fullPath },\n        isDefault: true,\n        // Seeded defaults are system-protected — operators can edit\n        // the config (e.g. relocate the path) but cannot delete them\n        // outright. Without the seed, consumers (sqlite-settings,\n        // backup-orchestrator, recordings, …) lose their target.\n        isSystem: true,\n      })\n      added++\n    }\n    if (added > 0) {\n      this.logger.info('storage-orchestrator: seeded default locations', {\n        meta: { providerId: input.providerId, added, basePath: input.basePath },\n      })\n    }\n  }\n\n  /** Internal: check whether any location of the given type exists. */\n  private hasAnyLocationOfType(type: StorageLocationType): boolean {\n    for (const loc of this.locations.values()) {\n      if (loc.type === type) return true\n    }\n    return false\n  }\n}\n\n/**\n * Operator-facing names for the default seeded location of each\n * `StorageLocationType`. Kept in this module (not in `interfaces/`)\n * because they're a concern of the orchestrator's seed step — operator\n * UI reads `location.displayName` after seeding.\n */\nconst DEFAULT_DISPLAY_NAMES: Readonly<Record<StorageLocationType, string>> = {\n  'data':              'Local Data',\n  'media':             'Local Media',\n  'recordings':        'Local Recordings',\n  'recordings-high':   'Local Recordings (High)',\n  'recordings-low':    'Local Recordings (Low)',\n  'recordings-clips':  'Local Recordings (Clips)',\n  'event-images':      'Local Event Images',\n  'models':            'Local Models',\n  'addons-data':       'Local Addons Data',\n  'cache':             'Local Cache',\n  'logs':              'Local Logs',\n  'backups':           'Local Backups',\n}\n","/**\n * Persistence layer for the storage-orchestrator's `StorageLocation`\n * map (Task 6 of the storage-unification refactor).\n *\n * The service depends only on the abstract `ILocationStore` —\n * production wires `SqliteLocationStore` (settings-backend-backed),\n * tests pass a fake (in-memory `Map`-backed) implementation. Same\n * pattern as `IntegrationRegistry` in `sqlite-storage/`.\n */\nimport type {\n  ISettingsBackend,\n  StorageLocation,\n  StorageLocationType,\n  TableSchema,\n} from '@camstack/types'\nimport { StorageLocationTypeSchema, parseJsonObject } from '@camstack/types'\n\n/**\n * Abstract storage interface for `StorageLocation` records. Methods are\n * async because production-side implementations hit SQLite — but the\n * orchestrator's mutation paths fire-and-forget the writes so a slow\n * disk doesn't block the cap surface.\n */\nexport interface ILocationStore {\n  /** Read every persisted location. Called once at boot. */\n  loadAll(): Promise<readonly StorageLocation[]>\n  /** Insert or replace a single location by id. */\n  upsert(loc: StorageLocation): Promise<void>\n  /** Remove a location by id. */\n  delete(id: string): Promise<void>\n}\n\nconst STORAGE_LOCATIONS_TABLE = 'storage_locations'\n\nconst STORAGE_LOCATIONS_SCHEMA: TableSchema = {\n  columns: [\n    { name: 'id', type: 'TEXT', primaryKey: true },\n    { name: 'type', type: 'TEXT', notNull: true },\n    { name: 'display_name', type: 'TEXT', notNull: true },\n    { name: 'provider_id', type: 'TEXT', notNull: true },\n    { name: 'config', type: 'TEXT', notNull: true, defaultValue: '{}' },\n    { name: 'is_default', type: 'INTEGER', notNull: true, defaultValue: 0 },\n    { name: 'is_system', type: 'INTEGER', notNull: true, defaultValue: 0 },\n    { name: 'created_at', type: 'INTEGER', notNull: true },\n    { name: 'updated_at', type: 'INTEGER', notNull: true },\n  ],\n  indexes: [\n    { name: 'idx_storage_locations_type', columns: ['type'] },\n  ],\n}\n\n/**\n * SQLite-backed implementation of `ILocationStore` — uses the\n * `settings-store` cap's structured-table surface (`ensureTable` /\n * `tableInsert` / `tableUpdate` / `tableDelete` / `tableQuery`). Wired\n * to the live `ISettingsBackend` provider obtained from\n * `kernel.capabilityRegistry.getSingleton('settings-store')`.\n *\n * The cap-router surface (`ctx.api.settingsStore.*`) does NOT expose\n * the `tableXxx` methods — they're only on the raw `ISettingsBackend`.\n * Same constraint that drives `IntegrationRegistry` to take a direct\n * provider reference instead of going through the cap.\n */\nexport class SqliteLocationStore implements ILocationStore {\n  private tableEnsured = false\n\n  constructor(private readonly backend: ISettingsBackend) {}\n\n  /**\n   * Lazy `ensureTable` — keeps the constructor cheap and async-free.\n   * Called from every mutation/read path; the backend's `ensureTable`\n   * is itself idempotent (additive migration), so repeated calls are\n   * effectively no-ops after the first.\n   */\n  private async ensureTable(): Promise<void> {\n    if (this.tableEnsured) return\n    if (!this.backend.ensureTable) {\n      throw new Error(\n        'SqliteLocationStore: settings backend does not implement ensureTable — ' +\n        'expected the SQLite settings backend, got a backend without structured-table support',\n      )\n    }\n    await this.backend.ensureTable(STORAGE_LOCATIONS_TABLE, STORAGE_LOCATIONS_SCHEMA)\n    this.tableEnsured = true\n  }\n\n  async loadAll(): Promise<readonly StorageLocation[]> {\n    await this.ensureTable()\n    if (!this.backend.tableQuery) return []\n    const rows = await this.backend.tableQuery(STORAGE_LOCATIONS_TABLE, {\n      orderBy: { field: 'created_at', direction: 'asc' },\n    })\n    const out: StorageLocation[] = []\n    for (const row of rows) {\n      const mapped = mapRowToLocation(row)\n      if (mapped) out.push(mapped)\n    }\n    return out\n  }\n\n  /**\n   * Replace-or-insert. Implemented as `delete` + `insert` rather than\n   * the conditional `tableUpdate` path because the orchestrator\n   * serializes every mutation through the in-memory map before\n   * dispatching to the store — there's no contention to lose, and the\n   * delete-then-insert path is unconditionally simpler.\n   */\n  async upsert(loc: StorageLocation): Promise<void> {\n    await this.ensureTable()\n    if (!this.backend.tableDelete || !this.backend.tableInsert) {\n      throw new Error('SqliteLocationStore: backend missing tableDelete/tableInsert')\n    }\n    await this.backend.tableDelete(STORAGE_LOCATIONS_TABLE, { id: loc.id })\n    await this.backend.tableInsert(STORAGE_LOCATIONS_TABLE, mapLocationToRow(loc))\n  }\n\n  async delete(id: string): Promise<void> {\n    await this.ensureTable()\n    if (!this.backend.tableDelete) {\n      throw new Error('SqliteLocationStore: backend missing tableDelete')\n    }\n    await this.backend.tableDelete(STORAGE_LOCATIONS_TABLE, { id })\n  }\n}\n\n// ── Row ↔ record mapping ──────────────────────────────────────────────\n\nfunction mapLocationToRow(loc: StorageLocation): Record<string, unknown> {\n  return {\n    id: loc.id,\n    type: loc.type,\n    display_name: loc.displayName,\n    provider_id: loc.providerId,\n    config: JSON.stringify(loc.config),\n    is_default: loc.isDefault ? 1 : 0,\n    is_system: loc.isSystem ? 1 : 0,\n    created_at: loc.createdAt,\n    updated_at: loc.updatedAt,\n  }\n}\n\n/**\n * Decode a row read from the structured table. Returns `null` when the\n * row's `type` doesn't parse against the Zod enum — the caller skips\n * the row and logs. Defensive against schema drift across upgrades\n * (e.g. an older build wrote a since-removed `recordings-archive`\n * type and the new build no longer recognises it).\n */\nfunction mapRowToLocation(row: Record<string, unknown>): StorageLocation | null {\n  const typeRaw = row['type']\n  const parsedType = StorageLocationTypeSchema.safeParse(typeRaw)\n  if (!parsedType.success) return null\n  const type: StorageLocationType = parsedType.data\n\n  const id = String(row['id'] ?? '')\n  if (!id) return null\n\n  // Defensive JSON parse: corrupt rows (hand-edited, written by an\n  // older build, partial migration, …) shouldn't lock the\n  // orchestrator out of boot — fall back to an empty config and let\n  // the location be served with whatever the provider's defaults are.\n  const configRaw = row['config']\n  const config: Record<string, unknown> = typeof configRaw === 'string' && configRaw.length > 0\n    ? (parseJsonObject(configRaw) ?? {})\n    : {}\n\n  return {\n    id,\n    type,\n    displayName: String(row['display_name'] ?? ''),\n    providerId: String(row['provider_id'] ?? ''),\n    config,\n    isDefault: row['is_default'] === 1 || row['is_default'] === true,\n    isSystem: row['is_system'] === 1 || row['is_system'] === true,\n    createdAt: Number(row['created_at'] ?? 0),\n    updatedAt: Number(row['updated_at'] ?? 0),\n  }\n}\n","/**\n * `storage-orchestrator` builtin — singleton owner of the consumer-\n * facing `storage` cap.\n *\n * Responsibilities:\n *   - Hold the `locationId → StorageLocation` map (in-memory; Task 6\n *     adds persistence).\n *   - Resolve `StorageLocationRef` → concrete `StorageLocation`.\n *   - Dispatch every cap method to the right `storage-provider`\n *     (collection cap, registered by `filesystem-storage` and future\n *     SFTP / S3 / WebDAV addons).\n *   - Track ownership of upload / download sessions so chunked I/O\n *     (which carries no `location` after the first hop) can route\n *     subsequent chunks to the same provider.\n *   - First-boot seed defaults from each provider's\n *     `getProviderInfo().supportedLocationTypes` (Task 5). Re-runs on\n *     every `capability:provider-registered` event so providers that\n *     register after the orchestrator boots also get seeded — the\n *     `hasAnyLocationOfType` guard makes the operation idempotent.\n *\n * Task 6 will plug a persistence backend in front of the in-memory map.\n * Task 7 will migrate consumers off the legacy storage shim.\n */\nimport { BaseAddon, storageCapability } from '@camstack/types'\nimport type {\n  IStorageCapProvider,\n  IStorageProviderImpl,\n  ISettingsBackend,\n  ProviderRegistration,\n  StorageLocation,\n  StorageLocationType,\n  IEventBus,\n} from '@camstack/types'\nimport * as path from 'node:path'\nimport { StorageOrchestratorService } from './storage-orchestrator.service.js'\nimport { SqliteLocationStore, type ILocationStore } from './location-store.js'\n\nconst STORAGE_PROVIDER_CAP_NAME = 'storage-provider'\n\n/**\n * Raw event category emitted by `CapabilityRegistry.registerProvider` —\n * not in the typed `EventCategory` enum because it lives in the kernel\n * infra layer (every cap-bound event is a custom-shape payload).\n */\nconst CAP_PROVIDER_REGISTERED_CATEGORY = 'capability:provider-registered'\n\ninterface StorageOrchestratorConfig extends Record<string, unknown> {}\n\nexport class StorageOrchestratorAddon extends BaseAddon<StorageOrchestratorConfig> {\n  private service: StorageOrchestratorService | null = null\n\n  /**\n   * `uploadId` → providerId. Populated on `beginUpload`, consulted on\n   * every subsequent `writeChunk` / `finalizeUpload` / `abortUpload`,\n   * cleared on terminal calls. The provider holds the actual session\n   * state (open file descriptor, buffered offsets, …) — we just\n   * remember which provider owns it.\n   */\n  private readonly uploadOwners: Map<string, string> = new Map()\n  /** Symmetric to `uploadOwners` for download sessions. */\n  private readonly downloadOwners: Map<string, string> = new Map()\n\n  /**\n   * Disposers run on `onShutdown` — currently the eventBus subscription\n   * for `capability:provider-registered` events used by the lazy seed\n   * fallback. Stored separately from the `BaseAddon` disposer chain so\n   * it can be inspected in tests.\n   */\n  private readonly seedSubscriptionDisposers: Array<() => void> = []\n\n  constructor() {\n    super({})\n  }\n\n  protected async onInitialize(): Promise<ProviderRegistration[]> {\n    const getProviders = (): readonly IStorageProviderImpl[] => {\n      const reg = this.ctx.kernel.capabilityRegistry\n      if (!reg) return []\n      return reg.getCollection<IStorageProviderImpl>(STORAGE_PROVIDER_CAP_NAME)\n    }\n\n    // Wire the persistence backend (Task 6). Skipped if the\n    // settings-store cap hasn't registered a provider yet (e.g. early\n    // boot tests, or a deployment without the sqlite-settings builtin\n    // mounted) — the service falls back to in-memory only.\n    const locationStore = this.resolveLocationStore()\n\n    const service = new StorageOrchestratorService(\n      this.ctx.logger,\n      getProviders,\n      locationStore,\n    )\n    this.service = service\n\n    // Hydrate persisted locations BEFORE seeding so re-seeds skip\n    // already-persisted defaults (the seed step's\n    // `hasAnyLocationOfType` gate looks at the in-memory map).\n    await service.initialize()\n\n    const provider: IStorageCapProvider = {\n      // ── Location management ─────────────────────────────────────────\n      listLocations: async ({ type }) => {\n        return type !== undefined\n          ? service.listLocations({ type })\n          : service.listLocations()\n      },\n      getDefaultLocation: async ({ type }) => service.getDefaultLocation(type),\n      upsertLocation: async (input) => service.upsertLocation(input),\n      deleteLocation: async ({ id }) => {\n        service.deleteLocation(id)\n      },\n      testLocation: async ({ id }) => {\n        const loc = service.getLocationById(id)\n        if (!loc) return { ok: false, error: `Location \"${id}\" not found` }\n        try {\n          const p = await service.getProviderFor(loc)\n          return p.testLocation({ config: loc.config })\n        } catch (err) {\n          return { ok: false, error: err instanceof Error ? err.message : String(err) }\n        }\n      },\n\n      // ── Provider discovery ──────────────────────────────────────────\n      // Walk every registered `storage-provider`, collect each one's\n      // `getProviderInfo()` blob. Used by the admin-UI \"Add location\"\n      // wizard. Errors from individual providers are isolated — a\n      // single misbehaving driver shouldn't deny the whole list.\n      listProviders: async () => {\n        const providers = getProviders()\n        const out: Array<{\n          providerId: string\n          displayName: string\n          supportedLocationTypes: readonly StorageLocationType[]\n          configSchema: unknown\n        }> = []\n        for (const p of providers) {\n          try {\n            const info = await p.getProviderInfo()\n            out.push({\n              providerId: info.providerId,\n              displayName: info.displayName,\n              supportedLocationTypes: info.supportedLocationTypes,\n              configSchema: info.configSchema,\n            })\n          } catch (err) {\n            this.ctx.logger.warn('storage-orchestrator: getProviderInfo failed', {\n              meta: { error: err instanceof Error ? err.message : String(err) },\n            })\n          }\n        }\n        return out\n      },\n\n      // Probe a candidate config against a specific provider WITHOUT\n      // persisting. Lets the wizard preflight credentials (SFTP / S3\n      // / WebDAV) before the operator commits. Validation errors are\n      // returned in `error`; transport errors are caught + reported.\n      testConfig: async ({ providerId, config }) => {\n        const providers = getProviders()\n        for (const p of providers) {\n          try {\n            const info = await p.getProviderInfo()\n            if (info.providerId !== providerId) continue\n            return p.testLocation({ config })\n          } catch (err) {\n            return { ok: false, error: err instanceof Error ? err.message : String(err) }\n          }\n        }\n        return { ok: false, error: `No storage-provider registered for providerId \"${providerId}\"` }\n      },\n\n      // ── Small-file primitives — every method resolves the ref then\n      // dispatches the inline-location form to the provider. ──────────\n      resolve: async ({ location, relativePath }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        return p.resolve({ location: loc, relativePath })\n      },\n      write: async ({ location, relativePath, data }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        return p.write({ location: loc, relativePath, data })\n      },\n      read: async ({ location, relativePath }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        return p.read({ location: loc, relativePath })\n      },\n      exists: async ({ location, relativePath }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        return p.exists({ location: loc, relativePath })\n      },\n      list: async ({ location, prefix }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        return prefix !== undefined\n          ? p.list({ location: loc, prefix })\n          : p.list({ location: loc })\n      },\n      delete: async ({ location, relativePath }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        return p.delete({ location: loc, relativePath })\n      },\n      getAvailableSpace: async ({ location }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        return p.getAvailableSpace({ location: loc })\n      },\n\n      // ── Chunked upload — first call records ownership, subsequent\n      // calls look it up. Cleanup happens in finalize/abort. ──────────\n      beginUpload: async ({ location, relativePath, sizeBytes }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        const result = sizeBytes !== undefined\n          ? await p.beginUpload({ location: loc, relativePath, sizeBytes })\n          : await p.beginUpload({ location: loc, relativePath })\n        this.uploadOwners.set(result.uploadId, loc.providerId)\n        return result\n      },\n      writeChunk: async (input) => {\n        const p = await this.resolveByUploadId(input.uploadId)\n        return p.writeChunk(input)\n      },\n      finalizeUpload: async (input) => {\n        const p = await this.resolveByUploadId(input.uploadId)\n        try {\n          return await p.finalizeUpload(input)\n        } finally {\n          this.uploadOwners.delete(input.uploadId)\n        }\n      },\n      abortUpload: async (input) => {\n        const p = await this.resolveByUploadId(input.uploadId)\n        try {\n          return await p.abortUpload(input)\n        } finally {\n          this.uploadOwners.delete(input.uploadId)\n        }\n      },\n\n      // ── Chunked download (symmetric to upload) ──────────────────────\n      beginDownload: async ({ location, relativePath }) => {\n        const loc = service.resolveRef(location)\n        const p = await service.getProviderFor(loc)\n        const result = await p.beginDownload({ location: loc, relativePath })\n        this.downloadOwners.set(result.downloadId, loc.providerId)\n        return result\n      },\n      readChunk: async (input) => {\n        const p = await this.resolveByDownloadId(input.downloadId)\n        return p.readChunk(input)\n      },\n      endDownload: async (input) => {\n        const p = await this.resolveByDownloadId(input.downloadId)\n        try {\n          return await p.endDownload(input)\n        } finally {\n          this.downloadOwners.delete(input.downloadId)\n        }\n      },\n    }\n\n    // Eager seed pass — covers the case where filesystem-storage (or\n    // any other storage-provider) already registered before the\n    // orchestrator booted. Lazy pass below catches providers that\n    // register later.\n    await this.seedFromAllProviders()\n\n    // Lazy pass — `CapabilityRegistry.registerProvider` emits\n    // `capability:provider-registered` on the kernel event bus; we\n    // re-run the seed step every time the storage-provider collection\n    // grows. `hasAnyLocationOfType` keeps the operation idempotent.\n    const eventBus = this.ctx.eventBus as IEventBus | undefined\n    if (eventBus) {\n      const unsub = eventBus.subscribe(\n        { category: CAP_PROVIDER_REGISTERED_CATEGORY },\n        (event) => {\n          const data = event.data as { capability?: string } | undefined\n          if (data?.capability !== STORAGE_PROVIDER_CAP_NAME) return\n          // Fire-and-forget: providers register synchronously but\n          // `getProviderInfo()` is async. Errors are scoped to the\n          // logger inside `seedFromAllProviders`.\n          void this.seedFromAllProviders()\n        },\n      )\n      this.seedSubscriptionDisposers.push(unsub)\n    }\n\n    this.ctx.logger.info('Storage orchestrator initialized')\n    return [{ capability: storageCapability, provider }]\n  }\n\n  protected async onShutdown(): Promise<void> {\n    for (const dispose of this.seedSubscriptionDisposers) {\n      try { dispose() } catch { /* noop */ }\n    }\n    this.seedSubscriptionDisposers.length = 0\n    this.uploadOwners.clear()\n    this.downloadOwners.clear()\n    this.service = null\n  }\n\n  // ── Persistence wiring (Task 6) ─────────────────────────────────────\n\n  /**\n   * Resolve the live `ISettingsBackend` from the capability registry\n   * and wrap it in a `SqliteLocationStore`. Returns `null` when the\n   * settings-store cap isn't registered yet — the service falls back\n   * to in-memory only. Production boot order (sqlite-settings runs\n   * before the orchestrator) makes this the rare path.\n   */\n  private resolveLocationStore(): ILocationStore | null {\n    const reg = this.ctx.kernel.capabilityRegistry\n    if (!reg) return null\n    const backend = reg.getSingleton<ISettingsBackend>('settings-store')\n    if (!backend) {\n      this.ctx.logger.warn(\n        'storage-orchestrator: no settings-store provider — running in-memory only',\n      )\n      return null\n    }\n    if (!backend.ensureTable || !backend.tableInsert) {\n      this.ctx.logger.warn(\n        'storage-orchestrator: settings backend lacks structured-table support — running in-memory only',\n      )\n      return null\n    }\n    return new SqliteLocationStore(backend)\n  }\n\n  // ── Seeding helpers (Task 5) ────────────────────────────────────────\n\n  /**\n   * Walk every registered `storage-provider` collection provider and\n   * call `service.seedDefaults` for each. Idempotent — re-running on\n   * a populated map is a no-op (each location's `id` is already in the\n   * service's map).\n   *\n   * `basePath` is derived per-call:\n   *   - Filesystem providers (and any provider whose `getProviderInfo`\n   *     doesn't include a `basePath` field) fall back to\n   *     `process.env.CAMSTACK_DATA ?? path.resolve(process.cwd(), 'camstack-data')`.\n   *   - Future remote providers (SFTP/S3/WebDAV) will report their own\n   *     base path through the wizard config — they're not relevant for\n   *     first-boot seeding (operators add them through the admin UI).\n   */\n  private async seedFromAllProviders(): Promise<void> {\n    if (!this.service) return\n    const reg = this.ctx.kernel.capabilityRegistry\n    if (!reg) return\n\n    const providers = reg.getCollection<IStorageProviderImpl>(STORAGE_PROVIDER_CAP_NAME)\n    if (providers.length === 0) return\n\n    const basePath = process.env['CAMSTACK_DATA'] ?? path.resolve(process.cwd(), 'camstack-data')\n\n    for (const p of providers) {\n      try {\n        const info = await p.getProviderInfo()\n        this.service.seedDefaults({\n          providerId: info.providerId,\n          supportedTypes: info.supportedLocationTypes,\n          basePath,\n        })\n      } catch (err) {\n        this.ctx.logger.warn('storage-orchestrator: seed failed for provider', {\n          meta: { error: err instanceof Error ? err.message : String(err) },\n        })\n      }\n    }\n  }\n\n  // ── Session ownership helpers ─────────────────────────────────────────\n\n  private async resolveByUploadId(uploadId: string): Promise<IStorageProviderImpl> {\n    const providerId = this.uploadOwners.get(uploadId)\n    if (!providerId) {\n      throw new Error(`Unknown uploadId \"${uploadId}\" — orchestrator has no record of beginUpload`)\n    }\n    return this.providerByProviderId(providerId, `uploadId \"${uploadId}\"`)\n  }\n\n  private async resolveByDownloadId(downloadId: string): Promise<IStorageProviderImpl> {\n    const providerId = this.downloadOwners.get(downloadId)\n    if (!providerId) {\n      throw new Error(`Unknown downloadId \"${downloadId}\" — orchestrator has no record of beginDownload`)\n    }\n    return this.providerByProviderId(providerId, `downloadId \"${downloadId}\"`)\n  }\n\n  /**\n   * Look up a `storage-provider` by `providerId` only — used for\n   * upload / download dispatch where the original `StorageLocation` is\n   * no longer in scope. Throws if the provider has gone away (e.g.\n   * addon unloaded mid-session).\n   */\n  private async providerByProviderId(providerId: string, sessionDescriptor: string): Promise<IStorageProviderImpl> {\n    if (!this.service) throw new Error('storage-orchestrator: service not initialized')\n    // Synthesize a minimal `StorageLocation`-shaped probe — the service\n    // only reads `providerId` + `id` for the lookup error message.\n    const probe: StorageLocation = {\n      id: `__session:${sessionDescriptor}`,\n      type: 'data',\n      displayName: sessionDescriptor,\n      providerId,\n      config: {},\n      isDefault: false,\n      isSystem: false,\n      createdAt: 0,\n      updatedAt: 0,\n    }\n    return this.service.getProviderFor(probe)\n  }\n}\n\nexport default StorageOrchestratorAddon\n"],"mappings":"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"}

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

@@ -0,0 +1,121 @@
+import { IScopedLogger, IStorageProviderImpl, StorageLocation, StorageLocationRef, StorageLocationType } from '@camstack/types';
+import { ILocationStore } from './location-store.js';
+export interface ListLocationsFilter {
+    readonly type?: StorageLocationType;
+}
+/**
+ * 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[];
+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.
+     */
+    private readonly locationStore;
+    private readonly locations;
+    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.
+     */
+    locationStore?: ILocationStore | null);
+    /**
+     * 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>;
+    listLocations(filter?: ListLocationsFilter): readonly StorageLocation[];
+    getDefaultLocation(type: StorageLocationType): StorageLocation | null;
+    /**
+     * Insert or update a location. If `isDefault: true`, atomically
+     * demotes any other default for the same type — operators always see
+     * exactly one default per type.
+     *
+     * When a persistence store is wired (Task 6), the new record AND any
+     * implicitly-demoted siblings are persisted before the in-memory map
+     * mutation returns. Persistence errors propagate to the caller.
+     */
+    upsertLocation(input: Omit<StorageLocation, 'createdAt' | 'updatedAt'>): StorageLocation;
+    /**
+     * Remove a location. Refuses to remove the default of a type unless a
+     * sibling default exists (defensive — `upsertLocation` already ensures
+     * at most one default per type, but the logic guards against future
+     * bypass paths e.g. SQLite migration that imports two defaults).
+     *
+     * Persistence (Task 6) mirrors the delete asynchronously, with errors
+     * routed to the logger — see `upsertLocation` for the rationale.
+     */
+    deleteLocation(id: string): 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. Lookup is by
+     * `location.providerId` against `getProviderInfo().providerId` from
+     * each registered collection provider. Throws with both the missing
+     * providerId and the offending location id so the operator can pick
+     * the right place to fix the config.
+     */
+    getProviderFor(location: StorageLocation): Promise<IStorageProviderImpl>;
+    /** Convenience: lookup by id (returns `undefined` if not found). */
+    getLocationById(id: string): StorageLocation | undefined;
+    /**
+     * Seed one default `StorageLocation` per `supportedTypes` entry that
+     * doesn't already have one. Idempotent — re-running with the same
+     * provider info on a populated map is a no-op (each entry already
+     * resolves on `id === <type>:default`).
+     *
+     * Convention: the bare-type ref `'backups'` resolves via
+     * `getDefaultLocation('backups')` (walks `isDefault === true`); the
+     * actual stored `id` is `'backups:default'` so it satisfies the
+     * `^[a-z][a-z0-9-]*:[a-z0-9-]+$` regex on `StorageLocationSchema.id`.
+     *
+     * `basePath` is the provider's storage root (e.g. the filesystem
+     * provider's `<CAMSTACK_DATA>` dir). Each location's `config.basePath`
+     * is set to `<basePath>/<DEFAULT_LOCATION_SUBDIRS[type]>` — except
+     * when the subdir is already absolute (today only `cache` →
+     * `/tmp/camstack-cache`), in which case it's used verbatim. The
+     * filesystem provider re-derives the same path on its own — this
+     * config field is purely an operator-visible record of what was
+     * provisioned. Task 7 will refactor providers to honour the
+     * location's `config.basePath` directly.
+     */
+    seedDefaults(input: {
+        readonly providerId: string;
+        readonly supportedTypes: readonly StorageLocationType[];
+        readonly basePath: string;
+    }): void;
+    /** Internal: check whether any location of the given type exists. */
+    private hasAnyLocationOfType;
+}
+//# sourceMappingURL=storage-orchestrator.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage-orchestrator.service.d.ts","sourceRoot":"","sources":["../../../src/builtins/storage-orchestrator/storage-orchestrator.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,iBAAiB,CAAA;AAOxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAA;CACpC;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,SAAS,oBAAoB,EAAE,CAAA;AAEzE,qBAAa,0BAA0B;IAInC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa;IAbhC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;gBAGjD,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,qBAAqB;IACpD;;;;;;;OAOG;IACc,aAAa,GAAE,cAAc,GAAG,IAAW;IAG9D;;;;;;;;;;;;OAYG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BjC,aAAa,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,SAAS,eAAe,EAAE;IAKvE,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,GAAG,IAAI;IAOrE;;;;;;;;OAQG;IACH,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG,eAAe;IAkExF;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAiChC;;;;;;;;;OASG;IACH,UAAU,CAAC,GAAG,EAAE,kBAAkB,GAAG,eAAe;IA0BpD;;;;;;OAMG;IACG,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAW9E,oEAAoE;IACpE,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAMxD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,KAAK,EAAE;QAClB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;QAC3B,QAAQ,CAAC,cAAc,EAAE,SAAS,mBAAmB,EAAE,CAAA;QACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAC1B,GAAG,IAAI;IA8BR,qEAAqE;IACrE,OAAO,CAAC,oBAAoB;CAM7B"}

package/dist/builtins/system-backup/system-backup.service.d.ts

@@ -0,0 +1,138 @@
+import { IScopedLogger } from '@camstack/types';
+/**
+ * Default set of paths considered part of a "system backup". Includes
+ * everything that isn't pure backend code — config, sqlite, addons
+ * (runtime overlay), addons-data (per-addon private dir), TLS certs,
+ * auto-update marker.
+ *
+ * Excluded by default: recordings/, media/, models/, logs/, cache/
+ * (too large or fully recreatable).
+ */
+export declare const DEFAULT_BACKUP_LOCATIONS: readonly ["config.yaml", "addons", "addons-data", "tls", "auto-update.json"];
+/** Path of the manifest file embedded inside every archive. */
+export declare const ARCHIVE_MANIFEST_NAME = ".camstack-backup-manifest.json";
+export type ArchiveEntryKind = 'file' | 'dir' | 'symlink';
+export interface ArchiveEntry {
+    /** Path relative to the archive root (== relative to dataDir). */
+    readonly path: string;
+    readonly kind: ArchiveEntryKind;
+    /** Content bytes. 0 for dirs / symlinks. */
+    readonly sizeBytes: number;
+    /** ms epoch from filesystem mtime. */
+    readonly mtime: number;
+}
+export interface ArchiveManifest {
+    archiveVersion: 1;
+    createdAt: number;
+    dataDir: string;
+    /**
+     * Mutable arrays — same shape as the zod-inferred type returned by
+     * `ArchiveManifestSchema.parse()`. `BaseAddon` providers receive
+     * this exact type via cap inputs, so making the interface readonly
+     * here would force callers to clone before forwarding.
+     */
+    locations: string[];
+    entries: ArchiveEntry[];
+    /** Sum of file `sizeBytes` (uncompressed). */
+    totalBytes: number;
+    totalFiles: number;
+}
+export interface CreateArchiveResult {
+    archivePath: string;
+    includedLocations: readonly string[];
+    /** Archive size in bytes (compressed, on disk). */
+    sizeBytes: number;
+    /** Embedded manifest — same shape as `getArchiveManifest()`. */
+    manifest: ArchiveManifest;
+}
+export interface RestoreMarker {
+    archivePath: string;
+    requestedAt: number;
+    /** Caller-supplied identifier (e.g. backup id) for traceability. */
+    source: string;
+    /**
+     * Optional whitelist of top-level locations to restore from the
+     * archive. When omitted the boot-time hook applies everything in
+     * the archive (full restore — same as the legacy behavior).
+     */
+    locations?: readonly string[];
+}
+export interface LocationStat {
+    readonly name: string;
+    readonly sizeBytes: number;
+    readonly fileCount: number;
+    /** False when the location doesn't exist under dataDir. */
+    readonly present: boolean;
+}
+/**
+ * System-level archive primitives. Construct one per server boot;
+ * methods are pure I/O.
+ */
+export declare class SystemBackupService {
+    private readonly dataDir;
+    private readonly logger;
+    constructor(dataDir: string, logger: IScopedLogger);
+    /**
+     * Snapshot the current size + file count of each well-known
+     * location. Used by the admin UI to render an opt-in checklist
+     * before triggering a backup, and by `createArchive` to derive the
+     * embedded manifest.
+     */
+    statLocations(locations?: readonly string[]): readonly LocationStat[];
+    /**
+     * Create a tar.gz of the given locations. Uses the `tar` npm package
+     * (used by npm itself) instead of shelling out — gives us:
+     *
+     *   - Symlink dereference (`follow: true`) so dev mode's
+     *     `addons/<name> → packages/<name>` overlay archives content,
+     *     not just link stubs.
+     *   - Programmatic walk → we build a manifest of every entry while
+     *     copying so the archive can self-describe.
+     *
+     * Locations that don't exist are silently skipped. Throws if zero
+     * locations would be included.
+     */
+    createArchive(opts: {
+        archivePath: string;
+        locations?: readonly string[];
+    }): Promise<CreateArchiveResult>;
+    /**
+     * Read the embedded manifest from a previously-created archive
+     * without extracting payload files. Streams the tar.gz, parses the
+     * one entry we care about, then aborts.
+     */
+    readArchiveManifest(archivePath: string): Promise<ArchiveManifest | null>;
+    /**
+     * Extract a previously-created archive over `targetDir`. Used at boot
+     * by the restore hook — never call from a running server (would
+     * corrupt sqlite mid-run).
+     *
+     * `locations` is an optional whitelist: only entries whose path
+     * starts with one of the locations get extracted. Used by the
+     * partial-restore flow where the operator picks a subset of the
+     * archive contents to apply (e.g. "restore my devices but keep
+     * my current TLS certs").
+     */
+    extractArchive(opts: {
+        archivePath: string;
+        targetDir: string;
+        locations?: readonly string[];
+    }): Promise<void>;
+    /**
+     * Schedule a restore for the next boot by writing a marker file.
+     * `locations` (optional) carries through to the boot-time
+     * extractArchive call so the operator's "restore only X and Y"
+     * choice survives the process restart.
+     */
+    scheduleRestoreMarker(opts: {
+        archivePath: string;
+        source: string;
+        locations?: readonly string[];
+    }): string;
+    /** Read the pending-restore marker if one is present. */
+    readPendingMarker(): RestoreMarker | null;
+    /** Drop the marker after a successful boot-time restore. */
+    clearPendingMarker(): void;
+    private getRestoreMarkerPath;
+}
+//# sourceMappingURL=system-backup.service.d.ts.map

package/dist/builtins/system-backup/system-backup.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-backup.service.d.ts","sourceRoot":"","sources":["../../../src/builtins/system-backup/system-backup.service.ts"],"names":[],"mappings":"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"}

package/dist/builtins/system-config/index.d.ts

@@ -0,0 +1,2 @@
+export { SystemConfigAddon, default } from './system-config.addon.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/builtins/system-config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builtins/system-config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/builtins/system-config/index.js

@@ -1,189 +1,7 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/builtins/system-config/index.ts
-var system_config_exports = {};
-__export(system_config_exports, {
-  SystemConfigAddon: () => SystemConfigAddon,
-  default: () => system_config_addon_default
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
 });
-module.exports = __toCommonJS(system_config_exports);
-
-// src/builtins/system-config/system-config.addon.ts
-var import_types = require("@camstack/types");
-var SECTION_TITLES = {
-  server: "Server",
-  auth: "Authentication",
-  ffmpeg: "FFmpeg"
-};
-var KEY_TO_SECTION = {
-  // server (read-only)
-  port: "server",
-  host: "server",
-  dataPath: "server",
-  // auth
-  tokenExpiry: "auth",
-  // ffmpeg
-  binaryPath: "ffmpeg",
-  hwAccel: "ffmpeg",
-  threadCount: "ffmpeg"
-};
-var SystemConfigAddon = class extends import_types.BaseAddon {
-  id = "system-config";
-  constructor() {
-    super({});
-  }
-  async onInitialize() {
-    this.ctx.logger.info("Initialized \u2014 exposes yml-backed sections via getGlobalSettings");
-  }
-  // ── Three-level settings API (only `getGlobalSettings` is implemented) ──
-  buildGlobalSchema() {
-    return {
-      sections: [
-        {
-          id: "system-config-server",
-          title: SECTION_TITLES["server"],
-          description: "Core server connection settings \u2014 read-only, loaded from config.yaml at bootstrap.",
-          columns: 2,
-          fields: [
-            {
-              type: "info",
-              key: "server-restart-note",
-              label: "Restart required",
-              content: "Server settings are read-only. Change them in config.yaml and restart.",
-              variant: "warning"
-            },
-            { type: "text", key: "port", label: "Port", description: "Listening port", disabled: true },
-            { type: "text", key: "host", label: "Host", description: "Bind address", disabled: true },
-            { type: "text", key: "dataPath", label: "Data Path", description: "Root data directory", disabled: true, span: 2 }
-          ]
-        },
-        {
-          id: "system-config-auth",
-          title: SECTION_TITLES["auth"],
-          description: "Token and session settings.",
-          columns: 1,
-          fields: [
-            {
-              type: "text",
-              key: "tokenExpiry",
-              label: "Token Expiry",
-              description: "JWT token lifetime (e.g. 24h, 7d, 1h)",
-              placeholder: "24h",
-              default: "24h"
-            }
-          ]
-        },
-        {
-          id: "system-config-ffmpeg",
-          title: SECTION_TITLES["ffmpeg"],
-          description: "FFmpeg binary and hardware acceleration settings.",
-          columns: 2,
-          fields: [
-            {
-              type: "text",
-              key: "binaryPath",
-              label: "Binary Path",
-              description: "Path to ffmpeg executable",
-              placeholder: "ffmpeg",
-              default: "ffmpeg",
-              span: 2
-            },
-            {
-              type: "select",
-              key: "hwAccel",
-              label: "Hardware Acceleration",
-              description: "GPU decoding/encoding backend",
-              default: "auto",
-              options: [
-                { value: "auto", label: "Auto-detect" },
-                { value: "none", label: "None (CPU only)" },
-                { value: "videotoolbox", label: "VideoToolbox (macOS)" },
-                { value: "vaapi", label: "VA-API (Linux Intel/AMD)" },
-                { value: "qsv", label: "QSV (Intel Quick Sync)" },
-                { value: "cuda", label: "CUDA (NVIDIA)" }
-              ]
-            },
-            {
-              type: "number",
-              key: "threadCount",
-              label: "Thread Count",
-              description: "0 = auto (let FFmpeg decide)",
-              min: 0,
-              max: 16,
-              step: 1,
-              default: 0
-            }
-          ]
-        }
-      ]
-    };
-  }
-  async getGlobalSettings() {
-    const schema = this.buildGlobalSchema();
-    if (!this.ctx.settings) {
-      return (0, import_types.hydrateSchema)(schema, {});
-    }
-    const sectionNames = Object.keys(SECTION_TITLES);
-    const merged = {};
-    for (const section of sectionNames) {
-      try {
-        const values = await this.ctx.settings.getSection(section);
-        Object.assign(merged, values);
-      } catch (err) {
-        const msg = (0, import_types.errMsg)(err);
-        this.ctx.logger.debug("Failed to read section", { meta: { section, error: msg } });
-      }
-    }
-    return (0, import_types.hydrateSchema)(schema, merged);
-  }
-  async updateGlobalSettings(patch) {
-    if (!this.ctx.settings) {
-      throw new Error("system-config: ctx.settings not available \u2014 cannot write sections");
-    }
-    const perSection = /* @__PURE__ */ new Map();
-    for (const [key, value] of Object.entries(patch)) {
-      const section = KEY_TO_SECTION[key];
-      if (section === void 0) {
-        this.ctx.logger.warn("update ignored unknown key (not mapped to any section)", { meta: { key } });
-        continue;
-      }
-      if (section === "server") {
-        this.ctx.logger.warn("update ignored read-only server-section key", { meta: { key } });
-        continue;
-      }
-      let bucket = perSection.get(section);
-      if (!bucket) {
-        bucket = {};
-        perSection.set(section, bucket);
-      }
-      bucket[key] = value;
-    }
-    for (const [section, sectionPatch] of perSection) {
-      await this.ctx.settings.setSection(section, sectionPatch);
-      this.ctx.logger.info("Wrote keys to section", { meta: { section, keyCount: Object.keys(sectionPatch).length } });
-    }
-  }
-};
-var system_config_addon_default = SystemConfigAddon;
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  SystemConfigAddon
-});
-//# sourceMappingURL=index.js.map
+const require_builtins_system_config_system_config_addon = require("./system-config.addon.js");
+exports.SystemConfigAddon = require_builtins_system_config_system_config_addon.SystemConfigAddon;
+exports.default = require_builtins_system_config_system_config_addon.SystemConfigAddon;

package/dist/builtins/system-config/index.mjs

@@ -1,10 +1,2 @@
-import "../../chunk-W6RTHQGP.mjs";
-import {
-  SystemConfigAddon,
-  system_config_addon_default
-} from "../../chunk-QT57H266.mjs";
-export {
-  SystemConfigAddon,
-  system_config_addon_default as default
-};
-//# sourceMappingURL=index.mjs.map
+import { SystemConfigAddon } from "./system-config.addon.mjs";
+export { SystemConfigAddon, SystemConfigAddon as default };

package/dist/builtins/system-config/system-config.addon.d.ts

@@ -0,0 +1,11 @@
+import { ConfigUISchemaWithValues, BaseAddon } from '@camstack/types';
+export declare class SystemConfigAddon extends BaseAddon {
+    readonly id = "system-config";
+    constructor();
+    protected onInitialize(): Promise<void>;
+    private buildGlobalSchema;
+    getGlobalSettings(): Promise<ConfigUISchemaWithValues>;
+    updateGlobalSettings(patch: Record<string, unknown>): Promise<void>;
+}
+export default SystemConfigAddon;
+//# sourceMappingURL=system-config.addon.d.ts.map

package/dist/builtins/system-config/system-config.addon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-config.addon.d.ts","sourceRoot":"","sources":["../../../src/builtins/system-config/system-config.addon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,wBAAwB,EACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,SAAS,EAA0B,MAAM,iBAAiB,CAAA;AA6DnE,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C,QAAQ,CAAC,EAAE,mBAAkB;;cAIb,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7C,OAAO,CAAC,iBAAiB;IAmFnB,iBAAiB,IAAI,OAAO,CAAC,wBAAwB,CAAC;IAwBtD,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAiC1E;AAED,eAAe,iBAAiB,CAAA"}