@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/composer/composer.d.ts

@@ -1,110 +1,155 @@
-import { CapabilityLookup, ComposerApplyInput, ComposerApplyResult, CompositionBlockState, IScopedLogger } from '@camstack/types';
-import { DeviceStateChangedData } from '../shared/device-state-changed.js';
-import { ComposerDeclare, ComposerDevicePorts } from './composed-device-set.js';
-import { PersistedComposedRow } from './composition-declarations.js';
-import { CompositionEventEmitter, DeadlineTimer } from './composition-runtime.js';
-import { ComposerClaimsApi, ComposerGraftPorts, DescribeTarget } from './existing-target.js';
-import { SourceBindingsChangeReason, SourceTracker } from './source-tracker.js';
-export type { ComposerDerivedSpec } from './composer-plan.js';
-export type { ComposerDeclareResult, ComposerDevicePorts } from './composed-device-set.js';
+/**
+* The composer: every declarative composition on this hub, in one runner
+* (D659).
+*
+* `apply` is called by `core-blocks`' supervisor on its existing converge with
+* the WHOLE set of composition blocks. It is idempotent: a block whose
+* `updatedAt`, device and plan are unchanged keeps its runtime; the declared set
+* is reconciled only when it changed. Every verdict names its reason.
+*
+* Nothing is declared or withdrawn until two things hold (D49): the
+* `core_blocks` store has loaded (R2), and the composer has read the rows it
+* already owns, so a restart is not the first miss of every block
+* (`WithdrawalGate.seed`). A block whose row exists but whose composition no
+* longer plans (a cap renamed by a release) keeps its device as an offline
+* placeholder with no capabilities, and reports `failed` naming why.
+*
+* Slice 2 (D663) — a composition on an EXISTING device declares nothing: the
+* row is not the composer's, `DeclaredDevices` never sees it, and the owner
+* filter in `composer.addon.ts` stays load-bearing. Its fields are CLAIMED on
+* the hub under the block id (`OwnedFieldsTarget`), and released through the
+* `ClaimGate` — two applies must agree, seeded at boot from the claims index —
+* when the block is gone, disabled, or lost the feature. Its own replaced
+* fields are read in the NATIVE view (rule 6). Its target row gone on two
+* agreeing index reads fails the block by name and ungrafts what it added —
+* whether the loss was seen on `device.unregistered` or on a later plan; its
+* claims die with the row. Nothing is claimed or released while the claims
+* index has not loaded (`CLAIMS_NOT_LOADED`). Planning is `composer-plan.ts`.
+*
+* A cap the customization ADDS is GRAFTED (`GraftHost`, Task 10): a
+* method-serving native on the target, decided at plan time only; when and why
+* is `composer-grafts.ts` (native always wins; an unserved cap is named in the
+* verdict; a previous process's leftover is retracted).
+*
+* A replaced field is handed back only on a CONFIRMED unavailability of its
+* source (D49, fix round 2): a failed, first or empty read HOLDS it on its last
+* value with its claim kept — the runtime's `held`, reported `starting` by name.
+* A runtime built by an apply starts in that apply's sync, never earlier from
+* an event (N-5).
+*
+* This file is the orchestration; the pieces live beside it:
+* `composer-apply-waits.ts` (the store / integration preconditions),
+* `composer-seeds.ts` (the two boot reads), `composer-runtime-factory.ts`
+* (where a runtime writes and how it reads) and `composer-live-set.ts` (the
+* pure reads of the live set: tracked sources, reset keys, wanted claims).
+*/
+import { type CapabilityLookup, type ComposerApplyInput, type ComposerApplyResult, type CompositionBlockState, type IScopedLogger } from "@camstack/types";
+import type { DeviceStateChangedData } from "../shared/device-state-changed.js";
+import { type ComposerDeclare, type ComposerDevicePorts } from "./composed-device-set.js";
+import { type PersistedComposedRow } from "./composition-declarations.js";
+import type { CompositionEventEmitter, DeadlineTimer } from "./composition-runtime.js";
+import { type ComposerClaimsApi, type ComposerGraftPorts, type DescribeTarget } from "./existing-target.js";
+import type { SourceBindingsChangeReason, SourceTracker } from "./source-tracker.js";
+export type { ComposerDerivedSpec } from "./composer-plan.js";
+export type { ComposerDeclareResult, ComposerDevicePorts } from "./composed-device-set.js";
 /** What the composer reads of a `device.bindings-changed` payload; the typed `EventCatalog` payload is assignable to it. */
 export interface DeviceBindingsChangedData {
-    readonly deviceId: number;
-    readonly capName: string;
-    readonly reason: SourceBindingsChangeReason;
-    /** The addon that registered (or unregistered) the provider: a foreign native vs the composer's own graft. */
-    readonly addonId: string;
+	readonly deviceId: number;
+	readonly capName: string;
+	readonly reason: SourceBindingsChangeReason;
+	/** The addon that registered (or unregistered) the provider: a foreign native vs the composer's own graft. */
+	readonly addonId: string;
 }
 /** The owner-only `device.native-shadow-changed` payload (D224): the provider's slice under a claim. */
 export interface NativeShadowChangedData {
-    readonly deviceId: number;
-    readonly capName: string;
-    readonly native: Readonly<Record<string, unknown>>;
+	readonly deviceId: number;
+	readonly capName: string;
+	readonly native: Readonly<Record<string, unknown>>;
 }
 export interface ComposerDeps {
-    readonly logger: IScopedLogger;
-    readonly tracker: SourceTracker;
-    readonly lookupCap: CapabilityLookup;
-    /** The composed rows that already exist (`listOwnDevices`), read once before the first withdrawal decision. */
-    readonly readPersisted: () => Promise<readonly PersistedComposedRow[]>;
-    readonly declare: ComposerDeclare;
-    readonly devices: ComposerDevicePorts;
-    /** The hub's per-field claims (D663): the write target's methods and the boot seed. */
-    readonly claims: ComposerClaimsApi;
-    /** Typed state-derived events emitted by composed capability fields. */
-    readonly events: CompositionEventEmitter;
-    /** Effective target state, read before an existing-target runtime owns any field. */
-    readonly readExistingTargetCap: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>;
-    /** ONE `getBindings` per target description read (rule 1). */
-    readonly describeTarget: DescribeTarget;
-    /** `GraftHost` (Task 10): a method-serving native for each ADDED cap. Absent, nothing is grafted. */
-    readonly grafts?: ComposerGraftPorts;
-    readonly now: () => number;
-    readonly newTimer: () => DeadlineTimer;
+	readonly logger: IScopedLogger;
+	readonly tracker: SourceTracker;
+	readonly lookupCap: CapabilityLookup;
+	/** The composed rows that already exist (`listOwnDevices`), read once before the first withdrawal decision. */
+	readonly readPersisted: () => Promise<readonly PersistedComposedRow[]>;
+	readonly declare: ComposerDeclare;
+	readonly devices: ComposerDevicePorts;
+	/** The hub's per-field claims (D663): the write target's methods and the boot seed. */
+	readonly claims: ComposerClaimsApi;
+	/** Typed state-derived events emitted by composed capability fields. */
+	readonly events: CompositionEventEmitter;
+	/** Effective target state, read before an existing-target runtime owns any field. */
+	readonly readExistingTargetCap: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>;
+	/** ONE `getBindings` per target description read (rule 1). */
+	readonly describeTarget: DescribeTarget;
+	/** `GraftHost` (Task 10): a method-serving native for each ADDED cap. Absent, nothing is grafted. */
+	readonly grafts?: ComposerGraftPorts;
+	readonly now: () => number;
+	readonly newTimer: () => DeadlineTimer;
 }
 export declare class Composer {
-    private readonly deps;
-    private live;
-    /** The composed devices of `new`-target blocks, and the rows that exist. */
-    private readonly composed;
-    /** The store / integration preconditions every apply waits on first (D49, R2). */
-    private readonly waits;
-    private readonly gate;
-    private readonly claimGate;
-    private readonly targets;
-    private readonly grafts;
-    /** The rows the composer owns, read ONCE before its first withdrawal decision. */
-    private readonly rowSeed;
-    /**
-     * The claims the hub holds, read ONCE before the first release decision (rule
-     * 3). Every owner in it is a composer block id — the Task 6 guard lets nothing
-     * else claim. `not-loaded` is UNKNOWN (D315), never empty. Until seeded, every
-     * existing-target block waits by name; new-target blocks are not held.
-     */
-    private readonly claimSeed;
-    /** Applies never interleave: each one reads and replaces the whole live set. */
-    private applyChain;
-    /**
-     * Runtimes built by an apply and not started yet: that apply's sync starts
-     * them, with their sources tracked. An event in between never does (N-5) —
-     * it would start one on sources "not tracked yet".
-     */
-    private unsynced;
-    constructor(deps: ComposerDeps);
-    apply(input: ComposerApplyInput): Promise<ComposerApplyResult>;
-    getStates(blockIds: readonly string[]): readonly CompositionBlockState[];
-    /** Runs on the tracker's one chain (R3): resolves once the change reached every runtime. */
-    onStateChanged(data: DeviceStateChangedData): Promise<void>;
-    onNativeChanged(data: NativeShadowChangedData): Promise<void>;
-    onDeviceUnregistered(deviceId: number): Promise<void>;
-    onBindingsChanged(data: DeviceBindingsChangedData): Promise<void>;
-    shutdown(): void;
-    /** Run `work` after every apply already queued, whether that settled or failed. */
-    private chained;
-    private applyNow;
-    private plan;
-    private rebuildRuntimes;
-    private ungraftGone;
-    /** C-1/N-1: the tracker follows the block's OWN claim as the hub answers it; every answer re-reads the native once. */
-    private onClaimEvent;
-    private heldFieldsFor;
-    private applyName;
-    private syncSources;
-    /** A failed sync leaves the tracker as it was: the runtimes read what it holds. */
-    private syncTracker;
-    /** Rule 3: release what no live customization wants, once two applies agree (`wantedClaims`). */
-    private reconcileClaims;
-    private release;
-    /**
-     * Rule 5: a customization whose target row is gone — the tracker's two
-     * agreeing reads — fails naming it, stops writing, and ungrafts every cap it
-     * added on that id (Task 10's seam). Its claims are left as they are: the row
-     * and its `$owned` died with the device. No auto-repair: an operator edit or
-     * restart re-resolves the target.
-     */
-    private failGoneTargets;
-    private dispatch;
-    private deviceIdOf;
-    private tagsOf;
-    private verdict;
+	private readonly deps;
+	private live;
+	/** The composed devices of `new`-target blocks, and the rows that exist. */
+	private readonly composed;
+	/** The store / integration preconditions every apply waits on first (D49, R2). */
+	private readonly waits;
+	private readonly gate;
+	private readonly claimGate;
+	private readonly targets;
+	private readonly grafts;
+	/** The rows the composer owns, read ONCE before its first withdrawal decision. */
+	private readonly rowSeed;
+	/**
+	* The claims the hub holds, read ONCE before the first release decision (rule
+	* 3). Every owner in it is a composer block id — the Task 6 guard lets nothing
+	* else claim. `not-loaded` is UNKNOWN (D315), never empty. Until seeded, every
+	* existing-target block waits by name; new-target blocks are not held.
+	*/
+	private readonly claimSeed;
+	/** Applies never interleave: each one reads and replaces the whole live set. */
+	private applyChain;
+	/**
+	* Runtimes built by an apply and not started yet: that apply's sync starts
+	* them, with their sources tracked. An event in between never does (N-5) —
+	* it would start one on sources "not tracked yet".
+	*/
+	private unsynced;
+	constructor(deps: ComposerDeps);
+	apply(input: ComposerApplyInput): Promise<ComposerApplyResult>;
+	getStates(blockIds: readonly string[]): readonly CompositionBlockState[];
+	/** Runs on the tracker's one chain (R3): resolves once the change reached every runtime. */
+	onStateChanged(data: DeviceStateChangedData): Promise<void>;
+	onNativeChanged(data: NativeShadowChangedData): Promise<void>;
+	onDeviceUnregistered(deviceId: number): Promise<void>;
+	onBindingsChanged(data: DeviceBindingsChangedData): Promise<void>;
+	shutdown(): void;
+	/** Run `work` after every apply already queued, whether that settled or failed. */
+	private chained;
+	private applyNow;
+	private plan;
+	private rebuildRuntimes;
+	private ungraftGone;
+	/** C-1/N-1: the tracker follows the block's OWN claim as the hub answers it; every answer re-reads the native once. */
+	private onClaimEvent;
+	private heldFieldsFor;
+	private applyName;
+	private syncSources;
+	/** A failed sync leaves the tracker as it was: the runtimes read what it holds. */
+	private syncTracker;
+	/** Rule 3: release what no live customization wants, once two applies agree (`wantedClaims`). */
+	private reconcileClaims;
+	private release;
+	/**
+	* Rule 5: a customization whose target row is gone — the tracker's two
+	* agreeing reads — fails naming it, stops writing, and ungrafts every cap it
+	* added on that id (Task 10's seam). Its claims are left as they are: the row
+	* and its `$owned` died with the device. No auto-repair: an operator edit or
+	* restart re-resolves the target.
+	*/
+	private failGoneTargets;
+	private dispatch;
+	private deviceIdOf;
+	private tagsOf;
+	private verdict;
 }

