@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/device-manager/adoption-job-engine.d.ts

@@ -1,110 +1,153 @@
-import { AdoptionJob, IScopedLogger } from '@camstack/types';
-import { RemovalFence } from './removal-fence.js';
 /**
- * The slice of a `device-adoption` provider this engine drives. Structural on
- * purpose: the real provider satisfies it, and a spec can exercise the whole
- * loop without standing up a registry.
- */
+* Background adoption job engine.
+*
+* `device-adoption.adopt({childNativeIds: [...]})` materialises one CamStack
+* device per candidate PLUS every accessory child, and the whole array shares
+* ONE UDS request deadline (60s). The deadline is correct and is not the thing
+* to raise — `SocketChannel.request` once had no timeout at all and a mute peer
+* hung forever. The work simply does not fit inside it:
+*
+* Measured on the live hub (Home Assistant, 491 candidates):
+*   - `listCandidates` for the whole inventory: ~200 ms. Not the cost.
+*   - Each device the kernel creates: ~450 ms, because `devices.create`
+*     pre-seeds meta with up to eleven SEQUENTIAL round trips before the class
+*     is constructed. An accessory child costs exactly what its parent costs.
+*   - 25 candidates × ~6 children → ~150 devices → timed out at 60,346 ms with
+*     9 of 25 landed; the provider kept going and finished all 25 at ~130 s.
+*   - ONE candidate with 217 children → timed out at 61,829 ms.
+*
+* That last line is the whole argument for a job. The count that blows the
+* budget is the SOURCE SYSTEM's accessory fan-out — the operator neither picks
+* it nor sees it — so no chunk size, no bounded concurrency over candidates and
+* no per-call tuning fixes a shape where N=1 already fails.
+*
+* ## Why serial, and not bounded-concurrent
+*
+* Every one of those ~450 ms is round trips into the single-threaded hub, not
+* work this process could overlap. Running candidates concurrently would
+* multiply pressure on the same event loop that the live pipeline shares, and
+* would race two `allocateDeviceId` calls for the same stableId when a source
+* system exposes one entity under two candidates. The concurrency here is
+* deliberately ONE; the fix for wall-clock is collapsing the eleven-RPC
+* pre-seed in `devices.create`, which is a separate, framework-wide change.
+*
+* ## Cheap question first
+*
+* A candidate that is already adopted is skipped BEFORE any provider call, from
+* one `listCandidates` snapshot taken at job start. That makes a retry after a
+* timeout a no-op for everything that already landed, instead of the current
+* behaviour — the provider throws on a duplicate stableId, and when EVERY
+* resubmitted candidate was already adopted the whole call fails with
+* "all N adopt(s) failed", which reads as "nothing worked" when in truth
+* everything did.
+*/
+import type { AdoptionJob, IScopedLogger } from "@camstack/types";
+import type { RemovalFence } from "./removal-fence.js";
+/**
+* The slice of a `device-adoption` provider this engine drives. Structural on
+* purpose: the real provider satisfies it, and a spec can exercise the whole
+* loop without standing up a registry.
+*/
 export interface AdoptionJobProvider {
-    listCandidates(input: {
-        integrationId: string;
-        page: number;
-        pageSize: number;
-        filter?: string;
-    }): Promise<{
-        readonly candidates: readonly {
-            readonly childNativeId: string;
-            readonly alreadyAdopted?: boolean;
-        }[];
-    }>;
-    adopt(input: {
-        integrationId: string;
-        childNativeIds: readonly string[];
-        filter?: string;
-        importLocations?: boolean;
-        perCandidate?: Record<string, {
-            name?: string;
-            hiddenChildIds?: string[];
-        }>;
-    }): Promise<AdoptResult>;
+	listCandidates(input: {
+		integrationId: string;
+		page: number;
+		pageSize: number;
+		filter?: string;
+	}): Promise<{
+		readonly candidates: readonly {
+			readonly childNativeId: string;
+			readonly alreadyAdopted?: boolean;
+		}[];
+	}>;
+	adopt(input: {
+		integrationId: string;
+		childNativeIds: readonly string[];
+		filter?: string;
+		importLocations?: boolean;
+		perCandidate?: Record<string, {
+			name?: string;
+			hiddenChildIds?: string[];
+		}>;
+	}): Promise<AdoptResult>;
 }
 /** What one `adopt` call answers. Named so the per-candidate suspension in
- *  {@link AdoptionJobEngine} has a return type to state. */
+*  {@link AdoptionJobEngine} has a return type to state. */
 export interface AdoptResult {
-    readonly adopted: readonly {
-        readonly childNativeId: string;
-        readonly parentDeviceId: number;
-        readonly accessoryDeviceIds: readonly number[];
-    }[];
+	readonly adopted: readonly {
+		readonly childNativeId: string;
+		readonly parentDeviceId: number;
+		readonly accessoryDeviceIds: readonly number[];
+	}[];
 }
 export interface AdoptionJobEngineDeps {
-    /** Resolve the integration's adoption provider for an `addonId` pin. */
-    resolveProvider(addonId: string): Promise<AdoptionJobProvider>;
-    readonly logger: IScopedLogger;
-    /**
-     * The device-manager's removal fence, so an operator re-adopting hardware
-     * they just deleted is not refused for their OWN action.
-     *
-     * `removal-fence.ts` says a deliberate re-add lifts the fence, and
-     * `adoptDevice` does exactly that — but a job never went near it, so every
-     * integration driven through this engine refused a re-add for the whole
-     * 5-minute TTL. Reported on a Dreame vacuum, 2026-09-16.
-     *
-     * It has to be suspended HERE and not by the caller: `runUnfenced` is a
-     * counter held for the length of an awaited call, while `start()` hands back
-     * a jobId immediately and adopts on a detached promise. Wrapping the caller
-     * would lower the fence for the microseconds it takes to mint an id.
-     *
-     * Optional: absent means exactly the previous behaviour.
-     */
-    readonly removalFence?: RemovalFence;
-    readonly now?: () => number;
-    readonly newId?: () => string;
+	/** Resolve the integration's adoption provider for an `addonId` pin. */
+	resolveProvider(addonId: string): Promise<AdoptionJobProvider>;
+	readonly logger: IScopedLogger;
+	/**
+	* The device-manager's removal fence, so an operator re-adopting hardware
+	* they just deleted is not refused for their OWN action.
+	*
+	* `removal-fence.ts` says a deliberate re-add lifts the fence, and
+	* `adoptDevice` does exactly that — but a job never went near it, so every
+	* integration driven through this engine refused a re-add for the whole
+	* 5-minute TTL. Reported on a Dreame vacuum, 2026-09-16.
+	*
+	* It has to be suspended HERE and not by the caller: `runUnfenced` is a
+	* counter held for the length of an awaited call, while `start()` hands back
+	* a jobId immediately and adopts on a detached promise. Wrapping the caller
+	* would lower the fence for the microseconds it takes to mint an id.
+	*
+	* Optional: absent means exactly the previous behaviour.
+	*/
+	readonly removalFence?: RemovalFence;
+	readonly now?: () => number;
+	readonly newId?: () => string;
 }
 export interface StartAdoptionJobInput {
-    readonly addonId: string;
-    readonly integrationId: string;
-    readonly childNativeIds: readonly string[];
-    readonly filter?: string;
-    readonly importLocations?: boolean;
-    readonly perCandidate?: Record<string, {
-        name?: string;
-        hiddenChildIds?: string[];
-    }>;
+	readonly addonId: string;
+	readonly integrationId: string;
+	readonly childNativeIds: readonly string[];
+	readonly filter?: string;
+	readonly importLocations?: boolean;
+	readonly perCandidate?: Record<string, {
+		name?: string;
+		hiddenChildIds?: string[];
+	}>;
 }
 export declare class AdoptionJobEngine {
-    private readonly deps;
-    private readonly jobs;
-    private seq;
-    constructor(deps: AdoptionJobEngineDeps);
-    private now;
-    private newId;
-    /**
-     * Accept the batch and return immediately. The provider is resolved BEFORE
-     * returning so an unroutable `addonId` is refused at the call the operator
-     * made, not buried in a job they have to go looking for.
-     */
-    start(input: StartAdoptionJobInput): Promise<{
-        jobId: string;
-    }>;
-    get(jobId: string): AdoptionJob | null;
-    list(filter: {
-        addonId?: string;
-        integrationId?: string;
-    }): readonly AdoptionJob[];
-    /** Cooperative cancel — the in-flight candidate finishes, the rest do not start. */
-    cancel(jobId: string): boolean;
-    /** Test-only: await the detached loop. Never called by production code. */
-    waitForTest(jobId: string): Promise<void>;
-    private prune;
-    private run;
-    /**
-     * One `listCandidates` snapshot at job start. A read that FAILS must not be
-     * read as "nothing is adopted" — that would send every candidate to the
-     * provider and turn a safe retry back into a wall of duplicate-stableId
-     * errors — so a failure yields an empty set AND a warning, and the
-     * per-candidate failure path stays the backstop.
-     */
-    private alreadyAdopted;
-    private adoptOne;
+	private readonly deps;
+	private readonly jobs;
+	private seq;
+	constructor(deps: AdoptionJobEngineDeps);
+	private now;
+	private newId;
+	/**
+	* Accept the batch and return immediately. The provider is resolved BEFORE
+	* returning so an unroutable `addonId` is refused at the call the operator
+	* made, not buried in a job they have to go looking for.
+	*/
+	start(input: StartAdoptionJobInput): Promise<{
+		jobId: string;
+	}>;
+	get(jobId: string): AdoptionJob | null;
+	list(filter: {
+		addonId?: string;
+		integrationId?: string;
+	}): readonly AdoptionJob[];
+	/** Cooperative cancel — the in-flight candidate finishes, the rest do not start. */
+	cancel(jobId: string): boolean;
+	/** Test-only: await the detached loop. Never called by production code. */
+	waitForTest(jobId: string): Promise<void>;
+	private prune;
+	private run;
+	/**
+	* One `listCandidates` snapshot at job start. A read that FAILS must not be
+	* read as "nothing is adopted" — that would send every candidate to the
+	* provider and turn a safe retry back into a wall of duplicate-stableId
+	* errors — so a failure yields an empty set AND a warning, and the
+	* per-candidate failure path stays the backstop.
+	*/
+	private alreadyAdopted;
+	private adoptOne;
 }

