@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/storage-orchestrator/hub-settings-forward.d.ts

@@ -1,68 +1,128 @@
-import { IClusterBroker, IScopedLogger, ISettingsStoreProvider } from '@camstack/types';
 /**
- * The envelope `$hub-cap-fwd.forward` takes. Structurally
- * `HubCapForwardParams` minus the routing hints this door never sets: a
- * settings call carries no `deviceId`, pins no node (the hub's store is THE
- * store) and asks for no native provider.
- */
+* 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.
+*/
+import { type IClusterBroker, type IScopedLogger, type ISettingsStoreProvider } from "@camstack/types";
+/**
+* The envelope `$hub-cap-fwd.forward` takes. Structurally
+* `HubCapForwardParams` minus the routing hints this door never sets: a
+* settings call carries no `deviceId`, pins no node (the hub's store is THE
+* store) and asks for no native provider.
+*/
 export interface HubForwardEnvelope {
-    readonly capName: string;
-    readonly method: string;
-    readonly args: unknown;
+	readonly capName: string;
+	readonly method: string;
+	readonly args: unknown;
 }
 /**
- * How a forward reaches the hub. Generic in the result so the provider's
- * per-method return types flow through without a cast — the transport is the
- * documented type boundary, exactly as it is for the generated cap routers'
- * remote proxies.
- */
+* How a forward reaches the hub. Generic in the result so the provider's
+* per-method return types flow through without a cast — the transport is the
+* documented type boundary, exactly as it is for the generated cap routers'
+* remote proxies.
+*/
 export type HubForwardCall = <TResult>(envelope: HubForwardEnvelope) => Promise<TResult>;
 /**
- * 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.
- */
+* 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.
+*/
 export declare function nodeOwnsItsDataStore(env: NodeJS.ProcessEnv): boolean;
 /**
- * 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.
- */
+* 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.
+*/
 export declare function createHubSettingsForward(forward: HubForwardCall): ISettingsStoreProvider;
 /**
- * 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.
- */
-export declare const HUB_SETTINGS_FORWARD_TIMEOUT_MS = 60000;
+* 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.
+*/
+export declare const HUB_SETTINGS_FORWARD_TIMEOUT_MS = 6e4;
 /** What {@link resolveHubSettingsForward} needs. Narrow on purpose — fakeable. */
 export interface HubSettingsForwardOptions {
-    readonly env: NodeJS.ProcessEnv;
-    /** `undefined` in a forked worker or a test harness — no cluster to reach. */
-    readonly broker: IClusterBroker | undefined;
-    readonly logger: Pick<IScopedLogger, 'info'>;
+	readonly env: NodeJS.ProcessEnv;
+	/** `undefined` in a forked worker or a test harness — no cluster to reach. */
+	readonly broker: IClusterBroker | undefined;
+	readonly logger: Pick<IScopedLogger, "info">;
 }
 /**
- * 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.
- */
+* 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.
+*/
 export declare function resolveHubSettingsForward(options: HubSettingsForwardOptions): ISettingsStoreProvider | null;

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

@@ -1,7 +1,7 @@
-export type { ILocationStore } from './location-store.js';
-export { SqliteLocationStore } from './location-store.js';
-export type { FootageMigrationParticipant, LeaseParticipant, MediaMigrationParticipant, MigrationState, StorageMigrationCoordinatorDeps, StorageMigrationParticipants, } from './storage-migration-coordinator.js';
-export { StorageMigrationCoordinator } from './storage-migration-coordinator.js';
-export { StorageOrchestratorAddon, StorageOrchestratorAddon as default, } from './storage-orchestrator.addon.js';
-export type { ListLocationsFilter, StorageProviderLookup } from './storage-orchestrator.service.js';
-export { StorageOrchestratorService } from './storage-orchestrator.service.js';
+export type { ILocationStore } from "./location-store.js";
+export { SqliteLocationStore } from "./location-store.js";
+export type { FootageMigrationParticipant, LeaseParticipant, MediaMigrationParticipant, MigrationState, StorageMigrationCoordinatorDeps, StorageMigrationParticipants } from "./storage-migration-coordinator.js";
+export { StorageMigrationCoordinator } from "./storage-migration-coordinator.js";
+export { StorageOrchestratorAddon, StorageOrchestratorAddon as default } from "./storage-orchestrator.addon.js";
+export type { ListLocationsFilter, StorageProviderLookup } from "./storage-orchestrator.service.js";
+export { StorageOrchestratorService } from "./storage-orchestrator.service.js";

