@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/device-manager/device-source-activation.d.ts

@@ -1,61 +1,103 @@
-import { AddonContext, ICapabilityRegistry, WrapperActivationRead } from '@camstack/types';
-import { WriteLock } from './write-lock.js';
 /**
- * What a wrapper-activation write needs, and nothing more.
- *
- * Deliberately narrower than `AggregationDeps`: the verb touches the settings
- * door, the event bus, the registry and the addon-store write lock. Handing it
- * the device ledger and the remote-native cache it never reads would make this
- * loop untestable without standing up the whole addon.
- */
+* The per-device wrapper activation — the operator-facing verb
+* (`deviceManager.setWrapperActive`) and the ONE place it is written, read
+* back, and mirrored onto the resolution path. [D556](../../../../../docs/decisions/adr-0556-a-per-device-source-switch-is-the-wrapper-activation-and-the-registry-holds-only-its-projection.md)
+*
+* ## The loop this closes
+*
+* `setWrapperActive` persisted into `deviceBindings[deviceId][capName]` and was
+* read by `getBindings` — so it was never a store *nobody* read. What it never
+* reached was the PROVIDER resolver: `CapabilityRegistry.getProviderForDevice`
+* consults `deviceOverrides`, an in-memory map written only from the admin
+* `capabilities` router, and `resolveCollectionForDevice` consulted a
+* per-device collection FILTER written from the same two places and persisted
+* by nothing. One half persisted and unresolved, the other resolved and
+* unpersisted (D554 context 3 measured the first half and recorded it open).
+*
+* D556's answer: **the persisted activation is the authority; the registry
+* holds only its projection.** This module is the hinge — it owns the store
+* shape, the toggle arithmetic, and the mirror, and nothing else may write the
+* registry's per-device source set.
+*
+* ## There is no longer a per-source switch, and that is the point
+*
+* D556 shipped a DENY list of a collection cap's switched-off sources, and
+* D555 re-keyed it by SOURCE. The operator removed the whole idea on
+* 2026-09-20: *"tutti i providers funzionano sempre, non serve
+* disattivarli/attivarli … loro vivono lì."* [all the providers always work, there is no need to deactivate/activate them … they live there.] A collection capability's
+* providers are a SET, derived from who provides it
+* (`device-bindings-store.ts` step 0) and persisted nowhere — so this verb has
+* nothing to write for one, and it says so rather than writing a store the
+* enumeration does not read. That store-nobody-reads is the D62 shape, and it
+* happened here for the third time in one day: the collection branch wrote
+* `disabledSourceIds` while `getBindings` answered from somewhere else, which
+* is how a provider could be registered and unbound at the same time with
+* nobody seeing it. `scripts/check-device-selection-authority.ts` now makes
+* that unrepresentable rather than merely absent: every field this module
+* writes must be a field `getBindings` reads.
+*
+* What survives is the SINGLETON half, which is what D62 is actually about:
+* one verb, one authority, no second store, the `{wrapperAddonId: null}`
+* marker, the write lock and the out-of-lock emit.
+*/
+import type { AddonContext, ICapabilityRegistry, WrapperActivationRead } from "@camstack/types";
+import type { WriteLock } from "./write-lock.js";
+/**
+* What a wrapper-activation write needs, and nothing more.
+*
+* Deliberately narrower than `AggregationDeps`: the verb touches the settings
+* door, the event bus, the registry and the addon-store write lock. Handing it
+* the device ledger and the remote-native cache it never reads would make this
+* loop untestable without standing up the whole addon.
+*/
 export interface WrapperActivationDeps {
-    readonly ctx: AddonContext;
-    readonly capabilityRegistry: ICapabilityRegistry | undefined;
-    /** Ordering for every read-modify-write of the fleet-wide `deviceBindings` blob (D62). */
-    readonly withAddonStoreWriteLock: WriteLock;
+	readonly ctx: AddonContext;
+	readonly capabilityRegistry: ICapabilityRegistry | undefined;
+	/** Ordering for every read-modify-write of the fleet-wide `deviceBindings` blob (D62). */
+	readonly withAddonStoreWriteLock: WriteLock;
 }
 /** The operator-facing activation, as it arrives from the cap router. */
 export interface WrapperActivationInput {
-    readonly deviceId: number;
-    readonly capName: string;
-    readonly wrapperAddonId: string;
-    readonly active: boolean;
+	readonly deviceId: number;
+	readonly capName: string;
+	readonly wrapperAddonId: string;
+	readonly active: boolean;
 }
 /**
- * Activate or deactivate a wrapper for one device.
- *
- * SINGLETON caps only, and that is now enforced rather than assumed: one
- * `wrapperAddonId`, or the explicit `null` "operator disabled" marker that
- * stops `getBindings` step 2 re-binding a `defaultActive` wrapper.
- *
- * A COLLECTION cap is REFUSED by name. Its providers are a derived SET
- * (`device-bindings-store.ts` step 0) — there is nothing to activate, and a
- * verb that accepted the call and wrote a store nobody reads is exactly what
- * this module shipped until 2026-09-20.
- */
+* Activate or deactivate a wrapper for one device.
+*
+* SINGLETON caps only, and that is now enforced rather than assumed: one
+* `wrapperAddonId`, or the explicit `null` "operator disabled" marker that
+* stops `getBindings` step 2 re-binding a `defaultActive` wrapper.
+*
+* A COLLECTION cap is REFUSED by name. Its providers are a derived SET
+* (`device-bindings-store.ts` step 0) — there is nothing to activate, and a
+* verb that accepted the call and wrote a store nobody reads is exactly what
+* this module shipped until 2026-09-20.
+*/
 export declare function setWrapperActive(deps: WrapperActivationDeps, input: WrapperActivationInput): Promise<void>;
 /** Which activation `getWrapperActivation` is asked about. */
 export interface WrapperActivationQuery {
-    readonly deviceId: number;
-    readonly capName: string;
+	readonly deviceId: number;
+	readonly capName: string;
 }
 /**
- * The STORED activation for one `(device, capName)` pair, three-way — the
- * provider behind `deviceManager.getWrapperActivation` (D675).
- *
- * Reads ONE row — this addon's `deviceBindings` key (~1.6 KB live) — through
- * the settings view's single-key three-way read, never the addon's whole store
- * (~625 KB) and never `readAddonStore()`, which folds a failed read into `{}`.
- *
- * Absence is graded by LEVEL:
- * - STORE level — the read failed, or the `deviceBindings` row does not exist,
- *   or it is not a map — is `failed`. Every hub that has ever bound anything
- *   holds that row, so its absence is the signature of a store answering from
- *   an empty or unready snapshot (D44), and it must never silence a press
- *   (D49). An install that has never bound anything lands here too; erring
- *   `failed` there costs nothing, because nothing is bound to silence.
- * - PAIR level — the row was read and has no entry for this device, or none
- *   for this cap, or none with `wrapperAddonId` — is `missing`: the operator
- *   never touched this pair.
- */
-export declare function readWrapperActivation(deps: Pick<WrapperActivationDeps, 'ctx'>, query: WrapperActivationQuery): Promise<WrapperActivationRead>;
+* The STORED activation for one `(device, capName)` pair, three-way — the
+* provider behind `deviceManager.getWrapperActivation` (D675).
+*
+* Reads ONE row — this addon's `deviceBindings` key (~1.6 KB live) — through
+* the settings view's single-key three-way read, never the addon's whole store
+* (~625 KB) and never `readAddonStore()`, which folds a failed read into `{}`.
+*
+* Absence is graded by LEVEL:
+* - STORE level — the read failed, or the `deviceBindings` row does not exist,
+*   or it is not a map — is `failed`. Every hub that has ever bound anything
+*   holds that row, so its absence is the signature of a store answering from
+*   an empty or unready snapshot (D44), and it must never silence a press
+*   (D49). An install that has never bound anything lands here too; erring
+*   `failed` there costs nothing, because nothing is bound to silence.
+* - PAIR level — the row was read and has no entry for this device, or none
+*   for this cap, or none with `wrapperAddonId` — is `missing`: the operator
+*   never touched this pair.
+*/
+export declare function readWrapperActivation(deps: Pick<WrapperActivationDeps, "ctx">, query: WrapperActivationQuery): Promise<WrapperActivationRead>;

