@camstack/system 1.2.476 → 1.2.477

package/dist/builtins/composer/composer.addon.mjs

@@ -1,5 +1,6 @@
 import { $n as planComposition, $r as DeviceType, Gr as compositionItemFieldPath, Hr as composedDeviceRef, It as composerCapability, Jr as createStatefulExpressionMemory, Kr as compositionSliceKey, Lt as compositionFieldKey, N as DeclaredDevices, Oa as EventCategory, Ot as buildCapabilityLookup, Ur as composedDeviceStableId, Vr as cloneStatefulExpressionMemory, Wi as createEvent, Wr as compositionFeatureEnabled, Xr as toExpressionValue, Yr as disarmRoseMemory, a as BaseDevice, cn as evaluateCompositionField, d as COMPOSED_ITEM_FIXED_FIELDS, dn as expressionContainsBuiltinCall, ei as errMsg, qr as compositionSourceKey, r as ALL_CAPABILITY_DEFINITIONS, ti as BaseAddon, zr as COMPOSER_ADDON_ID } from "../../dist-B_V9r61Z.mjs";
 import { n as normalizedNativeOwner } from "../../composition-sources-B5nK7pHt.mjs";
+import { i as DAY_MS, m as capSeriesKey, t as DEFAULT_RETENTION } from "../../retention-lPgwLane.mjs";
 import { z } from "zod";
 //#region src/builtins/shared/device-state-changed.ts
 /** Structural narrowing helper for untrusted bus payloads. */
@@ -1196,9 +1197,33 @@ function createFieldRecord(plan, byCap, lookupCap) {
 		hasWritten: false,
 		written: void 0,
 		expressionMemory: createStatefulExpressionMemory(),
-		eventHighWater: typeof initial === "number" && Number.isFinite(initial) ? initial : null
+		eventHighWater: typeof initial === "number" && Number.isFinite(initial) ? initial : null,
+		pulseHold: false
 	};
 }
+/** Apply a pulse start seed (D938). `keep` leaves the slice seed in place. */
+function applyPulseSeed(record, seed) {
+	if (seed === void 0 || seed.kind === "keep") return record;
+	if (seed.kind === "hold") return {
+		...record,
+		initial: void 0,
+		eventHighWater: null,
+		pulseHold: true
+	};
+	const value = seed.value;
+	return {
+		...record,
+		initial: value,
+		eventHighWater: typeof value === "number" && Number.isFinite(value) ? value : null,
+		pulseHold: false
+	};
+}
+function fieldRecords(fields, byCap, lookupCap, pulseSeeds) {
+	return new Map(fields.map((plan) => {
+		const key = fieldKey(plan);
+		return [key, applyPulseSeed(createFieldRecord(plan, byCap, lookupCap), pulseSeeds?.get(key))];
+	}));
+}
 function currentOutput(record) {
 	return record.hasWritten ? record.written : record.initial;
 }
