@camstack/system 1.2.169 → 1.2.170

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.js

@@ -3,7 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-D6kBG4fg.js");
+const require_dist = require("../../dist-DsoVfJSR.js");
+const require_hub_cap_forward = require("../../hub-cap-forward-DmHNjbB0.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
@@ -1118,6 +1119,201 @@ function canProbeOccupancyLocally(locality) {
 	return locality === true;
 }
 //#endregion
+//#region src/builtins/storage-orchestrator/data-store-dispatch.ts
+/**
+* Pick the target to serve a call.
+*
+* A LOCAL engine always wins: the remote is a fallback for a node that has
+* none, never a policy. Two cases are refused rather than guessed:
+*
+*  - **none registered, and no remote** — resolving to a no-op would make
+*    every read answer `undefined` and every write disappear, which reads
+*    exactly like an empty database;
+*  - **more than one engine** — there is no routing rule yet. The `engine`
+*    hint on `declareCollection` is what will choose, and until it exists a
+*    silent pick would send a collection to whichever engine happened to
+*    register first. A remote does not rescue this: the ambiguity is local.
+*/
+function resolveEngine(getEngines, getRemote) {
+	const engines = getEngines();
+	if (engines.length === 0) {
+		const remote = getRemote?.() ?? null;
+		if (remote) return remote;
+		throw new Error("settings-store: no data-store-provider engine is registered — the data door has nothing behind it");
+	}
+	if (engines.length > 1) throw new Error(`settings-store: ${engines.length} data-store-provider engines are registered and there is no routing rule yet — declare the engine on the collection first`);
+	const engine = engines[0];
+	if (!engine) throw new Error("settings-store: data-store-provider collection yielded an empty entry");
+	return engine;
+}
+/**
+* Build the `settings-store` provider that fronts the registered engines,
+* with an optional remote behind it for a node that registers none.
+*
+* `getEngines` and `getRemote` are read on every call, never captured:
+* engines register during boot and a runner respawn replaces the instance, so
+* a snapshot taken at construction time would go stale exactly when an addon
+* crashed and came back.
+*/
+function createDataStoreDispatch(getEngines, getRemote) {
+	const engine = async () => resolveEngine(getEngines, getRemote);
+	return {
+		get: async (input) => (await engine()).get(input),
+		set: async (input) => (await engine()).set(input),
+		query: async (input) => (await engine()).query(input),
+		insert: async (input) => (await engine()).insert(input),
+		insertMany: async (input) => (await engine()).insertMany(input),
+		update: async (input) => (await engine()).update(input),
+		delete: async (input) => (await engine()).delete(input),
+		deleteWhere: async (input) => (await engine()).deleteWhere(input),
+		updateWhere: async (input) => (await engine()).updateWhere(input),
+		count: async (input) => (await engine()).count(input),
+		aggregate: async (input) => (await engine()).aggregate(input),
+		histogram: async (input) => (await engine()).histogram(input),
+		isEmpty: async (input) => (await engine()).isEmpty(input),
+		declareCollection: async (input) => (await engine()).declareCollection(input)
+	};
+}
+//#endregion
+//#region src/builtins/storage-orchestrator/hub-settings-forward.ts
+/**
+* The data door with the HUB behind it — an agent's `settings-store` provider.
+*
+* ## Why this exists
+*
+* Persistence is the hub's. An agent runs no `data-store-provider` engine
+* (see `resolveAgentInfraCapabilities` in `server/backend/src/agent/`), so the
+* `settings-store` door the storage-orchestrator registers on an agent has
+* nothing local behind it. Rather than refuse — which would strand the four
+* infra addons that boot inside agent-main (`hub-forwarder`, `native-metrics`,
+* `platform-probe`, the orchestrator itself) with a `ctx.settings` that throws
+* on every read — the door FORWARDS into the hub's own routing.
+*
+* This is not a new transport. It is the same `$hub-cap-fwd.forward` a forked
+* addon on an agent has always used to reach a hub-hosted cap
+* (`kernel/transport/hub-cap-forward.ts` names `settings-store` in its own
+* header); agent-main's infra addons simply never had it, because they resolve
+* `ctx.api.settingsStore` through `localProviderLink` against the process's own
+* provider registry — which is exactly the local door.
+*
+* ## The payload crosses untouched
+*
+* The engine composes its table name from `namespace` + `collection` **out of
+* the payload**. A forwarder that injected, defaulted or stripped a namespace
+* would silently rename every table on the hub. Every method here is the same
+* forward, and the args are the caller's object verbatim — the same rule
+* `data-store-dispatch.ts` states for the local path, for the same reason.
+*
+* ## No second key space
+*
+* Per-node scoping already exists, one layer up, and it is per FIELD:
+* `BaseAddon` persists a `perNode: true` schema field as `<key>@<nodeId>`
+* inside the addon's single shared blob (`packages/types/src/addon/
+* per-node-store.ts`). The agent therefore reads and writes the SAME row the
+* hub's copy of that addon reads — `<addonId>:addon-settings` / `root` — and
+* the two agree by construction. Introducing a second, addon-level
+* `(nodeId, addonId)` row here would be a second authority over one fact,
+* which is the shape [D224](../../../../../docs/decisions/adr-0224-the-freshness-of-a-camera-fact-lives-in-its-provider.md)
+* forbids: the hub's copy would keep writing the bare row and nothing would
+* reconcile them.
+*
+* ## A hub NEVER forwards
+*
+* {@link nodeOwnsItsDataStore} gates construction. A hub that built one would
+* route its own door back into itself through `$hub-cap-fwd`, which resolves
+* `settings-store` to… this. The gate reads the same env var, with the same
+* default, as `settingsStoreIsAuthoritativeHere` — unset means hub, because
+* that is what the launcher defaults to.
+*
+* ## When the hub is down
+*
+* Every method REJECTS. It never answers "empty": `ctx.settings`' read path
+* (`addon-context-factory.ts`) distinguishes a MISS from a FAILURE precisely
+* so a failed read cannot make the next read-modify-write persist the patch
+* alone and destroy every field the patch does not mention. An empty answer
+* would be indistinguishable from an empty store; a rejection is not. The
+* operator's rule for this node is the same one that already governs it —
+* without the hub an agent has no work — so a rejection is the whole of the
+* degraded behaviour, and it is loud.
+*/
+/**
+* Does THIS node hold its own data store?
+*
+* Unset or `'hub'` means hub — the launcher's own default, mirrored from
+* `resolveNodeRole` (`server/backend/src/node-role.ts`) the same way
+* `settingsStoreIsAuthoritativeHere` mirrors it, and duplicated rather than
+* imported for the same reason: `@camstack/system` is a dependency OF the
+* backend, not the other way round.
+*
+* Anything else is an agent, and an agent's answer is the hub's store.
+*/
+function nodeOwnsItsDataStore(env) {
+	const raw = (env["CAMSTACK_ROLE"] ?? "").trim().toLowerCase();
+	return raw === "" || raw === "hub";
+}
+/**
+* Build the `settings-store` provider that forwards to the hub.
+*
+* Every method is the same forward under the CAP name — never the engine
+* name. The hub routes `settings-store` to its own door, which then picks its
+* local engine; asking for `data-store-provider` would step around the door on
+* the far side and lose whatever the door is for.
+*/
+function createHubSettingsForward(forward) {
+	const send = (method, args) => forward({
+		capName: require_dist.settingsStoreCapability.name,
+		method,
+		args
+	});
+	return {
+		get: (input) => send("get", input),
+		set: (input) => send("set", input),
+		query: (input) => send("query", input),
+		insert: (input) => send("insert", input),
+		insertMany: (input) => send("insertMany", input),
+		update: (input) => send("update", input),
+		delete: (input) => send("delete", input),
+		deleteWhere: (input) => send("deleteWhere", input),
+		updateWhere: (input) => send("updateWhere", input),
+		count: (input) => send("count", input),
+		aggregate: (input) => send("aggregate", input),
+		histogram: (input) => send("histogram", input),
+		isEmpty: (input) => send("isEmpty", input),
+		declareCollection: (input) => send("declareCollection", input)
+	};
+}
+/**
+* How long an agent waits for the hub to answer a settings call before the
+* door rejects. Matches the agent's own `forwardToHub` budget in
+* `server/backend/src/agent/main.ts` — the same hop, over the same action, so
+* a shorter one here would only manufacture a timeout the transport did not
+* have.
+*/
+var HUB_SETTINGS_FORWARD_TIMEOUT_MS = 6e4;
+/**
+* The whole decision, in one place: does this node's data door have the hub
+* behind it, and how does it get there?
+*
+* `null` means "no remote" and the door keeps its old behaviour — it refuses
+* when no engine is registered. That is the answer on a hub (which IS the
+* store) and in any process with no cluster broker.
+*
+* Extracted from the addon so the gate is unit-testable without booting a
+* `BaseAddon` — the same reason `data-store-dispatch.ts` and
+* `provider-discovery.ts` exist.
+*/
+function resolveHubSettingsForward(options) {
+	if (nodeOwnsItsDataStore(options.env)) return null;
+	const broker = options.broker;
+	if (!broker) return null;
+	options.logger.info("storage-orchestrator: no local data-store engine on this node — the data door forwards to the hub");
+	return createHubSettingsForward((envelope) => broker.call(require_hub_cap_forward.HUB_CAP_FWD_ACTION, {
+		capName: envelope.capName,
+		method: envelope.method,
+		args: envelope.args
+	}, { timeout: HUB_SETTINGS_FORWARD_TIMEOUT_MS }));
+}
+//#endregion
 //#region src/builtins/storage-orchestrator/location-occupancy.ts
 /**
 * Delete-time occupancy of a location's on-disk root.
@@ -1190,57 +1386,6 @@ async function probeLocalDirectoryOccupancy(input) {
 	return "empty";
 }
 //#endregion
-//#region src/builtins/storage-orchestrator/data-store-dispatch.ts
-/**
-* Pick the engine to serve a call.
-*
-* Today the rule is "the only one there is". Two cases are refused rather
-* than guessed:
-*
-*  - **none registered** — resolving to a no-op would make every read
-*    answer `undefined` and every write disappear, which reads exactly
-*    like an empty database;
-*  - **more than one** — there is no routing rule yet. The `engine` hint
-*    on `declareCollection` is what will choose, and until it exists a
-*    silent pick would send a collection to whichever engine happened to
-*    register first.
-*/
-function resolveEngine(getEngines) {
-	const engines = getEngines();
-	if (engines.length === 0) throw new Error("settings-store: no data-store-provider engine is registered — the data door has nothing behind it");
-	if (engines.length > 1) throw new Error(`settings-store: ${engines.length} data-store-provider engines are registered and there is no routing rule yet — declare the engine on the collection first`);
-	const engine = engines[0];
-	if (!engine) throw new Error("settings-store: data-store-provider collection yielded an empty entry");
-	return engine;
-}
-/**
-* Build the `settings-store` provider that fronts the registered engines.
-*
-* `getEngines` is read on every call, never captured: engines register
-* during boot and a runner respawn replaces the instance, so a snapshot
-* taken at construction time would go stale exactly when an addon crashed
-* and came back.
-*/
-function createDataStoreDispatch(getEngines) {
-	const engine = async () => resolveEngine(getEngines);
-	return {
-		get: async (input) => (await engine()).get(input),
-		set: async (input) => (await engine()).set(input),
-		query: async (input) => (await engine()).query(input),
-		insert: async (input) => (await engine()).insert(input),
-		insertMany: async (input) => (await engine()).insertMany(input),
-		update: async (input) => (await engine()).update(input),
-		delete: async (input) => (await engine()).delete(input),
-		deleteWhere: async (input) => (await engine()).deleteWhere(input),
-		updateWhere: async (input) => (await engine()).updateWhere(input),
-		count: async (input) => (await engine()).count(input),
-		aggregate: async (input) => (await engine()).aggregate(input),
-		histogram: async (input) => (await engine()).histogram(input),
-		isEmpty: async (input) => (await engine()).isEmpty(input),
-		declareCollection: async (input) => (await engine()).declareCollection(input)
-	};
-}
-//#endregion
 //#region src/builtins/storage-orchestrator/location-secrets.ts
 /**
 * The config keys the ORCHESTRATOR itself owns, as opposed to the ones a
@@ -2838,10 +2983,32 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 			},
 			{
 				capability: require_dist.settingsStoreCapability,
-				provider: createDataStoreDispatch(getEngines)
+				provider: createDataStoreDispatch(getEngines, () => this.hubSettingsForward())
 			}
 		];
 	}
+	/**
+	* The remote behind the data door on a node that owns no engine.
+	*
+	* `null` on a hub — the hub IS the store, and a hub that forwarded would
+	* route its own door back into itself through `$hub-cap-fwd`. `null` too
+	* when this process has no cluster broker (a forked worker, or a test
+	* harness); the door then behaves exactly as it always did and refuses.
+	*
+	* Built once and memoised. It is only consulted when `getEngines()` is
+	* empty, so on a hub — and on an agent rolled back to a local engine via
+	* `CAMSTACK_AGENT_LOCAL_DATA_STORE` — the resolve never runs a second time.
+	*/
+	hubForward = null;
+	hubSettingsForward() {
+		if (this.hubForward) return this.hubForward;
+		this.hubForward = resolveHubSettingsForward({
+			env: process.env,
+			broker: this.ctx.kernel.cluster?.broker,
+			logger: this.ctx.logger
+		});
+		return this.hubForward;
+	}
 	async onShutdown() {
 		for (const dispose of this.seedSubscriptionDisposers) try {
 			dispose();
@@ -2862,9 +3029,19 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 	/**
 	* Resolve the live engine from the capability registry and wrap it in a
 	* `SqliteLocationStore`. Returns `null` when no engine has registered
-	* yet — the service falls back to in-memory only. Production boot order
-	* (`data-store-provider` precedes `storage` in `INFRA_CAPABILITIES`)
-	* makes this the rare path.
+	* yet — the service falls back to in-memory only. On a HUB that is a
+	* boot-order window: `data-store-provider` precedes `storage` in
+	* `INFRA_CAPABILITIES`, so it is the rare path.
+	*
+	* On an AGENT it is permanent and intended, and the line says so. An agent
+	* boots no engine (`resolveAgentInfraCapabilities`), and this store must NOT
+	* be pointed at the hub-forwarding data door: `storage_locations` is keyed by
+	* a bare location id (`recordings:default`, `eventMedia:default`, …) which
+	* every node in the cluster shares, so an agent writing through the door
+	* would land on the HUB's rows. The locations an agent needs are re-seeded
+	* from its addon declarations at every boot; the operator's real, node-pinned
+	* locations live in the hub's own table (`__nodeId` in the config blob) and
+	* are dispatched to the agent's `storage-provider` from there.
 	*
 	* Reads the ENGINE, not the `settings-store` singleton: since D44 this
 	* addon *is* that singleton, so asking the registry for it would hand
@@ -2876,7 +3053,8 @@ var StorageOrchestratorAddon = class extends require_dist.BaseAddon {
 		if (!reg) return null;
 		const engine = reg.getCollection(DATA_STORE_PROVIDER_CAP_NAME)[0];
 		if (!engine) {
-			if (!quiet) this.ctx.logger.warn("storage-orchestrator: no data-store-provider engine yet — running in-memory until one registers");
+			if (!quiet) if (nodeOwnsItsDataStore(process.env)) this.ctx.logger.warn("storage-orchestrator: no data-store-provider engine yet — running in-memory until one registers");
+			else this.ctx.logger.info("storage-orchestrator: this node boots no data-store engine — storage locations are seeded from addon declarations at every boot, and node-pinned locations live on the hub");
 			return null;
 		}
 		return new SqliteLocationStore(engine);

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

@@ -1,4 +1,5 @@
-import { $t as parseJsonObject, C as StorageMigrationJobSchema, Ct as settingsStoreCapability, Et as storageMigrationCapability, Nt as BaseAddon, P as collectSecretConfigKeys, S as StorageLocationTypeSchema, Tt as storageCapability, m as REDACTED_SECRET, x as StorageCleanupJobSchema } from "../../dist-digPByP6.mjs";
+import { $t as parseJsonObject, C as StorageMigrationJobSchema, Ct as settingsStoreCapability, Et as storageMigrationCapability, Nt as BaseAddon, P as collectSecretConfigKeys, S as StorageLocationTypeSchema, Tt as storageCapability, m as REDACTED_SECRET, x as StorageCleanupJobSchema } from "../../dist-1DEQFmTq.mjs";
+import { t as HUB_CAP_FWD_ACTION } from "../../hub-cap-forward-BdT320dq.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
@@ -1113,6 +1114,201 @@ function canProbeOccupancyLocally(locality) {
 	return locality === true;
 }
 //#endregion
+//#region src/builtins/storage-orchestrator/data-store-dispatch.ts
+/**
+* Pick the target to serve a call.
+*
+* A LOCAL engine always wins: the remote is a fallback for a node that has
+* none, never a policy. Two cases are refused rather than guessed:
+*
+*  - **none registered, and no remote** — resolving to a no-op would make
+*    every read answer `undefined` and every write disappear, which reads
+*    exactly like an empty database;
+*  - **more than one engine** — there is no routing rule yet. The `engine`
+*    hint on `declareCollection` is what will choose, and until it exists a
+*    silent pick would send a collection to whichever engine happened to
+*    register first. A remote does not rescue this: the ambiguity is local.
+*/
+function resolveEngine(getEngines, getRemote) {
+	const engines = getEngines();
+	if (engines.length === 0) {
+		const remote = getRemote?.() ?? null;
+		if (remote) return remote;
+		throw new Error("settings-store: no data-store-provider engine is registered — the data door has nothing behind it");
+	}
+	if (engines.length > 1) throw new Error(`settings-store: ${engines.length} data-store-provider engines are registered and there is no routing rule yet — declare the engine on the collection first`);
+	const engine = engines[0];
+	if (!engine) throw new Error("settings-store: data-store-provider collection yielded an empty entry");
+	return engine;
+}
+/**
+* Build the `settings-store` provider that fronts the registered engines,
+* with an optional remote behind it for a node that registers none.
+*
+* `getEngines` and `getRemote` are read on every call, never captured:
+* engines register during boot and a runner respawn replaces the instance, so
+* a snapshot taken at construction time would go stale exactly when an addon
+* crashed and came back.
+*/
+function createDataStoreDispatch(getEngines, getRemote) {
+	const engine = async () => resolveEngine(getEngines, getRemote);
+	return {
+		get: async (input) => (await engine()).get(input),
+		set: async (input) => (await engine()).set(input),
+		query: async (input) => (await engine()).query(input),
+		insert: async (input) => (await engine()).insert(input),
+		insertMany: async (input) => (await engine()).insertMany(input),
+		update: async (input) => (await engine()).update(input),
+		delete: async (input) => (await engine()).delete(input),
+		deleteWhere: async (input) => (await engine()).deleteWhere(input),
+		updateWhere: async (input) => (await engine()).updateWhere(input),
+		count: async (input) => (await engine()).count(input),
+		aggregate: async (input) => (await engine()).aggregate(input),
+		histogram: async (input) => (await engine()).histogram(input),
+		isEmpty: async (input) => (await engine()).isEmpty(input),
+		declareCollection: async (input) => (await engine()).declareCollection(input)
+	};
+}
+//#endregion
+//#region src/builtins/storage-orchestrator/hub-settings-forward.ts
+/**
+* The data door with the HUB behind it — an agent's `settings-store` provider.
+*
+* ## Why this exists
+*
+* Persistence is the hub's. An agent runs no `data-store-provider` engine
+* (see `resolveAgentInfraCapabilities` in `server/backend/src/agent/`), so the
+* `settings-store` door the storage-orchestrator registers on an agent has
+* nothing local behind it. Rather than refuse — which would strand the four
+* infra addons that boot inside agent-main (`hub-forwarder`, `native-metrics`,
+* `platform-probe`, the orchestrator itself) with a `ctx.settings` that throws
+* on every read — the door FORWARDS into the hub's own routing.
+*
+* This is not a new transport. It is the same `$hub-cap-fwd.forward` a forked
+* addon on an agent has always used to reach a hub-hosted cap
+* (`kernel/transport/hub-cap-forward.ts` names `settings-store` in its own
+* header); agent-main's infra addons simply never had it, because they resolve
+* `ctx.api.settingsStore` through `localProviderLink` against the process's own
+* provider registry — which is exactly the local door.
+*
+* ## The payload crosses untouched
+*
+* The engine composes its table name from `namespace` + `collection` **out of
+* the payload**. A forwarder that injected, defaulted or stripped a namespace
+* would silently rename every table on the hub. Every method here is the same
+* forward, and the args are the caller's object verbatim — the same rule
+* `data-store-dispatch.ts` states for the local path, for the same reason.
+*
+* ## No second key space
+*
+* Per-node scoping already exists, one layer up, and it is per FIELD:
+* `BaseAddon` persists a `perNode: true` schema field as `<key>@<nodeId>`
+* inside the addon's single shared blob (`packages/types/src/addon/
+* per-node-store.ts`). The agent therefore reads and writes the SAME row the
+* hub's copy of that addon reads — `<addonId>:addon-settings` / `root` — and
+* the two agree by construction. Introducing a second, addon-level
+* `(nodeId, addonId)` row here would be a second authority over one fact,
+* which is the shape [D224](../../../../../docs/decisions/adr-0224-the-freshness-of-a-camera-fact-lives-in-its-provider.md)
+* forbids: the hub's copy would keep writing the bare row and nothing would
+* reconcile them.
+*
+* ## A hub NEVER forwards
+*
+* {@link nodeOwnsItsDataStore} gates construction. A hub that built one would
+* route its own door back into itself through `$hub-cap-fwd`, which resolves
+* `settings-store` to… this. The gate reads the same env var, with the same
+* default, as `settingsStoreIsAuthoritativeHere` — unset means hub, because
+* that is what the launcher defaults to.
+*
+* ## When the hub is down
+*
+* Every method REJECTS. It never answers "empty": `ctx.settings`' read path
+* (`addon-context-factory.ts`) distinguishes a MISS from a FAILURE precisely
+* so a failed read cannot make the next read-modify-write persist the patch
+* alone and destroy every field the patch does not mention. An empty answer
+* would be indistinguishable from an empty store; a rejection is not. The
+* operator's rule for this node is the same one that already governs it —
+* without the hub an agent has no work — so a rejection is the whole of the
+* degraded behaviour, and it is loud.
+*/
+/**
+* Does THIS node hold its own data store?
+*
+* Unset or `'hub'` means hub — the launcher's own default, mirrored from
+* `resolveNodeRole` (`server/backend/src/node-role.ts`) the same way
+* `settingsStoreIsAuthoritativeHere` mirrors it, and duplicated rather than
+* imported for the same reason: `@camstack/system` is a dependency OF the
+* backend, not the other way round.
+*
+* Anything else is an agent, and an agent's answer is the hub's store.
+*/
+function nodeOwnsItsDataStore(env) {
+	const raw = (env["CAMSTACK_ROLE"] ?? "").trim().toLowerCase();
+	return raw === "" || raw === "hub";
+}
+/**
+* Build the `settings-store` provider that forwards to the hub.
+*
+* Every method is the same forward under the CAP name — never the engine
+* name. The hub routes `settings-store` to its own door, which then picks its
+* local engine; asking for `data-store-provider` would step around the door on
+* the far side and lose whatever the door is for.
+*/
+function createHubSettingsForward(forward) {
+	const send = (method, args) => forward({
+		capName: settingsStoreCapability.name,
+		method,
+		args
+	});
+	return {
+		get: (input) => send("get", input),
+		set: (input) => send("set", input),
+		query: (input) => send("query", input),
+		insert: (input) => send("insert", input),
+		insertMany: (input) => send("insertMany", input),
+		update: (input) => send("update", input),
+		delete: (input) => send("delete", input),
+		deleteWhere: (input) => send("deleteWhere", input),
+		updateWhere: (input) => send("updateWhere", input),
+		count: (input) => send("count", input),
+		aggregate: (input) => send("aggregate", input),
+		histogram: (input) => send("histogram", input),
+		isEmpty: (input) => send("isEmpty", input),
+		declareCollection: (input) => send("declareCollection", input)
+	};
+}
+/**
+* How long an agent waits for the hub to answer a settings call before the
+* door rejects. Matches the agent's own `forwardToHub` budget in
+* `server/backend/src/agent/main.ts` — the same hop, over the same action, so
+* a shorter one here would only manufacture a timeout the transport did not
+* have.
+*/
+var HUB_SETTINGS_FORWARD_TIMEOUT_MS = 6e4;
+/**
+* The whole decision, in one place: does this node's data door have the hub
+* behind it, and how does it get there?
+*
+* `null` means "no remote" and the door keeps its old behaviour — it refuses
+* when no engine is registered. That is the answer on a hub (which IS the
+* store) and in any process with no cluster broker.
+*
+* Extracted from the addon so the gate is unit-testable without booting a
+* `BaseAddon` — the same reason `data-store-dispatch.ts` and
+* `provider-discovery.ts` exist.
+*/
+function resolveHubSettingsForward(options) {
+	if (nodeOwnsItsDataStore(options.env)) return null;
+	const broker = options.broker;
+	if (!broker) return null;
+	options.logger.info("storage-orchestrator: no local data-store engine on this node — the data door forwards to the hub");
+	return createHubSettingsForward((envelope) => broker.call(HUB_CAP_FWD_ACTION, {
+		capName: envelope.capName,
+		method: envelope.method,
+		args: envelope.args
+	}, { timeout: HUB_SETTINGS_FORWARD_TIMEOUT_MS }));
+}
+//#endregion
 //#region src/builtins/storage-orchestrator/location-occupancy.ts
 /**
 * Delete-time occupancy of a location's on-disk root.
@@ -1185,57 +1381,6 @@ async function probeLocalDirectoryOccupancy(input) {
 	return "empty";
 }
 //#endregion
-//#region src/builtins/storage-orchestrator/data-store-dispatch.ts
-/**
-* Pick the engine to serve a call.
-*
-* Today the rule is "the only one there is". Two cases are refused rather
-* than guessed:
-*
-*  - **none registered** — resolving to a no-op would make every read
-*    answer `undefined` and every write disappear, which reads exactly
-*    like an empty database;
-*  - **more than one** — there is no routing rule yet. The `engine` hint
-*    on `declareCollection` is what will choose, and until it exists a
-*    silent pick would send a collection to whichever engine happened to
-*    register first.
-*/
-function resolveEngine(getEngines) {
-	const engines = getEngines();
-	if (engines.length === 0) throw new Error("settings-store: no data-store-provider engine is registered — the data door has nothing behind it");
-	if (engines.length > 1) throw new Error(`settings-store: ${engines.length} data-store-provider engines are registered and there is no routing rule yet — declare the engine on the collection first`);
-	const engine = engines[0];
-	if (!engine) throw new Error("settings-store: data-store-provider collection yielded an empty entry");
-	return engine;
-}
-/**
-* Build the `settings-store` provider that fronts the registered engines.
-*
-* `getEngines` is read on every call, never captured: engines register
-* during boot and a runner respawn replaces the instance, so a snapshot
-* taken at construction time would go stale exactly when an addon crashed
-* and came back.
-*/
-function createDataStoreDispatch(getEngines) {
-	const engine = async () => resolveEngine(getEngines);
-	return {
-		get: async (input) => (await engine()).get(input),
-		set: async (input) => (await engine()).set(input),
-		query: async (input) => (await engine()).query(input),
-		insert: async (input) => (await engine()).insert(input),
-		insertMany: async (input) => (await engine()).insertMany(input),
-		update: async (input) => (await engine()).update(input),
-		delete: async (input) => (await engine()).delete(input),
-		deleteWhere: async (input) => (await engine()).deleteWhere(input),
-		updateWhere: async (input) => (await engine()).updateWhere(input),
-		count: async (input) => (await engine()).count(input),
-		aggregate: async (input) => (await engine()).aggregate(input),
-		histogram: async (input) => (await engine()).histogram(input),
-		isEmpty: async (input) => (await engine()).isEmpty(input),
-		declareCollection: async (input) => (await engine()).declareCollection(input)
-	};
-}
-//#endregion
 //#region src/builtins/storage-orchestrator/location-secrets.ts
 /**
 * The config keys the ORCHESTRATOR itself owns, as opposed to the ones a
@@ -2833,10 +2978,32 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 			},
 			{
 				capability: settingsStoreCapability,
-				provider: createDataStoreDispatch(getEngines)
+				provider: createDataStoreDispatch(getEngines, () => this.hubSettingsForward())
 			}
 		];
 	}
+	/**
+	* The remote behind the data door on a node that owns no engine.
+	*
+	* `null` on a hub — the hub IS the store, and a hub that forwarded would
+	* route its own door back into itself through `$hub-cap-fwd`. `null` too
+	* when this process has no cluster broker (a forked worker, or a test
+	* harness); the door then behaves exactly as it always did and refuses.
+	*
+	* Built once and memoised. It is only consulted when `getEngines()` is
+	* empty, so on a hub — and on an agent rolled back to a local engine via
+	* `CAMSTACK_AGENT_LOCAL_DATA_STORE` — the resolve never runs a second time.
+	*/
+	hubForward = null;
+	hubSettingsForward() {
+		if (this.hubForward) return this.hubForward;
+		this.hubForward = resolveHubSettingsForward({
+			env: process.env,
+			broker: this.ctx.kernel.cluster?.broker,
+			logger: this.ctx.logger
+		});
+		return this.hubForward;
+	}
 	async onShutdown() {
 		for (const dispose of this.seedSubscriptionDisposers) try {
 			dispose();
@@ -2857,9 +3024,19 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 	/**
 	* Resolve the live engine from the capability registry and wrap it in a
 	* `SqliteLocationStore`. Returns `null` when no engine has registered
-	* yet — the service falls back to in-memory only. Production boot order
-	* (`data-store-provider` precedes `storage` in `INFRA_CAPABILITIES`)
-	* makes this the rare path.
+	* yet — the service falls back to in-memory only. On a HUB that is a
+	* boot-order window: `data-store-provider` precedes `storage` in
+	* `INFRA_CAPABILITIES`, so it is the rare path.
+	*
+	* On an AGENT it is permanent and intended, and the line says so. An agent
+	* boots no engine (`resolveAgentInfraCapabilities`), and this store must NOT
+	* be pointed at the hub-forwarding data door: `storage_locations` is keyed by
+	* a bare location id (`recordings:default`, `eventMedia:default`, …) which
+	* every node in the cluster shares, so an agent writing through the door
+	* would land on the HUB's rows. The locations an agent needs are re-seeded
+	* from its addon declarations at every boot; the operator's real, node-pinned
+	* locations live in the hub's own table (`__nodeId` in the config blob) and
+	* are dispatched to the agent's `storage-provider` from there.
 	*
 	* Reads the ENGINE, not the `settings-store` singleton: since D44 this
 	* addon *is* that singleton, so asking the registry for it would hand
@@ -2871,7 +3048,8 @@ var StorageOrchestratorAddon = class extends BaseAddon {
 		if (!reg) return null;
 		const engine = reg.getCollection(DATA_STORE_PROVIDER_CAP_NAME)[0];
 		if (!engine) {
-			if (!quiet) this.ctx.logger.warn("storage-orchestrator: no data-store-provider engine yet — running in-memory until one registers");
+			if (!quiet) if (nodeOwnsItsDataStore(process.env)) this.ctx.logger.warn("storage-orchestrator: no data-store-provider engine yet — running in-memory until one registers");
+			else this.ctx.logger.info("storage-orchestrator: this node boots no data-store engine — storage locations are seeded from addon declarations at every boot, and node-pinned locations live on the hub");
 			return null;
 		}
 		return new SqliteLocationStore(engine);

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

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-D6kBG4fg.js");
+const require_dist = require("../../dist-DsoVfJSR.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.