package/dist/builtins/storage-orchestrator/location-occupancy-slice.d.ts

@@ -1,47 +1,71 @@
-import { IScopedLogger, IStorageOccupancyProvider } from '@camstack/types';
+/**
+* How much of each location CamStack ITSELF holds (D388) — the slice
+* `listLocations` stamps from.
+*
+* ## Why this is a slice and not a call
+*
+* `listLocations` is on the admin UI's hot path. Fanning out a per-addon RPC
+* synchronously on every list would put a cross-process round trip (and, in the
+* providers, an indexed SQL aggregate) in front of a screen that repaints on
+* every navigation, and a slow or dead addon would hang the whole page.
+*
+* So this follows D224's freshness discipline: the figure has a WINDOW, a read
+* is answered from the slice — empty included — and a read NEVER joins a
+* refresh already in flight. Staleness costs the operator a figure that is up
+* to one window old, which the stamped `measuredAtMs` tells them; the
+* alternative costs them the screen.
+*
+* ## Absence is the answer (D315)
+*
+* A location no provider reported for is UNKNOWN, and this module has no code
+* path that turns that into a zero. `ownedFor` returns `undefined`, the
+* orchestrator omits the field, and a UI omits the segment. A share drawn at
+* zero would claim we occupy nothing, which is a different and false statement.
+*/
+import type { IScopedLogger, IStorageOccupancyProvider } from "@camstack/types";
 /** What one location's owners hold there, merged. */
 export interface LocationOwnedBytes {
-    readonly bytes: number;
-    /** The OLDEST contributing measurement — honest about the whole figure
-     *  rather than about its freshest part. */
-    readonly measuredAtMs: number;
+	readonly bytes: number;
+	/** The OLDEST contributing measurement — honest about the whole figure
+	*  rather than about its freshest part. */
+	readonly measuredAtMs: number;
 }
 export interface OccupancySliceDeps {
-    readonly logger: IScopedLogger;
-    /** Registered `storage-occupancy` providers (cross-process proxies). */
-    readonly getProviders: () => readonly IStorageOccupancyProvider[];
-    /** Every location worth asking about, at refresh time. */
-    readonly locationIds: () => readonly string[];
-    readonly now: () => number;
-    /** How long a figure stays servable before a refresh is kicked. */
-    readonly staleAfterMs?: number;
+	readonly logger: IScopedLogger;
+	/** Registered `storage-occupancy` providers (cross-process proxies). */
+	readonly getProviders: () => readonly IStorageOccupancyProvider[];
+	/** Every location worth asking about, at refresh time. */
+	readonly locationIds: () => readonly string[];
+	readonly now: () => number;
+	/** How long a figure stays servable before a refresh is kicked. */
+	readonly staleAfterMs?: number;
 }
 export declare class LocationOccupancySlice {
-    private readonly deps;
-    private slice;
-    private refreshing;
-    private lastRefreshMs;
-    constructor(deps: OccupancySliceDeps);
-    /**
-     * What the last completed refresh saw for this location, or `undefined` when
-     * nothing has reported for it. There is deliberately no fallback: unknown is
-     * the truth about a location nobody owns bytes on.
-     */
-    ownedFor(locationId: string): LocationOwnedBytes | undefined;
-    /**
-     * Serve-and-revalidate. Called by every read: it returns immediately, and
-     * kicks a background refresh when the slice is older than the window. A read
-     * never awaits, and never joins a refresh already in flight (D224).
-     */
-    serveAndRevalidate(): void;
-    /**
-     * Ask every provider once and replace the slice.
-     *
-     * A provider that throws contributes NOTHING and is logged — it does not
-     * contribute a zero, and it does not take the other providers' answers down
-     * with it. A location that ends up with no contribution at all simply stays
-     * out of the slice, which is what makes it read back as unknown.
-     */
-    refresh(): Promise<void>;
-    private runRefresh;
+	private readonly deps;
+	private slice;
+	private refreshing;
+	private lastRefreshMs;
+	constructor(deps: OccupancySliceDeps);
+	/**
+	* What the last completed refresh saw for this location, or `undefined` when
+	* nothing has reported for it. There is deliberately no fallback: unknown is
+	* the truth about a location nobody owns bytes on.
+	*/
+	ownedFor(locationId: string): LocationOwnedBytes | undefined;
+	/**
+	* Serve-and-revalidate. Called by every read: it returns immediately, and
+	* kicks a background refresh when the slice is older than the window. A read
+	* never awaits, and never joins a refresh already in flight (D224).
+	*/
+	serveAndRevalidate(): void;
+	/**
+	* Ask every provider once and replace the slice.
+	*
+	* A provider that throws contributes NOTHING and is logged — it does not
+	* contribute a zero, and it does not take the other providers' answers down
+	* with it. A location that ends up with no contribution at all simply stays
+	* out of the slice, which is what makes it read back as unknown.
+	*/
+	refresh(): Promise<void>;
+	private runRefresh;
 }

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