@@ -1252,6 +1277,7 @@ function namedField(r) {
 function writable(record) {
 	const outcome = record.outcome;
 	if (outcome === null) return void 0;
+	if (record.pulseHold && !record.hasWritten && (outcome.state === "unavailable" || outcome.value === null)) return;
 	if (outcome.state !== "unavailable") return outcome.value;
 	switch (record.plan.unavailable) {
 		case "null": return null;
@@ -1689,7 +1715,7 @@ var CompositionRuntime = class {
 	constructor(deps) {
 		this.deps = deps;
 		this.startedAtMs = deps.now();
-		this.records = new Map(deps.fields.map((plan) => [fieldKey(plan), createFieldRecord(plan, deps.initialByCap, deps.lookupCap)]));
+		this.records = fieldRecords(deps.fields, deps.initialByCap, deps.lookupCap, deps.pulseSeeds);
 		deps.target.onAsyncFailure?.((cap, failure) => this.onTargetWriteFailed(cap, failure));
 		const eventContext = {
 			deviceId: deps.target.id,
@@ -2536,7 +2562,7 @@ function writerFor(deps, p, device, onClaimEvent) {
 		onClaim: (cap, event) => onClaimEvent(deviceId, cap, owner, event)
 	});
 }
-function newCompositionRuntime(deps, p, target, seed) {
+function newCompositionRuntime(deps, p, target, seed, pulseSeeds) {
 	const self = p.target.kind === "existing" ? selfReadCaps(p.fields, p.target.ref, p.target.features) : null;
 	const targetKey = p.target.kind === "existing" ? compositionSourceKey(p.target.ref) : null;
 	const nativeCaps = new Set(self?.native ?? []);
@@ -2549,6 +2575,7 @@ function newCompositionRuntime(deps, p, target, seed) {
 		target,
 		lookupCap: deps.lookupCap,
 		...seed === void 0 ? {} : { initialByCap: seed.byCap },
+		...pulseSeeds === void 0 ? {} : { pulseSeeds },
 		read: (read) => deps.tracker.read(read, compositionSourceKey(read.source) === targetKey && nativeCaps.has(read.cap) ? "native" : "effective"),
 		isOwnRead: (read) => compositionSourceKey(read.source) === ownKey && !nativeCaps.has(read.cap),
 		now: deps.now,
@@ -2754,6 +2781,389 @@ function verdictOf(blockId, entry, unsynced, grafts = null) {
 	};
 }
 //#endregion
+//#region src/builtins/composer/pulse-seed.ts
+/** The last false→true in time order. A series that opens already on is not a transition. */
+function lastOffToOn(points, beforeOn) {
+	const ordered = [...points].toSorted((a, b) => a.t - b.t);
+	let previous = beforeOn;
+	let rise = null;
+	for (const point of ordered) {
+		if (previous === false && point.on && Number.isFinite(point.t)) rise = point.t;
+		previous = point.on;
+	}
+	return rise;
+}
+function finite(value) {
+	return value !== null && Number.isFinite(value) ? value : null;
+}
+/**
+* What the source proves. A failed read is `hold`, never `none`.
+* When the source records no history and it is off, `lastChangedAt` is the
+* end of the last ring: it bounds the ring from above (the press was at or
+* before that instant). It is used only when it is newer than the target's
+* native stamp — an older bound does not prove the native value.
+*/
+function proof(facts) {
+	if (facts.history.kind === "unread") return {
+		kind: "hold",
+		reason: "history-unread"
+	};
+	if (facts.history.kind === "series") {
+		const at = lastOffToOn(facts.history.points, facts.history.beforeOn);
+		return at === null ? { kind: "none" } : {
+			kind: "rise",
+			at,
+			via: "history"
+		};
+	}
+	if (facts.level.kind === "unread") return {
+		kind: "hold",
+		reason: "level-unread"
+	};
+	const changedAt = facts.level.kind === "off" ? finite(facts.level.changedAt) : null;
+	const newerThanNative = changedAt !== null && (facts.nativeStamp === null || changedAt > facts.nativeStamp);
+	if (changedAt !== null && newerThanNative) return {
+		kind: "rise",
+		at: changedAt,
+		via: "changed-at-bound"
+	};
+	return { kind: "none" };
+}
+function claimed(owned) {
+	return owned.kind === "stamp" || owned.kind === "never";
+}
+function decidePulseSeed(facts) {
+	const proved = proof(facts);
+	if (proved.kind === "hold") return claimed(facts.owned) ? { kind: "keep" } : proved;
+	if (proved.kind === "rise") {
+		if (facts.owned.kind === "stamp" && facts.owned.at >= proved.at) return { kind: "keep" };
+		const count = facts.owned.kind === "stamp" ? facts.owned.count : 0;
+		return {
+			kind: "stamp",
+			at: proved.at,
+			count,
+			via: proved.via
+		};
+	}
+	return claimed(facts.owned) ? { kind: "keep" } : {
+		kind: "none",
+		count: 0
+	};
+}
+/** One failed source blocks "no ring". A rise from another source still stands. */
+function mergePulseDecisions(decisions) {
+	if (decisions.length === 0) return {
+		kind: "none",
+		count: 0
+	};
+	const stamps = decisions.flatMap((decision) => decision.kind === "stamp" ? [decision] : []);
+	if (stamps.length > 0) return stamps.reduce((best, next) => next.at > best.at ? next : best);
+	const hold = decisions.find((decision) => decision.kind === "hold");
+	if (hold !== void 0) return hold;
+	if (decisions.some((decision) => decision.kind === "keep")) return { kind: "keep" };
+	return {
+		kind: "none",
+		count: 0
+	};
+}
+//#endregion
+//#region src/builtins/composer/pulse-seed-resolve.ts
+/**
+* Gather a pulse override's start seed (D938). The stored expression is not
+* changed. A failed read holds the field: no seed, and a claimed stamp is
+* not cleared (D49).
+*/
+var ROSE_CALL = String.raw`rose\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,\s*([A-Za-z_][A-Za-z0-9_]*)`;
+function historySeriesKey(cap, fieldPath) {
+	return capSeriesKey(cap, fieldPath);
+}
+async function resolvePulseSeeds(input) {
+	try {
+		return await resolveNow(input);
+	} catch (err) {
+		input.logger.warn("pulse override seed held — gathering the source facts threw, so nothing is seeded and nothing is cleared", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				error: errMsg(err)
+			}
+		});
+		return /* @__PURE__ */ new Map();
+	}
+}
+async function resolveNow(input) {
+	const roses = input.fields.filter(isPulseTimestamp);
+	if (roses.length === 0) return /* @__PURE__ */ new Map();
+	const listing = await readClaims(input);
+	if (listing === null) return /* @__PURE__ */ new Map();
+	const seeds = /* @__PURE__ */ new Map();
+	for (const field of roses) {
+		const decision = await decideField(input, field, listing);
+		logDecision(input, field, decision);
+		for (const [key, seed] of seedsFor(input.fields, field, decision)) seeds.set(key, seed);
+	}
+	return seeds;
+}
+function isPulseTimestamp(field) {
+	return field.source.kind === "expression" && expressionContainsBuiltinCall(field.source.expr, "rose");
+}
+async function readClaims(input) {
+	try {
+		const listing = await input.claims.listClaims({ ownerPrefix: input.blockId });
+		if (listing.state === "loaded") return listing;
+		input.logger.warn("pulse override seed held — the claims index has not loaded, so nothing is seeded and nothing is cleared", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				reason: listing.reason
+			}
+		});
+		return null;
+	} catch (err) {
+		input.logger.warn("pulse override seed held — the claims index could not be read, so nothing is seeded and nothing is cleared", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				error: errMsg(err)
+			}
+		});
+		return null;
+	}
+}
+async function decideField(input, field, listing) {
+	if (listing.state !== "loaded") return {
+		kind: "hold",
+		reason: "claims-unread"
+	};
+	const claim = listing.claims.find((row) => row.owner === input.blockId && row.deviceId === input.deviceId && row.capName === field.cap);
+	const slice = input.targetSeed.byCap.get(field.cap) ?? null;
+	const counter = counterField(input.fields, field);
+	const owned = ownedOf(claim, slice, field.path, counter?.path ?? null);
+	const nativeStamp = stampOf(slice, field.path);
+	const pairs = rosePairs(field);
+	if (pairs.length === 0) return { kind: "keep" };
+	const decisions = [];
+	for (const pair of pairs) decisions.push(await decidePair(input, pair, owned, nativeStamp));
+	return mergePulseDecisions(decisions);
+}
+async function decidePair(input, pair, owned, nativeStamp) {
+	const resolution = await input.sources.resolve(pair.source, false);
+	if (resolution.kind === "missing") return { kind: "keep" };
+	if (resolution.kind !== "found") return decidePulseSeed({
+		owned,
+		nativeStamp,
+		history: { kind: "unread" },
+		level: { kind: "unread" }
+	});
+	return decidePulseSeed({
+		owned,
+		nativeStamp,
+		history: await historyOf(input, resolution.deviceId, pair),
+		level: await levelOf(input, resolution.deviceId, pair)
+	});
+}
+async function historyOf(input, deviceId, pair) {
+	if (!recordsField(input.lookupCap, pair.cap, pair.activeField)) return { kind: "absent" };
+	const now = input.now();
+	const fromMs = now - DEFAULT_RETENTION.rawDays * DAY_MS;
+	try {
+		const answer = await input.readPulseHistory(deviceId, pair.cap, pair.activeField, fromMs, now);
+		if (answer.kind === "unread") return { kind: "unread" };
+		return {
+			kind: "series",
+			beforeOn: answer.series.beforeOn,
+			points: answer.series.points
+		};
+	} catch (err) {
+		input.logger.warn("pulse override history read threw — treated as unread", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				sourceDeviceId: deviceId,
+				cap: pair.cap,
+				field: pair.activeField,
+				error: errMsg(err)
+			}
+		});
+		return { kind: "unread" };
+	}
+}
+async function levelOf(input, deviceId, pair) {
+	try {
+		return levelFromSlice(await input.readCap(deviceId, pair.cap), pair);
+	} catch (err) {
+		input.logger.warn("pulse override source slice could not be read — treated as unread", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				blockId: input.blockId,
+				sourceDeviceId: deviceId,
+				cap: pair.cap,
+				error: errMsg(err)
+			}
+		});
+		return { kind: "unread" };
+	}
+}
+function levelFromSlice(slice, pair) {
+	if (slice === null) return {
+		kind: "off",
+		changedAt: null
+	};
+	const active = slice[pair.activeField];
+	if (typeof active !== "boolean") return { kind: "unread" };
+	const changed = slice[pair.changedAtField];
+	const changedAt = typeof changed === "number" && Number.isFinite(changed) ? changed : null;
+	return active ? {
+		kind: "on",
+		changedAt
+	} : {
+		kind: "off",
+		changedAt
+	};
+}
+function recordsField(lookup, cap, fieldPath) {
+	const history = lookup(cap)?.history;
+	if (history === void 0 || history === "none") return false;
+	return Object.hasOwn(history.fields, fieldPath);
+}
+function ownedOf(claim, slice, timestampPath, counterPath) {
+	if (claim === void 0 || slice === null || !claim.fields.includes(timestampPath)) return { kind: "none" };
+	const at = slice[timestampPath];
+	if (at === null) return { kind: "never" };
+	if (typeof at !== "number" || !Number.isFinite(at)) return { kind: "none" };
+	const rawCount = counterPath === null ? void 0 : slice[counterPath];
+	return {
+		kind: "stamp",
+		at,
+		count: typeof rawCount === "number" && Number.isFinite(rawCount) && rawCount >= 0 ? rawCount : 0
+	};
+}
+function stampOf(slice, path) {
+	const at = slice?.[path];
+	return typeof at === "number" && Number.isFinite(at) ? at : null;
+}
+function counterField(fields, timestamp) {
+	return fields.find((field) => {
+		if (field.cap !== timestamp.cap || field.path === timestamp.path) return false;
+		return field.source.kind === "expression" && field.source.expr === `count(${timestamp.path})`;
+	});
+}
+function rosePairs(field) {
+	if (field.source.kind !== "expression") return [];
+	const found = [];
+	for (const match of field.source.expr.matchAll(new RegExp(ROSE_CALL, "g"))) {
+		const pair = rosePair(field, match[1], match[2]);
+		if (pair !== null) found.push(pair);
+	}
+	return found;
+}
+function rosePair(field, activeName, changedName) {
+	if (field.source.kind !== "expression") return null;
+	if (activeName === void 0 || changedName === void 0) return null;
+	const active = field.source.bindings[activeName];
+	const changed = field.source.bindings[changedName];
+	if (active === void 0 || changed === void 0) return null;
+	if (active.kind !== "from" || changed.kind !== "from") return null;
+	if (active.cap !== changed.cap) return null;
+	if (active.source.addonId !== changed.source.addonId) return null;
+	if (active.source.stableId !== changed.source.stableId) return null;
+	return {
+		source: active.source,
+		cap: active.cap,
+		activeField: active.fieldPath,
+		changedAtField: changed.fieldPath
+	};
+}
+function seedsFor(fields, timestamp, decision) {
+	const seeds = /* @__PURE__ */ new Map();
+	if (decision.kind === "keep") return seeds;
+	const counter = counterField(fields, timestamp);
+	if (decision.kind === "hold") {
+		seeds.set(fieldKey(timestamp), { kind: "hold" });
+		if (counter !== void 0) seeds.set(fieldKey(counter), {
+			kind: "value",
+			value: 0
+		});
+		return seeds;
+	}
+	if (decision.kind === "none") {
+		seeds.set(fieldKey(timestamp), {
+			kind: "value",
+			value: null
+		});
+		if (counter !== void 0) seeds.set(fieldKey(counter), {
+			kind: "value",
+			value: 0
+		});
+		return seeds;
+	}
+	seeds.set(fieldKey(timestamp), {
+		kind: "value",
+		value: decision.at
+	});
+	if (counter !== void 0) seeds.set(fieldKey(counter), {
+		kind: "value",
+		value: decision.count
+	});
+	return seeds;
+}
+/** Raw boolean points of the device-level series (`scope` empty). 1 is on. */
+function pulseHistoryFromQuery(series) {
+	const row = series.find((item) => item.scope === "");
+	if (row === void 0) return {
+		beforeOn: null,
+		points: []
+	};
+	return {
+		beforeOn: levelBit(row.before?.value ?? null),
+		points: row.points.flatMap((point) => {
+			const on = levelBit(point.last);
+			return on === null ? [] : [{
+				t: point.t,
+				on
+			}];
+		})
+	};
+}
+function levelBit(value) {
+	if (value === 1) return true;
+	if (value === 0) return false;
+	return null;
+}
+function logDecision(input, field, decision) {
+	const meta = {
+		blockId: input.blockId,
+		cap: field.cap,
+		field: field.path
+	};
+	if (decision.kind === "stamp") {
+		input.logger.info("pulse override seeded lastPressedAt from its source", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				...meta,
+				at: decision.at,
+				via: decision.via,
+				count: decision.count
+			}
+		});
+		return;
+	}
+	if (decision.kind === "none") {
+		input.logger.info("pulse override seeded no ring — the source proved none, so the native stamp is not used", {
+			tags: { deviceId: input.deviceId },
+			meta
+		});
+		return;
+	}
+	if (decision.kind === "hold") input.logger.warn("pulse override seed held — a source read failed, so nothing is seeded and nothing is cleared", {
+		tags: { deviceId: input.deviceId },
+		meta: {
+			...meta,
+			reason: decision.reason
+		}
+	});
+}
+//#endregion
 //#region src/builtins/composer/composer.ts
 /**
 * The composer: every declarative composition on this hub, in one runner
@@ -2991,6 +3401,7 @@ var Composer = class {
 				continue;
 			}
 			let targetSeed;
+			let pulseSeeds;
 			if (p.target.kind === "existing" && p.target.deviceId !== null && p.target.waiting === null && p.target.gone === null && p.block.enabled && p.fields.length > 0) try {
 				targetSeed = await readExistingTargetSeeds(p.target.deviceId, p.fields.map((field) => field.cap), this.deps.readExistingTargetCap);
 				reportSeedlessRestoredCaps({
@@ -3001,6 +3412,20 @@ var Composer = class {
 					seed: targetSeed,
 					lookupCap: this.deps.lookupCap
 				});
+				const readHistory = this.deps.readPulseHistory;
+				if (readHistory !== void 0) pulseSeeds = await resolvePulseSeeds({
+					blockId: p.block.id,
+					deviceId: p.target.deviceId,
+					fields: p.fields,
+					targetSeed,
+					lookupCap: this.deps.lookupCap,
+					claims: this.deps.claims,
+					sources: this.deps.tracker,
+					readCap: this.deps.readExistingTargetCap,
+					readPulseHistory: readHistory,
+					now: this.deps.now,
+					logger: this.deps.logger
+				});
 			} catch (err) {
 				const reason = `the target device state could not be read before ownership (${errMsg(err)}) — nothing is grafted or claimed until it is; retried on the next apply`;
 				this.deps.logger.warn(previous?.runtime === null || previous === void 0 ? "customization target state could not be read — ownership is held" : "customization edit target state could not be read — the previous runtime stays installed", {
@@ -3026,7 +3451,7 @@ var Composer = class {
 			const writer = writerFor(this.deps, p, device, (deviceId, cap, owner, event) => {
 				this.onClaimEvent(deviceId, cap, owner, event);
 			});
-			const runtime = writer === null || p.fields.length === 0 ? null : newCompositionRuntime(this.deps, p, writer, targetSeed);
+			const runtime = writer === null || p.fields.length === 0 ? null : newCompositionRuntime(this.deps, p, writer, targetSeed, pulseSeeds);
 			if (writer !== null && p.target.kind === "existing" && p.target.deviceId !== null) this.grafts.plan({
 				deviceId: p.target.deviceId,
 				ref: p.target.ref,
@@ -4159,6 +4584,8 @@ var SourceTracker = class {
 */
 /** Ignored by `DeclaredDevices` whenever `integrationId` is supplied, which is always here. */
 var DECLARED_INTEGRATION_NAME_UNUSED = "Blocks";
