@camstack/system 1.2.390 → 1.2.392

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

@@ -1,131 +1,184 @@
-import { CapabilityLookup, CompositionEventPlan, CompositionFieldPlan, CompositionFieldRead, CompositionFieldState, IScopedLogger, SourceReader } from '@camstack/types';
-import { ComposedWriteTarget, CompositionEventEmitter, DeadlineTimer } from './composition-target.js';
-import { ReleasedField } from './field-record.js';
-export type { ReleasedField } from './field-record.js';
-export type { ComposedWriteTarget, CompositionEventEmitter, DeadlineTimer, TargetAsyncFailure, WriteOk, WriteOutcome, WriteRefused, } from './composition-target.js';
+/**
+* One running composition: per-field state, writes to the composed device, and
+* one deadline timer (D659).
+*
+* - Only the fields a change affects are recomputed.
+* - A cap is SEEDED once (`setCapState`, every required field present), then
+*   PATCHED (`patchCapState` merges; the runtime-state twin of "`setAll`
+*   already merges").
+* - Unavailable is per field. A nullable field is written `null`; a
+*   non-nullable one is not written and the device goes offline (D393).
+* - A `clock` field (`now` only) is recomputed when a sibling of its cap
+*   changes value, so `binary.lastChangedAt` is the last transition. A
+*   `constant` is computed once.
+* - A windowed expression reports when it flips; ONE timer at the earliest
+*   such instant. It waits for no source (D3). Every evaluation is STORED, so
+*   a deadline that moved reaches the timer even when the value did not: an
+*   unstored deadline fires early, re-evaluates to "same", and re-arms
+*   `setTimeout(0)` until the real window closes — a poll (R1).
+* - A fatal (source gone) outcome is the block's failure, and it is sticky:
+*   the device stays offline until a new runtime, created on an operator edit
+*   or restart, clears it.
+* - A write the target REFUSES or THROWS on leaves the evaluated outcomes
+*   alone and marks its cap write-pending: the next pass that evaluates any
+*   field of that cap, and every deadline pass, re-writes the WHOLE current
+*   slice (a seed if it was never seeded). No retry timer — the next source
+*   event or deadline is the retry (D3). One log line per failure transition.
+* - Nothing escapes: a pass that throws is logged, and the timer is re-armed
+*   from the stored deadlines regardless.
+* - `stop()` is terminal: every entry point is a no-op afterwards.
+*
+* Slice 2 (D663):
+* - Records are keyed by `compositionFieldKey`: two items' `status` are two
+*   records. An item-array cap is written WHOLE — a change to one item leaf
+*   re-sends every item, assembled by `assembleSlice` on the cap's `emptyItem`.
+*   A required item leaf with no fallback holds the array, named once.
+* - `'unknown'` unavailable mode writes the enum's own word.
+* - `'release'` unavailable mode hands the field BACK (ruling S1b): the target
+*   is told to `withhold` it, the field's record forgets what it wrote, and the
+*   source returning re-widens and writes it again. Stale is a value (D49),
+*   never a release — and neither is an UNCONFIRMED unavailability (a failed,
+*   first or empty read): the field is HELD on its last value, not written,
+*   not withheld, its claim kept, until the source answers (D49, fix round 2).
+*   `state().released` / `state().held` name every such field for the report.
+* - A target whose writes are asynchronous (claims on the hub) reports what did
+*   not land through `onAsyncFailure`: the cap is marked write-pending by name
+*   and re-written whole on the next pass — no retry timer (D3).
+*
+* Slice 2b (D670): evaluation — stateful memory, state-derived events before
+* their write, and reads of the composition's OWN fields answered from the
+* records rather than the hub (D670 amendment) — is `composition-evaluation.ts`.
+* Neither an event-bus failure nor a refused write can replay an event, and the
+* hub's echo of the runtime's own write re-runs nothing.
+*/
+import { type CapabilityLookup, type CompositionEventPlan, type CompositionFieldPlan, type CompositionFieldRead, type CompositionFieldState, type IScopedLogger, type SourceReader } from "@camstack/types";
+import type { ComposedWriteTarget, CompositionEventEmitter, DeadlineTimer } from "./composition-target.js";
+import { type ReleasedField } from "./field-record.js";
+export type { ReleasedField } from "./field-record.js";
+export type { ComposedWriteTarget, CompositionEventEmitter, DeadlineTimer, TargetAsyncFailure, WriteOk, WriteOutcome, WriteRefused } from "./composition-target.js";
 export interface CompositionRuntimeDeps {
-    readonly blockId: string;
-    readonly fields: readonly CompositionFieldPlan[];
-    readonly eventPlans: readonly CompositionEventPlan[];
-    readonly events: CompositionEventEmitter;
-    readonly target: ComposedWriteTarget;
-    readonly lookupCap: CapabilityLookup;
-    /** Effective target slices captured before an existing-target runtime takes ownership. */
-    readonly initialByCap?: ReadonlyMap<string, Readonly<Record<string, unknown>> | null>;
-    readonly read: SourceReader;
-    /**
-     * Whether `read` is of this composition's OWN output (an added cap on its
-     * existing target, or its composed device): answered from the runtime's
-     * record, never from `read`. Absent = none is.
-     */
-    readonly isOwnRead?: (read: CompositionFieldRead) => boolean;
-    readonly now: () => number;
-    readonly timer: DeadlineTimer;
-    readonly logger: IScopedLogger;
+	readonly blockId: string;
+	readonly fields: readonly CompositionFieldPlan[];
+	readonly eventPlans: readonly CompositionEventPlan[];
+	readonly events: CompositionEventEmitter;
+	readonly target: ComposedWriteTarget;
+	readonly lookupCap: CapabilityLookup;
+	/** Effective target slices captured before an existing-target runtime takes ownership. */
+	readonly initialByCap?: ReadonlyMap<string, Readonly<Record<string, unknown>> | null>;
+	readonly read: SourceReader;
+	/**
+	* Whether `read` is of this composition's OWN output (an added cap on its
+	* existing target, or its composed device): answered from the runtime's
+	* record, never from `read`. Absent = none is.
+	*/
+	readonly isOwnRead?: (read: CompositionFieldRead) => boolean;
+	readonly now: () => number;
+	readonly timer: DeadlineTimer;
+	readonly logger: IScopedLogger;
 }
 export interface CompositionRuntimeState {
-    readonly failure: string | null;
-    readonly available: boolean;
-    readonly fields: readonly CompositionFieldState[];
-    readonly released: readonly ReleasedField[];
-    /** `release`-mode fields HELD on their last value: unavailable, but no source has answered so (D49). */
-    readonly held: readonly ReleasedField[];
+	readonly failure: string | null;
+	readonly available: boolean;
+	readonly fields: readonly CompositionFieldState[];
+	readonly released: readonly ReleasedField[];
+	/** `release`-mode fields HELD on their last value: unavailable, but no source has answered so (D49). */
+	readonly held: readonly ReleasedField[];
 }
 export declare class CompositionRuntime {
-    private readonly deps;
-    private records;
-    private readonly startedAtMs;
-    private seeded;
-    private available;
-    private failure;
-    private disabledReason;
-    private stopped;
-    /** The last `pass threw` logged (`during: message`); cleared by a pass that completes. */
-    private lastPassError;
-    private pending;
-    private heldBack;
-    /** Caps whose item array is not written because a required leaf has no value. */
-    private itemsHeld;
-    /** Record keys currently released (S1b), for transition logs and the report. */
-    private released;
-    /** Per cap, the top-level fields the target last accepted as withheld; absent = none. */
-    private withheld;
-    /** Per record key, how many times the field has been released — churn the transition line reports (D391). */
-    private releaseFlaps;
-    /** Caps the target refused for good (`TERMINAL_REFUSALS`): never written again by this runtime. */
-    private terminal;
-    /** What `composition-evaluation.ts` reads and commits through. */
-    private readonly evaluation;
-    constructor(deps: CompositionRuntimeDeps);
-    start(): void;
-    onSourcesChanged(sliceKeys: ReadonlySet<string>): void;
-    disable(reason: string): void;
-    /** Terminal: no write, no evaluation and no timer after this. */
-    stop(): void;
-    state(): CompositionRuntimeState;
-    /**
-     * The target's enqueued write of `cap` did not land: the cap is write-pending
-     * by name and re-written WHOLE on the next pass that evaluates it (or the next
-     * deadline pass). A withhold sent to that target is forgotten too, so it is
-     * re-sent. No retry timer (D3).
-     */
-    private onTargetWriteFailed;
-    /**
-     * The target refused this cap for good: nothing on this side can retry it
-     * away (I-3). The cap is never written again by this runtime, its fields
-     * report the refusal, and the block fails naming it — only the operator ends
-     * this (edit or delete the block, or the competing one), like a gone source.
-     */
-    private markTerminal;
-    /**
-     * Every entry point runs here: a no-op once stopped, nothing thrown escapes,
-     * and the one timer is re-armed from the stored deadlines whatever happened.
-     */
-    private guarded;
-    /** Once per distinct failure, not once per pass: a reader that keeps throwing logs one line. */
-    private logPassError;
-    private pass;
-    private recordsOf;
-    /** `retry`: write-pending caps this pass re-writes WHOLE, whether or not a value changed. */
-    private writeCaps;
-    /**
-     * S1b: tell the target which fields of `cap` are released, when that set
-     * changed since it last accepted one. A released record forgets what it wrote,
-     * so the source returning writes it again. False when the target refused or
-     * threw: the cap is write-pending and the withhold is re-sent next pass.
-     */
-    private syncReleased;
-    /** One info line per field per direction, never one per pass. */
-    private logReleaseTransitions;
-    private seedCap;
-    private patchCap;
-    /**
-     * After a failed write nothing is known about what landed, and after a
-     * changed withhold the claim must be re-stated: send every current value.
-     * `afterWithhold` with nothing left to write means the cap was released
-     * whole — a pending write is moot then, not retried (M-2).
-     */
-    private patchWholeCap;
-    private dropPending;
-    /**
-     * What one write of `cap` carries: the writable `candidates` — and, when any
-     * of them is an item leaf, EVERY item leaf of the cap, because the array is
-     * written whole (a patch of `items` replaces it). A required item leaf with
-     * no value holds the whole array (its top-level siblings still go out).
-     */
-    private entriesFor;
-    private writableEntries;
-    private holdItems;
-    private holdBackSeed;
-    /** One write. A refusal or a throw marks the cap write-pending; true when the target took it. */
-    private write;
-    private clearPending;
-    private markPending;
-    private markWritten;
-    private updateAvailability;
-    private updateFailure;
-    /** `after`: arm only deadlines later than this instant; null arms the earliest stored one. */
-    private armDeadline;
-    private onDeadline;
-    private logTransition;
+	private readonly deps;
+	private records;
+	private readonly startedAtMs;
+	private seeded;
+	private available;
+	private failure;
+	private disabledReason;
+	private stopped;
+	/** The last `pass threw` logged (`during: message`); cleared by a pass that completes. */
+	private lastPassError;
+	private pending;
+	private heldBack;
+	/** Caps whose item array is not written because a required leaf has no value. */
+	private itemsHeld;
+	/** Record keys currently released (S1b), for transition logs and the report. */
+	private released;
+	/** Per cap, the top-level fields the target last accepted as withheld; absent = none. */
+	private withheld;
+	/** Per record key, how many times the field has been released — churn the transition line reports (D391). */
+	private releaseFlaps;
+	/** Caps the target refused for good (`TERMINAL_REFUSALS`): never written again by this runtime. */
+	private terminal;
+	/** What `composition-evaluation.ts` reads and commits through. */
+	private readonly evaluation;
+	constructor(deps: CompositionRuntimeDeps);
+	start(): void;
+	onSourcesChanged(sliceKeys: ReadonlySet<string>): void;
+	disable(reason: string): void;
+	/** Terminal: no write, no evaluation and no timer after this. */
+	stop(): void;
+	state(): CompositionRuntimeState;
+	/**
+	* The target's enqueued write of `cap` did not land: the cap is write-pending
+	* by name and re-written WHOLE on the next pass that evaluates it (or the next
+	* deadline pass). A withhold sent to that target is forgotten too, so it is
+	* re-sent. No retry timer (D3).
+	*/
+	private onTargetWriteFailed;
+	/**
+	* The target refused this cap for good: nothing on this side can retry it
+	* away (I-3). The cap is never written again by this runtime, its fields
+	* report the refusal, and the block fails naming it — only the operator ends
+	* this (edit or delete the block, or the competing one), like a gone source.
+	*/
+	private markTerminal;
+	/**
+	* Every entry point runs here: a no-op once stopped, nothing thrown escapes,
+	* and the one timer is re-armed from the stored deadlines whatever happened.
+	*/
+	private guarded;
+	/** Once per distinct failure, not once per pass: a reader that keeps throwing logs one line. */
+	private logPassError;
+	private pass;
+	private recordsOf;
+	/** `retry`: write-pending caps this pass re-writes WHOLE, whether or not a value changed. */
+	private writeCaps;
+	/**
+	* S1b: tell the target which fields of `cap` are released, when that set
+	* changed since it last accepted one. A released record forgets what it wrote,
+	* so the source returning writes it again. False when the target refused or
+	* threw: the cap is write-pending and the withhold is re-sent next pass.
+	*/
+	private syncReleased;
+	/** One info line per field per direction, never one per pass. */
+	private logReleaseTransitions;
+	private seedCap;
+	private patchCap;
+	/**
+	* After a failed write nothing is known about what landed, and after a
+	* changed withhold the claim must be re-stated: send every current value.
+	* `afterWithhold` with nothing left to write means the cap was released
+	* whole — a pending write is moot then, not retried (M-2).
+	*/
+	private patchWholeCap;
+	private dropPending;
+	/**
+	* What one write of `cap` carries: the writable `candidates` — and, when any
+	* of them is an item leaf, EVERY item leaf of the cap, because the array is
+	* written whole (a patch of `items` replaces it). A required item leaf with
+	* no value holds the whole array (its top-level siblings still go out).
+	*/
+	private entriesFor;
+	private writableEntries;
+	private holdItems;
+	private holdBackSeed;
+	/** One write. A refusal or a throw marks the cap write-pending; true when the target took it. */
+	private write;
+	private clearPending;
+	private markPending;
+	private markWritten;
+	private updateAvailability;
+	private updateFailure;
+	/** `after`: arm only deadlines later than this instant; null arms the earliest stored one. */
+	private armDeadline;
+	private onDeadline;
+	private logTransition;
 }

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