@@ -1,19 +1,19 @@
-import { LocationOccupancy } from './storage-orchestrator.service.js';
+import type { LocationOccupancy } from "./storage-orchestrator.service.js";
 /**
- * Class → directories under `<root>/<camera>/`. Same map as the discard
- * wipe (`DISCARD_SUBTREES` in the recorder / pipeline-analytics addons).
- * Types not listed keep the legacy "any non-dot entry at the root" rule
- * (backups, addon-data, …).
- */
+* Class → directories under `<root>/<camera>/`. Same map as the discard
+* wipe (`DISCARD_SUBTREES` in the recorder / pipeline-analytics addons).
+* Types not listed keep the legacy "any non-dot entry at the root" rule
+* (backups, addon-data, …).
+*/
 export declare const STORAGE_CLASS_SUBTREES: Readonly<Record<string, readonly string[]>>;
 /**
- * Occupancy of `basePath` for a location of `type`.
- *
- *  - missing root → `empty` (nothing this delete can strand)
- *  - class-mapped type → occupied iff any `<camera>/<subtree>` has an entry
- *  - other types → occupied iff the root has a non-dot entry
- */
+* Occupancy of `basePath` for a location of `type`.
+*
+*  - missing root → `empty` (nothing this delete can strand)
+*  - class-mapped type → occupied iff any `<camera>/<subtree>` has an entry
+*  - other types → occupied iff the root has a non-dot entry
+*/
 export declare function probeLocalDirectoryOccupancy(input: {
-    readonly type: string;
-    readonly basePath: string;
+	readonly type: string;
+	readonly basePath: string;
 }): Promise<LocationOccupancy>;

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

@@ -1,20 +1,20 @@
 /** statfs of the location's volume, when this node could take it. */
 export interface LocationVolumeCapacity {
-    readonly totalBytes: number;
-    readonly availableBytes: number;
+	readonly totalBytes: number;
+	readonly availableBytes: number;
 }
 /** One line, at most once per location per process. */
 export type ProtectionNotice = (message: string, meta: Record<string, unknown>) => void;
 /**
- * The free-space percentage the guard enforces for one location.
- *
- * Order:
- *   1. `config.minFreeGb`, converted against the volume total — the operator's
- *      criterion in the unit they set it in.
- *   2. `config.minFreePercent` — the legacy per-location override, and the
- *      fallback when `minFreeGb` cannot be converted (no volume total: a
- *      remote-node or unstattable location). Falling back is the right
- *      direction — the alternative is a location with no guard at all.
- *   3. the provider's declared default.
- */
+* The free-space percentage the guard enforces for one location.
+*
+* Order:
+*   1. `config.minFreeGb`, converted against the volume total — the operator's
+*      criterion in the unit they set it in.
+*   2. `config.minFreePercent` — the legacy per-location override, and the
+*      fallback when `minFreeGb` cannot be converted (no volume total: a
+*      remote-node or unstattable location). Falling back is the right
+*      direction — the alternative is a location with no guard at all.
+*   3. the provider's declared default.
+*/
 export declare function resolveMinFreePercent(config: Readonly<Record<string, unknown>>, providerDefaultPercent: number, capacity: LocationVolumeCapacity | null, notice: ProtectionNotice): number;

package/dist/builtins/storage-orchestrator/location-repoint-move.d.ts