package/dist/builtins/device-manager/device-state-claim-views.d.ts

@@ -1,77 +1,92 @@
-import { z } from 'zod';
-import { ClaimOutcome, IScopedLogger } from '@camstack/types';
-import { MergedSlice, OwnedCap, OwnedCaps } from './field-ownership.js';
+/**
+* The claims half of the hub runtime-state mirror (D663): which caps of a
+* device are claimed, by whom, and what the MERGED view of each claimed cap
+* currently is. `DeviceStateMirror` owns the native shadow, the seeding and
+* the disk writes; this class owns the two maps the merge lives in and the
+* rule for what a consumer sees.
+*
+* The view of a claimed cap is `mergeOwned(native, claim)`. When the merge is
+* a slice it is what reads answer and what is emitted. When it is HELD, what
+* reads answer depends on WHY: a bad overlay (every value present, schema
+* refused it) keeps the last good slice readable; a value or native that has
+* not arrived yet answers nothing — otherwise the previous merge would answer a
+* newly claimed field from the native (S5, D62). Held transitions log once per
+* (device, cap, reason) with `tags: { deviceId }` (D391).
+*/
+import type { z } from "zod";
+import type { ClaimOutcome, IScopedLogger } from "@camstack/types";
+import { type MergedSlice, type OwnedCap, type OwnedCaps } from "./field-ownership.js";
 /** Resolves a cap's `runtimeState` schema by name; null when it declares none. */
 export type RuntimeStateSchemaLookup = (capName: string) => z.ZodType | null;
 /** Per (device, cap) state of a claimed cap: what the merge last said, and the
- *  last GOOD merged slice — kept readable while a bad overlay holds the cap. */
+*  last GOOD merged slice — kept readable while a bad overlay holds the cap. */
 export interface ClaimedView {
-    readonly merged: MergedSlice;
-    readonly visible: Readonly<Record<string, unknown>> | null;
+	readonly merged: MergedSlice;
+	readonly visible: Readonly<Record<string, unknown>> | null;
 }
 /** What the views need from their owner: the schema, the log and the public emit. */
 export interface ClaimViewSink {
-    readonly logger: IScopedLogger;
-    readonly schemaFor: RuntimeStateSchemaLookup;
-    emitSlice(deviceId: number, capName: string, slice: Record<string, unknown>): void;
+	readonly logger: IScopedLogger;
+	readonly schemaFor: RuntimeStateSchemaLookup;
+	emitSlice(deviceId: number, capName: string, slice: Record<string, unknown>): void;
 }
 /** Lazily indexes the codegen'd cap set — the hub already carries the barrel. */
 export declare function defaultSchemaFor(capName: string): z.ZodType | null;
 export declare function sameOwnedCap(a: OwnedCap, b: OwnedCap): boolean;
 type ClaimRefusal = Extract<ClaimOutcome, {
-    ok: false;
+	ok: false;
 }>;