@@ -1,50 +1,54 @@
-import { ClaimOutcome, SystemEvent } from '@camstack/types';
-import { SlicePatch } from './slice-assembler.js';
+/**
+* Where a composition writes, and the ports its runtime drives (D659, D663).
+* Split from `composition-runtime.ts`, which re-exports every name here.
+*/
+import type { ClaimOutcome, SystemEvent } from "@camstack/types";
+import type { SlicePatch } from "./slice-assembler.js";
 export interface WriteOk {
-    readonly ok: true;
+	readonly ok: true;
 }
 export interface WriteRefused {
-    readonly ok: false;
-    readonly error: string;
+	readonly ok: false;
+	readonly error: string;
 }
 export type WriteOutcome = WriteOk | WriteRefused;
 /** Why an enqueued write did not land. `refused` carries the hub's code so the target can escalate by name (S5). */
 export type TargetAsyncFailure = {
-    readonly kind: 'threw';
-    readonly error: string;
+	readonly kind: "threw";
+	readonly error: string;
 } | {
-    readonly kind: 'refused';
-    readonly code: Extract<ClaimOutcome, {
-        ok: false;
-    }>['code'];
-    readonly message: string;
+	readonly kind: "refused";
+	readonly code: Extract<ClaimOutcome, {
+		ok: false;
+	}>["code"];
+	readonly message: string;
 };
 /**
- * Where a composition writes. A write answers `{ ok: false }` rather than
- * throwing, and `setAvailable` does not throw. The runtime survives either
- * anyway: a throwing write is a failed write, a throwing `setAvailable` is
- * retried on the next pass. A target whose writes are asynchronous reports
- * what did not land through `onAsyncFailure`.
- */
+* Where a composition writes. A write answers `{ ok: false }` rather than
+* throwing, and `setAvailable` does not throw. The runtime survives either
+* anyway: a throwing write is a failed write, a throwing `setAvailable` is
+* retried on the next pass. A target whose writes are asynchronous reports
+* what did not land through `onAsyncFailure`.
+*/
 export interface ComposedWriteTarget {
-    readonly id: number;
-    seed(capName: string, slice: SlicePatch): WriteOutcome;
-    patch(capName: string, patch: SlicePatch): WriteOutcome;
-    setAvailable(available: boolean): void;
-    onAsyncFailure?(listener: (cap: string, failure: TargetAsyncFailure) => void): void;
-    /**
-     * S1b: these fields of `cap` are NOT the composition's to write right now
-     * (their `release`-mode source is unavailable). The claim is narrowed to the
-     * rest; an empty rest releases the whole cap. `[]` re-widens. Absent on a
-     * `new`-target device (`ComposedDevice`): `release` is planned only on
-     * existing targets.
-     */
-    withhold?(cap: string, fields: readonly string[]): WriteOutcome;
+	readonly id: number;
+	seed(capName: string, slice: SlicePatch): WriteOutcome;
+	patch(capName: string, patch: SlicePatch): WriteOutcome;
+	setAvailable(available: boolean): void;
+	onAsyncFailure?(listener: (cap: string, failure: TargetAsyncFailure) => void): void;
+	/**
+	* S1b: these fields of `cap` are NOT the composition's to write right now
+	* (their `release`-mode source is unavailable). The claim is narrowed to the
+	* rest; an empty rest releases the whole cap. `[]` re-widens. Absent on a
+	* `new`-target device (`ComposedDevice`): `release` is planned only on
+	* existing targets.
+	*/
+	withhold?(cap: string, fields: readonly string[]): WriteOutcome;
 }
 export interface DeadlineTimer {
-    arm(at: number, fire: () => void): void;
-    disarm(): void;
+	arm(at: number, fire: () => void): void;
+	disarm(): void;
 }
 export interface CompositionEventEmitter {
-    emit(event: SystemEvent): void;
+	emit(event: SystemEvent): void;
 }