@@ -1,52 +1,52 @@
 /**
- * Moving a location's bytes when its root is re-pointed.
- *
- * ## Why this exists, and why only for singletons
- *
- * A `multi` location moves the sanctioned way: register a second instance,
- * drain the first, watch it empty (D386). A **singleton** cannot — the
- * cardinality guard in `upsertLocation` refuses the second instance by
- * declaration, so there is no destination to drain into. For those, editing
- * the `basePath` IS the migration, and either it carries the data or the data
- * is stranded.
- *
- * It was stranded. On 2026-09-08 the `artifacts` root moved and 320 enrolled
- * gallery blobs stayed at the previous path — invisible until every face in the
- * Review panel answered 404, and one boot away from being collected as "the
- * pixels are gone" by a reconcile that had no way to know better.
- *
- * ## The order is the safety property
- *
- * copy → verify → (caller saves the row) → delete. A crash at any point leaves
- * the bytes somewhere that a location still points at: before the row moves,
- * that is the OLD root; after it, the new one holds a verified copy. Nothing
- * here deletes anything until every file has landed and been read back.
- *
- * A failure ABORTS with nothing deleted, so the caller can refuse the edit and
- * leave the operator pointing at intact data.
- *
- * I/O is injected: the walk and the ordering are what matter and they are
- * testable without a filesystem.
- */
+* Moving a location's bytes when its root is re-pointed.
+*
+* ## Why this exists, and why only for singletons
+*
+* A `multi` location moves the sanctioned way: register a second instance,
+* drain the first, watch it empty (D386). A **singleton** cannot — the
+* cardinality guard in `upsertLocation` refuses the second instance by
+* declaration, so there is no destination to drain into. For those, editing
+* the `basePath` IS the migration, and either it carries the data or the data
+* is stranded.
+*
+* It was stranded. On 2026-09-08 the `artifacts` root moved and 320 enrolled
+* gallery blobs stayed at the previous path — invisible until every face in the
+* Review panel answered 404, and one boot away from being collected as "the
+* pixels are gone" by a reconcile that had no way to know better.
+*
+* ## The order is the safety property
+*
+* copy → verify → (caller saves the row) → delete. A crash at any point leaves
+* the bytes somewhere that a location still points at: before the row moves,
+* that is the OLD root; after it, the new one holds a verified copy. Nothing
+* here deletes anything until every file has landed and been read back.
+*
+* A failure ABORTS with nothing deleted, so the caller can refuse the edit and
+* leave the operator pointing at intact data.
+*
+* I/O is injected: the walk and the ordering are what matter and they are
+* testable without a filesystem.
+*/
 /** The four operations a move needs, in the caller's own terms. */
 export interface RepointMoveIo {
-    /** Entries directly under `prefix` (undefined = the root), as relative paths. */
-    list(prefix: string | undefined): Promise<readonly string[]>;
-    /** Bytes of a source file. THROWS when the path is a directory. */
-    read(relativePath: string): Promise<Uint8Array<ArrayBuffer>>;
-    /** Write into the destination root. */
-    write(relativePath: string, data: Uint8Array<ArrayBuffer>): Promise<void>;
-    /** Read back from the DESTINATION, to prove the copy landed. */
-    readBack(relativePath: string): Promise<Uint8Array<ArrayBuffer>>;
-    /** Remove one file from the source root. */
-    deleteSource(relativePath: string): Promise<void>;
+	/** Entries directly under `prefix` (undefined = the root), as relative paths. */
+	list(prefix: string | undefined): Promise<readonly string[]>;
+	/** Bytes of a source file. THROWS when the path is a directory. */
+	read(relativePath: string): Promise<Uint8Array<ArrayBuffer>>;
+	/** Write into the destination root. */
+	write(relativePath: string, data: Uint8Array<ArrayBuffer>): Promise<void>;
+	/** Read back from the DESTINATION, to prove the copy landed. */
+	readBack(relativePath: string): Promise<Uint8Array<ArrayBuffer>>;
+	/** Remove one file from the source root. */
+	deleteSource(relativePath: string): Promise<void>;
 }
 export interface RepointMoveResult {
-    readonly files: number;
-    readonly bytes: number;
+	readonly files: number;
+	readonly bytes: number;
 }
 /**
- * Copy every file from the source root to the destination, verify each, then
- * delete the originals. Throws with NOTHING deleted if any copy fails.
- */
+* Copy every file from the source root to the destination, verify each, then
+* delete the originals. Throws with NOTHING deleted if any copy fails.
+*/
 export declare function moveLocationTree(io: RepointMoveIo): Promise<RepointMoveResult>;

package/dist/builtins/storage-orchestrator/location-root-collision.d.ts

