@camstack/system 1.2.313 → 1.2.315

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

@@ -1,27 +1,25 @@
-import { CapabilityLookup, ComposerApplyInput, ComposerApplyResult, CompositionBlockState, DeviceDeclaration, DeviceType, IScopedLogger } from '@camstack/types';
+import { CapabilityLookup, ComposerApplyInput, ComposerApplyResult, CompositionBlockState, IScopedLogger } from '@camstack/types';
 import { DeviceStateChangedData } from '../shared/device-state-changed.js';
-import { ComposedDeviceHandle } from './composed-device.js';
+import { ComposerDeclare, ComposerDevicePorts } from './composed-device-set.js';
 import { PersistedComposedRow } from './composition-declarations.js';
-import { DeadlineTimer } from './composition-runtime.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';
 /** 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;
 }
-export interface ComposerDerivedSpec {
-    readonly type: DeviceType;
-    readonly role?: string;
-}
-export interface ComposerDevicePorts {
-    setName(deviceId: number, name: string): Promise<void>;
-    decommission(deviceId: number): Promise<void>;
-    applyDerivedSpec(deviceId: number, derived: ComposerDerivedSpec): Promise<void>;
-}
-export interface ComposerDeclareResult {
-    /** Live composed devices by stableId. */
-    readonly devices: ReadonlyMap<string, ComposedDeviceHandle>;
+/** 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>>;
 }
 export interface ComposerDeps {
     readonly logger: IScopedLogger;
@@ -29,75 +27,96 @@ export interface ComposerDeps {
     readonly lookupCap: CapabilityLookup;
     /** The composed rows that already exist (`listOwnDevices`), read once before the first withdrawal decision. */
     readonly readPersisted: () => Promise<readonly PersistedComposedRow[]>;
-    readonly declare: (integrationId: string, devices: readonly DeviceDeclaration[]) => Promise<ComposerDeclareResult>;
+    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;
-    private devices;
-    /** StableIds whose row exists: the seeded persisted rows, then what every declare kept. */
-    private rows;
-    private seeded;
-    /** The previous seed read answered `[]`: one more `[]` confirms it (D49). */
-    private emptySeedSeen;
+    /** The composed devices of `new`-target blocks, and the rows that exist. */
+    private readonly composed;
     /** Consecutive applies refused because `core_blocks` had not loaded: warned once per run. */
     private storeWaitApplies;
     /** Consecutive applies refused because the Blocks integration had not reconciled: warned once per run. */
     private integrationWaitApplies;
-    private declaredFingerprint;
     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 waiting;
-    /**
-     * Seed the withdrawal gate with the rows that exist, ONCE, before its first
-     * `filter`; answers null once seeded, else why this apply must wait.
-     *
-     * An EMPTY answer is the destroying direction: a cold registry answers `[]`
-     * too, and `DeclaredDevices.reconcile` sweeps from its OWN later read — so a
-     * cold seed followed by a warm sweep would delete the row of a block that no
-     * longer plans, with no placeholder to hold it. `[]` is therefore trusted
-     * only when the next apply's read agrees (D49); that apply comes from the
-     * supervisor's existing converge, never a timer here (D3). A failed read
-     * changes nothing and breaks the agreement.
-     */
-    private ensureSeeded;
-    /**
-     * A row that exists but does not parse is held exactly like a composition
-     * that stopped planning: its device (if it has a row) stays as an offline
-     * placeholder, and the block fails naming the parse error. Absent, it would
-     * be withdrawn on the second apply that omitted it (D49).
-     */
-    private planUnreadable;
     private plan;
-    /** One line when a block starts or stops planning — never one per apply. */
-    private logPlanTransitions;
-    /**
-     * A changed type/role/cap set (or a switch to or from a placeholder) needs a
-     * NEW device object: decommission, and let the reconcile adopt it with the
-     * new class. A failure keeps the old device and is retried next apply.
-     */
-    private rebuildShapes;
-    private reconcileDevices;
     private rebuildRuntimes;
+    private ungraftGone;
+    /** Where a block's runtime writes: its composed device, or a claim-backed target on the existing device. */
+    private writerFor;
+    /** 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 newRuntime;
     private applyName;
     private syncSources;
     /** A failed sync leaves the tracker as it was: the runtimes read what it holds. */
     private syncTracker;
+    /**
+     * Rule 3: the claims every live customization WANTS this apply; everything
+     * else the gate knows is a release candidate, handed back once two applies
+     * agree. A block that cannot plan — waiting, unreadable, failed, or with its
+     * target gone — HOLDS its claims (rule 4, rule 5): they are wanted as they
+     * are. A disabled block wants none (rule 7).
+     */
+    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-runtime.d.ts

@@ -1,4 +1,7 @@
-import { CompositionFieldPlan, CompositionFieldState, ExpressionValue, IScopedLogger, SourceReader } from '@camstack/types';
+import { CapabilityLookup, ClaimOutcome, CompositionEventPlan, CompositionFieldPlan, CompositionFieldState, IScopedLogger, SourceReader, SystemEvent } from '@camstack/types';
+import { SlicePatch } from './slice-assembler.js';
+import { ReleasedField } from './field-record.js';
+export type { ReleasedField } from './field-record.js';
 export interface WriteOk {
     readonly ok: true;
 }