package/dist/builtins/composer/confirmed-seed.d.ts

@@ -1,32 +1,44 @@
-import { IScopedLogger } from '@camstack/types';
+/**
+* A boot read the composer must trust before it withdraws anything (D49): the
+* rows it owns (`WithdrawalGate.seed`) and the claims it holds (`ClaimGate.seed`).
+*
+* A read that FAILS answers nothing — not `[]` — and is retried on the next
+* apply, which the supervisor's converge drives (never a timer, D3). An EMPTY
+* answer is the destroying direction: a cold registry and a cold index both
+* answer `[]`, and a seed trusted from it would let the next apply sweep every
+* row or release every claim nobody planned yet. So `[]` is trusted only when
+* the next apply's read agrees, and a failed read in between breaks the
+* agreement. Warned once per run of refused applies, not once per apply.
+*/
+import type { IScopedLogger } from "@camstack/types";
 export interface SeedItems<T> {
-    readonly kind: 'items';
-    readonly items: readonly T[];
+	readonly kind: "items";
+	readonly items: readonly T[];
 }
 export interface SeedUnknown {
-    readonly kind: 'unknown';
-    readonly error: string;
+	readonly kind: "unknown";
+	readonly error: string;
 }
 export type SeedRead<T> = SeedItems<T> | SeedUnknown;
 export interface ConfirmedSeedDeps<T> {
-    readonly logger: IScopedLogger;
-    /** What this seed is about, for its log lines: `rows`, `claims`. */
-    readonly subject: string;
-    readonly read: () => Promise<SeedRead<T>>;
-    readonly onSeeded: (items: readonly T[]) => void;
-    /** The reason a block waits while the read failed / answered `[]` once. */
-    readonly unreadReason: string;
-    readonly emptyUnconfirmedReason: string;
+	readonly logger: IScopedLogger;
+	/** What this seed is about, for its log lines: `rows`, `claims`. */
+	readonly subject: string;
+	readonly read: () => Promise<SeedRead<T>>;
+	readonly onSeeded: (items: readonly T[]) => void;
+	/** The reason a block waits while the read failed / answered `[]` once. */
+	readonly unreadReason: string;
+	readonly emptyUnconfirmedReason: string;
 }
 export declare class ConfirmedSeed<T> {
-    private readonly deps;
-    private seeded;
-    /** The previous read answered `[]`: one more `[]` confirms it (D49). */
-    private emptySeen;
-    /** Consecutive applies whose read did not answer: warned once per run. */
-    private waitApplies;
-    constructor(deps: ConfirmedSeedDeps<T>);
-    get done(): boolean;
-    /** Null once seeded, else why this apply must wait. */
-    ensure(): Promise<string | null>;
+	private readonly deps;
+	private seeded;
+	/** The previous read answered `[]`: one more `[]` confirms it (D49). */
+	private emptySeen;
+	/** Consecutive applies whose read did not answer: warned once per run. */
+	private waitApplies;
+	constructor(deps: ConfirmedSeedDeps<T>);
+	get done(): boolean;
+	/** Null once seeded, else why this apply must wait. */
+	ensure(): Promise<string | null>;
 }

