@camstack/system 1.2.390 → 1.2.392

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

@@ -1,92 +1,109 @@
-import { CapabilityLookup, ClaimsListing, CompositionFeaturePlan, CompositionFieldPlan, CompositionFieldState, CompositionSourceRef, CompositionTargetFound, deviceStateCapability, DeviceType, FieldClaimMode, IScopedLogger } from '@camstack/types';
-import { z } from 'zod';
-import { ReleasedField } from './composition-runtime.js';
-import { GraftOutcome } from './graft-host.js';
-import { OwnedFieldsApi } from './owned-fields-target.js';
-import { BoundCapsRead } from './source-tracker.js';
+/**
+* What the composer needs to run a composition on an EXISTING device (D663)
+* besides the runtime and the claim-backed target: the target's description,
+* the claim shapes derived from the plan, and the block report's words.
+*
+* - The target is DESCRIBED (bound caps → native addon, row type) with ONE
+*   `getBindings` per plan change, cached until `device.bindings-changed` for
+*   that device. A read that fails keeps the previous description; with none,
+*   the block waits and nothing is claimed (D49).
+* - A claim's field set is the PLAN's (S5): the top-level fields of the cap, an
+*   item leaf contributing its whole array. Its mode is the feature's.
+* - A self-read of the target (rule 6) is served from the NATIVE view unless it
+*   reads an ADDED cap — that is the composition's own output. Whether a native
+*   cap's `device.state-changed` is the native or the composition's own merge
+*   is NOT decided here from the plan: it follows whether the claim has landed
+*   (`HeldClaims`, C-1).
+*/
+import { type CapabilityLookup, type ClaimsListing, type CompositionFeaturePlan, type CompositionFieldPlan, type CompositionFieldState, type CompositionSourceRef, type CompositionTargetFound, type deviceStateCapability, type DeviceType, type FieldClaimMode, type IScopedLogger } from "@camstack/types";
+import type { z } from "zod";
+import type { ReleasedField } from "./composition-runtime.js";
+import type { GraftOutcome } from "./graft-host.js";
+import type { OwnedFieldsApi } from "./owned-fields-target.js";
+import type { BoundCapsRead } from "./source-tracker.js";
 export type ListClaimsInput = z.infer<typeof deviceStateCapability.methods.listClaims.input>;
 /** The hub's claim surface the composer uses: the write target's three methods plus the boot seed. */
 export interface ComposerClaimsApi extends OwnedFieldsApi {
-    listClaims(input: ListClaimsInput): Promise<ClaimsListing>;
+	listClaims(input: ListClaimsInput): Promise<ClaimsListing>;
 }
 export interface ExistingTargetSeedRead {
-    readonly byCap: ReadonlyMap<string, Readonly<Record<string, unknown>> | null>;
+	readonly byCap: ReadonlyMap<string, Readonly<Record<string, unknown>> | null>;
 }
 export interface SeedlessRestoredCapsInput {
-    readonly logger: IScopedLogger;
-    readonly blockId: string;
-    readonly deviceId: number;
-    readonly features: readonly CompositionFeaturePlan[];
-    readonly seed: ExistingTargetSeedRead;
-    readonly lookupCap: CapabilityLookup;
+	readonly logger: IScopedLogger;
+	readonly blockId: string;
+	readonly deviceId: number;
+	readonly features: readonly CompositionFeaturePlan[];
+	readonly seed: ExistingTargetSeedRead;
+	readonly lookupCap: CapabilityLookup;
 }
 /**
- * Review M3: an ADDED `restored` cap seeded from NOTHING says so, once per
- * runtime build, on its device. After a restart its state comes from the
- * target's runtime-state row; a row that lost the slice (D677: 615's doorbell,
- * dropped at a hub boot) used to surface as "not seeded yet" and now seeds a
- * clean `{ null, 0 }` — a lifetime count silently reset unless this line
- * names it. A first composition of a device that never had the slice logs it
- * too: the line cannot tell the two apart, and says both.
- */
+* Review M3: an ADDED `restored` cap seeded from NOTHING says so, once per
+* runtime build, on its device. After a restart its state comes from the
+* target's runtime-state row; a row that lost the slice (D677: 615's doorbell,
+* dropped at a hub boot) used to surface as "not seeded yet" and now seeds a
+* clean `{ null, 0 }` — a lifetime count silently reset unless this line
+* names it. A first composition of a device that never had the slice logs it
+* too: the line cannot tell the two apart, and says both.
+*/
 export declare function reportSeedlessRestoredCaps(input: SeedlessRestoredCapsInput): void;
 /**
- * Read every affected effective capability exactly once, before the composer
- * grafts or claims any of them. A null slice is a successful empty seed; a
- * rejection is deliberately left to the caller so ownership cannot begin.
- */
+* Read every affected effective capability exactly once, before the composer
+* grafts or claims any of them. A null slice is a successful empty seed; a
+* rejection is deliberately left to the caller so ownership cannot begin.
+*/
 export declare function readExistingTargetSeeds(targetDeviceId: number, caps: readonly string[], read: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>): Promise<ExistingTargetSeedRead>;
 /**
- * The composer's grafts (`GraftHost`, Task 10): a method-serving native for each
- * cap a customization ADDS. Grafted at PLAN time only; removed when a foreign
- * native appears, when the target is gone (Kernel ruling,
- * `DeviceContext.unregisterNativeCap`), or when the block's add claim is
- * released — else the runner keeps a native on that id and `LocalChildRegistry`
- * keeps routing to it.
- */
+* The composer's grafts (`GraftHost`, Task 10): a method-serving native for each
+* cap a customization ADDS. Grafted at PLAN time only; removed when a foreign
+* native appears, when the target is gone (Kernel ruling,
+* `DeviceContext.unregisterNativeCap`), or when the block's add claim is
+* released — else the runner keeps a native on that id and `LocalChildRegistry`
+* keeps routing to it.
+*/
 export interface ComposerGraftPorts {
-    graft(deviceId: number, stableId: string, capName: string): GraftOutcome;
-    ungraft(deviceId: number, capName: string, reason: string): void;
-    grafted(deviceId: number): ReadonlySet<string>;
-    /**
-     * Retract a binding a PREVIOUS incarnation of the composer left on `deviceId`
-     * (I-3): this process never registered it, so `ungraft` cannot reach it. The
-     * caller has read that the binding IS the composer's.
-     */
-    retractStale(deviceId: number, capName: string, reason: string): void;
+	graft(deviceId: number, stableId: string, capName: string): GraftOutcome;
+	ungraft(deviceId: number, capName: string, reason: string): void;
+	grafted(deviceId: number): ReadonlySet<string>;
+	/**
+	* Retract a binding a PREVIOUS incarnation of the composer left on `deviceId`
+	* (I-3): this process never registered it, so `ungraft` cannot reach it. The
+	* caller has read that the binding IS the composer's.
+	*/
+	retractStale(deviceId: number, capName: string, reason: string): void;
 }
 /** The reason every ungraft of a gone target carries (Task 9 rule 5 / Task 10 rule 2). */
 export declare const TARGET_GONE_UNGRAFT_REASON = "target device gone";
 export interface GoneTargetUngraft {
-    readonly grafts: ComposerGraftPorts | undefined;
-    readonly logger: IScopedLogger;
-    readonly blockId: string;
-    readonly deviceId: number;
-    readonly ref: CompositionSourceRef;
-    readonly features: readonly CompositionFeaturePlan[];
+	readonly grafts: ComposerGraftPorts | undefined;
+	readonly logger: IScopedLogger;
+	readonly blockId: string;
+	readonly deviceId: number;
+	readonly ref: CompositionSourceRef;
+	readonly features: readonly CompositionFeaturePlan[];
 }
 /**
- * Rule 5, on either path that finds the target gone (`device.unregistered`, or
- * a later plan when that event was dropped): ungraft every cap the block ADDED
- * on that id, with the one ERROR that says so.
- */
+* Rule 5, on either path that finds the target gone (`device.unregistered`, or
+* a later plan when that event was dropped): ungraft every cap the block ADDED
+* on that id, with the one ERROR that says so.
+*/
 export declare function ungraftGoneTarget(input: GoneTargetUngraft): void;
 /** ONE `getBindings` read: cap → the addon serving it natively. */
 export type DescribeTarget = (deviceId: number) => Promise<BoundCapsRead>;
 export declare class TargetDescriptions {
-    private readonly logger;
-    private readonly readBoundCaps;
-    private cache;
-    constructor(logger: IScopedLogger, readBoundCaps: DescribeTarget);
-    /** `device.bindings-changed` for this device: the next read is a real read. */
-    invalidate(deviceId: number): void;
-    /**
-     * The description of `ref`, resolved to `deviceId`. Served from the cache
-     * unless `force` (the block's plan changed) or nothing is cached. A read that
-     * fails keeps the previous description of the SAME device id, and answers
-     * null when there is none: the caller waits, and claims nothing.
-     */
-    describe(ref: CompositionSourceRef, deviceId: number, type: DeviceType, force: boolean): Promise<CompositionTargetFound | null>;
+	private readonly logger;
+	private readonly readBoundCaps;
+	private cache;
+	constructor(logger: IScopedLogger, readBoundCaps: DescribeTarget);
+	/** `device.bindings-changed` for this device: the next read is a real read. */
+	invalidate(deviceId: number): void;
+	/**
+	* The description of `ref`, resolved to `deviceId`. Served from the cache
+	* unless `force` (the block's plan changed) or nothing is cached. A read that
+	* fails keeps the previous description of the SAME device id, and answers
+	* null when there is none: the caller waits, and claims nothing.
+	*/
+	describe(ref: CompositionSourceRef, deviceId: number, type: DeviceType, force: boolean): Promise<CompositionTargetFound | null>;
 }
 /** The PLANNED field set a claim carries for `cap` (S5): an item leaf claims its whole array. */
 export declare function claimFieldsOf(fields: readonly CompositionFieldPlan[], cap: string): readonly string[];