package/dist/builtins/composer/composition-declarations.d.ts

@@ -1,53 +1,64 @@
-import { CapabilityDefinition, CompositionNewTarget, DeviceDeclaration, IScopedLogger } from '@camstack/types';
+/**
+* Which composed devices exist (D659): one declaration per composition block,
+* owned by `composer` and hung off the shared Blocks integration.
+*
+* `DeclaredDevices` sweeps any row whose declaration is absent. A block missing
+* from ONE apply (a transient store read, a race) would delete the device, and
+* with it its id, exports and rules. The `WithdrawalGate` is D49 for that path:
+* a withdrawal needs a second consecutive apply to agree. The other half of the
+* rule — nothing is declared or withdrawn while the `core_blocks` store has not
+* loaded — is `Composer.apply`'s, which never reaches this gate then (R2).
+*/
+import { type CapabilityDefinition, type CompositionNewTarget, type DeviceDeclaration, type IScopedLogger } from "@camstack/types";
 export interface ComposerDeclarationInput {
-    readonly blockId: string;
-    readonly name: string;
-    readonly target: CompositionNewTarget;
-    readonly caps: readonly CapabilityDefinition[];
+	readonly blockId: string;
+	readonly name: string;
+	readonly target: CompositionNewTarget;
+	readonly caps: readonly CapabilityDefinition[];
 }
 export declare function declarationFor(input: ComposerDeclarationInput): DeviceDeclaration;
 /** What forces a rebuild of the live device: type, role, cap set. Never the name. */
 export declare function shapeOf(input: ComposerDeclarationInput): string;
 /**
- * The numeric id of the live composed device behind a stableId, or null when
- * none was ever built (its declare failed). Every gate line carries it as
- * `tags.deviceId` — the id the operator asks about (CLAUDE.md "Logging").
- */
+* The numeric id of the live composed device behind a stableId, or null when
+* none was ever built (its declare failed). Every gate line carries it as
+* `tags.deviceId` — the id the operator asks about (CLAUDE.md "Logging").
+*/
 export type ComposedDeviceIdOf = (stableId: string) => number | null;
 /**
- * The declaration that holds a persisted composed row whose block has no plan
- * in this apply. `name` and `type` are used only if the row has to be CREATED,
- * which `DeclaredDevices` does not do for a row it finds: it adopts it, and the
- * row's own name and type stay canonical (`ComposedPlaceholderDevice`).
- */
+* The declaration that holds a persisted composed row whose block has no plan
+* in this apply. `name` and `type` are used only if the row has to be CREATED,
+* which `DeclaredDevices` does not do for a row it finds: it adopts it, and the
+* row's own name and type stay canonical (`ComposedPlaceholderDevice`).
+*/
 export declare function placeholderDeclaration(stableId: string): DeviceDeclaration;
 /** A composed device row that already exists — `DeclaredDevicePorts.listOwnDevices()` answers these. */
 export interface PersistedComposedRow {
-    readonly id: number;
-    readonly stableId: string;
+	readonly id: number;
+	readonly stableId: string;
 }
 export declare class WithdrawalGate {
-    private readonly logger;
-    private readonly deviceIdOf;
-    private known;
-    private misses;
-    private persistedIds;
-    constructor(logger: IScopedLogger, deviceIdOf: ComposedDeviceIdOf);
-    /**
-     * The rows that exist before this process applied anything. Called once at
-     * boot, before the first `filter`: without it the mirror starts empty and a
-     * row missing from the first apply after a restart (a release, a block that
-     * no longer plans) is swept at once — one apply, not two. A seeded row
-     * missing from that apply counts as its FIRST miss and is held by
-     * `placeholderDeclaration`. A row the gate already knows keeps its entry and
-     * its miss count.
-     */
-    seed(rows: readonly PersistedComposedRow[]): void;
-    filter(current: readonly DeviceDeclaration[]): readonly DeviceDeclaration[];
-    /**
-     * The live device's id, else the persisted row's. A declaration whose device
-     * was never built and never persisted has no numeric id to carry: the
-     * stableId in `meta` is then all there is.
-     */
-    private tagsOf;
+	private readonly logger;
+	private readonly deviceIdOf;
+	private known;
+	private misses;
+	private persistedIds;
+	constructor(logger: IScopedLogger, deviceIdOf: ComposedDeviceIdOf);
+	/**
+	* The rows that exist before this process applied anything. Called once at
+	* boot, before the first `filter`: without it the mirror starts empty and a
+	* row missing from the first apply after a restart (a release, a block that
+	* no longer plans) is swept at once — one apply, not two. A seeded row
+	* missing from that apply counts as its FIRST miss and is held by
+	* `placeholderDeclaration`. A row the gate already knows keeps its entry and
+	* its miss count.
+	*/
+	seed(rows: readonly PersistedComposedRow[]): void;
+	filter(current: readonly DeviceDeclaration[]): readonly DeviceDeclaration[];
+	/**
+	* The live device's id, else the persisted row's. A declaration whose device
+	* was never built and never persisted has no numeric id to carry: the
+	* stableId in `meta` is then all there is.
+	*/
+	private tagsOf;
 }