package/dist/builtins/composer/deadline-timer.d.ts

@@ -1,18 +1,18 @@
-import { DeadlineTimer } from './composition-runtime.js';
+import type { DeadlineTimer } from "./composition-runtime.js";
 /** Node's largest `setTimeout` delay; anything longer is clamped to 1 ms (`TimeoutOverflowWarning`). */
 export declare const MAX_TIMER_DELAY_MS = 2147483647;
 /** One pending wake-up per composition, at its earliest expression deadline. Never a poll. */
 export declare class NodeDeadlineTimer implements DeadlineTimer {
-    private readonly now;
-    private handle;
-    constructor(now: () => number);
-    arm(at: number, fire: () => void): void;
-    /**
-     * A deadline further away than the largest delay is reached in legs: the
-     * clamped wake-up is NOT the deadline, so it re-arms the remainder instead of
-     * firing — firing early would re-arm the same deadline and, unclamped, Node
-     * turns it into a 1 ms spin (D3).
-     */
-    private schedule;
-    disarm(): void;
+	private readonly now;
+	private handle;
+	constructor(now: () => number);
+	arm(at: number, fire: () => void): void;
+	/**
+	* A deadline further away than the largest delay is reached in legs: the
+	* clamped wake-up is NOT the deadline, so it re-arms the remainder instead of
+	* firing — firing early would re-arm the same deadline and, unclamped, Node
+	* turns it into a 1 ms spin (D3).
+	*/
+	private schedule;
+	disarm(): void;
 }