+/** The device-history query ceiling. A switch's raw tier is change-only, so this is the whole window. */
+var PULSE_HISTORY_MAX_POINTS = 5e3;
 /** The owner-only shadow payload is not in the typed catalog: narrowed at the boundary, like `device.state-changed`. */
 function parseNativeShadowChanged(data) {
 	if (!isRecord$2(data)) return null;
@@ -4307,6 +4734,26 @@ var ComposerAddon = class extends BaseAddon {
 				deviceId,
 				capName
 			}) ?? null,
+			readPulseHistory: async (deviceId, cap, fieldPath, fromMs, toMs) => {
+				try {
+					return {
+						kind: "series",
+						series: pulseHistoryFromQuery((await api.deviceHistory.query.query({
+							deviceId,
+							key: historySeriesKey(cap, fieldPath),
+							from: fromMs,
+							to: toMs,
+							resolution: "raw",
+							maxPoints: PULSE_HISTORY_MAX_POINTS
+						})).series)
+					};
+				} catch (err) {
+					return {
+						kind: "unread",
+						error: errMsg(err)
+					};
+				}
+			},
 			describeTarget: readBoundCaps,
 			grafts,
 			now: () => Date.now(),

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

@@ -53,6 +53,7 @@ import { type ComposerDeclare, type ComposerDevicePorts } from "./composed-devic
 import { type PersistedComposedRow } from "./composition-declarations.js";
 import type { CompositionEventEmitter, DeadlineTimer } from "./composition-runtime.js";
 import { type ComposerClaimsApi, type ComposerGraftPorts, type DescribeTarget } from "./existing-target.js";