package/dist/builtins/device-manager/claimed-status-overlay.d.ts

@@ -1,12 +1,45 @@
-import { ICapabilityRegistry, IScopedLogger } from '@camstack/types';
-import { DeviceManagerSettings } from './device-meta-store.js';
-import { ClaimsIndexView, DeviceStateMirror } from './device-state-mirror.js';
+/**
+* The device-manager's side of the claimed-status overlay (D663, ruling S3):
+* the `CapabilityRegistry` asks "is `(cap, device)` claimed, and what does the
+* merge say?" and the answer comes from the mirror's `effectiveIfClaimed` —
+* once the device's claims are KNOWN.
+*
+* Knowing them is the point (D315, D49). The mirror seeds a device lazily, on
+* its provider's first native write, so from hub boot until then
+* `effectiveIfClaimed` is `null` for every device — and `null` read as
+* "unclaimed" would hand every caller the native value of a claimed cap for as
+* long as a sleeping battery camera takes to report (an hour, per boot), then
+* swap it under them. So:
+*   - `peek` (synchronous, the registry's resolve-time question) answers from
+*     what is known: a seeded device from its merge; an unseeded device the
+*     LOADED claims index does not name is KNOWN unclaimed (and marked seeded,
+*     as `ensureSeeded` would); anything else is `unknown`.
+*   - `resolve` (awaited on the `getStatus` call path) makes the claims known
+*     first — `ensureSeeded`: the index, and when it cannot vouch for the
+*     device, its row read once, single-flight — then answers from the merge.
+*     A row that cannot be read stays `unknown`, which every consumer answers
+*     as "not reported", never the native; the mirror logs that refusal once
+*     per device.
+*
+* A cap that declares no `runtimeState` can never be claimed — claims live
+* only on runtime-state slices — so it is answered `unclaimed` before either
+* question is asked (final review M-2): no row read on its call path while the
+* index is not loaded (D447), and no false "unknown" while the row is
+* unreadable (D315).
+*
+* Installed once at init, over the mirror and index the addon owns; the
+* returned uninstall runs on shutdown so a registry that outlives this addon
+* does not keep asking a dead mirror.
+*/
+import type { ICapabilityRegistry, IScopedLogger } from "@camstack/types";
+import type { DeviceManagerSettings } from "./device-meta-store.js";
+import type { ClaimsIndexView, DeviceStateMirror } from "./device-state-mirror.js";
 export interface ClaimedStatusOverlayDeps {
-    readonly mirror: DeviceStateMirror;
-    /** The claims index as it is NOW — loaded or not; read at every question, never captured. */
-    readonly claimsIndex: () => ClaimsIndexView;
-    /** The settings door the mirror reads a device's row through. */
-    readonly settings: () => DeviceManagerSettings;
-    readonly logger: IScopedLogger;
+	readonly mirror: DeviceStateMirror;
+	/** The claims index as it is NOW — loaded or not; read at every question, never captured. */
+	readonly claimsIndex: () => ClaimsIndexView;
+	/** The settings door the mirror reads a device's row through. */
+	readonly settings: () => DeviceManagerSettings;
+	readonly logger: IScopedLogger;
 }
 export declare function installClaimedStatusOverlay(registry: ICapabilityRegistry, deps: ClaimedStatusOverlayDeps): () => void;