@@ -96,10 +113,10 @@ export declare function claimModeOf(features: readonly CompositionFeaturePlan[],
 export declare function addedCapsOf(features: readonly CompositionFeaturePlan[]): readonly string[];
 /** How the target's own caps are tracked for a block's self-reads (rule 6). */
 export interface SelfReadCaps {
-    /** Added caps read back: the composition's own output, the effective view. */
-    readonly effective: readonly string[];
-    /** Every other self-read cap: the native view. */
-    readonly native: readonly string[];
+	/** Added caps read back: the composition's own output, the effective view. */
+	readonly effective: readonly string[];
+	/** Every other self-read cap: the native view. */
+	readonly native: readonly string[];
 }
 export declare function selfReadCaps(fields: readonly CompositionFieldPlan[], target: CompositionSourceRef, features: readonly CompositionFeaturePlan[]): SelfReadCaps;
 /** The `degraded` reason (rule 8): one entry per released field, the source's own reason after the dash. */
@@ -107,8 +124,8 @@ export declare function degradedReason(released: readonly ReleasedField[]): stri
 /** The `starting` reason of a block with HELD fields: each keeps its last value and claim until its source answers (D49). */
 export declare function heldReason(held: readonly ReleasedField[]): string;
 /**
- * Rule 4: a customization whose row exists but whose plan failed keeps its
- * claims, so its owned fields stay at their last value on the hub. The report
- * says so — each field that had a value is `stale`, with the reason.
- */
+* Rule 4: a customization whose row exists but whose plan failed keeps its
+* claims, so its owned fields stay at their last value on the hub. The report
+* says so — each field that had a value is `stale`, with the reason.
+*/
 export declare function heldFieldsOf(fields: readonly CompositionFieldState[], reason: string): readonly CompositionFieldState[];

package/dist/builtins/composer/field-record.d.ts

@@ -1,17 +1,24 @@
-import { CapabilityLookup, CompositionFieldItem, CompositionFieldPlan, CompositionFieldState, ExpressionValue, FieldOutcome, StatefulExpressionMemory } from '@camstack/types';
+/**
+* One composed field's record and the pure judgements over it (D659, D663):
+* what it may write, whether it is released (a CONFIRMED unavailability of a
+* `release`-mode field, S1b) or HELD (no answer yet, D49), and how a report or a
+* log line names it. Split from `composition-runtime.ts`, which holds the
+* behaviour.
+*/
+import { type CapabilityLookup, type CompositionFieldItem, type CompositionFieldPlan, type CompositionFieldState, type ExpressionValue, type FieldOutcome, type StatefulExpressionMemory } from "@camstack/types";
 export declare const NO_FIELDS: ReadonlySet<string>;
 export interface FieldRecord {
-    readonly plan: CompositionFieldPlan;
-    readonly outcome: FieldOutcome | null;
-    /** The effective target value observed before this runtime took ownership. Never changes. */
-    readonly initial: unknown;
-    /** Whether `written` is an accepted runtime answer; kept separate because every falsey value is valid. */
-    readonly hasWritten: boolean;
-    /** What the target last accepted from this runtime. */
-    readonly written: unknown;
-    readonly expressionMemory: StatefulExpressionMemory;
-    /** Last finite state value already represented by a derived event. */
-    readonly eventHighWater: number | null;
+	readonly plan: CompositionFieldPlan;
+	readonly outcome: FieldOutcome | null;
+	/** The effective target value observed before this runtime took ownership. Never changes. */
+	readonly initial: unknown;
+	/** Whether `written` is an accepted runtime answer; kept separate because every falsey value is valid. */
+	readonly hasWritten: boolean;
+	/** What the target last accepted from this runtime. */
+	readonly written: unknown;
+	readonly expressionMemory: StatefulExpressionMemory;
+	/** Last finite state value already represented by a derived event. */
+	readonly eventHighWater: number | null;
 }
 export declare function fieldKey(plan: CompositionFieldPlan): string;
 export declare function createFieldRecord(plan: CompositionFieldPlan, byCap: ReadonlyMap<string, Readonly<Record<string, unknown>> | null> | undefined, lookupCap: CapabilityLookup): FieldRecord;
@@ -20,7 +27,7 @@ export declare function currentOutput(record: FieldRecord): unknown;
 export declare function topLevelField(plan: CompositionFieldPlan): string;
 /** The field as a report or a log line names it: `items[desiccant].status` for an item leaf. */
 export declare function fieldPath(plan: CompositionFieldPlan): string;
-export declare function itemOf(plan: CompositionFieldPlan): Partial<Pick<CompositionFieldState, 'item'>>;
+export declare function itemOf(plan: CompositionFieldPlan): Partial<Pick<CompositionFieldState, "item">>;
 export declare function sameSet(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean;
 export declare function valueOf(outcome: FieldOutcome | null): ExpressionValue | undefined;
 export declare function reasonOf(outcome: FieldOutcome | null): string | null;
@@ -36,15 +43,15 @@ export declare function namedField(r: FieldRecord): ReleasedField;
 export declare function writable(record: FieldRecord): ExpressionValue | undefined;
 /** A `release`-mode field handed back to the native provider, and why (for the block report). */
 export interface ReleasedField {
-    readonly cap: string;
-    readonly path: string;
-    readonly item?: CompositionFieldItem;
-    readonly reason: string;
+	readonly cap: string;
+	readonly path: string;
+	readonly item?: CompositionFieldItem;
+	readonly reason: string;
 }
 /** Why a cap's last write did not land; the cap is re-written whole on the next pass that evaluates it. */
 export interface PendingWrite {
-    readonly kind: 'refused' | 'threw';
-    readonly error: string;
+	readonly kind: "refused" | "threw";
+	readonly error: string;
 }
 export declare function errorText(error: unknown): string;
 export declare function pendingReason(cap: string, pending: PendingWrite): string;

package/dist/builtins/composer/graft-host.d.ts

@@ -1,16 +1,40 @@
-import { CapabilityLookup, DeviceContext, IScopedLogger } from '@camstack/types';
-import { ComposerGraftPorts } from './existing-target.js';
+/**
+* Grafts (D663): a method-serving native provider for a cap a customization
+* ADDS to a device the composer does not own — a battery on an HA pet feeder
+* that registers none. Without it the added cap has claimed values on the hub
+* but nothing answers its methods, so `getBindings` never lists it and a caller
+* of `battery.wakeForStream` finds no provider.
+*
+* - The provider is built ONLY from the cap's `composedMethods` (Task 1): an
+*   `answer` resolves to its value, a `refuse` rejects naming its reason. A cap
+*   with a served method that has no composed answer is refused here as it is
+*   at plan time (`has-commands`, slice 1). `getStatus` reads the MERGED slice
+*   (`readMerged`): the hub overlays it anyway (Task 7), but a direct call to
+*   this runner must never answer `{}`.
+* - The context is `createContext(stableId, id)` on a FOREIGN device id: the
+*   second use of the forked-runner native path D659 lists as unverified live
+*   (D659 live item 1). Task 16 step 4.1 is its live proof. Its EMPTY runtime
+*   state is correct and deliberate (D677): no device is built from it and no
+*   slice is written through it — the graft only registers method-serving
+*   natives, and `getStatus` reads the hub's merged slice.
+* - `ungraft` removes only what THIS host registered, through the context's
+*   optional `unregisterNativeCap`. An older kernel without it leaves the graft
+*   routable until the composer respawns — warned once per device, never
+*   silent.
+*/
+import { type CapabilityLookup, type DeviceContext, type IScopedLogger } from "@camstack/types";
+import type { ComposerGraftPorts } from "./existing-target.js";
 export interface GraftPorts {
-    readonly createContext: (stableId: string, id: number) => DeviceContext;
-    readonly logger: IScopedLogger;
+	readonly createContext: (stableId: string, id: number) => DeviceContext;
+	readonly logger: IScopedLogger;
 }
 export type GraftOutcome = {
-    readonly kind: 'grafted';
+	readonly kind: "grafted";
 } | {
-    readonly kind: 'already';
+	readonly kind: "already";
 } | {
-    readonly kind: 'refused';
-    readonly reason: string;
+	readonly kind: "refused";
+	readonly reason: string;
 };
 /** The merged (effective) slice of `cap` on `deviceId`, as every consumer reads it; null when there is none. */
 export type ReadMergedSlice = (deviceId: number, cap: string) => Promise<Readonly<Record<string, unknown>> | null>;
@@ -19,29 +43,29 @@ type GraftMethod = (input: unknown) => Promise<unknown>;
 /** The provider a graft registers: method name → its composed implementation. */
 export type GraftProvider = Readonly<Record<string, GraftMethod>>;
 export declare class GraftHost implements ComposerGraftPorts {
-    private readonly ports;
-    private readonly lookupCap;
-    private readonly readMerged;
-    /** One context per foreign device: `registerNativeCap` is per context, and so is its unregister. */
-    private contexts;
-    private caps;
-    /** Devices already warned that this kernel cannot unregister a graft. */
-    private warnedNoUnregister;
-    constructor(ports: GraftPorts, lookupCap: CapabilityLookup, readMerged: ReadMergedSlice);
-    graft(deviceId: number, stableId: string, capName: string): GraftOutcome;
-    ungraft(deviceId: number, capName: string, reason: string): void;
-    /**
-     * I-3: a binding a PREVIOUS composer process left on `deviceId` — this one
-     * never registered it. The kernel retracts it under the composer's addon id;
-     * the hub drops only an entry the composer registered (rule 4). The caller has
-     * read that the binding is the composer's.
-     */
-    retractStale(deviceId: number, capName: string, reason: string): void;
-    grafted(deviceId: number): ReadonlySet<string>;
-    /** A throw keeps the graft known, so a later plan retries (M-2); an older kernel forgets it (warned once). */
-    private unregister;
-    private contextFor;
-    private providerFor;
-    private refuse;
+	private readonly ports;
+	private readonly lookupCap;
+	private readonly readMerged;
+	/** One context per foreign device: `registerNativeCap` is per context, and so is its unregister. */
+	private contexts;
+	private caps;
+	/** Devices already warned that this kernel cannot unregister a graft. */
+	private warnedNoUnregister;
+	constructor(ports: GraftPorts, lookupCap: CapabilityLookup, readMerged: ReadMergedSlice);
+	graft(deviceId: number, stableId: string, capName: string): GraftOutcome;
+	ungraft(deviceId: number, capName: string, reason: string): void;
+	/**
+	* I-3: a binding a PREVIOUS composer process left on `deviceId` — this one
+	* never registered it. The kernel retracts it under the composer's addon id;
+	* the hub drops only an entry the composer registered (rule 4). The caller has
+	* read that the binding is the composer's.
+	*/
+	retractStale(deviceId: number, capName: string, reason: string): void;
+	grafted(deviceId: number): ReadonlySet<string>;
+	/** A throw keeps the graft known, so a later plan retries (M-2); an older kernel forgets it (warned once). */
+	private unregister;
+	private contextFor;
+	private providerFor;
+	private refuse;
 }
 export {};

package/dist/builtins/composer/held-claims.d.ts

@@ -1,12 +1,29 @@
-import { FieldClaim } from '@camstack/types';
+/**
+* Which of a block's OWN `replace` claims the hub holds, or is being asked for
+* (D663) — the fact that decides what a `device.state-changed` of that cap is
+* for the block's native self-reads. With no claim it IS the provider's native;
+* under the block's claim it is the block's own merge, and the native arrives
+* only on `device.native-shadow-changed`.
+*
+* - Fed by what actually LANDED, never by the plan (C-1): the boot seed (the
+*   hub's claims index), a claim the hub answered `ok`, a release the hub
+*   confirmed. A throw or an unexplained refusal changes nothing (D49).
+* - While a claim RPC is IN FLIGHT the hub may already merge (the mirror emits
+*   from inside `claim()`, before the answer): a `device.state-changed` then is
+*   neither native nor composed, and is not taken as either (N-1). The reply —
+*   any reply — ends the window, and the caller re-reads the native once.
+* - Keyed by OWNER (N-7): another block's claim on the same cap, and an `add`
+*   claim (which emits no shadow), never make this block's cap held.
+*/
+import type { FieldClaim } from "@camstack/types";
 /** What one claim RPC of an owner did, as its target saw it. */
-export type ClaimEvent = 'claiming' | 'held' | 'free' | 'unsettled';
+export type ClaimEvent = "claiming" | "held" | "free" | "unsettled";
 export declare class HeldClaims {
-    private held;
-    private claiming;
-    /** The `replace` claims the hub holds before this process wrote any (the boot seed). */
-    seed(claims: readonly FieldClaim[]): void;
-    apply(deviceId: number, cap: string, owner: string, event: ClaimEvent): void;
-    /** `device.state-changed` of `cap` is NOT the native for `owner`'s self-reads: its claim is held, or being asked for. */
-    shadowsNative(deviceId: number, cap: string, owner: string): boolean;
+	private held;
+	private claiming;
+	/** The `replace` claims the hub holds before this process wrote any (the boot seed). */
+	seed(claims: readonly FieldClaim[]): void;
+	apply(deviceId: number, cap: string, owner: string, event: ClaimEvent): void;
+	/** `device.state-changed` of `cap` is NOT the native for `owner`'s self-reads: its claim is held, or being asked for. */
+	shadowsNative(deviceId: number, cap: string, owner: string): boolean;
 }

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

@@ -1 +1 @@
-export { ComposerAddon as default, ComposerAddon } from './composer.addon.js';
+export { ComposerAddon as default, ComposerAddon } from "./composer.addon.js";

package/dist/builtins/composer/own-field-reads.d.ts

@@ -1,19 +1,30 @@
-import { SourceReading } from '@camstack/types';
-import { FieldRecord } from './field-record.js';
+/**
+* A composition's read of its OWN output, answered from the runtime's records
+* (D670 amendment, 2026-09-29). Split from `composition-runtime.ts`, which
+* decides WHEN a read is an own read (`isOwnRead`) and re-runs its readers.
+*
+* Through the hub such a read was circular: the effective slice of an ADDED cap
+* exists only once the composer's claim lands, and the claim lands only once
+* every required field has a value — camera 615's `pressCountSinceStart =
+* count(lastPressedAt)` was one of them, and nothing served its doorbell for
+* 12 h.
+*/
+import type { SourceReading } from "@camstack/types";
+import { type FieldRecord } from "./field-record.js";
 /** `keys` in evaluation order: derived, then accumulators, then the rest; stable within a rank. */
 export declare function orderForEvaluation(keys: readonly string[], records: ReadonlyMap<string, FieldRecord>): readonly string[];
 /**
- * The own field `key` as the runtime holds it right now (`records`: the pass in
- * progress) — exactly what the runtime PUBLISHES for it, which is what the hub
- * answered before (review H1). An unavailable field under the `null` or
- * `unknown` policy is published as `null` / `'unknown'`, so a reader sees that
- * value; only a field nothing is written for (`release`, `offline`) reads as
- * unavailable. Answering those as unavailable left `count` unprimed while a
- * source was late at boot, and it then swallowed the first press as its seed.
- *
- * Not evaluated yet is unavailable: nothing is published, and unknown is never
- * `null` (D393). The evaluation order makes this unreachable for a derived
- * reader of a derived field. Never fatal here: a gone source fails the block
- * through the field that reads it directly.
- */
+* The own field `key` as the runtime holds it right now (`records`: the pass in
+* progress) — exactly what the runtime PUBLISHES for it, which is what the hub
+* answered before (review H1). An unavailable field under the `null` or
+* `unknown` policy is published as `null` / `'unknown'`, so a reader sees that
+* value; only a field nothing is written for (`release`, `offline`) reads as
+* unavailable. Answering those as unavailable left `count` unprimed while a
+* source was late at boot, and it then swallowed the first press as its seed.
+*
+* Not evaluated yet is unavailable: nothing is published, and unknown is never
+* `null` (D393). The evaluation order makes this unreachable for a derived
+* reader of a derived field. Never fatal here: a gone source fails the block
+* through the field that reads it directly.
+*/
 export declare function ownFieldReading(records: ReadonlyMap<string, FieldRecord>, key: string): SourceReading;

package/dist/builtins/composer/owned-fields-target.d.ts

@@ -1,55 +1,86 @@
-import { ClaimOutcome, deviceStateCapability, FieldClaimMode, IScopedLogger } from '@camstack/types';
-import { z } from 'zod';
-import { ComposedWriteTarget, TargetAsyncFailure, WriteOutcome } from './composition-runtime.js';
-import { ClaimEvent } from './held-claims.js';
-import { SlicePatch } from './slice-assembler.js';
+/**
+* The write target of a composition on an EXISTING device (D663): its fields
+* are CLAIMED on the hub (`deviceState.claimFields`), then patched
+* (`patchOwnedFields`). The runtime's `seed`/`patch` are synchronous and never
+* fail here — the RPC is enqueued — so what did not land is reported through
+* `onAsyncFailure`, and the runtime marks the cap write-pending and re-writes
+* it whole on its next pass. No retry timer (D3).
+*
+* - **The claim is re-sent until it has LANDED (ruling S5).** A cap enters
+*   `landed` only on an `ok` claim answer. Every write of a cap not in `landed`
+*   is a claim carrying the FULL planned field set (`fieldsOf`, never inferred
+*   from the values). `not-claimed` / `field-not-claimed` — the hub lost or
+*   never had the claim — drop the cap from `landed` and are escalated by
+*   name, so the next write claims again.
+* - **Concurrent partial patches are MERGED, never dropped (S5).** One chain
+*   per cap: while an RPC is in flight, later patches fold into one pending
+*   value set (later keys win; a seed replaces it wholly), and the landing log
+*   says how many were absorbed (D391).
+* - **A released field is withheld (S1b).** `withhold(cap, fields)` narrows the
+*   next claim to the rest and omits their values; nothing left → the claim is
+*   released at once. `[]` re-widens.
+* - **Every claim RPC of a `replace` cap is reported** (`onClaim`, C-1/N-1):
+*   `claiming` when it goes out, then `held` on an `ok`, `free` on a confirmed
+*   release or `not-claimed`, `unsettled` on a throw or any other refusal (D49:
+*   changes nothing). `field-not-claimed` on a patch drops `landed` so the next
+*   write claims again, but the hub still holds the claim: `held` stays (N-3).
+*   The tracker follows this — never the plan — to know whether
+*   `device.state-changed` of the cap is the provider's native, the
+*   composition's own merge, or (while a claim is in flight) neither.
+* - `setAvailable` is a no-op: `device-status` is the native device's.
+*/
+import { type ClaimOutcome, type deviceStateCapability, type FieldClaimMode, type IScopedLogger } from "@camstack/types";
+import type { z } from "zod";
+import type { ComposedWriteTarget, TargetAsyncFailure, WriteOutcome } from "./composition-runtime.js";
+import type { ClaimEvent } from "./held-claims.js";
+import type { SlicePatch } from "./slice-assembler.js";
 export type ClaimFieldsInput = z.infer<typeof deviceStateCapability.methods.claimFields.input>;
 export type PatchOwnedFieldsInput = z.infer<typeof deviceStateCapability.methods.patchOwnedFields.input>;
 export type ReleaseClaimInput = z.infer<typeof deviceStateCapability.methods.releaseClaim.input>;
 export interface OwnedFieldsApi {
-    claimFields(input: ClaimFieldsInput): Promise<ClaimOutcome>;
-    patchOwnedFields(input: PatchOwnedFieldsInput): Promise<ClaimOutcome>;
-    releaseClaim(input: ReleaseClaimInput): Promise<ClaimOutcome>;
+	claimFields(input: ClaimFieldsInput): Promise<ClaimOutcome>;
+	patchOwnedFields(input: PatchOwnedFieldsInput): Promise<ClaimOutcome>;
+	releaseClaim(input: ReleaseClaimInput): Promise<ClaimOutcome>;
 }
 export interface OwnedFieldsTargetDeps {
-    readonly deviceId: number;
-    readonly owner: string;
-    readonly modeOf: (cap: string) => FieldClaimMode;
-    /** The PLANNED field set per cap, from the plan — sent on every claim, never inferred from values (S5). */
-    readonly fieldsOf: (cap: string) => readonly string[];
-    readonly api: OwnedFieldsApi;
-    readonly logger: IScopedLogger;
-    /** A claim RPC of this owner on a `replace` cap went out or was answered (see the header). */
-    readonly onClaim?: (cap: string, event: ClaimEvent) => void;
+	readonly deviceId: number;
+	readonly owner: string;
+	readonly modeOf: (cap: string) => FieldClaimMode;
+	/** The PLANNED field set per cap, from the plan — sent on every claim, never inferred from values (S5). */
+	readonly fieldsOf: (cap: string) => readonly string[];
+	readonly api: OwnedFieldsApi;
+	readonly logger: IScopedLogger;
+	/** A claim RPC of this owner on a `replace` cap went out or was answered (see the header). */
+	readonly onClaim?: (cap: string, event: ClaimEvent) => void;
 }
 type AsyncFailureListener = (cap: string, failure: TargetAsyncFailure) => void;
 export declare class OwnedFieldsTarget implements ComposedWriteTarget {
-    private readonly deps;
-    readonly id: number;
-    private landed;
-    private withheld;
-    private inFlight;
-    private pending;
-    private listeners;
-    /** Per cap, bumped by every `withhold`: a claim that settles under another epoch claimed a stale field set and does not land (I-2). */
-    private epoch;
-    constructor(deps: OwnedFieldsTargetDeps);
-    seed(cap: string, slice: SlicePatch): WriteOutcome;
-    patch(cap: string, patch: SlicePatch): WriteOutcome;
-    /** `device-status` belongs to the native device; availability lives in the block report only. */
-    setAvailable(_available: boolean): void;
-    onAsyncFailure(listener: AsyncFailureListener): void;
-    withhold(cap: string, fields: readonly string[]): WriteOutcome;
-    private claimableFields;
-    private enqueue;
-    private send;
-    private settled;
-    private sendWrite;
-    private sendRelease;
-    private logLanded;
-    /** Only a `replace` cap has a native the tracker must tell apart from the merge (N-7). */
-    private report;
-    /** Escalated to the runtime; a failure nobody listens to is logged — never silent (D391). */
-    private fail;
+	private readonly deps;
+	readonly id: number;
+	private landed;
+	private withheld;
+	private inFlight;
+	private pending;
+	private listeners;
+	/** Per cap, bumped by every `withhold`: a claim that settles under another epoch claimed a stale field set and does not land (I-2). */
+	private epoch;
+	constructor(deps: OwnedFieldsTargetDeps);
+	seed(cap: string, slice: SlicePatch): WriteOutcome;
+	patch(cap: string, patch: SlicePatch): WriteOutcome;
+	/** `device-status` belongs to the native device; availability lives in the block report only. */
+	setAvailable(_available: boolean): void;
+	onAsyncFailure(listener: AsyncFailureListener): void;
+	withhold(cap: string, fields: readonly string[]): WriteOutcome;
+	private claimableFields;
+	private enqueue;
+	private send;
+	private settled;
+	private sendWrite;
+	private sendRelease;
+	private logLanded;
+	/** Only a `replace` cap has a native the tracker must tell apart from the merge (N-7). */
+	private report;
+	/** Escalated to the runtime; a failure nobody listens to is logged — never silent (D391). */
+	private fail;
 }
 export {};

package/dist/builtins/composer/slice-assembler.d.ts

@@ -1,10 +1,26 @@
-import { CapabilityLookup, CompositionFieldPlan, ExpressionValue } from '@camstack/types';
+/**
+* From the runtime's flat field values to the slice a target takes (D663).
+*
+* A top-level field is written under its path. An item leaf
+* (`consumables.items[desiccant].remaining.value`) is one entry of an ARRAY:
+* every leaf of one item is grouped by `(cap, arrayPath, key)` and set, by
+* path segment, onto the cap's OWN `status.itemArray.emptyItem` — so an
+* unsourced nullable leaf is `null` because the cap says so, not because this
+* module guessed. The key, the label and {@link COMPOSED_ITEM_FIXED_FIELDS}
+* are the composer's; items are sorted by key so two writes of the same
+* values are one slice.
+*
+* A cap the lookup does not know as an item array cannot be assembled: that
+* is thrown by name, and the runtime's write path turns a throw into a named,
+* retried failure — never a half-built array.
+*/
+import { type CapabilityLookup, type CompositionFieldPlan, type ExpressionValue } from "@camstack/types";
 /** One item of an item-array field, as written. */
 export type SliceItem = Readonly<Record<string, unknown>>;
 export type SliceValue = ExpressionValue | readonly SliceItem[];
 export type SlicePatch = Readonly<Record<string, SliceValue>>;
 export interface AssemblerEntry {
-    readonly plan: CompositionFieldPlan;
-    readonly value: ExpressionValue;
+	readonly plan: CompositionFieldPlan;
+	readonly value: ExpressionValue;
 }
 export declare function assembleSlice(entries: readonly AssemblerEntry[], lookupCap: CapabilityLookup): SlicePatch;