@camstack/system 1.2.307 → 1.2.309

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

@@ -0,0 +1,103 @@
+import { CapabilityLookup, ComposerApplyInput, ComposerApplyResult, CompositionBlockState, DeviceDeclaration, DeviceType, IScopedLogger } from '@camstack/types';
+import { DeviceStateChangedData } from '../shared/device-state-changed.js';
+import { ComposedDeviceHandle } from './composed-device.js';
+import { PersistedComposedRow } from './composition-declarations.js';
+import { DeadlineTimer } from './composition-runtime.js';
+import { SourceBindingsChangeReason, SourceTracker } from './source-tracker.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;
+}
+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>;
+}
+export interface ComposerDeps {
+    readonly logger: IScopedLogger;
+    readonly tracker: SourceTracker;
+    readonly lookupCap: CapabilityLookup;
+    /** The composed rows that already exist (`listOwnDevices`), read once before the first withdrawal decision. */
+    readonly readPersisted: () => Promise<readonly PersistedComposedRow[]>;
+    readonly declare: (integrationId: string, devices: readonly DeviceDeclaration[]) => Promise<ComposerDeclareResult>;
+    readonly devices: ComposerDevicePorts;
+    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;
+    /** 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;
+    /** Applies never interleave: each one reads and replaces the whole live set. */
+    private applyChain;
+    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>;
+    onDeviceUnregistered(deviceId: number): Promise<void>;
+    onBindingsChanged(data: DeviceBindingsChangedData): Promise<void>;
+    shutdown(): void;
+    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 newRuntime;
+    private applyName;
+    private syncSources;
+    /** A failed sync leaves the tracker as it was: the runtimes read what it holds. */
+    private syncTracker;
+    private dispatch;
+    private tagsOf;
+    private verdict;
+}

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

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

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