@@ -7,26 +10,55 @@ export interface WriteRefused {
     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: 'refused';
+    readonly code: Extract<ClaimOutcome, {
+        ok: false;
+    }>['code'];
+    readonly message: string;
+};
 /**
- * The composed device. 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.
+ * 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: Readonly<Record<string, ExpressionValue>>): WriteOutcome;
-    patch(capName: string, patch: Readonly<Record<string, ExpressionValue>>): WriteOutcome;
+    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;
 }
+export interface CompositionEventEmitter {
+    emit(event: SystemEvent): void;
+}
 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;
     readonly now: () => number;
     readonly timer: DeadlineTimer;
@@ -36,10 +68,14 @@ 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[];
 }
 export declare class CompositionRuntime {
     private readonly deps;
     private records;
+    private readonly startedAtMs;
     private seeded;
     private available;
     private failure;
@@ -49,6 +85,16 @@ export declare class CompositionRuntime {
     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;
     constructor(deps: CompositionRuntimeDeps);
     start(): void;
     onSourcesChanged(sliceKeys: ReadonlySet<string>): void;
@@ -56,6 +102,20 @@ export declare class CompositionRuntime {
     /** 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.
@@ -65,16 +125,40 @@ export declare class CompositionRuntime {
     private logPassError;
     private pass;
     private evaluate;
+    private emitStateEvent;
     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: send every current value. */
+    /**
+     * 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 it landed. */
+    /** One write. A refusal or a throw marks the cap write-pending; true when the target took it. */
     private write;
     private clearPending;
     private markPending;

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

@@ -0,0 +1,32 @@
+import { IScopedLogger } from '@camstack/types';
+export interface SeedItems<T> {
+    readonly kind: 'items';
+    readonly items: readonly T[];
+}
+export interface SeedUnknown {
+    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;
+}
+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>;
+}

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

@@ -0,0 +1,96 @@
+import { 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';
+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>;
+}
+export interface ExistingTargetSeedRead {
+    readonly byCap: ReadonlyMap<string, Readonly<Record<string, unknown>> | null>;
+}
+/**
+ * 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.
+ */
+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;
+}
+/** 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[];
+}
+/**
+ * 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>;
+}
+/** 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[];
+/** The claim mode of `cap`: `replace` for a cap the device serves natively, else `add`. */
+export declare function claimModeOf(features: readonly CompositionFeaturePlan[], cap: string): FieldClaimMode;
+/** The caps a customization ADDS to its target — the ones it grafts a native for (Task 10). */
+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[];
+}
+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. */
+export declare function degradedReason(released: readonly ReleasedField[]): string;
+/** 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.
+ */
+export declare function heldFieldsOf(fields: readonly CompositionFieldState[], reason: string): readonly CompositionFieldState[];

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

@@ -0,0 +1,50 @@
+import { CapabilityLookup, CompositionFieldItem, CompositionFieldPlan, CompositionFieldState, ExpressionValue, FieldOutcome, 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;
+}
+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;
+export declare function currentOutput(record: FieldRecord): unknown;
+/** The top-level field a record writes: an item leaf writes its whole array. */
+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 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;
+/** State, value and reason — what a write or a log line is about. NEVER the deadline (R1). */
+export declare function sameOutcome(a: FieldOutcome | null, b: FieldOutcome): boolean;
+/** A source is GONE: the outcome that must never be masked by a non-fatal one. */
+export declare function isFatal(outcome: FieldOutcome | null): boolean;
+/** A `release`-mode field whose source is CONFIRMED unavailable: not the composition's to write (S1b). Stale is a value (D49). */
+export declare function isReleased(record: FieldRecord): boolean;
+/** A `release`-mode field with no value and no ANSWER yet (a failed, first or empty read): held on its last value, never released (D49). */
+export declare function isHeld(record: FieldRecord): boolean;
+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;
+}
+/** 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;
+}
+export declare function errorText(error: unknown): string;
+export declare function pendingReason(cap: string, pending: PendingWrite): string;

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

@@ -0,0 +1,47 @@
+import { CapabilityLookup, DeviceContext, IScopedLogger } from '@camstack/types';
+import { ComposerGraftPorts } from './existing-target.js';
+export interface GraftPorts {
+    readonly createContext: (stableId: string, id: number) => DeviceContext;
+    readonly logger: IScopedLogger;
+}
+export type GraftOutcome = {
+    readonly kind: 'grafted';
+} | {
+    readonly kind: 'already';
+} | {
+    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>;
+/** One grafted method: the composed answer, or the merged-slice status read. */
+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;
+}
+export {};

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

@@ -0,0 +1,12 @@
+import { 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 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;
+}

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

@@ -0,0 +1,55 @@
+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';
+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>;
+}
+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;
+}
+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;
+}
+export {};

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

@@ -0,0 +1,10 @@
+import { CapabilityLookup, CompositionFieldPlan, 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;
+}
+export declare function assembleSlice(entries: readonly AssemblerEntry[], lookupCap: CapabilityLookup): SlicePatch;