package/dist/builtins/device-manager/contribution-cache.d.ts

@@ -1,68 +1,68 @@
 /**
- * The device-details fan-out, made survivable: budgeted, cached, single-flight.
- *
- * ## What it is for
- *
- * `getDeviceAggregate` asks every contributing provider for this device's
- * settings panel and waits for all of them. Measured on this hub (2026-09-14):
- * 10 595 ms on a battery camera against 331 ms on a mains one, while the page
- * re-polls every 2 500 ms. One slow contributor stalled the whole device page,
- * the poll stacked a fresh 10 s call on top of the one still running, and not
- * one line named which provider was holding it.
- *
- * ## Why a budget alone would have been worse
- *
- * Dropping the provider that overran makes its settings SECTION disappear and
- * come back between polls. A section of settings that flickers is worse than a
- * slow one — and it is also what moved the operator's page: the schema loses a
- * tab for a beat, and everything downstream reacts to a tab that is not there.
- *
- * So the budget is paired with the last answer that provider gave. A slow
- * provider costs the page its budget ONCE; after that the page is instant and
- * shows what that provider last said, until it says something new.
- *
- * ## The rules
- *
- * - **A read never joins a refresh already in flight** (D224). Without this the
- *   2.5 s poll starts a new 10 s call every tick and they pile up.
- * - **An explicit `null` is an ANSWER**, not a miss: it means "I have nothing
- *   for this device", and it replaces what was cached. A cache that only ever
- *   remembers successes would serve a stale panel around a provider that has
- *   since disowned the device.
- * - **A failure falls back**, but a failure with nothing behind it is ABSENT
- *   and says which of the two it was — "never answered" and "answered once and
- *   is now broken" are different operator problems.
- */
+* The device-details fan-out, made survivable: budgeted, cached, single-flight.
+*
+* ## What it is for
+*
+* `getDeviceAggregate` asks every contributing provider for this device's
+* settings panel and waits for all of them. Measured on this hub (2026-09-14):
+* 10 595 ms on a battery camera against 331 ms on a mains one, while the page
+* re-polls every 2 500 ms. One slow contributor stalled the whole device page,
+* the poll stacked a fresh 10 s call on top of the one still running, and not
+* one line named which provider was holding it.
+*
+* ## Why a budget alone would have been worse
+*
+* Dropping the provider that overran makes its settings SECTION disappear and
+* come back between polls. A section of settings that flickers is worse than a
+* slow one — and it is also what moved the operator's page: the schema loses a
+* tab for a beat, and everything downstream reacts to a tab that is not there.
+*
+* So the budget is paired with the last answer that provider gave. A slow
+* provider costs the page its budget ONCE; after that the page is instant and
+* shows what that provider last said, until it says something new.
+*
+* ## The rules
+*
+* - **A read never joins a refresh already in flight** (D224). Without this the
+*   2.5 s poll starts a new 10 s call every tick and they pile up.
+* - **An explicit `null` is an ANSWER**, not a miss: it means "I have nothing
+*   for this device", and it replaces what was cached. A cache that only ever
+*   remembers successes would serve a stale panel around a provider that has
+*   since disowned the device.
+* - **A failure falls back**, but a failure with nothing behind it is ABSENT
+*   and says which of the two it was — "never answered" and "answered once and
+*   is now broken" are different operator problems.
+*/
 /** How long the page waits for ONE provider before serving what it has. */
 export declare const CONTRIBUTION_BUDGET_MS = 1500;
 /**
- * Entries held across all devices. A device page touches a dozen or so, and an
- * operator walks a fleet — bounded so a long session cannot grow it without
- * limit. Oldest-inserted is evicted first; a re-read of an evicted key simply
- * pays the budget again.
- */
+* Entries held across all devices. A device page touches a dozen or so, and an
+* operator walks a fleet — bounded so a long session cannot grow it without
+* limit. Oldest-inserted is evicted first; a re-read of an evicted key simply
+* pays the budget again.
+*/
 export declare const CONTRIBUTION_CACHE_MAX_ENTRIES = 512;
 /** How a single provider's contribution was resolved. */
 export type ContributionOutcome<T> = {
-    readonly kind: 'fresh';
-    readonly value: T | null;
+	readonly kind: "fresh";
+	readonly value: T | null;
 } | {
-    readonly kind: 'stale';
-    readonly value: T;
+	readonly kind: "stale";
+	readonly value: T;
 } | {
-    readonly kind: 'absent';
-    readonly reason: 'slow' | 'failed';
+	readonly kind: "absent";
+	readonly reason: "slow" | "failed";
 };
 export declare class ContributionCache<T = unknown> {
-    private readonly maxEntries;
-    private readonly entries;
-    constructor(maxEntries?: number);
-    /**
-     * Resolve one provider's contribution within `budgetMs`.
-     *
-     * The call is never cancelled: it keeps running and its answer refreshes the
-     * cache, so the provider that overran this page pays for the next one.
-     */
-    resolve(key: string, call: () => Promise<T | null>, budgetMs?: number): Promise<ContributionOutcome<T>>;
-    private remember;
+	private readonly maxEntries;
+	private readonly entries;
+	constructor(maxEntries?: number);
+	/**
+	* Resolve one provider's contribution within `budgetMs`.
+	*
+	* The call is never cancelled: it keeps running and its answer refreshes the
+	* cache, so the provider that overran this page pays for the next one.
+	*/
+	resolve(key: string, call: () => Promise<T | null>, budgetMs?: number): Promise<ContributionOutcome<T>>;
+	private remember;
 }