-export declare function refused(code: ClaimRefusal['code'], message: string): ClaimOutcome;
+export declare function refused(code: ClaimRefusal["code"], message: string): ClaimOutcome;
 export declare class ClaimViews {
-    private readonly sink;
-    /** Claims by device, by cap. Absent for every device without one. */
-    private readonly owned;
-    /** The merged view of each claimed cap; recomputed on every native or owned write. */
-    private readonly views;
-    constructor(sink: ClaimViewSink);
-    claim(deviceId: number, capName: string): OwnedCap | undefined;
-    setClaim(deviceId: number, capName: string, claim: OwnedCap): void;
-    /** Removes the claim AND its view. */
-    deleteClaim(deviceId: number, capName: string): void;
-    /** Fill gaps only: a claim already in memory was written through and is newer than the row. */
-    seedClaims(deviceId: number, claims: OwnedCaps): void;
-    clearDevice(deviceId: number): void;
-    ownedCaps(deviceId: number): OwnedCaps;
-    claimsOf(deviceId: number): Iterable<[string, OwnedCap]>;
-    /** Devices with at least one view — for the whole-system dump. */
-    deviceIds(): Iterable<number>;
-    isClaimed(deviceId: number, capName: string): boolean;
-    /** `undefined` when the cap is not claimed; `null` when it is claimed and held with nothing to show. */
-    visible(deviceId: number, capName: string): Readonly<Record<string, unknown>> | null | undefined;
-    /** Every claimed cap of a device that currently has something to show. */
-    visibleCaps(deviceId: number): Iterable<[string, Readonly<Record<string, unknown>>]>;
-    /** What the merge says for a claimed cap; null when the cap is not claimed. */
-    effective(deviceId: number, capName: string): MergedSlice | null;
-    view(deviceId: number, capName: string): ClaimedView | undefined;
-    /** Put a view back (rollback of a failed write-through); `undefined` removes it. */
-    restoreView(deviceId: number, capName: string, view: ClaimedView | undefined): void;
-    /**
-     * Recompute a claimed cap's merged view and emit it when it is a slice and
-     * either changed or `emitUnchanged` (the native moved). A held view emits
-     * nothing and logs once per transition, naming the fields; a bad overlay
-     * keeps the last good slice readable, a missing value or native does not.
-     */
-    recompute(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null, emitUnchanged: boolean): void;
-    /**
-     * The view a claim has NOW — set, never emitted, never logged. A claim is
-     * written through, and readers must see it from the moment it is accepted
-     * (S5): without this, `capSlice` answered the NATIVE for an already-claimed
-     * field for the whole row round-trip (D663 re-review N-5). The emit is judged
-     * later, by `recompute`, against what consumers last saw.
-     */
-    previewView(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null): void;
-    /** The one rule for what a claimed cap shows: the merge when it is a slice; on
-     *  a bad overlay the last good slice stays readable; a value or native not yet
-     *  arrived shows nothing. */
-    private derive;
-    /** The merged view for a claim that arrived by seed: computed, never emitted. */
-    seedView(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null): void;
-    private ownedFor;
-    private viewsFor;
+	private readonly sink;
+	/** Claims by device, by cap. Absent for every device without one. */
+	private readonly owned;
+	/** The merged view of each claimed cap; recomputed on every native or owned write. */
+	private readonly views;
+	constructor(sink: ClaimViewSink);
+	claim(deviceId: number, capName: string): OwnedCap | undefined;
+	setClaim(deviceId: number, capName: string, claim: OwnedCap): void;
+	/** Removes the claim AND its view. */
+	deleteClaim(deviceId: number, capName: string): void;
+	/** Fill gaps only: a claim already in memory was written through and is newer than the row. */
+	seedClaims(deviceId: number, claims: OwnedCaps): void;
+	clearDevice(deviceId: number): void;
+	ownedCaps(deviceId: number): OwnedCaps;
+	claimsOf(deviceId: number): Iterable<[string, OwnedCap]>;
+	/** Devices with at least one view — for the whole-system dump. */
+	deviceIds(): Iterable<number>;
+	isClaimed(deviceId: number, capName: string): boolean;
+	/** `undefined` when the cap is not claimed; `null` when it is claimed and held with nothing to show. */
+	visible(deviceId: number, capName: string): Readonly<Record<string, unknown>> | null | undefined;
+	/** Every claimed cap of a device that currently has something to show. */
+	visibleCaps(deviceId: number): Iterable<[string, Readonly<Record<string, unknown>>]>;
+	/** What the merge says for a claimed cap; null when the cap is not claimed. */
+	effective(deviceId: number, capName: string): MergedSlice | null;
+	view(deviceId: number, capName: string): ClaimedView | undefined;
+	/** Put a view back (rollback of a failed write-through); `undefined` removes it. */
+	restoreView(deviceId: number, capName: string, view: ClaimedView | undefined): void;
+	/**
+	* Recompute a claimed cap's merged view and emit it when it is a slice and
+	* either changed or `emitUnchanged` (the native moved). A held view emits
+	* nothing and logs once per transition, naming the fields; a bad overlay
+	* keeps the last good slice readable, a missing value or native does not.
+	*/
+	recompute(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null, emitUnchanged: boolean): void;
+	/**
+	* The view a claim has NOW — set, never emitted, never logged. A claim is
+	* written through, and readers must see it from the moment it is accepted
+	* (S5): without this, `capSlice` answered the NATIVE for an already-claimed
+	* field for the whole row round-trip (D663 re-review N-5). The emit is judged
+	* later, by `recompute`, against what consumers last saw.
+	*/
+	previewView(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null): void;
+	/** The one rule for what a claimed cap shows: the merge when it is a slice; on
+	*  a bad overlay the last good slice stays readable; a value or native not yet
+	*  arrived shows nothing. */
+	private derive;
+	/** The merged view for a claim that arrived by seed: computed, never emitted. */
+	seedView(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null): void;
+	private ownedFor;
+	private viewsFor;
 }
 export {};