@@ -1,44 +1,80 @@
-import { PhysicalRoot } from '@camstack/types/node';
+/**
+* Two locations of the SAME type must not share a physical root (D389).
+*
+* ## What is legitimate and must stay legitimate
+*
+* Two locations of DIFFERENT types on one root is a designed configuration, not
+* an accident: stock `recordings` and `recordingsLow` deliberately share a root
+* (D327 scores occupancy by class SUBTREE — `high|mid` against `low` — and the
+* recorder's eviction domain merges same-root aliases into one oldest-first
+* pool on purpose). A check that refused every shared root would break the
+* default install.
+*
+* ## What is a collision
+*
+* Two locations of the same TYPE on one physical root. Their class subtrees are
+* identical, so every per-location figure double-counts and every deletion
+* under one is a deletion under the other. The recorder already has a late
+* parachute for this — `demoteWritableAliasConflicts` demotes the extras to
+* read-only and logs — but by then the operator has created the row and may
+* have pointed configuration at it. This refuses it at the door, and the
+* parachute stays: it still guards rows created before this check existed, and
+* a guard that only exists at the door is not a guard.
+*
+* Containment counts, in BOTH directions. A location nested inside another's
+* tree is worse than two equal roots: the accounting overlaps and a deletion
+* under the outer one can take the inner one's footage with it.
+*
+* ## "They collide" is not "I cannot tell"
+*
+* A location on another node, or behind a remote provider, cannot be resolved
+* from here. An unresolvable root produces a WARNING and lets the write
+* through — never a refusal. Refusing on an unanswerable read blocks the
+* operator on a doubt (D49's spirit: a fallible read is not the gate).
+*
+* Pure: the realpath derivation is injected.
+*/
+import type { PhysicalRoot } from "@camstack/types/node";
 /** The minimum a row must expose for this check. */
 export interface RootCollisionCandidate {
-    readonly id: string;
-    readonly type: string;
-    /** Which node the path lives on. Two locations on DIFFERENT nodes can never
-     *  collide, however identical their paths look. */
-    readonly nodeId?: string;
-    readonly config: Readonly<Record<string, unknown>>;
+	readonly id: string;
+	readonly type: string;
+	/** Which node the path lives on. Two locations on DIFFERENT nodes can never
+	*  collide, however identical their paths look. */
+	readonly nodeId?: string;
+	readonly config: Readonly<Record<string, unknown>>;
 }
 /** How this location's physical root was derived, or that it could not be. */
 export type ResolveRoot = (basePath: string) => PhysicalRoot;
 /** A same-type root collision, with everything the message needs to name it. */
 export interface RootCollision {
-    readonly otherId: string;
-    readonly type: string;
-    readonly sharedRoot: string;
-    /** `equal` — the same directory. `nested` — one inside the other's tree. */
-    readonly kind: 'equal' | 'nested';
+	readonly otherId: string;
+	readonly type: string;
+	readonly sharedRoot: string;
+	/** `equal` — the same directory. `nested` — one inside the other's tree. */
+	readonly kind: "equal" | "nested";
 }
 /** Why the check could not be made. Never a refusal — the caller warns. */
 export interface RootCollisionUnknown {
-    readonly reason: 'no-base-path' | 'unresolvable';
-    readonly detail: string;
+	readonly reason: "no-base-path" | "unresolvable";
+	readonly detail: string;
 }
 export type RootCollisionVerdict = {
-    readonly outcome: 'clear';
+	readonly outcome: "clear";
 } | {
-    readonly outcome: 'collides';
-    readonly collision: RootCollision;
+	readonly outcome: "collides";
+	readonly collision: RootCollision;
 } | {
-    readonly outcome: 'unknown';
-    readonly unknown: RootCollisionUnknown;
+	readonly outcome: "unknown";
+	readonly unknown: RootCollisionUnknown;
 };
 /**
- * Does `next` collide with anything already stored?
- *
- * `existing` is every other location; the row being EDITED is excluded by id,
- * so re-saving a location without moving its root never refuses itself.
- */
+* Does `next` collide with anything already stored?
+*
+* `existing` is every other location; the row being EDITED is excluded by id,
+* so re-saving a location without moving its root never refuses itself.
+*/
 export declare function findRootCollision(next: RootCollisionCandidate, existing: Iterable<RootCollisionCandidate>, resolveRoot: ResolveRoot, storedSelf?: RootCollisionCandidate): RootCollisionVerdict;
 /** The operator-facing refusal. Names the location it collides with and the
- *  shared root — a refusal that says only "conflict" makes the operator hunt. */
+*  shared root — a refusal that says only "conflict" makes the operator hunt. */
 export declare function rootCollisionMessage(id: string, collision: RootCollision): string;