package/dist/builtins/device-manager/day-night-config-schema.d.ts

@@ -1,16 +1,30 @@
-import { ConfigUISchema, DayNightOptions, DayNightSettingsPatch, DayNightStatus } from '@camstack/types';
 /**
- * Build the `day-night` `ConfigUISchema` from the camera-probed options +
- * current status. Returns `null` when the camera exposes no configurable
- * property — the cap then reports "no schema" and the renderer shows the
- * unsupported-camera message.
- */
+* day-night — server-side `ConfigUISchema` builder + form-patch parser.
+*
+* Sibling of `stream-params-config-schema.ts` (which lives in
+* `@camstack/types` because both vendor providers call it directly from
+* their `getConfigSchema` cap method). `day-night` has no such method —
+* it follows the plain D14 `derived-form` archetype (`getOptions` +
+* `getStatus` + one `setSettings` mutation, no per-vendor schema code) —
+* so this builder lives here in `@camstack/system`, registered against
+* the `day-night` builderId in `device-config-contribution.ts`.
+*
+* Field keys use the `dayNight_<prop>` prefix so a flat form patch can be
+* re-parsed into a `DayNightSettingsPatch` by `parseDayNightFormPatch`.
+*/
+import type { ConfigUISchema, DayNightOptions, DayNightSettingsPatch, DayNightStatus } from "@camstack/types";
+/**
+* Build the `day-night` `ConfigUISchema` from the camera-probed options +
+* current status. Returns `null` when the camera exposes no configurable
+* property — the cap then reports "no schema" and the renderer shows the
+* unsupported-camera message.
+*/
 export declare function buildDayNightConfigSchema(options: DayNightOptions, status: DayNightStatus | null): ConfigUISchema | null;
 /**
- * Re-parse a flat `ConfigFormBuilder` patch into a `DayNightSettingsPatch`.
- * Returns an empty object when no `dayNight_*` field changed — the caller
- * (`parseDerivedFormSettingsPatch`) forwards the result verbatim to the
- * cap's `setSettings` mutation, which itself ignores fields it doesn't
- * support.
- */
+* Re-parse a flat `ConfigFormBuilder` patch into a `DayNightSettingsPatch`.
+* Returns an empty object when no `dayNight_*` field changed — the caller
+* (`parseDerivedFormSettingsPatch`) forwards the result verbatim to the
+* cap's `setSettings` mutation, which itself ignores fields it doesn't
+* support.
+*/
 export declare function parseDayNightFormPatch(patch: Record<string, unknown>): DayNightSettingsPatch;

