@camstack/system 1.2.390 → 1.2.391

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

@@ -1,137 +1,158 @@
-import { ComposerApplyInput, ComposerApplyResult, ComposerUnreadableBlock, CoreBlock, IScopedLogger } from '@camstack/types';
+/**
+* Converging the running block processes onto the stored blocks.
+*
+* Reconcile against the registry, not one-shot reactions to events: a spawn
+* that was missed because an event was dropped (D8 — events are telemetry) has
+* to be fixed by the next pass, and an operator restarting the hub must end up
+* with exactly the blocks the store says are enabled. So `converge()` is
+* idempotent and safe to call from a timer, from a write, and from boot.
+*
+* **The supervision itself is not in this file, and that is deliberate.** A
+* block that never returns is bounded by `process-service`'s `CrashSupervisor`
+* (D6) — the same circuit-breaker that bounds every addon. This class only
+* decides which runners should exist and translates their state back into
+* something the author can read. Re-implementing backoff here would be a second
+* supervisor to keep in step with the first.
+*
+* The invariant it exists to hold: **a block that is not running says why.**
+* Every path out of `converge()` that does not end in a live process writes a
+* status the operator can see, with the reason attached. A block that is
+* silently absent is the failure mode this whole feature has to avoid.
+*/
+import { type ComposerApplyInput, type ComposerApplyResult, type ComposerUnreadableBlock, type CoreBlock, type 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';
+*  are transient states of a runner on its way out and are treated as absent. */
+export type BlockRunnerState = "starting" | "running" | "stopping" | "stopped" | "crashed" | "failed";
 export interface BlockRunnerSnapshot {
-    /** The runner id — equal to the generated addon id for a block runner. */
-    readonly name: string;
-    readonly state: BlockRunnerState;
+	/** The runner id — equal to the generated addon id for a block runner. */
+	readonly name: string;
+	readonly state: BlockRunnerState;
 }
 /**
- * The process plane, narrowed to the three things a block needs.
- *
- * Injected rather than reached for, so the decision logic above is testable
- * without a broker — and so the day a block runs on an agent, only this
- * implementation changes.
- */
+* The process plane, narrowed to the three things a block needs.
+*
+* Injected rather than reached for, so the decision logic above is testable
+* without a broker — and so the day a block runs on an agent, only this
+* implementation changes.
+*/
 export interface BlockProcessHost {
-    list(): Promise<readonly BlockRunnerSnapshot[]>;
-    spawn(input: {
-        runnerId: string;
-        addonId: string;
-        addonDir: string;
-    }): Promise<void>;
-    stop(runnerId: string): Promise<void>;
+	list(): Promise<readonly BlockRunnerSnapshot[]>;
+	spawn(input: {
+		runnerId: string;
+		addonId: string;
+		addonDir: string;
+	}): Promise<void>;
+	stop(runnerId: string): Promise<void>;
 }
 export interface BlockCompileOutcome {
-    readonly ok: boolean;
-    readonly error?: string;
-    readonly js?: string;
+	readonly ok: boolean;
+	readonly error?: string;
+	readonly js?: string;
 }
 export interface BlockCompileSource {
-    readonly code: string;
-    readonly files?: Readonly<Record<string, string>>;
-    readonly entry?: string;
+	readonly code: string;
+	readonly files?: Readonly<Record<string, string>>;
+	readonly entry?: string;
 }
 /** The composer's one verb, as the supervisor needs it. */
 export interface ComposerPort {
-    apply(input: ComposerApplyInput): Promise<ComposerApplyResult>;
+	apply(input: ComposerApplyInput): Promise<ComposerApplyResult>;
 }
 export interface BlockSupervisorDeps {
-    /** This node's id, already stripped of any `/<addon>` runner suffix. */
-    readonly nodeId: string;
-    /** Where block packages are materialised — one directory per block. */
-    readonly root: string;
-    readonly store: BlockStoreView;
-    readonly host: BlockProcessHost;
-    readonly compile: (source: BlockCompileSource) => 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>;
+	/** This node's id, already stripped of any `/<addon>` runner suffix. */
+	readonly nodeId: string;
+	/** Where block packages are materialised — one directory per block. */
+	readonly root: string;
+	readonly store: BlockStoreView;
+	readonly host: BlockProcessHost;
+	readonly compile: (source: BlockCompileSource) => 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>;
+	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 {
-    private readonly deps;
-    /**
-     * `blockId → updatedAt` of the source this supervisor last materialised.
-     * The only way to know a running block is running YESTERDAY'S code: the
-     * process is alive either way, and nothing on disk carries the version.
-     * In-memory is correct — a hub restart takes every child with it.
-     */
-    private readonly materialized;
-    private timer;
-    /** 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;
-    stop(): void;
-    /** One reconcile pass. Never throws — a pass that failed must not stop the
-     *  next one, and the reason belongs in the log, not in a rejected promise
-     *  nobody awaits. */
-    converge(): Promise<void>;
-    /**
-     * Stop one block's runner and let the pass that follows bring it back.
-     *
-     * The same path a code change already takes (see `stale` in `reconcile`),
-     * exposed on purpose. It writes NO state of its own: forgetting the
-     * materialised `updatedAt` is what makes the next pass treat the block as
-     * needing a launch, and that pass is still the authority — so a restart that
-     * raced a converge ends with one runner, not two.
-     *
-     * Queued on the same chain as `converge()`: a restart that interleaved with a
-     * timer tick could stop a runner the tick had just decided was healthy and
-     * then never re-launch it.
-     */
-    restart(blockId: string): Promise<void>;
-    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. */
-    private launch;
-    private reportRunnerState;
-    /**
-     * Write a status only when it actually changed.
-     *
-     * A reconcile pass runs on a timer, and every write rewrites the row AND
-     * moves `lastChangedAt` — which is the only thing telling an operator WHEN a
-     * block last did something. Rewriting it every tick would make it read as
-     * "just now", forever.
-     */
-    private report;
-    private isPlacedHere;
-    private stopReason;
+	private readonly deps;
+	/**
+	* `blockId → updatedAt` of the source this supervisor last materialised.
+	* The only way to know a running block is running YESTERDAY'S code: the
+	* process is alive either way, and nothing on disk carries the version.
+	* In-memory is correct — a hub restart takes every child with it.
+	*/
+	private readonly materialized;
+	private timer;
+	/** 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;
+	stop(): void;
+	/** One reconcile pass. Never throws — a pass that failed must not stop the
+	*  next one, and the reason belongs in the log, not in a rejected promise
+	*  nobody awaits. */
+	converge(): Promise<void>;
+	/**
+	* Stop one block's runner and let the pass that follows bring it back.
+	*
+	* The same path a code change already takes (see `stale` in `reconcile`),
+	* exposed on purpose. It writes NO state of its own: forgetting the
+	* materialised `updatedAt` is what makes the next pass treat the block as
+	* needing a launch, and that pass is still the authority — so a restart that
+	* raced a converge ends with one runner, not two.
+	*
+	* Queued on the same chain as `converge()`: a restart that interleaved with a
+	* timer tick could stop a runner the tick had just decided was healthy and
+	* then never re-launch it.
+	*/
+	restart(blockId: string): Promise<void>;
+	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. */
+	private launch;
+	private reportRunnerState;
+	/**
+	* Write a status only when it actually changed.
+	*
+	* A reconcile pass runs on a timer, and every write rewrites the row AND
+	* moves `lastChangedAt` — which is the only thing telling an operator WHEN a
+	* block last did something. Rewriting it every tick would make it read as
+	* "just now", forever.
+	*/
+	private report;
+	private isPlacedHere;
+	private stopReason;
 }

package/dist/builtins/core-blocks/block-type-defs.d.ts

@@ -1,29 +1,29 @@
-import { IScopedLogger } from '@camstack/types';
+import type { IScopedLogger } from "@camstack/types";
 export interface BlockTypeLib {
-    readonly filePath: string;
-    readonly content: string;
+	readonly filePath: string;
+	readonly content: string;
 }
 /**
- * Minimal Node surface for block authorship. Not `@types/node` — that package
- * is a build-time dep and is not in the production closure. This is enough
- * that Save is not refused for the builtins real scripts use (`process`,
- * `node:net`, `node:fs`, `node:path`, `node:http(s)`, `node:crypto`, timers).
- * Widen when a block hits a new missing name; do not paste the full DefinitelyTyped
- * tree into every getTypeDefs response.
- */
+* Minimal Node surface for block authorship. Not `@types/node` — that package
+* is a build-time dep and is not in the production closure. This is enough
+* that Save is not refused for the builtins real scripts use (`process`,
+* `node:net`, `node:fs`, `node:path`, `node:http(s)`, `node:crypto`, timers).
+* Widen when a block hits a new missing name; do not paste the full DefinitelyTyped
+* tree into every getTypeDefs response.
+*/
 export declare const BLOCK_NODE_AMBIENT: string;
 /**
- * Read every declaration a block editor needs: `@camstack/types`, `zod`, and
- * the Node ambient.
- *
- * Best-effort by design: a node that cannot find `@camstack/types` serves an
- * EMPTY types list (plus whatever else resolved), and the editor then registers
- * an empty lib set rather than keeping a stale one — so an author sees "no
- * types" instead of validating against a contract that has moved.
- */
+* Read every declaration a block editor needs: `@camstack/types`, `zod`, and
+* the Node ambient.
+*
+* Best-effort by design: a node that cannot find `@camstack/types` serves an
+* EMPTY types list (plus whatever else resolved), and the editor then registers
+* an empty lib set rather than keeping a stale one — so an author sees "no
+* types" instead of validating against a contract that has moved.
+*/
 export declare function loadBlockTypeDefs(logger: IScopedLogger): Promise<readonly BlockTypeLib[]>;
 /**
- * Resolve a package's directory that holds `index.d.ts` (the types dist root).
- * Exported for the test that pins createRequire-over-cwd.
- */
+* Resolve a package's directory that holds `index.d.ts` (the types dist root).
+* Exported for the test that pins createRequire-over-cwd.
+*/
 export declare function resolveTypesDist(): Promise<string | null>;

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

@@ -1,62 +1,89 @@
-import { DeclaredDevicePorts, IScopedLogger } from '@camstack/types';
+/**
+* The integration every block's devices hang from.
+*
+* ## Why it is not the block's own
+*
+* A core block CANNOT own an integration, and the failure was silent and
+* accumulating. Every integration READ is gated on the installed-addon set
+* (`addon-registry.service.ts` → `createFilteredRegistry`), and a block's addon
+* id — `core-block-<uuid>` — is never in that set: a block is materialised and
+* spawned, not installed. So `getIntegrationByAddonId` answered `null` forever
+* while `createIntegration` succeeded, and every block start minted a fresh row
+* that `listIntegrations` then hid and `integrations.delete` refused to remove.
+* Measured on the live hub 2026-08-09: `int_0021` and `int_0022`, two starts of
+* one block, invisible and undeletable through the API.
+*
+* `core-blocks` is an installed builtin, so it passes the filter. It reconciles
+* ONE integration; a block names that integration by id
+* (`DeclaredDevicesSpec.integrationId`) and mints nothing. Ownership of the
+* DEVICE is untouched — that is `(addonId, stableId)`, and `listOwnDevices`
+* stays addon-scoped, which is what keeps one block's withdrawal sweep away
+* from another block's devices now that the integration no longer distinguishes
+* them.
+*
+* The block-side read is
+* `ctx.api.integrations.getByAddonId.query({ addonId: CORE_BLOCKS_ADDON_ID })`
+* — legal, because `core-blocks` is installed. No new cap method is needed.
+*/
+import { type DeclaredDevicePorts, type IScopedLogger } from "@camstack/types";
 /** Operator-visible name of the shared integration. Seeded once, at create. */
 export declare const BLOCKS_INTEGRATION_NAME = "Blocks";
 /**
- * The declared-device ports minus the owner — `reconcileBlocksIntegration`
- * pins that itself, because getting it wrong is the entire bug above.
- */
-export type BlocksIntegrationPorts = Omit<DeclaredDevicePorts, 'addonId'>;
+* The declared-device ports minus the owner — `reconcileBlocksIntegration`
+* pins that itself, because getting it wrong is the entire bug above.
+*/
+export type BlocksIntegrationPorts = Omit<DeclaredDevicePorts, "addonId">;
 /**
- * Reconcile the shared integration. Idempotent; safe on every boot.
- *
- * Returns its id, or `null` when this node does not own the declaration (it is
- * hub-owned, like every declaration).
- *
- * **The trap, stated where it lives:** `devices: []` makes every row the index
- * returns under this integration a withdrawal candidate. That is safe ONLY
- * because `listOwnDevices` is scoped to `core-blocks` and a block's devices are
- * owned by `core-block-<uuid>` — so the listing is empty. Two ways to destroy
- * that: wire `listOwnDevices` without its owner filter (it would then answer
- * 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`.
- */
+* Reconcile the shared integration. Idempotent; safe on every boot.
+*
+* Returns its id, or `null` when this node does not own the declaration (it is
+* hub-owned, like every declaration).
+*
+* **The trap, stated where it lives:** `devices: []` makes every row the index
+* returns under this integration a withdrawal candidate. That is safe ONLY
+* because `listOwnDevices` is scoped to `core-blocks` and a block's devices are
+* owned by `core-block-<uuid>` — so the listing is empty. Two ways to destroy
+* that: wire `listOwnDevices` without its owner filter (it would then answer
+* 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. */
 export interface ArmBlocksIntegrationOptions {
-    readonly logger: IScopedLogger;
-    readonly reconcile: () => Promise<string | null>;
-    readonly onLanded: (integrationId: string | null) => void;
-    readonly retryDelayMs?: number;
-    readonly maxAttempts?: number;
+	readonly logger: IScopedLogger;
+	readonly reconcile: () => Promise<string | null>;
+	readonly onLanded: (integrationId: string | null) => void;
+	readonly retryDelayMs?: number;
+	readonly maxAttempts?: number;
 }
 /** A reconcile running in the background, and a handle to await in tests. */
 export interface ArmedBlocksIntegration {
-    readonly settled: Promise<void>;
+	readonly settled: Promise<void>;
 }
 /**
- * Arm the shared integration WITHOUT putting it on the boot path (D167).
- *
- * `integrations` is a hub-core namespace served by the `$core-caps` Moleculer
- * service, and that service is registered only after `app.init()` returns —
- * which is where the entire addon boot runs. During boot the read is therefore
- * not slow, it is unanswerable: it burns the full 30 s discovery deadline and
- * fast-fails, with no boot-window retry (core caps are excluded from it).
- *
- * Awaited inside `onInitialize()`, that 30 s sat on the hub's SERIAL in-process
- * builtin loop and delayed `device-manager` — which every provider runner waits
- * on before it may publish a single capability. Measured 2026-08-15: builtins
- * stalled t0+10 s → t0+40 s, and the first camera's first keyframe landed at
- * t0+75 s.
- *
- * So: arm it, let boot finish, and let the retry land it a few seconds later. A
- * block that declares a device before it lands finds `null` and gets the
- * integration on the next converge tick — which was already the documented
- * behaviour when the API was unavailable.
- */
+* Arm the shared integration WITHOUT putting it on the boot path (D167).
+*
+* `integrations` is a hub-core namespace served by the `$core-caps` Moleculer
+* service, and that service is registered only after `app.init()` returns —
+* which is where the entire addon boot runs. During boot the read is therefore
+* not slow, it is unanswerable: it burns the full 30 s discovery deadline and
+* fast-fails, with no boot-window retry (core caps are excluded from it).
+*
+* Awaited inside `onInitialize()`, that 30 s sat on the hub's SERIAL in-process
+* builtin loop and delayed `device-manager` — which every provider runner waits
+* on before it may publish a single capability. Measured 2026-08-15: builtins
+* stalled t0+10 s → t0+40 s, and the first camera's first keyframe landed at
+* t0+75 s.
+*
+* So: arm it, let boot finish, and let the retry land it a few seconds later. A
+* block that declares a device before it lands finds `null` and gets the
+* integration on the next converge tick — which was already the documented
+* behaviour when the API was unavailable.
+*/
 export declare function armBlocksIntegration(options: ArmBlocksIntegrationOptions): ArmedBlocksIntegration;

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

@@ -1,52 +1,52 @@
-import { CoreBlockCompileResult, DEFAULT_CORE_BLOCK_ENTRY } from '@camstack/types';
+import { type CoreBlockCompileResult, DEFAULT_CORE_BLOCK_ENTRY } from "@camstack/types";
 /** The esbuild surface this needs — injected so the compile is testable and so
- *  the kernel does not hard-depend on a bundler at import time. */
+*  the kernel does not hard-depend on a bundler at import time. */
 export interface BlockTranspiler {
-    transform(code: string, options: {
-        loader: 'ts';
-        format: 'esm';
-        target: string;
-    }): Promise<{
-        code: string;
-    }>;
-    /**
-     * Multi-file bundle. Absent on a node that only got `transform` (tests that
-     * never exercise files); then a files compile answers "unavailable".
-     */
-    build?(options: BlockBundleOptions): Promise<BlockBundleResult>;
+	transform(code: string, options: {
+		loader: "ts";
+		format: "esm";
+		target: string;
+	}): Promise<{
+		code: string;
+	}>;
+	/**
+	* Multi-file bundle. Absent on a node that only got `transform` (tests that
+	* never exercise files); then a files compile answers "unavailable".
+	*/
+	build?(options: BlockBundleOptions): Promise<BlockBundleResult>;
 }
 export interface BlockBundleOptions {
-    readonly absWorkingDir: string;
-    readonly entryPoints: readonly string[];
-    readonly outfile: string;
-    readonly bundle: true;
-    readonly format: 'esm';
-    readonly platform: 'node';
-    readonly target: string;
-    readonly write: true;
-    readonly logLevel: 'silent';
+	readonly absWorkingDir: string;
+	readonly entryPoints: readonly string[];
+	readonly outfile: string;
+	readonly bundle: true;
+	readonly format: "esm";
+	readonly platform: "node";
+	readonly target: string;
+	readonly write: true;
+	readonly logLevel: "silent";
 }
 export interface BlockBundleResult {
-    readonly errors: readonly {
-        text: string;
-        location?: {
-            line: number;
-            column: number;
-        } | null;
-    }[];
+	readonly errors: readonly {
+		text: string;
+		location?: {
+			line: number;
+			column: number;
+		} | null;
+	}[];
 }
 export interface CompileBlockFilesInput {
-    readonly files: Readonly<Record<string, string>>;
-    readonly entry?: string;
+	readonly files: Readonly<Record<string, string>>;
+	readonly entry?: string;
 }
 export type CompileBlockSource = string | CompileBlockFilesInput;
 export interface CompileBlockResult extends CoreBlockCompileResult {
-    /** The emitted JavaScript, when it compiled. */
-    readonly js?: string;
+	/** The emitted JavaScript, when it compiled. */
+	readonly js?: string;
 }
 /**
- * Never throws. A compile failure is an ANSWER — the author needs to read it,
- * and a thrown error at this layer becomes a 500 with the useful part buried.
- */
+* Never throws. A compile failure is an ANSWER — the author needs to read it,
+* and a thrown error at this layer becomes a 500 with the useful part buried.
+*/
 export declare function compileBlock(transpiler: BlockTranspiler, source: CompileBlockSource): Promise<CompileBlockResult>;
 export { DEFAULT_CORE_BLOCK_ENTRY };

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

@@ -1,30 +1,44 @@
-import { CapabilityDefinition, CapabilityLookup, CompositionBlockPatch, CompositionBlockState, CompositionSourceRef, CoreBlock, ICoreBlocksProvider, IScopedLogger } from '@camstack/types';
-import { NamedCompositionInput } from './core-block-store.js';
-import { CompositionDescriptions } from './composition-sources.js';
+/**
+* The composition half of the `core-blocks` provider (D659). Flat methods,
+* spread into the provider: no nested sub-object.
+*
+* Every save is VALIDATED against the live sources, its existing target (read
+* once: slim row + `getBindings`) and every stored composition first; a refusal
+* names each problem by path and reason (D391) and stores nothing. The store's
+* own refusals (not loaded, unknown block, a code block) propagate unchanged —
+* this layer never swallows them.
+*
+* A customization of an existing device (D663) has no name of its own: the
+* server derives it (`customizationBlockName`), refuses one the client sends,
+* and never lets it move to another device. One per device, by block id (S2).
+*/
+import { type CapabilityDefinition, type CapabilityLookup, type CompositionBlockPatch, type CompositionBlockState, type CompositionSourceRef, type CoreBlock, type ICoreBlocksProvider, type IScopedLogger } from "@camstack/types";
+import type { NamedCompositionInput } from "./core-block-store.js";
+import type { CompositionDescriptions } from "./composition-sources.js";
 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: NamedCompositionInput, createdBy: string): Promise<CoreBlock>;
-    updateComposition(blockId: string, patch: CompositionBlockPatch): Promise<CoreBlock>;
+	/** 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: NamedCompositionInput, createdBy: string): Promise<CoreBlock>;
+	updateComposition(blockId: string, patch: CompositionBlockPatch): Promise<CoreBlock>;
 }
 export interface CompositionApiDeps {
-    readonly store: CompositionStoreView;
-    /** One read of every source and every existing target a save names (`describeCompositionSources`). */
-    readonly describe: (sources: readonly CompositionSourceRef[], targets: readonly CompositionSourceRef[]) => Promise<CompositionDescriptions>;
-    readonly lookupCap: CapabilityLookup;
-    readonly composerStates: (blockIds: readonly string[]) => Promise<readonly CompositionBlockState[]>;
-    readonly convergeSoon: () => void;
-    readonly logger: IScopedLogger;
-    /** Every capability definition — the listing is derived from them, never from the registry's live state. */
-    readonly capabilityDefinitions: readonly CapabilityDefinition[];
+	readonly store: CompositionStoreView;
+	/** One read of every source and every existing target a save names (`describeCompositionSources`). */
+	readonly describe: (sources: readonly CompositionSourceRef[], targets: readonly CompositionSourceRef[]) => Promise<CompositionDescriptions>;
+	readonly lookupCap: CapabilityLookup;
+	readonly composerStates: (blockIds: readonly string[]) => Promise<readonly CompositionBlockState[]>;
+	readonly convergeSoon: () => void;
+	readonly logger: IScopedLogger;
+	/** Every capability definition — the listing is derived from them, never from the registry's live state. */
+	readonly capabilityDefinitions: readonly CapabilityDefinition[];
 }
-export type CompositionApi = Pick<ICoreBlocksProvider, 'createComposition' | 'updateComposition' | 'getComposition' | 'listCompositions' | 'validateComposition' | 'getCustomization' | 'listComposableCaps'>;
+export type CompositionApi = Pick<ICoreBlocksProvider, "createComposition" | "updateComposition" | "getComposition" | "listCompositions" | "validateComposition" | "getCustomization" | "listComposableCaps">;
 /**
- * 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.
- */
+* 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;