@camstack/system 1.2.390 → 1.2.391

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

@@ -1,8 +1,30 @@
-import { CapabilityLookup, CompositionPeer, CompositionSourceRef, CompositionTargetDescription, CoreBlock } from '@camstack/types';
+/**
+* The stored compositions a save is judged against, as graph peers (D663,
+* ruling S2). Each is identified by its BLOCK ID, targets the device it writes
+* — `composedDeviceRef(block.id)` for a new device, the customized device for an
+* existing one — and, on an existing device, names the fields it REPLACES, so
+* its self-read of a replaced field is the native value and never an edge.
+*
+* `replaced` is not stored anywhere: it is recomputed at save time from the
+* peer's target description (`planComposition(..., target)`), read in the same
+* batch as the candidate's. A peer whose device could not be read has unknown
+* replaced fields: it is OVER-approximated — nothing replaced, every self-read
+* an edge (edges only added, never a cycle hidden) — and its device is listed
+* in `unread`, so the validator refuses a cyclic component only when it holds
+* a candidate node, and names the device (`findCandidateCycles`). An unreadable
+* device never blocks an unrelated save. A peer whose device is GONE is treated
+* the same way (M-1): a stored peer validated earlier may still read it, and
+* assuming every field replaced would remove edges.
+*
+* The candidate's own old version is kept in the list: the graph drops it BY ID
+* (`compositionEdges`), never by target — that is how a second block on
+* the same device reaches `duplicate-target`.
+*/
+import { type CapabilityLookup, type CompositionPeer, type CompositionSourceRef, type CompositionTargetDescription, type CoreBlock } from "@camstack/types";
 export interface StoredPeers {
-    readonly peers: readonly CompositionPeer[];
-    /** `compositionSourceKey` → why, for each OTHER stored customization whose device could not be read. */
-    readonly unread: ReadonlyMap<string, string>;
+	readonly peers: readonly CompositionPeer[];
+	/** `compositionSourceKey` → why, for each OTHER stored customization whose device could not be read. */
+	readonly unread: ReadonlyMap<string, string>;
 }
 /** The existing devices the stored customizations write — each read once with the candidate's. */
 export declare function storedCustomizationTargets(blocks: readonly CoreBlock[]): readonly CompositionSourceRef[];

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

@@ -1,22 +1,37 @@
-import { CompositionSourceDescription, CompositionSourceRef, CompositionTargetDescription, DeviceType } from '@camstack/types';
+/**
+* Describe what a composition reads and writes for SAVE-time validation
+* (D659, D663): one `listAll` per owning addon, one `getBindings` per found
+* device — shared by a device that is both a source and a target. A read that
+* fails makes the device `unreadable`, and the save is REFUSED rather than
+* stored unchecked. Refusing a save destroys nothing (D49).
+*
+* A SOURCE is described by the caps bound to it; an EXISTING TARGET by its row
+* type and each bound cap with the addon serving it — what `planComposition`
+* needs to tell a replace from an add (the composer reads it the same way, from
+* the same two reads: the slim row and `getBindings`).
+*
+* Devices are keyed by `{addonId, stableId}` — never a numeric device id,
+* which is this node's allocation and not the composition's identity.
+*/
+import { type CompositionSourceDescription, type CompositionSourceRef, type CompositionTargetDescription, type DeviceType } from "@camstack/types";
 export interface SourceRowView {
-    readonly id: number;
-    readonly stableId: string;
-    readonly type: DeviceType;
+	readonly id: number;
+	readonly stableId: string;
+	readonly type: DeviceType;
 }
 /** One `getBindings` entry: the cap, and the addon serving it natively. */
 export interface BoundCapView {
-    readonly capName: string;
-    readonly nativeAddonId?: string | null;
+	readonly capName: string;
+	readonly nativeAddonId?: string | null;
 }
 export interface CompositionSourcePorts {
-    readonly listByAddon: (addonId: string) => Promise<readonly SourceRowView[]>;
-    readonly bindings: (deviceId: number) => Promise<readonly BoundCapView[]>;
+	readonly listByAddon: (addonId: string) => Promise<readonly SourceRowView[]>;
+	readonly bindings: (deviceId: number) => Promise<readonly BoundCapView[]>;
 }
 /** Every device a save reads, described once. Both maps are keyed by `compositionSourceKey`. */
 export interface CompositionDescriptions {
-    readonly sources: ReadonlyMap<string, CompositionSourceDescription>;
-    readonly targets: ReadonlyMap<string, CompositionTargetDescription>;
+	readonly sources: ReadonlyMap<string, CompositionSourceDescription>;
+	readonly targets: ReadonlyMap<string, CompositionTargetDescription>;
 }
 /** Blank binding owners are not native providers and must not turn ADD into REPLACE. */
 export declare function normalizedNativeOwner(owner: string | null | undefined): string | null;

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

