@camstack/system 1.2.313 → 1.2.314

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

@@ -0,0 +1,122 @@
+import { CompositionSourceRef, DeviceType, EventCatalog, IScopedLogger } from '@camstack/types';
+/** One row of the slim device listing: what resolves a `(addonId, stableId)` ref and types an existing target. */
+export interface SourceRow {
+    readonly id: number;
+    readonly stableId: string;
+    readonly type: DeviceType;
+}
+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;
+/** The caps bound on a device, each with the addon serving it natively (`getBindings`, one read). */
+export interface BoundCaps {
+    readonly kind: 'caps';
+    readonly caps: ReadonlyMap<string, string>;
+}
+export type BoundCapsRead = BoundCaps | SourceUnreadable;
+/** Which slice of a cap is read: what every consumer sees, or what the provider wrote (the shadow under a claim, D663). */
+export type SliceView = 'effective' | 'native';
+export interface SourceTrackerPorts {
+    readonly logger: IScopedLogger;
+    /** `deviceManager.listAll({ addonId, projection: 'slim' })`: one call per owning addon per pass. */
+    readonly listDevicesOf: (addonId: string) => Promise<SourceListRead>;
+    /** `deviceState.getCapSlice` for the effective view; `deviceState.getNativeCapSlice` for the native one. */
+    readonly readSlice: (deviceId: number, capName: string, view: SliceView) => 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;
+    /** Caps read in the effective view — what every consumer sees. */
+    readonly caps: readonly string[];
+    /** Caps of the REF read in the NATIVE view: the target's own replaced or uncomposed fields (rule 6). */
+    readonly nativeCaps?: readonly string[];
+    /** The block whose own claims decide whether `device.state-changed` of a native cap is the native (N-7). */
+    readonly nativeOwner?: string;
+}
+/** How a `(addonId, stableId)` ref resolves against the device index. */
+export interface SourceFound {
+    readonly kind: 'found';
+    readonly deviceId: number;
+    readonly type: DeviceType;
+}
+export interface SourceMissing {
+    readonly kind: 'missing';
+    readonly reason: string;
+}
+export interface SourceUnknown {
+    readonly kind: 'unknown';
+    readonly error: string;
+}
+export type SourceResolution = SourceFound | SourceMissing | SourceUnknown;
+export interface CapSlice {
+    readonly kind: 'slice';
+    readonly slice: Readonly<Record<string, unknown>>;
+    readonly staleReason: string | null;
+}
+export interface CapNoValue {
+    readonly kind: 'none';
+    readonly reason: string;
+    /** An ANSWER — the provider unregistered the cap and a bindings re-read agreed — not an empty or first read (D49). */
+    readonly confirmed: boolean;
+}
+/** Not bound on a device whose row exists: non-fatal, healed by `native-registered` (R7b). */
+export interface CapUnbound {
+    readonly kind: 'unbound';
+    readonly reason: string;
+}
+/** Nothing is known: the read failed with no value held, or read empty under a held claim. Re-read by the next `sync` (D49). */
+export interface CapUnread {
+    readonly kind: 'unread';
+    readonly reason: string;
+}
+export type CapReading = CapSlice | CapNoValue | CapUnbound | CapUnread;
+/** One cap in one view — the unit a reading is held for. */
+export interface CapEntry {
+    readonly cap: string;
+    readonly view: SliceView;
+}
+export interface TrackedSource {
+    readonly ref: CompositionSourceRef;
+    readonly deviceId: number | null;
+    readonly type: DeviceType | null;
+    readonly missingReason: string | null;
+    /** The index could not be read the last time: retried on the next apply. */
+    readonly indexError: string | null;
+    readonly online: boolean | null;
+    /** Keyed by `entryKey`: an effective and a native reading of one cap are two entries. */
+    readonly caps: ReadonlyMap<string, CapReading>;
+    /** Whose claims decide what a `device.state-changed` is for the native-view caps; null: nobody claims here. */
+    readonly nativeOwner: string | null;
+}
+export interface Absent {
+    readonly kind: 'absent';
+}
+export type RowVerdict = SourceFound | Absent | SourceUnknown;
+export type Resolution = SourceFound | SourceMissing | SourceUnknown;
+export type BindingVerdict = 'bound' | 'unbound' | 'unknown';
+export declare const DEVICE_STATUS_CAP = "device-status";
+export declare const NATIVE_SUFFIX = "@native";
+export declare const NO_CAPS: readonly string[];
+export declare function entryKey(entry: CapEntry): string;
+export declare function entryOf(key: string): CapEntry;
+export declare function entriesOf(request: TrackedSourceRequest): readonly CapEntry[];
+export declare function valueAtPath(slice: Readonly<Record<string, unknown>>, path: string): unknown;
+export declare function onlineOf(slice: Readonly<Record<string, unknown>>): boolean | null;
+export declare function findRow(read: SourceListRead, stableId: string): RowVerdict;
+export declare function resolutionOf(source: TrackedSource): SourceResolution;

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