package/dist/builtins/device-manager/device-aggregation-merge.d.ts

@@ -1,22 +1,22 @@
-import { ConfigUISchemaWithValues } from '@camstack/types';
-import { ContributionShape } from './device-meta-types.js';
+import type { ConfigUISchemaWithValues } from "@camstack/types";
+import type { ContributionShape } from "./device-meta-types.js";
 /**
- * Walk the sections/fields of a contribution and inject `writerCapName` +
- * `writerAddonId` + `source` on each editable field. Readonly fields and
- * structural fields (separator/info/button) pass through untouched. The
- * aggregator is the single place that knows provenance — provider schemas
- * stay clean, UI-bound metadata is attached once at the boundary.
- */
-export declare function tagContribution(contribution: ContributionShape, capName: string, addonId: string, kind: 'settings' | 'live'): ContributionShape;
+* Walk the sections/fields of a contribution and inject `writerCapName` +
+* `writerAddonId` + `source` on each editable field. Readonly fields and
+* structural fields (separator/info/button) pass through untouched. The
+* aggregator is the single place that knows provenance — provider schemas
+* stay clean, UI-bound metadata is attached once at the boundary.
+*/
+export declare function tagContribution(contribution: ContributionShape, capName: string, addonId: string, kind: "settings" | "live"): ContributionShape;
 export declare function isFieldRecord(value: unknown): value is Record<string, unknown>;
 /**
- * Convert a strict `ConfigUISchemaWithValues` (readonly arrays, typed
- * field union) into the cap wire shape `ContributionShape` (mutable
- * arrays, opaque field records). Required because the cap method z.infer
- * uses mutable arrays — readonly arrays are not assignable to mutable
- * even when structurally identical, so a structural copy bridges the gap
- * without disabling the type checker.
- */
+* Convert a strict `ConfigUISchemaWithValues` (readonly arrays, typed
+* field union) into the cap wire shape `ContributionShape` (mutable
+* arrays, opaque field records). Required because the cap method z.infer
+* uses mutable arrays — readonly arrays are not assignable to mutable
+* even when structurally identical, so a structural copy bridges the gap
+* without disabling the type checker.
+*/
 export declare function toWireShape(input: ConfigUISchemaWithValues): ContributionShape;
-export declare function tagField(field: unknown, capName: string, addonId: string, source: 'settings' | 'live', kind: 'settings' | 'live'): unknown;
+export declare function tagField(field: unknown, capName: string, addonId: string, source: "settings" | "live", kind: "settings" | "live"): unknown;
 export declare function mergeAggregates(parts: readonly ContributionShape[]): ContributionShape;