@@ -1,128 +1,128 @@
-import { ComposerUnreadableBlock, CompositionBlockInput, CompositionBlockPatch, CoreBlock, CoreBlockInput, IScopedLogger, SettingsStoreClient } from '@camstack/types';
+import type { ComposerUnreadableBlock, CompositionBlockInput, CompositionBlockPatch, CoreBlock, CoreBlockInput, IScopedLogger, SettingsStoreClient } from "@camstack/types";
 /**
- * A composition block as the store keeps it: always NAMED. A customization's
- * client input carries no name — the API derives it before the store sees it (D663).
- */
+* A composition block as the store keeps it: always NAMED. A customization's
+* client input carries no name — the API derives it before the store sees it (D663).
+*/
 export interface NamedCompositionInput extends CompositionBlockInput {
-    readonly name: string;
+	readonly name: string;
 }
 /**
- * @durable class=config owner=core-blocks
- *   write="`create` and `update` persist the operator's block after it compiles;
- *     `setStatus` rewrites what the runner reported (status, `lastChangedAt`,
- *     `lastError`) — so a running block is written on every state change"
- *   retention="`delete` only, when the operator removes a block. Nothing ages out,
- *     and a row whose JSON stops validating is left on disk rather than repaired.
- *     The real loss path is a `declareCollection` REBUILD — a legacy (id, data)
- *     shape, or a new PK/UNIQUE/NOT-NULL-without-default column — which drops the
- *     table and takes the operator's source code with it."
- */
+* @durable class=config owner=core-blocks
+*   write="`create` and `update` persist the operator's block after it compiles;
+*     `setStatus` rewrites what the runner reported (status, `lastChangedAt`,
+*     `lastError`) — so a running block is written on every state change"
+*   retention="`delete` only, when the operator removes a block. Nothing ages out,
+*     and a row whose JSON stops validating is left on disk rather than repaired.
+*     The real loss path is a `declareCollection` REBUILD — a legacy (id, data)
+*     shape, or a new PK/UNIQUE/NOT-NULL-without-default column — which drops the
+*     table and takes the operator's source code with it."
+*/
 export declare const CORE_BLOCKS_COLLECTION = "core_blocks";
 export declare const CORE_BLOCKS_COLUMNS: readonly [{
-    readonly name: "id";
-    readonly type: "TEXT";
-    readonly primaryKey: true;
-    readonly notNull: true;
+	readonly name: "id";
+	readonly type: "TEXT";
+	readonly primaryKey: true;
+	readonly notNull: true;
 }, {
-    readonly name: "name";
-    readonly type: "TEXT";
-    readonly notNull: true;
+	readonly name: "name";
+	readonly type: "TEXT";
+	readonly notNull: true;
 }, {
-    readonly name: "enabled";
-    readonly type: "BOOLEAN";
-    readonly notNull: true;
+	readonly name: "enabled";
+	readonly type: "BOOLEAN";
+	readonly notNull: true;
 }, {
-    readonly name: "placement";
-    readonly type: "TEXT";
-    readonly notNull: true;
+	readonly name: "placement";
+	readonly type: "TEXT";
+	readonly notNull: true;
 }, {
-    readonly name: "updatedAt";
-    readonly type: "INTEGER";
-    readonly notNull: true;
+	readonly name: "updatedAt";
+	readonly type: "INTEGER";
+	readonly notNull: true;
 }, {
-    readonly name: "block";
-    readonly type: "JSON";
-    readonly notNull: true;
+	readonly name: "block";
+	readonly type: "JSON";
+	readonly notNull: true;
 }];
 export declare const CORE_BLOCKS_INDEXES: readonly [{
-    readonly name: "idx_core_blocks_enabled";
-    readonly columns: readonly ["enabled"];
+	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;
+* 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 = 1e3;
 export interface CoreBlockStoreDeps {
-    readonly store: SettingsStoreClient;
-    readonly logger: IScopedLogger;
-    readonly now?: () => number;
-    readonly newId?: () => string;
+	readonly store: SettingsStoreClient;
+	readonly logger: IScopedLogger;
+	readonly now?: () => number;
+	readonly newId?: () => string;
 }
 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. 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[];
-    get(blockId: string): CoreBlock | null;
-    /** Blocks that should be running here. The runner's input. */
-    enabledFor(nodeId: string): readonly CoreBlock[];
-    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: NamedCompositionInput, 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.
-     *
-     * Separate from {@link update} on purpose: status is the RUNNER's to write
-     * and the author's to read, and letting an edit set it would let the UI claim
-     * 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;
-    /**
-     * Resolve a source-affecting patch into the normalized `{ code, files?, entry? }`
-     * that will be stored. `null` when the patch does not touch source.
-     */
-    private normalizeSourcePatch;
+	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. 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[];
+	get(blockId: string): CoreBlock | null;
+	/** Blocks that should be running here. The runner's input. */
+	enabledFor(nodeId: string): readonly CoreBlock[];
+	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: NamedCompositionInput, 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.
+	*
+	* Separate from {@link update} on purpose: status is the RUNNER's to write
+	* and the author's to read, and letting an edit set it would let the UI claim
+	* 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;
+	/**
+	* Resolve a source-affecting patch into the normalized `{ code, files?, entry? }`
+	* that will be stored. `null` when the patch does not touch source.
+	*/
+	private normalizeSourcePatch;
 }

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

@@ -1,75 +1,75 @@
-import { BaseAddon, CoreBlock, ProviderRegistration } from '@camstack/types';
+import { BaseAddon, type CoreBlock, type ProviderRegistration } from "@camstack/types";
 export declare class CoreBlocksAddon extends BaseAddon {
-    /**
-     * `super({})` is NOT optional, and its absence is invisible until runtime:
-     * `BaseAddon.resolveConfig` does `Object.keys(this.defaults)`, so an addon
-     * that skips it dies at init with "Cannot convert undefined or null to
-     * object" — while the build stays green, the tests pass, and the addon still
-     * reports as `running`. Found in production, not here.
-     */
-    constructor();
-    private store;
-    private prefs;
-    private transpiler;
-    private typeDefs;
-    private supervisor;
-    /** The shared integration, or null when this node does not own it. */
-    private blocksIntegrationId;
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    protected onShutdown(): Promise<void>;
-    /**
-     * Build the supervisor, or explain in one line why this node runs no blocks.
-     *
-     * Two ways to end up with none, and both are logged rather than inferred:
-     * this is not the hub (execution is hub-only for now), or the kernel exposed
-     * no cluster broker, which is the only door to `$process.*`.
-     */
-    private buildSupervisor;
-    /**
-     * Own the integration blocks hang their devices from.
-     *
-     * A block cannot: every integration read is gated on the installed-addon set
-     * and `core-block-<uuid>` is never in it, so a block's get-or-create minted a
-     * fresh invisible row on every start. `core-blocks` IS installed, so it does
-     * this once here and a block names the result by id.
-     *
-     * Failure is a feature missing, not a boot failure — blocks that declare no
-     * devices are unaffected, and the next boot converges.
-     */
-    private declareBlocksIntegration;
-    /**
-     * Reconcile now, after a write.
-     *
-     * The timer would get there on its own, but an operator who presses Save and
-     * watches a block sit at `stopped` for fifteen seconds has been told nothing
-     * happened. Deliberately NOT awaited by the cap method: converging forks a
-     * process, and the write is already durable.
-     */
-    private convergeSoon;
-    private requireStore;
-    /**
-     * Compile, or explain why not. Returns the emitted JS so a successful gate
-     * can also extract `settingsSchema` without compiling twice.
-     *
-     * A missing transpiler REFUSES the write rather than waving it through: code
-     * that reached disk uncompiled is code the runner will fail on, far from the
-     * person who wrote it.
-     */
-    private gate;
-    private requirePrefs;
-    /**
-     * After a successful compile, cache the entry's `settingsSchema` export on
-     * the block when the author did not set one by hand. Never overwrites an
-     * explicit schema the editor already stored.
-     */
-    private maybeCacheSettingsSchema;
-    private buildProvider;
-    /**
-     * The composition methods (D659), flat. Sources and existing targets are read
-     * over `ctx.api` at SAVE time — one slim listing per owning addon, one binding
-     * read per found device — and a read that fails refuses the save rather than
-     * skipping it.
-     */
-    private buildCompositionApi;
+	/**
+	* `super({})` is NOT optional, and its absence is invisible until runtime:
+	* `BaseAddon.resolveConfig` does `Object.keys(this.defaults)`, so an addon
+	* that skips it dies at init with "Cannot convert undefined or null to
+	* object" — while the build stays green, the tests pass, and the addon still
+	* reports as `running`. Found in production, not here.
+	*/
+	constructor();
+	private store;
+	private prefs;
+	private transpiler;
+	private typeDefs;
+	private supervisor;
+	/** The shared integration, or null when this node does not own it. */
+	private blocksIntegrationId;
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	protected onShutdown(): Promise<void>;
+	/**
+	* Build the supervisor, or explain in one line why this node runs no blocks.
+	*
+	* Two ways to end up with none, and both are logged rather than inferred:
+	* this is not the hub (execution is hub-only for now), or the kernel exposed
+	* no cluster broker, which is the only door to `$process.*`.
+	*/
+	private buildSupervisor;
+	/**
+	* Own the integration blocks hang their devices from.
+	*
+	* A block cannot: every integration read is gated on the installed-addon set
+	* and `core-block-<uuid>` is never in it, so a block's get-or-create minted a
+	* fresh invisible row on every start. `core-blocks` IS installed, so it does
+	* this once here and a block names the result by id.
+	*
+	* Failure is a feature missing, not a boot failure — blocks that declare no
+	* devices are unaffected, and the next boot converges.
+	*/
+	private declareBlocksIntegration;
+	/**
+	* Reconcile now, after a write.
+	*
+	* The timer would get there on its own, but an operator who presses Save and
+	* watches a block sit at `stopped` for fifteen seconds has been told nothing
+	* happened. Deliberately NOT awaited by the cap method: converging forks a
+	* process, and the write is already durable.
+	*/
+	private convergeSoon;
+	private requireStore;
+	/**
+	* Compile, or explain why not. Returns the emitted JS so a successful gate
+	* can also extract `settingsSchema` without compiling twice.
+	*
+	* A missing transpiler REFUSES the write rather than waving it through: code
+	* that reached disk uncompiled is code the runner will fail on, far from the
+	* person who wrote it.
+	*/
+	private gate;
+	private requirePrefs;
+	/**
+	* After a successful compile, cache the entry's `settingsSchema` export on
+	* the block when the author did not set one by hand. Never overwrites an
+	* explicit schema the editor already stored.
+	*/
+	private maybeCacheSettingsSchema;
+	private buildProvider;
+	/**
+	* The composition methods (D659), flat. Sources and existing targets are read
+	* over `ctx.api` at SAVE time — one slim 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 };

package/dist/builtins/core-blocks/extract-settings-schema.d.ts

@@ -1,6 +1,6 @@
-import { ConfigUISchema } from '@camstack/types';
+import type { ConfigUISchema } from "@camstack/types";
 /**
- * Import the bundled module and return its `settingsSchema` export, or null.
- * Never throws.
- */
+* Import the bundled module and return its `settingsSchema` export, or null.
+* Never throws.
+*/
 export declare function extractSettingsSchema(js: string): Promise<ConfigUISchema | null>;

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

@@ -1,8 +1,8 @@
-export { BLOCK_ADDON_PREFIX, blockAddonId, blockIdFromAddonId, materializeBlock, removeBlockPackage, } from './block-package.js';
-export { type BlockProcessHost, type BlockRunnerSnapshot, type BlockRunnerState, BlockSupervisor, } from './block-supervisor.js';
-export { BlockSettingsStore, CORE_BLOCK_SETTINGS_COLLECTION, } from './block-settings-store.js';
-export { type BlockTypeLib, loadBlockTypeDefs } from './block-type-defs.js';
-export { type BlockTranspiler, type CompileBlockSource, compileBlock } from './compile-block.js';
-export { CORE_BLOCKS_COLLECTION, CoreBlockStore } from './core-block-store.js';
-export { CoreBlocksAddon as default, CoreBlocksAddon } from './core-blocks.addon.js';
-export { extractSettingsSchema } from './extract-settings-schema.js';
+export { BLOCK_ADDON_PREFIX, blockAddonId, blockIdFromAddonId, materializeBlock, removeBlockPackage } from "./block-package.js";
+export { type BlockProcessHost, type BlockRunnerSnapshot, type BlockRunnerState, BlockSupervisor } from "./block-supervisor.js";
+export { BlockSettingsStore, CORE_BLOCK_SETTINGS_COLLECTION } from "./block-settings-store.js";
+export { type BlockTypeLib, loadBlockTypeDefs } from "./block-type-defs.js";
+export { type BlockTranspiler, type CompileBlockSource, compileBlock } from "./compile-block.js";
+export { CORE_BLOCKS_COLLECTION, CoreBlockStore } from "./core-block-store.js";
+export { CoreBlocksAddon as default, CoreBlocksAddon } from "./core-blocks.addon.js";
+export { extractSettingsSchema } from "./extract-settings-schema.js";