+import { type ReadPulseHistory } from "./pulse-seed-resolve.js";
 import type { SourceBindingsChangeReason, SourceTracker } from "./source-tracker.js";
 export type { ComposerDerivedSpec } from "./composer-plan.js";
 export type { ComposerDeclareResult, ComposerDevicePorts } from "./composed-device-set.js";
@@ -84,6 +85,11 @@ export interface ComposerDeps {
 	readonly events: CompositionEventEmitter;
 	/** Effective target state, read before an existing-target runtime owns any field. */
 	readonly readExistingTargetCap: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>;
+	/**
+	* Raw history of a source field, for a pulse override's start seed (D938).
+	* Absent (tests that predate the seed) leaves the boot slice as the initial.
+	*/
+	readonly readPulseHistory?: ReadPulseHistory;
 	/** ONE `getBindings` per target description read (rule 1). */
 	readonly describeTarget: DescribeTarget;
 	/** `GraftHost` (Task 10): a method-serving native for each ADDED cap. Absent, nothing is grafted. */

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

@@ -54,6 +54,7 @@
 import { type CapabilityLookup, type CompositionEventPlan, type CompositionFieldPlan, type CompositionFieldRead, type CompositionFieldState, type IScopedLogger, type SourceReader } from "@camstack/types";
 import type { ComposedWriteTarget, CompositionEventEmitter, DeadlineTimer } from "./composition-target.js";
 import { type ReleasedField } from "./field-record.js";
+import type { PulseFieldSeed } from "./pulse-seed.js";
 export type { ReleasedField } from "./field-record.js";
 export type { ComposedWriteTarget, CompositionEventEmitter, DeadlineTimer, TargetAsyncFailure, WriteOk, WriteOutcome, WriteRefused } from "./composition-target.js";
 export interface CompositionRuntimeDeps {
@@ -65,6 +66,8 @@ export interface CompositionRuntimeDeps {
 	readonly lookupCap: CapabilityLookup;
 	/** Effective target slices captured before an existing-target runtime takes ownership. */
 	readonly initialByCap?: ReadonlyMap<string, Readonly<Record<string, unknown>> | null>;
+	/** Pulse start seed (D938). Absent keeps `initialByCap`. `hold` publishes nothing. */
+	readonly pulseSeeds?: ReadonlyMap<string, PulseFieldSeed>;
 	readonly read: SourceReader;
 	/**
 	* Whether `read` is of this composition's OWN output (an added cap on its

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

@@ -6,6 +6,7 @@
 * behaviour.
 */
 import { type CapabilityLookup, type CompositionFieldItem, type CompositionFieldPlan, type CompositionFieldState, type ExpressionValue, type FieldOutcome, type StatefulExpressionMemory } from "@camstack/types";
+import type { PulseFieldSeed } from "./pulse-seed.js";
 export declare const NO_FIELDS: ReadonlySet<string>;
 export interface FieldRecord {
 	readonly plan: CompositionFieldPlan;
@@ -19,9 +20,15 @@ export interface FieldRecord {
 	readonly expressionMemory: StatefulExpressionMemory;
 	/** Last finite state value already represented by a derived event. */
 	readonly eventHighWater: number | null;
+	/**
+	* A pulse timestamp whose start seed could not be read (D49, D938). A null
+	* result is not published, so a failed read is not "no ring".
+	*/
+	readonly pulseHold: boolean;
 }
 export declare function fieldKey(plan: CompositionFieldPlan): string;
 export declare function createFieldRecord(plan: CompositionFieldPlan, byCap: ReadonlyMap<string, Readonly<Record<string, unknown>> | null> | undefined, lookupCap: CapabilityLookup): FieldRecord;
+export declare function fieldRecords(fields: readonly CompositionFieldPlan[], byCap: ReadonlyMap<string, Readonly<Record<string, unknown>> | null> | undefined, lookupCap: CapabilityLookup, pulseSeeds: ReadonlyMap<string, PulseFieldSeed> | undefined): ReadonlyMap<string, FieldRecord>;
 export declare function currentOutput(record: FieldRecord): unknown;
 /** The top-level field a record writes: an item leaf writes its whole array. */
 export declare function topLevelField(plan: CompositionFieldPlan): string;

package/dist/builtins/composer/pulse-seed-resolve.d.ts

@@ -0,0 +1,59 @@
+/**
+* Gather a pulse override's start seed (D938). The stored expression is not
+* changed. A failed read holds the field: no seed, and a claimed stamp is
+* not cleared (D49).
+*/
+import { type CapabilityLookup, type ClaimsListing, type CompositionFieldPlan, type CompositionSourceRef, type IScopedLogger } from "@camstack/types";
+import type { ExistingTargetSeedRead } from "./existing-target.js";
+import { type PulseFieldSeed, type PulseHistoryPoint } from "./pulse-seed.js";
+import type { SourceResolution } from "./source-readings.js";
+export type { PulseFieldSeed } from "./pulse-seed.js";
+export interface PulseHistorySeries {
+	readonly beforeOn: boolean | null;
+	readonly points: readonly PulseHistoryPoint[];
+}
+export type PulseHistoryAnswer = {
+	readonly kind: "unread";
+	readonly error: string;
+} | {
+	readonly kind: "series";
+	readonly series: PulseHistorySeries;
+};
+export type ReadPulseHistory = (deviceId: number, cap: string, fieldPath: string, fromMs: number, toMs: number) => Promise<PulseHistoryAnswer>;
+export interface PulseClaimListing {
+	listClaims(input: {
+		readonly ownerPrefix?: string;
+	}): Promise<ClaimsListing>;
+}
+export interface PulseSourceLookup {
+	resolve(ref: CompositionSourceRef, reset: boolean): Promise<SourceResolution>;
+}
+export interface ResolvePulseSeedsInput {
+	readonly blockId: string;
+	readonly deviceId: number;
+	readonly fields: readonly CompositionFieldPlan[];
+	readonly targetSeed: ExistingTargetSeedRead;
+	readonly lookupCap: CapabilityLookup;
+	readonly claims: PulseClaimListing;
+	readonly sources: PulseSourceLookup;
+	readonly readCap: (deviceId: number, capName: string) => Promise<Readonly<Record<string, unknown>> | null>;
+	readonly readPulseHistory: ReadPulseHistory;
+	readonly now: () => number;
+	readonly logger: IScopedLogger;
+}
+export declare function historySeriesKey(cap: string, fieldPath: string): string;
+export declare function resolvePulseSeeds(input: ResolvePulseSeedsInput): Promise<ReadonlyMap<string, PulseFieldSeed>>;
+export interface PulseHistoryQueryPoint {
+	readonly t: number;
+	readonly last: number | null;
+}
+export interface PulseHistoryQueryBefore {
+	readonly value: number | null;
+}
+export interface PulseHistoryQuerySeries {
+	readonly scope: string;
+	readonly before: PulseHistoryQueryBefore | null;
+	readonly points: readonly PulseHistoryQueryPoint[];
+}
+/** Raw boolean points of the device-level series (`scope` empty). 1 is on. */
+export declare function pulseHistoryFromQuery(series: readonly PulseHistoryQuerySeries[]): PulseHistorySeries;