package/dist/builtins/device-manager/device-state-claims.d.ts

@@ -1,43 +1,66 @@
-import { ClaimOutcome, ClaimsListing, FieldClaimMode, IScopedLogger } from '@camstack/types';
-import { DeviceManagerSettings } from './device-meta-store.js';
-import { DeviceStateMirror } from './device-state-mirror.js';
-import { FieldClaimsIndex } from './field-claims-index.js';
+/**
+* The `deviceState` CLAIM methods (D663): `claimFields`, `patchOwnedFields`,
+* `releaseClaim`, `listClaims`. Thin over two authorities — the mirror owns the
+* row and the merge, the index owns the listing — and the ORDER between them:
+*
+*   claim   : index first, then the row — when the index does not yet name the
+*             (device, cap). A crash leaves an index entry with no row claim,
+*             which is harmless (a row read at the next seed) and self-heals;
+*             the reverse would let a claimed device seed without its row.
+*             When the index ALREADY names the pair (a standing owner), the
+*             row goes first and the index moves only on `ok`: `hasClaims` is
+*             already true, so index-first buys nothing, and it would name an
+*             owner the row is about to refuse.
+*   release : row first, then the index.  `not-claimed` from the row also drops
+*             the index entry — that is how an orphan heals (condition ii).
+*
+* Every method refuses by NAME (`ClaimOutcome`), never by silence: an unknown
+* device, a device whose migration is in flight (its row is about to be swapped
+* with another's — D663 5b), a value outside the planned field set (S5). A
+* failed store write REJECTS (I-4): the composer reads a rejection as unknown
+* and re-sends; a typed refusal is a fact about the claim, a rejection a fact
+* about the store.
+*/
+import type { ClaimOutcome, ClaimsListing, FieldClaimMode, IScopedLogger } from "@camstack/types";
+import type { DeviceManagerSettings } from "./device-meta-store.js";
+import type { DeviceStateMirror } from "./device-state-mirror.js";
+import type { FieldClaimsIndex } from "./field-claims-index.js";
 export interface ClaimFieldsInput {
-    readonly deviceId: number;
-    readonly capName: string;
-    readonly owner: string;
-    readonly mode: FieldClaimMode;
-    readonly fields: readonly string[];
-    readonly values: Readonly<Record<string, unknown>>;
+	readonly deviceId: number;
+	readonly capName: string;
+	readonly owner: string;
+	readonly mode: FieldClaimMode;
+	readonly fields: readonly string[];
+	readonly values: Readonly<Record<string, unknown>>;
 }
 export interface PatchOwnedFieldsInput {
-    readonly deviceId: number;
-    readonly capName: string;
-    readonly owner: string;
-    readonly values: Readonly<Record<string, unknown>>;
+	readonly deviceId: number;
+	readonly capName: string;
+	readonly owner: string;
+	readonly values: Readonly<Record<string, unknown>>;
 }
 export interface ReleaseClaimInput {
-    readonly deviceId: number;
-    readonly capName: string;
-    readonly owner: string;
+	readonly deviceId: number;
+	readonly capName: string;
+	readonly owner: string;
 }
 export interface ListClaimsInput {
-    readonly ownerPrefix?: string;
+	readonly ownerPrefix?: string;
 }
 export interface DeviceStateClaimMethods {
-    claimFields(input: ClaimFieldsInput): Promise<ClaimOutcome>;
-    patchOwnedFields(input: PatchOwnedFieldsInput): Promise<ClaimOutcome>;
-    releaseClaim(input: ReleaseClaimInput): Promise<ClaimOutcome>;
-    listClaims(input: ListClaimsInput): Promise<ClaimsListing>;
+	claimFields(input: ClaimFieldsInput): Promise<ClaimOutcome>;
+	patchOwnedFields(input: PatchOwnedFieldsInput): Promise<ClaimOutcome>;
+	releaseClaim(input: ReleaseClaimInput): Promise<ClaimOutcome>;
+	listClaims(input: ListClaimsInput): Promise<ClaimsListing>;
 }
 export interface DeviceStateClaimDeps {
-    readonly mirror: Pick<DeviceStateMirror, 'claim' | 'patchOwned' | 'release'>;
-    readonly index: FieldClaimsIndex;
-    readonly settings: DeviceManagerSettings;
-    readonly logger: IScopedLogger;
-    /** Is this a device the ledger knows? `resolvePersistedById(id) !== null`. */
-    deviceExists(deviceId: number): Promise<boolean>;
-    /** Is a migration involving this device running right now? */
-    migrationInFlight(deviceId: number): boolean;
+	readonly mirror: Pick<DeviceStateMirror, "claim" | "patchOwned" | "release">;
+	readonly index: FieldClaimsIndex;
+	readonly settings: DeviceManagerSettings;
+	readonly logger: IScopedLogger;
+	/** Is this a device the ledger knows? `resolvePersistedById(id) !== null`. */
+	deviceExists(deviceId: number): Promise<boolean>;
+	/** Is a migration involving this device running right now? */
+	migrationInFlight(deviceId: number): boolean;
 }
 export declare function createDeviceStateClaimMethods(deps: DeviceStateClaimDeps): DeviceStateClaimMethods;