@@ -1,46 +1,12 @@
-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[];
-}
+import { CompositionFieldRead, CompositionSourceRef, FieldClaim, SourceReading } from '@camstack/types';
+import { ClaimEvent } from './held-claims.js';
+import { SliceView, SourceBindingsChangeReason, SourceResolution, SourceTrackerPorts, TrackedSourceRequest } from './source-readings.js';
+export type { BoundCaps, BoundCapsRead, SliceFound, SliceNone, SliceRead, SliceView, SourceBindingsChangeReason, SourceFound, SourceListRead, SourceMissing, SourceResolution, SourceRow, SourceRowsRead, SourceTrackerPorts, SourceUnknown, SourceUnreadable, TrackedSourceRequest, } from './source-readings.js';
 export declare class SourceTracker {
     private readonly ports;
     private sources;
+    /** The claims the hub holds — what LANDED, never what a plan wants (C-1). */
+    private readonly held;
     /** The one chain every entry point joins (R3); the pattern is `BlockSupervisor.inFlight`. */
     private chain;
     constructor(ports: SourceTrackerPorts);
@@ -50,20 +16,45 @@ export declare class SourceTracker {
      * or restart): only those lose a sticky `missing`.
      */
     sync(requests: readonly TrackedSourceRequest[], reset: ReadonlySet<string>): Promise<ReadonlySet<string>>;
+    /**
+     * Resolve a ref against the device index through the same path as a source
+     * (D663 rule 1): one list read; two agreeing absent reads make it `missing`,
+     * sticky until `reset` (an operator edit or restart). A source already
+     * resolved is answered from memory; one whose index read FAILED is read
+     * again. The bare source stays tracked, so a later `sync` that names it keeps
+     * its resolution and reads only the caps it asks for.
+     */
+    resolve(ref: CompositionSourceRef, reset: boolean): Promise<SourceResolution>;
+    /** The claims the hub held at boot (the claims index seed). Nothing is read: no native self-read is tracked before it. */
+    seedClaims(claims: readonly FieldClaim[]): void;
+    /**
+     * A claim RPC of `owner` on `(deviceId, cap)`: dispatched (`claiming`), or
+     * answered — the hub holds it (`held`), holds none of it (`free`), or said
+     * nothing that changes it (`unsettled`). Every ANSWER re-reads the owner's
+     * native-view readings of that cap ONCE: while the RPC was in flight (or a
+     * release was being applied) the provider's writes arrived as a
+     * `device.state-changed` the tracker could not take as the native.
+     */
+    claimEvent(deviceId: number, cap: string, owner: string, event: ClaimEvent): Promise<ReadonlySet<string>>;
+    /** The last settled resolution of a ref; `unknown` when it was never resolved. Synchronous, from memory. */
+    resolution(ref: CompositionSourceRef): SourceResolution;
     onStateChanged(deviceId: number, capName: string, slice: Readonly<Record<string, unknown>>): Promise<ReadonlySet<string>>;
+    /** `device.native-shadow-changed`: the provider's own slice of a cap under a claim (owner-only, D224). */
+    onNativeChanged(deviceId: number, capName: string, native: 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;
+    read(read: CompositionFieldRead, view?: SliceView): SourceReading;
     private applyStateChanged;
+    private applyNativeChanged;
     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. */
+    /** Read `toRead` (bindings first, then slices); every other requested entry keeps what `known` holds. */
     private readCaps;
     private resolveConfirmed;
     /**
@@ -73,6 +64,8 @@ export declare class SourceTracker {
      */
     private readBindings;
     private readCap;
+    /** A claim or release of `owner` on `(deviceId, cap)` was answered: read the owner's native-view readings of it once, in place. */
+    private rereadNative;
     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-CkRwnhbo.js");
+const require_dist = require("../../dist-BtNkk3Qz.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 { Ut as logDestinationCapability, jn as BaseAddon } from "../../dist-Cj7pJmXq.mjs";
+import { Bn as BaseAddon, Ht as logDestinationCapability } from "../../dist-cH4t1ZEm.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/composition-api.d.ts

@@ -1,21 +1,24 @@
-import { CapabilityLookup, CompositionBlockInput, CompositionBlockPatch, CompositionBlockState, CompositionSourceDescription, CompositionSourceRef, CoreBlock, ICoreBlocksProvider, IScopedLogger } from '@camstack/types';
+import { CapabilityLookup, CompositionBlockPatch, CompositionBlockState, CompositionSourceRef, CoreBlock, ICoreBlocksProvider, IScopedLogger } from '@camstack/types';
+import { NamedCompositionInput } from './core-block-store.js';
+import { 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: CompositionBlockInput, createdBy: string): Promise<CoreBlock>;
+    createComposition(input: NamedCompositionInput, 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>>;
+    /** 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;
 }
-export type CompositionApi = Pick<ICoreBlocksProvider, 'createComposition' | 'updateComposition' | 'getComposition' | 'listCompositions' | 'validateComposition'>;
+export type CompositionApi = Pick<ICoreBlocksProvider, 'createComposition' | 'updateComposition' | 'getComposition' | 'listCompositions' | 'validateComposition' | 'getCustomization'>;
 /**
  * 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

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

@@ -0,0 +1,9 @@
+import { CapabilityLookup, CompositionPeer, CompositionSourceRef, CompositionTargetDescription, 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>;
+}
+/** The existing devices the stored customizations write — each read once with the candidate's. */
+export declare function storedCustomizationTargets(blocks: readonly CoreBlock[]): readonly CompositionSourceRef[];
+export declare function storedPeers(blocks: readonly CoreBlock[], targets: ReadonlyMap<string, CompositionTargetDescription>, lookupCap: CapabilityLookup, candidateBlockId: string | null): StoredPeers;

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

@@ -1,10 +1,21 @@
-import { CompositionSourceDescription, CompositionSourceRef } from '@camstack/types';
+import { CompositionSourceDescription, CompositionSourceRef, CompositionTargetDescription, DeviceType } from '@camstack/types';
 export interface SourceRowView {
     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;
 }
 export interface CompositionSourcePorts {
     readonly listByAddon: (addonId: string) => Promise<readonly SourceRowView[]>;
-    readonly boundCaps: (deviceId: number) => Promise<readonly string[]>;
+    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>;
 }
-export declare function describeCompositionSources(ports: CompositionSourcePorts, refs: readonly CompositionSourceRef[]): Promise<ReadonlyMap<string, CompositionSourceDescription>>;
+export declare function describeCompositionSources(ports: CompositionSourcePorts, sources: readonly CompositionSourceRef[], targets?: readonly CompositionSourceRef[]): Promise<CompositionDescriptions>;

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

@@ -1,4 +1,11 @@
 import { 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).
+ */
+export interface NamedCompositionInput extends CompositionBlockInput {
+    readonly name: string;
+}
 /**
  * @durable class=config owner=core-blocks
  *   write="`create` and `update` persist the operator's block after it compiles;
@@ -94,7 +101,7 @@ export declare class CoreBlockStore {
      * 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>;
+    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>;
     /**

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

@@ -56,9 +56,10 @@ 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.
+     * 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;
 }