package/dist/builtins/composer/composition-evaluation.d.ts

@@ -1,37 +1,53 @@
-import { CompositionEventPlan, CompositionFieldRead, FieldOutcome, IScopedLogger, SourceReader } from '@camstack/types';
-import { CompositionEventEmitter } from './composition-target.js';
-import { FieldRecord } from './field-record.js';
+/**
+* Evaluating a composition's fields (D659, D670): one pass over the keys a
+* change affects, the own-field readers it must re-run (D670 amendment), and
+* the state-derived events it emits. Split from `composition-runtime.ts`,
+* which owns the records and hands them in through {@link EvaluationHost}.
+*
+* - Stateful expression memory commits only when the whole expression
+*   succeeds.
+* - A declared state-derived event advances its high-water and is emitted
+*   BEFORE the corresponding target write; the committed records are visible
+*   to a synchronous subscriber first.
+* - Derived fields are evaluated before accumulators, and every field reading
+*   an own field that changed is re-evaluated in the same pass.
+* - An edge-latched (`rose`) field holds its last edge through a source
+*   outage: the field goes stale, its value does not change (D713).
+*/
+import { type CompositionEventPlan, type CompositionFieldRead, type FieldOutcome, type IScopedLogger, type SourceReader } from "@camstack/types";
+import type { CompositionEventEmitter } from "./composition-target.js";
+import { type FieldRecord } from "./field-record.js";
 export interface EvaluationDelta {
-    readonly keys: ReadonlySet<string>;
-    readonly valueCaps: ReadonlySet<string>;
+	readonly keys: ReadonlySet<string>;
+	readonly valueCaps: ReadonlySet<string>;
 }
 /** What an evaluation reads from, and writes back to, the runtime that owns the records. */
 export interface EvaluationHost {
-    records(): ReadonlyMap<string, FieldRecord>;
-    commit(records: ReadonlyMap<string, FieldRecord>): void;
-    readonly read: SourceReader;
-    readonly isOwnRead?: (read: CompositionFieldRead) => boolean;
-    readonly eventPlans: readonly CompositionEventPlan[];
-    readonly startedAtMs: number;
-    emit(plan: CompositionEventPlan, timestamp: number): void;
-    logTransition(record: FieldRecord, outcome: FieldOutcome): void;
+	records(): ReadonlyMap<string, FieldRecord>;
+	commit(records: ReadonlyMap<string, FieldRecord>): void;
+	readonly read: SourceReader;
+	readonly isOwnRead?: (read: CompositionFieldRead) => boolean;
+	readonly eventPlans: readonly CompositionEventPlan[];
+	readonly startedAtMs: number;
+	emit(plan: CompositionEventPlan, timestamp: number): void;
+	logTransition(record: FieldRecord, outcome: FieldOutcome): void;
 }
 /** The record key an own read is answered from; null when `read` is a source's. */
 export declare function ownKeyOf(host: EvaluationHost, read: CompositionFieldRead): string | null;
 /**
- * `keys`, derived before accumulators, then — in the same pass — every
- * derived/accumulator field that reads an own field that changed. Bounded by
- * the record count: the validator refuses a cycle, so a chain is at most that
- * long (D6).
- */
+* `keys`, derived before accumulators, then — in the same pass — every
+* derived/accumulator field that reads an own field that changed. Bounded by
+* the record count: the validator refuses a cycle, so a chain is at most that
+* long (D6).
+*/
 export declare function evaluateWithOwnReaders(host: EvaluationHost, keys: readonly string[], now: number): EvaluationDelta;
 /** Evaluate `keys` in order against the records in progress; commit whatever was evaluated, even on a throw. */
 export declare function evaluateFields(host: EvaluationHost, keys: readonly string[], now: number): EvaluationDelta;
 export interface StateEventContext {
-    readonly deviceId: number;
-    readonly blockId: string;
-    readonly events: CompositionEventEmitter;
-    readonly logger: IScopedLogger;
+	readonly deviceId: number;
+	readonly blockId: string;
+	readonly events: CompositionEventEmitter;
+	readonly logger: IScopedLogger;
 }
 /** Emit one state-derived event; a delivery failure is logged, never thrown (D670). */
 export declare function emitStateDerivedEvent(ctx: StateEventContext, plan: CompositionEventPlan, timestamp: number): void;