@@ -0,0 +1,88 @@
+import { CompositionFieldPlan, CompositionFieldState, ExpressionValue, IScopedLogger, SourceReader } from '@camstack/types';
+export interface WriteOk {
+    readonly ok: true;
+}
+export interface WriteRefused {
+    readonly ok: false;
+    readonly error: string;
+}
+export type WriteOutcome = WriteOk | WriteRefused;
+/**
+ * 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.
+ */
+export interface ComposedWriteTarget {
+    readonly id: number;
+    seed(capName: string, slice: Readonly<Record<string, ExpressionValue>>): WriteOutcome;
+    patch(capName: string, patch: Readonly<Record<string, ExpressionValue>>): WriteOutcome;
+    setAvailable(available: boolean): void;
+}
+export interface DeadlineTimer {
+    arm(at: number, fire: () => void): void;
+    disarm(): void;
+}
+export interface CompositionRuntimeDeps {
+    readonly blockId: string;
+    readonly fields: readonly CompositionFieldPlan[];
+    readonly target: ComposedWriteTarget;
+    readonly read: SourceReader;
+    readonly now: () => number;
+    readonly timer: DeadlineTimer;
+    readonly logger: IScopedLogger;
+}
+export interface CompositionRuntimeState {
+    readonly failure: string | null;
+    readonly available: boolean;
+    readonly fields: readonly CompositionFieldState[];
+}
+export declare class CompositionRuntime {
+    private readonly deps;
+    private records;
+    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;
+    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;
+    /**
+     * 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 evaluate;
+    private recordsOf;
+    /** `retry`: write-pending caps this pass re-writes WHOLE, whether or not a value changed. */
+    private writeCaps;
+    private seedCap;
+    private patchCap;
+    /** After a failed write nothing is known about what landed: send every current value. */
+    private patchWholeCap;
+    private writableEntries;
+    private holdBackSeed;
+    /** One write. A refusal or a throw marks the cap write-pending; true when it landed. */
+    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/deadline-timer.d.ts

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

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

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

package/dist/builtins/composer/index.js

@@ -0,0 +1,8 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Cek0wNdY.js");
+const require_builtins_composer_composer_addon = require("./composer.addon.js");
+exports.ComposerAddon = require_builtins_composer_composer_addon.ComposerAddon;
+exports.default = require_builtins_composer_composer_addon.ComposerAddon;

package/dist/builtins/composer/index.mjs

@@ -0,0 +1,2 @@
+import { ComposerAddon } from "./composer.addon.mjs";
+export { ComposerAddon, ComposerAddon as default };

package/dist/builtins/composer/source-tracker.d.ts

@@ -0,0 +1,78 @@
+import { CompositionFieldRead, CompositionSourceRef, EventCatalog, IScopedLogger, SourceReading } from '@camstack/types';
+export interface SourceRow {
+    readonly id: number;
+    readonly stableId: string;
+}
+export interface SourceRowsRead {
+    readonly kind: 'rows';
+    readonly rows: readonly SourceRow[];
+}
+export interface SourceUnreadable {
+    readonly kind: 'unreadable';
+    readonly error: string;
+}
+export type SourceListRead = SourceRowsRead | SourceUnreadable;
+export interface SliceFound {
+    readonly kind: 'slice';
+    readonly slice: Readonly<Record<string, unknown>>;
+}
+export interface SliceNone {
+    readonly kind: 'none';
+}
+export type SliceRead = SliceFound | SliceNone | SourceUnreadable;
+export interface BoundCaps {
+    readonly kind: 'caps';
+    readonly caps: ReadonlySet<string>;
+}
+export type BoundCapsRead = BoundCaps | SourceUnreadable;
+export interface SourceTrackerPorts {
+    readonly logger: IScopedLogger;
+    /** `deviceManager.listAll({ addonId, projection: 'slim' })`: one call per owning addon per pass. */
+    readonly listDevicesOf: (addonId: string) => Promise<SourceListRead>;
+    readonly readSlice: (deviceId: number, capName: string) => Promise<SliceRead>;
+    readonly readBoundCaps: (deviceId: number) => Promise<BoundCapsRead>;
+}
+/** Why a `device.bindings-changed` fired — the catalog's own closed union. */
+export type SourceBindingsChangeReason = EventCatalog['device.bindings-changed']['reason'];
+export interface TrackedSourceRequest {
+    readonly ref: CompositionSourceRef;
+    readonly caps: readonly string[];
+}
+export declare class SourceTracker {
+    private readonly ports;
+    private sources;
+    /** The one chain every entry point joins (R3); the pattern is `BlockSupervisor.inFlight`. */
+    private chain;
+    constructor(ports: SourceTrackerPorts);
+    /**
+     * Track exactly `requests`. Hydrate what is new or unresolved; keep what is
+     * known. `reset` names source keys an OPERATOR action re-opens (a block edit
+     * or restart): only those lose a sticky `missing`.
+     */
+    sync(requests: readonly TrackedSourceRequest[], reset: ReadonlySet<string>): Promise<ReadonlySet<string>>;
+    onStateChanged(deviceId: number, capName: string, slice: Readonly<Record<string, unknown>>): Promise<ReadonlySet<string>>;
+    onDeviceUnregistered(deviceId: number): Promise<ReadonlySet<string>>;
+    onBindingsChanged(deviceId: number, capName: string, reason: SourceBindingsChangeReason): Promise<ReadonlySet<string>>;
+    /** Run `work` after everything already queued, whether that settled or failed; never let one failure stall the chain. */
+    private serialized;
+    private syncNow;
+    read(read: CompositionFieldRead): SourceReading;
+    private applyStateChanged;
+    private confirmUnregistered;
+    private applyBindingsChanged;
+    /** A source found under a NEW id is a re-registration: read it there now (R7c). */
+    private rereadUnderNewId;
+    private hydrate;
+    /** Read `toRead` (bindings first, then slices); every other requested cap keeps what `known` holds. */
+    private readCaps;
+    private resolveConfirmed;
+    /**
+     * One bindings read. A second one would not confirm anything: back to back
+     * they are one correlated read, and "unbound" no longer destroys work — it is
+     * a non-fatal `none` that `native-registered` heals.
+     */
+    private readBindings;
+    private readCap;
+    private logHealed;
+    private readOnline;
+}

package/dist/builtins/console-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-D3ch99WD.js");
+const require_dist = require("../../dist-BhO9eYKO.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 //#region src/builtins/console-logging/console-destination.ts
 var LEVEL_RANK = {

package/dist/builtins/console-logging/index.mjs

@@ -1,4 +1,4 @@
-import { gn as BaseAddon, jt as logDestinationCapability } from "../../dist-DdfJa8Zn.mjs";
+import { Ut as logDestinationCapability, jn as BaseAddon } from "../../dist-BEuQPDk_.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 //#region src/builtins/console-logging/console-destination.ts
 var LEVEL_RANK = {

package/dist/builtins/core-blocks/block-supervisor.d.ts

@@ -1,4 +1,4 @@
-import { CoreBlock, IScopedLogger } from '@camstack/types';
+import { ComposerApplyInput, ComposerApplyResult, ComposerUnreadableBlock, CoreBlock, IScopedLogger } from '@camstack/types';
 /** The runner lifecycle states `$process.list` reports. `stopping`/`stopped`
  *  are transient states of a runner on its way out and are treated as absent. */
 export type BlockRunnerState = 'starting' | 'running' | 'stopping' | 'stopped' | 'crashed' | 'failed';
@@ -28,6 +28,10 @@ export interface BlockCompileOutcome {
     readonly error?: string;
     readonly js?: string;
 }
+/** The composer's one verb, as the supervisor needs it. */
+export interface ComposerPort {
+    apply(input: ComposerApplyInput): Promise<ComposerApplyResult>;
+}
 export interface BlockSupervisorDeps {
     /** This node's id, already stripped of any `/<addon>` runner suffix. */
     readonly nodeId: string;
@@ -37,11 +41,21 @@ export interface BlockSupervisorDeps {
     readonly host: BlockProcessHost;
     readonly compile: (code: string) => Promise<BlockCompileOutcome>;
     readonly logger: IScopedLogger;
+    /** Null when this node exposes no composer, and then every composition says so. */
+    readonly composer: ComposerPort | null;
+    /** The shared Blocks integration, null until it has reconciled. */
+    readonly integrationId: () => string | null;
+    /** False while the `core_blocks` read has not succeeded — the composer then withdraws nothing (D49). */
+    readonly storeLoaded: () => boolean;
+    /** Re-read `core_blocks`. Called by a converge while `storeLoaded()` is false — the converge IS the retry (D3). Never throws. */
+    readonly loadStore: () => Promise<void>;
 }
 /** The slice of `CoreBlockStore` the supervisor uses. */
 export interface BlockStoreView {
     list(): readonly CoreBlock[];
     get(blockId: string): CoreBlock | null;
+    /** Stored composition rows that do not parse: sent to the composer so their devices are held (D49). */
+    unreadableCompositions(): readonly ComposerUnreadableBlock[];
     setStatus(blockId: string, status: CoreBlock['status'], error?: string): Promise<void>;
 }
 export declare class BlockSupervisor {
@@ -57,6 +71,16 @@ export declare class BlockSupervisor {
     /** Serialises passes so a timer tick cannot interleave with a write-driven
      *  converge and spawn the same runner twice. */
     private inFlight;
+    /** Composition restarts not yet delivered to the composer. Stores nothing durable (D62). */
+    private pendingCompositionRestarts;
+    /**
+     * Empty applies still owed: the composer withdraws only after TWO agree
+     * (D49), and a boot sends one. Only an apply the composer says it ACTED on
+     * (`result.acted`) pays one off — it can refuse with the store loaded.
+     */
+    private emptyAppliesOwed;
+    /** Consecutive applies that could not reach the composer: warned once per run. */
+    private failedApplies;
     constructor(deps: BlockSupervisorDeps);
     /** Start the reconcile timer. The first pass runs immediately. */
     start(intervalMs: number): void;
@@ -82,6 +106,13 @@ export declare class BlockSupervisor {
     private runRestart;
     private runPass;
     private reconcile;
+    /**
+     * Send every composition placed here to the composer and mirror its verdicts
+     * into the block status, reason verbatim. A `starting` verdict (the composer
+     * does not trust its store or seed yet) is mirrored as `starting`; the next
+     * pass of this same converge is the retry — no timer of its own (D3).
+     */
+    private convergeCompositions;
     /** Compile, write the package, spawn. Each failure is reported ON the block
      *  — the author asked for this to run, so they are owed the reason it does
      *  not. */

package/dist/builtins/core-blocks/blocks-integration.d.ts

@@ -20,6 +20,11 @@ export type BlocksIntegrationPorts = Omit<DeclaredDevicePorts, 'addonId'>;
  * with every device on the cluster, and the sweep would delete the blocks'), or
  * make `core-blocks` declare a device of its own. Neither is worth the
  * convenience; the spec test pins both.
+ *
+ * A SECOND owner hangs devices here since D659: `composer` (every composed
+ * device). It is equally safe for the same reason — its rows are owned by
+ * `composer`, never by `core-blocks`, and its own withdrawal sweep is scoped to
+ * `composer`.
  */
 export declare function reconcileBlocksIntegration(ports: BlocksIntegrationPorts): Promise<string | null>;
 /** What {@link armBlocksIntegration} needs, and the seam its spec drives. */

package/dist/builtins/core-blocks/composition-api.d.ts

@@ -0,0 +1,25 @@
+import { CapabilityLookup, CompositionBlockInput, CompositionBlockPatch, CompositionBlockState, CompositionSourceDescription, CompositionSourceRef, CoreBlock, ICoreBlocksProvider, IScopedLogger } from '@camstack/types';
+export interface CompositionStoreView {
+    /** False until the table has been READ; a verdict against an empty peer set would hide a cycle. */
+    isLoaded(): boolean;
+    list(): readonly CoreBlock[];
+    get(blockId: string): CoreBlock | null;
+    createComposition(input: CompositionBlockInput, createdBy: string): Promise<CoreBlock>;
+    updateComposition(blockId: string, patch: CompositionBlockPatch): Promise<CoreBlock>;
+}
+export interface CompositionApiDeps {
+    readonly store: CompositionStoreView;
+    readonly describeSources: (refs: readonly CompositionSourceRef[]) => Promise<ReadonlyMap<string, CompositionSourceDescription>>;
+    readonly lookupCap: CapabilityLookup;
+    readonly composerStates: (blockIds: readonly string[]) => Promise<readonly CompositionBlockState[]>;
+    readonly convergeSoon: () => void;
+    readonly logger: IScopedLogger;
+}
+export type CompositionApi = Pick<ICoreBlocksProvider, 'createComposition' | 'updateComposition' | 'getComposition' | 'listCompositions' | 'validateComposition'>;
+/**
+ * Every write runs validate-then-persist on ONE chain. Validation awaits a
+ * source read before the save lands; two unserialized saves (A reads B, B
+ * reads A) would each be judged against a store without the other and BOTH
+ * pass — a stored cycle nothing downstream catches.
+ */
+export declare function buildCompositionApi(deps: CompositionApiDeps): CompositionApi;

package/dist/builtins/core-blocks/composition-sources.d.ts

@@ -0,0 +1,10 @@
+import { CompositionSourceDescription, CompositionSourceRef } from '@camstack/types';
+export interface SourceRowView {
+    readonly id: number;
+    readonly stableId: string;
+}
+export interface CompositionSourcePorts {
+    readonly listByAddon: (addonId: string) => Promise<readonly SourceRowView[]>;
+    readonly boundCaps: (deviceId: number) => Promise<readonly string[]>;
+}
+export declare function describeCompositionSources(ports: CompositionSourcePorts, refs: readonly CompositionSourceRef[]): Promise<ReadonlyMap<string, CompositionSourceDescription>>;

package/dist/builtins/core-blocks/core-block-store.d.ts

@@ -1,4 +1,4 @@
-import { CoreBlock, CoreBlockInput, IScopedLogger, SettingsStoreClient } from '@camstack/types';
+import { ComposerUnreadableBlock, CompositionBlockInput, CompositionBlockPatch, CoreBlock, CoreBlockInput, IScopedLogger, SettingsStoreClient } from '@camstack/types';
 /**
  * @durable class=config owner=core-blocks
  *   write="`create` and `update` persist the operator's block after it compiles;
@@ -41,6 +41,12 @@ export declare const CORE_BLOCKS_INDEXES: readonly [{
     readonly name: "idx_core_blocks_enabled";
     readonly columns: readonly ["enabled"];
 }];
+/**
+ * Rows one read asks for. A read that ANSWERS this many is not a loaded table:
+ * rows past the limit would be absent, and an absent composition reads as a
+ * deleted one (D49).
+ */
+export declare const CORE_BLOCKS_LOAD_LIMIT = 1000;
 export interface CoreBlockStoreDeps {
     readonly store: SettingsStoreClient;
     readonly logger: IScopedLogger;
@@ -49,18 +55,32 @@ export interface CoreBlockStoreDeps {
 }
 export declare class CoreBlockStore {
     private readonly byId;
+    /** Rows that exist but do not parse and may be compositions — held for the composer, never dropped (D49). */
+    private unreadable;
     private readonly store;
     private readonly logger;
     private readonly now;
     private readonly newId;
+    private loaded;
+    /** Consecutive failed reads — the warn is once per run of them, not once per retry. */
+    private failedLoads;
     constructor(deps: CoreBlockStoreDeps);
     static declare(store: SettingsStoreClient): Promise<void>;
+    /** True only after a `load()` that READ the table. The composer withdraws nothing otherwise (D49). */
+    isLoaded(): boolean;
+    /** Stored composition rows that do not parse, by id — the composer holds their devices. */
+    unreadableCompositions(): readonly ComposerUnreadableBlock[];
     /**
      * Hydrate every block.
      *
      * A row whose JSON no longer validates is SKIPPED with a warning rather than
      * dropped or repaired: it is somebody's code, and the honest answer to "I
-     * cannot read this" is to leave it on disk and say so.
+     * cannot read this" is to leave it on disk and say so. A skipped row that may
+     * be a COMPOSITION is also kept in `unreadableCompositions()`: absent from the
+     * composer's input it would read as deleted, and its device would go (D49).
+     *
+     * `source` is parsed here, and a build older than D659 strips `source` and
+     * rewrites the row — rolling back below D659 erases compositions.
      */
     load(): Promise<void>;
     list(): readonly CoreBlock[];
@@ -70,6 +90,13 @@ export declare class CoreBlockStore {
     create(input: CoreBlockInput, createdBy: string): Promise<CoreBlock>;
     /** Apply a partial patch. Immutable: returns the NEW block. */
     update(blockId: string, patch: Partial<CoreBlockInput>): Promise<CoreBlock>;
+    /**
+     * Store a composition block (D659): hub-placed, no code, never `running` on
+     * creation — the composer's verdict, mirrored by the supervisor, says that.
+     */
+    createComposition(input: CompositionBlockInput, createdBy: string): Promise<CoreBlock>;
+    /** Patch a composition block. Immutable: returns the NEW block. Refuses a code block by name. */
+    updateComposition(blockId: string, patch: CompositionBlockPatch): Promise<CoreBlock>;
     /**
      * Record what the runner did with this block.
      *
@@ -78,6 +105,11 @@ export declare class CoreBlockStore {
      * a block is running because somebody renamed it.
      */
     setStatus(blockId: string, status: CoreBlock['status'], error?: string): Promise<void>;
+    /**
+     * A write before the table has been read would be wiped from memory by the
+     * load that follows (it clears and refills), so it is refused by name.
+     */
+    private requireLoaded;
     /** Idempotent delete — an unknown id is a no-op. */
     delete(blockId: string): Promise<void>;
     private persist;

package/dist/builtins/core-blocks/core-blocks.addon.d.ts

@@ -55,5 +55,11 @@ export declare class CoreBlocksAddon extends BaseAddon {
      */
     private gate;
     private buildProvider;
+    /**
+     * The composition methods (D659), flat. Sources are read over `ctx.api` at
+     * SAVE time — one listing per owning addon, one binding read per found
+     * device — and a read that fails refuses the save rather than skipping it.
+     */
+    private buildCompositionApi;
 }
 export type { CoreBlock };