@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/substrate/runtime/observability/redaction.mjs

@@ -1,15 +1,17 @@
 import { __exportAll } from "../../../_virtual/_rolldown/runtime.mjs";
-import { Context, Effect, Layer, Ref } from "effect";
 //#region src/substrate/runtime/observability/redaction.ts
 var redaction_exports = /* @__PURE__ */ __exportAll({
-	Redactor: () => Redactor,
-	layerRedactor: () => layerRedactor,
 	redactText: () => redactText,
 	redactValue: () => redactValue
 });
-var Redactor = class extends Context.Service()("@devstack-rewrite/substrate/Redactor") {};
 const DEFAULT_REPLACEMENT = "<redacted>";
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/** A non-global pattern redacts only its FIRST match — every later
+*  occurrence leaks. Force the global flag so all occurrences are
+*  redacted; clone (don't mutate the caller's RegExp) and preserve any
+*  unicode flag. Already-global patterns pass through untouched so we
+*  don't double-apply. */
+const asGlobalPattern = (pattern) => pattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`);
 const redactText = (text, rules) => {
 	let next = text;
 	for (const rule of rules) {
@@ -17,7 +19,7 @@ const redactText = (text, rules) => {
 		if (rule.kind === "literal") {
 			if (rule.value.length === 0) continue;
 			next = next.replace(new RegExp(escapeRegExp(rule.value), "gu"), replacement);
-		} else next = next.replace(rule.pattern, replacement);
+		} else next = next.replace(asGlobalPattern(rule.pattern), replacement);
 	}
 	return next;
 };
@@ -31,15 +33,7 @@ const redactValue = (value, rules, visited = /* @__PURE__ */ new WeakSet()) => {
 	for (const [key, entry] of Object.entries(value)) out[key] = redactValue(entry, rules, visited);
 	return out;
 };
-const layerRedactor = Layer.effect(Redactor, Effect.gen(function* () {
-	const ref = yield* Ref.make([]);
-	return Redactor.of({
-		register: (rule) => Ref.update(ref, (rules) => [...rules, rule]),
-		redact: (text) => Ref.get(ref).pipe(Effect.map((rules) => redactText(text, rules))),
-		rules: Ref.get(ref)
-	});
-}));
 //#endregion
-export { Redactor, layerRedactor, redactText, redactValue, redaction_exports };
+export { redactText, redactValue, redaction_exports };
 
 //# sourceMappingURL=redaction.mjs.map

package/dist/substrate/runtime/observability/redaction.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"redaction.mjs","names":[],"sources":["../../../../src/substrate/runtime/observability/redaction.ts"],"sourcesContent":["import { Context, Effect, Layer, Ref } from 'effect';\n\nexport type RedactionRule =\n\t| {\n\t\t\treadonly kind: 'literal';\n\t\t\treadonly value: string;\n\t\t\treadonly replacement?: string;\n\t  }\n\t| {\n\t\t\treadonly kind: 'pattern';\n\t\t\treadonly pattern: RegExp;\n\t\t\treadonly replacement?: string;\n\t  };\n\nexport interface RedactorShape {\n\treadonly register: (rule: RedactionRule) => Effect.Effect<void>;\n\treadonly redact: (text: string) => Effect.Effect<string>;\n\treadonly rules: Effect.Effect<ReadonlyArray<RedactionRule>>;\n}\n\nexport class Redactor extends Context.Service<Redactor, RedactorShape>()(\n\t'@devstack-rewrite/substrate/Redactor',\n) {}\n\nconst DEFAULT_REPLACEMENT = '<redacted>';\n\nconst escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\\]\\\\]/gu, '\\\\$&');\n\nexport const redactText = (text: string, rules: ReadonlyArray<RedactionRule>): string => {\n\tlet next = text;\n\tfor (const rule of rules) {\n\t\tconst replacement = rule.replacement ?? DEFAULT_REPLACEMENT;\n\t\tif (rule.kind === 'literal') {\n\t\t\tif (rule.value.length === 0) continue;\n\t\t\tnext = next.replace(new RegExp(escapeRegExp(rule.value), 'gu'), replacement);\n\t\t} else {\n\t\t\tnext = next.replace(rule.pattern, replacement);\n\t\t}\n\t}\n\treturn next;\n};\n\nexport const redactValue = (\n\tvalue: unknown,\n\trules: ReadonlyArray<RedactionRule>,\n\tvisited: WeakSet<object> = new WeakSet(),\n): unknown => {\n\tif (typeof value === 'string') return redactText(value, rules);\n\tif (typeof value !== 'object' || value === null) return value;\n\tif (visited.has(value)) return value;\n\tvisited.add(value);\n\tif (Array.isArray(value)) return value.map((entry) => redactValue(entry, rules, visited));\n\tconst out: Record<string, unknown> = {};\n\tfor (const [key, entry] of Object.entries(value)) {\n\t\tout[key] = redactValue(entry, rules, visited);\n\t}\n\treturn out;\n};\n\nexport const layerRedactor: Layer.Layer<Redactor> = Layer.effect(\n\tRedactor,\n\tEffect.gen(function* () {\n\t\tconst ref = yield* Ref.make<ReadonlyArray<RedactionRule>>([]);\n\t\treturn Redactor.of({\n\t\t\tregister: (rule) => Ref.update(ref, (rules) => [...rules, rule]),\n\t\t\tredact: (text) => Ref.get(ref).pipe(Effect.map((rules) => redactText(text, rules))),\n\t\t\trules: Ref.get(ref),\n\t\t});\n\t}),\n);\n"],"mappings":";;;;;;;;;AAoBA,IAAa,WAAb,cAA8B,QAAQ,SAAkC,CACvE,uCACA,CAAC;AAEF,MAAM,sBAAsB;AAE5B,MAAM,gBAAgB,UAA0B,MAAM,QAAQ,wBAAwB,OAAO;AAE7F,MAAa,cAAc,MAAc,UAAgD;CACxF,IAAI,OAAO;AACX,MAAK,MAAM,QAAQ,OAAO;EACzB,MAAM,cAAc,KAAK,eAAe;AACxC,MAAI,KAAK,SAAS,WAAW;AAC5B,OAAI,KAAK,MAAM,WAAW,EAAG;AAC7B,UAAO,KAAK,QAAQ,IAAI,OAAO,aAAa,KAAK,MAAM,EAAE,KAAK,EAAE,YAAY;QAE5E,QAAO,KAAK,QAAQ,KAAK,SAAS,YAAY;;AAGhD,QAAO;;AAGR,MAAa,eACZ,OACA,OACA,0BAA2B,IAAI,SAAS,KAC3B;AACb,KAAI,OAAO,UAAU,SAAU,QAAO,WAAW,OAAO,MAAM;AAC9D,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,KAAI,QAAQ,IAAI,MAAM,CAAE,QAAO;AAC/B,SAAQ,IAAI,MAAM;AAClB,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,MAAM,KAAK,UAAU,YAAY,OAAO,OAAO,QAAQ,CAAC;CACzF,MAAM,MAA+B,EAAE;AACvC,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,CAC/C,KAAI,OAAO,YAAY,OAAO,OAAO,QAAQ;AAE9C,QAAO;;AAGR,MAAa,gBAAuC,MAAM,OACzD,UACA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,OAAO,IAAI,KAAmC,EAAE,CAAC;AAC7D,QAAO,SAAS,GAAG;EAClB,WAAW,SAAS,IAAI,OAAO,MAAM,UAAU,CAAC,GAAG,OAAO,KAAK,CAAC;EAChE,SAAS,SAAS,IAAI,IAAI,IAAI,CAAC,KAAK,OAAO,KAAK,UAAU,WAAW,MAAM,MAAM,CAAC,CAAC;EACnF,OAAO,IAAI,IAAI,IAAI;EACnB,CAAC;EACD,CACF"}
+{"version":3,"file":"redaction.mjs","names":[],"sources":["../../../../src/substrate/runtime/observability/redaction.ts"],"sourcesContent":["// Pure redaction helpers. These back the inline plugin-level redaction\n// in seal (`redactMasterKey`) and wallet (`redactToken`), and the\n// cascade-formatter's `safeJson` field scrubbing. There is intentionally\n// no engine-wide Redactor service: plugins that surface secret-bearing\n// output defend themselves at the point of emission with a local rule\n// set, which keeps the rules co-located with the thing they protect.\n\nexport type RedactionRule =\n\t| {\n\t\t\treadonly kind: 'literal';\n\t\t\treadonly value: string;\n\t\t\treadonly replacement?: string;\n\t  }\n\t| {\n\t\t\treadonly kind: 'pattern';\n\t\t\treadonly pattern: RegExp;\n\t\t\treadonly replacement?: string;\n\t  };\n\nconst DEFAULT_REPLACEMENT = '<redacted>';\n\nconst escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\\]\\\\]/gu, '\\\\$&');\n\n/** A non-global pattern redacts only its FIRST match — every later\n *  occurrence leaks. Force the global flag so all occurrences are\n *  redacted; clone (don't mutate the caller's RegExp) and preserve any\n *  unicode flag. Already-global patterns pass through untouched so we\n *  don't double-apply. */\nconst asGlobalPattern = (pattern: RegExp): RegExp =>\n\tpattern.global ? pattern : new RegExp(pattern.source, `${pattern.flags}g`);\n\nexport const redactText = (text: string, rules: ReadonlyArray<RedactionRule>): string => {\n\tlet next = text;\n\tfor (const rule of rules) {\n\t\tconst replacement = rule.replacement ?? DEFAULT_REPLACEMENT;\n\t\tif (rule.kind === 'literal') {\n\t\t\tif (rule.value.length === 0) continue;\n\t\t\tnext = next.replace(new RegExp(escapeRegExp(rule.value), 'gu'), replacement);\n\t\t} else {\n\t\t\tnext = next.replace(asGlobalPattern(rule.pattern), replacement);\n\t\t}\n\t}\n\treturn next;\n};\n\nexport const redactValue = (\n\tvalue: unknown,\n\trules: ReadonlyArray<RedactionRule>,\n\tvisited: WeakSet<object> = new WeakSet(),\n): unknown => {\n\tif (typeof value === 'string') return redactText(value, rules);\n\tif (typeof value !== 'object' || value === null) return value;\n\tif (visited.has(value)) return value;\n\tvisited.add(value);\n\tif (Array.isArray(value)) return value.map((entry) => redactValue(entry, rules, visited));\n\tconst out: Record<string, unknown> = {};\n\tfor (const [key, entry] of Object.entries(value)) {\n\t\tout[key] = redactValue(entry, rules, visited);\n\t}\n\treturn out;\n};\n"],"mappings":";;;;;;AAmBA,MAAM,sBAAsB;AAE5B,MAAM,gBAAgB,UAA0B,MAAM,QAAQ,wBAAwB,OAAO;;;;;;AAO7F,MAAM,mBAAmB,YACxB,QAAQ,SAAS,UAAU,IAAI,OAAO,QAAQ,QAAQ,GAAG,QAAQ,MAAM,GAAG;AAE3E,MAAa,cAAc,MAAc,UAAgD;CACxF,IAAI,OAAO;AACX,MAAK,MAAM,QAAQ,OAAO;EACzB,MAAM,cAAc,KAAK,eAAe;AACxC,MAAI,KAAK,SAAS,WAAW;AAC5B,OAAI,KAAK,MAAM,WAAW,EAAG;AAC7B,UAAO,KAAK,QAAQ,IAAI,OAAO,aAAa,KAAK,MAAM,EAAE,KAAK,EAAE,YAAY;QAE5E,QAAO,KAAK,QAAQ,gBAAgB,KAAK,QAAQ,EAAE,YAAY;;AAGjE,QAAO;;AAGR,MAAa,eACZ,OACA,OACA,0BAA2B,IAAI,SAAS,KAC3B;AACb,KAAI,OAAO,UAAU,SAAU,QAAO,WAAW,OAAO,MAAM;AAC9D,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,KAAI,QAAQ,IAAI,MAAM,CAAE,QAAO;AAC/B,SAAQ,IAAI,MAAM;AAClB,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,MAAM,KAAK,UAAU,YAAY,OAAO,OAAO,QAAQ,CAAC;CACzF,MAAM,MAA+B,EAAE;AACvC,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,CAC/C,KAAI,OAAO,YAAY,OAAO,OAAO,QAAQ;AAE9C,QAAO"}

package/dist/substrate/runtime/observability/span-store.d.mts

@@ -0,0 +1 @@
+import { Context, Effect, Layer, Tracer } from "effect";

package/dist/substrate/runtime/observability/span-store.mjs

@@ -0,0 +1,110 @@
+import { SpanAttr } from "./spans.mjs";
+import { Context, Effect, Exit, Layer, Option, Tracer } from "effect";
+//#region src/substrate/runtime/observability/span-store.ts
+/** Completed-span retention. Bounded so a long-lived stack stays flat. */
+const DEFAULT_SPAN_CAPACITY = 2e3;
+var SpanStore = class extends Context.Service()("@devstack/substrate/SpanStore") {};
+const pushRecord = (ring, record) => {
+	ring.records.push(record);
+	if (ring.records.length > ring.capacity) ring.records.shift();
+};
+const NANOS_PER_MILLI = 1000000n;
+const nanosToMillis = (n) => Number(n / NANOS_PER_MILLI);
+/** Derive the dashboard `service` for a span: prefer the canonical
+*  `devstack.plugin` attribute, else fall back to the span name. Plugin
+*  spans without the attribute use the dotted `devstack.plugin.<name>.…`
+*  convention, so we special-case that prefix to recover `<name>` (e.g.
+*  `devstack.plugin.postgres.acquire` → `postgres`) instead of bucketing
+*  every plugin span under the shared `devstack` head. Other namespaced
+*  spans fall back to the leading dotted/slashed segment
+*  (`lifecycle.supervisor.runCommand` → `lifecycle`). `null` when neither
+*  is informative. */
+const PLUGIN_SPAN_PREFIX = "devstack.plugin.";
+const deriveService = (name, attributes) => {
+	const plugin = attributes.get(SpanAttr.plugin);
+	if (typeof plugin === "string" && plugin.length > 0) return plugin;
+	if (name.startsWith(PLUGIN_SPAN_PREFIX)) {
+		const pluginName = name.slice(16).split(/[./]/, 1)[0];
+		if (pluginName !== void 0 && pluginName.length > 0) return pluginName;
+	}
+	const head = name.split(/[./]/, 1)[0];
+	return head !== void 0 && head.length > 0 && head !== name ? head : null;
+};
+const flattenAttributes = (attributes) => {
+	const out = {};
+	for (const [k, v] of attributes) out[k] = typeof v === "string" ? v : String(v);
+	return out;
+};
+/** Build the recording span from the native span at end time. */
+const recordFrom = (span, endTime, exit) => {
+	const parent = Option.getOrUndefined(span.parent);
+	const startMillis = nanosToMillis(span.startTime);
+	return {
+		traceId: span.traceId,
+		spanId: span.spanId,
+		parentId: parent?.spanId ?? null,
+		name: span.name,
+		service: deriveService(span.name, span.attributes),
+		startMillis,
+		durationMillis: Math.max(0, nanosToMillis(endTime) - startMillis),
+		status: Exit.isSuccess(exit) ? "ok" : "error",
+		attributes: flattenAttributes(span.attributes)
+	};
+};
+/** A `Tracer` that builds Effect's `NativeSpan` (so parent/trace propagation
+*  and attribute capture behave exactly like the default) and records each
+*  span into `ring` when it ends. */
+const recordingTracer = (ring) => Tracer.make({ span: (options) => {
+	const span = new Tracer.NativeSpan(options);
+	const originalEnd = span.end.bind(span);
+	span.end = (endTime, exit) => {
+		originalEnd(endTime, exit);
+		try {
+			pushRecord(ring, recordFrom(span, endTime, exit));
+		} catch {}
+	};
+	return span;
+} });
+/** Build a `SpanStoreShape` over a fresh ring. The supervisor calls this so
+*  the ring is process-scoped. `capacity` is injectable for tests. */
+const makeSpanStore = (capacity = DEFAULT_SPAN_CAPACITY) => Effect.sync(() => {
+	const ring = {
+		records: [],
+		capacity
+	};
+	const query = (filter) => Effect.sync(() => applySpanFilter(ring.records, filter, capacity));
+	const services = Effect.sync(() => {
+		const seen = /* @__PURE__ */ new Set();
+		for (const r of ring.records) if (r.service !== null) seen.add(r.service);
+		return [...seen].sort();
+	});
+	return SpanStore.of({
+		query,
+		services,
+		tracer: recordingTracer(ring)
+	});
+});
+/** Pure filter application — exported for tests. Stored oldest-first; we
+*  return newest-first and cap to `limit`. */
+const applySpanFilter = (records, filter, capacity) => {
+	const serviceSet = filter?.services && filter.services.length > 0 ? new Set(filter.services) : null;
+	const statusSet = filter?.statuses && filter.statuses.length > 0 ? new Set(filter.statuses) : null;
+	const search = filter?.search?.trim().toLowerCase();
+	const since = filter?.sinceMillis;
+	const limit = filter?.limit ?? capacity;
+	const out = [];
+	for (let i = records.length - 1; i >= 0 && out.length < limit; i -= 1) {
+		const r = records[i];
+		if (serviceSet !== null && (r.service === null || !serviceSet.has(r.service))) continue;
+		if (statusSet !== null && !statusSet.has(r.status)) continue;
+		if (since !== void 0 && r.startMillis < since) continue;
+		if (search !== void 0 && search.length > 0 && !r.name.toLowerCase().includes(search) && !(r.service ?? "").toLowerCase().includes(search)) continue;
+		out.push(r);
+	}
+	return out;
+};
+Layer.effect(SpanStore, makeSpanStore());
+//#endregion
+export { DEFAULT_SPAN_CAPACITY, SpanStore, applySpanFilter, makeSpanStore };
+
+//# sourceMappingURL=span-store.mjs.map

package/dist/substrate/runtime/observability/span-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-store.mjs","names":[],"sources":["../../../../src/substrate/runtime/observability/span-store.ts"],"sourcesContent":["// Completed-span ring + recording Tracer.\n//\n// Devstack emits spans with `Effect.withSpan` all over the substrate\n// (`acquire-node`, command names, background tasks, teardown, http handlers,\n// …) carrying the canonical `devstack.*` attributes (see spans.ts). Until\n// now no `Tracer` was provided, so those spans hit Effect's default no-op\n// native tracer and evaporated — the dashboard's \"Traces\" tab had nothing to\n// read.\n//\n// This module provides a minimal RECORDING tracer: it wraps Effect's\n// `NativeSpan` and, when a span ends, projects it into a bounded ring the\n// dashboard can query. The tracer is a drop-in for the default native tracer\n// (it still produces real `Span` objects with parent/trace ids, so span\n// propagation and any future OTel layer keep working) — it just also pushes\n// the completed span into the ring on `end()`.\n//\n// Hot-path discipline: `span()` allocates one `NativeSpan` (same as the\n// default). `end()` does one synchronous array push + bounded trim via a\n// direct mutable array — NO Effect/Ref round-trip on the hot path, since\n// `Tracer.span` / `Span.end` are synchronous and run on the fiber's critical\n// path. The ring is a plain object captured in the closure; reads go through\n// an Effect accessor for the service surface.\n//\n// Process-scoped: the ring object is created in the supervisor alongside the\n// log store, so it survives `stack.restart`.\n\nimport { Context, Effect, Exit, Layer, Option, Tracer } from 'effect';\n\nimport { SpanAttr } from './spans.ts';\n\n// -----------------------------------------------------------------------------\n// Record shape\n// -----------------------------------------------------------------------------\n\n/** One completed span. Plain data; the dashboard schema projects it\n *  directly. `op` is the span name; `service` is derived from the\n *  `devstack.plugin` attribute (falling back to the span name's leading\n *  segment). */\nexport interface SpanRecord {\n\treadonly traceId: string;\n\treadonly spanId: string;\n\treadonly parentId: string | null;\n\t/** Span name / operation (`acquire-node`, `lifecycle.supervisor.runCommand`, …). */\n\treadonly name: string;\n\t/** `devstack.plugin` attribute when present, else `null`. */\n\treadonly service: string | null;\n\treadonly startMillis: number;\n\treadonly durationMillis: number;\n\treadonly status: 'ok' | 'error';\n\t/** Flattened span attributes (string-coerced values). */\n\treadonly attributes: Readonly<Record<string, string>>;\n}\n\n/** Server-side span filter. Every field optional. */\nexport interface SpanFilter {\n\t/** Keep only spans whose derived `service` is in this set. */\n\treadonly services?: ReadonlyArray<string>;\n\t/** Keep only spans with one of these statuses. */\n\treadonly statuses?: ReadonlyArray<'ok' | 'error'>;\n\t/** Case-insensitive substring match against the span name (and service). */\n\treadonly search?: string;\n\t/** Keep only spans that STARTED at/after this epoch-ms. */\n\treadonly sinceMillis?: number;\n\t/** Cap on returned spans (most recent first). */\n\treadonly limit?: number;\n}\n\n// -----------------------------------------------------------------------------\n// Capacity policy\n// -----------------------------------------------------------------------------\n\n/** Completed-span retention. Bounded so a long-lived stack stays flat. */\nexport const DEFAULT_SPAN_CAPACITY = 2000;\n\n// -----------------------------------------------------------------------------\n// Service\n// -----------------------------------------------------------------------------\n\nexport interface SpanStoreShape {\n\t/** Query the ring with a filter (most-recent-first). Never fails. */\n\treadonly query: (filter?: SpanFilter) => Effect.Effect<ReadonlyArray<SpanRecord>>;\n\t/** Distinct derived service keys currently in the ring. */\n\treadonly services: Effect.Effect<ReadonlyArray<string>>;\n\t/** The recording `Tracer` to provide into the supervisor's effect\n\t *  context. Wraps Effect's native tracer; records on span `end()`. */\n\treadonly tracer: Tracer.Tracer;\n}\n\nexport class SpanStore extends Context.Service<SpanStore, SpanStoreShape>()(\n\t'@devstack/substrate/SpanStore',\n) {}\n\n// -----------------------------------------------------------------------------\n// Plain mutable ring (hot-path-cheap; no Ref round-trip in `end()`)\n// -----------------------------------------------------------------------------\n\ninterface Ring {\n\trecords: SpanRecord[];\n\treadonly capacity: number;\n}\n\nconst pushRecord = (ring: Ring, record: SpanRecord): void => {\n\tring.records.push(record);\n\tif (ring.records.length > ring.capacity) {\n\t\t// Drop the oldest. `shift` is O(n) but spans complete far slower than\n\t\t// logs and the capacity is bounded; keep it simple over a head index.\n\t\tring.records.shift();\n\t}\n};\n\nconst NANOS_PER_MILLI = 1_000_000n;\nconst nanosToMillis = (n: bigint): number => Number(n / NANOS_PER_MILLI);\n\n/** Derive the dashboard `service` for a span: prefer the canonical\n *  `devstack.plugin` attribute, else fall back to the span name. Plugin\n *  spans without the attribute use the dotted `devstack.plugin.<name>.…`\n *  convention, so we special-case that prefix to recover `<name>` (e.g.\n *  `devstack.plugin.postgres.acquire` → `postgres`) instead of bucketing\n *  every plugin span under the shared `devstack` head. Other namespaced\n *  spans fall back to the leading dotted/slashed segment\n *  (`lifecycle.supervisor.runCommand` → `lifecycle`). `null` when neither\n *  is informative. */\nconst PLUGIN_SPAN_PREFIX = 'devstack.plugin.';\nconst deriveService = (name: string, attributes: ReadonlyMap<string, unknown>): string | null => {\n\tconst plugin = attributes.get(SpanAttr.plugin);\n\tif (typeof plugin === 'string' && plugin.length > 0) return plugin;\n\tif (name.startsWith(PLUGIN_SPAN_PREFIX)) {\n\t\t// `devstack.plugin.<name>.<op>` → `<name>` (the segment after the prefix).\n\t\tconst rest = name.slice(PLUGIN_SPAN_PREFIX.length);\n\t\tconst pluginName = rest.split(/[./]/, 1)[0];\n\t\tif (pluginName !== undefined && pluginName.length > 0) return pluginName;\n\t}\n\tconst head = name.split(/[./]/, 1)[0];\n\treturn head !== undefined && head.length > 0 && head !== name ? head : null;\n};\n\nconst flattenAttributes = (attributes: ReadonlyMap<string, unknown>): Record<string, string> => {\n\tconst out: Record<string, string> = {};\n\tfor (const [k, v] of attributes) {\n\t\tout[k] = typeof v === 'string' ? v : String(v);\n\t}\n\treturn out;\n};\n\n/** Build the recording span from the native span at end time. */\nconst recordFrom = (\n\tspan: Tracer.NativeSpan,\n\tendTime: bigint,\n\texit: Exit.Exit<unknown, unknown>,\n): SpanRecord => {\n\tconst parent = Option.getOrUndefined(span.parent);\n\tconst startMillis = nanosToMillis(span.startTime);\n\treturn {\n\t\ttraceId: span.traceId,\n\t\tspanId: span.spanId,\n\t\tparentId: parent?.spanId ?? null,\n\t\tname: span.name,\n\t\tservice: deriveService(span.name, span.attributes),\n\t\tstartMillis,\n\t\tdurationMillis: Math.max(0, nanosToMillis(endTime) - startMillis),\n\t\tstatus: Exit.isSuccess(exit) ? 'ok' : 'error',\n\t\tattributes: flattenAttributes(span.attributes),\n\t};\n};\n\n/** A `Tracer` that builds Effect's `NativeSpan` (so parent/trace propagation\n *  and attribute capture behave exactly like the default) and records each\n *  span into `ring` when it ends. */\nconst recordingTracer = (ring: Ring): Tracer.Tracer =>\n\tTracer.make({\n\t\tspan: (options) => {\n\t\t\tconst span = new Tracer.NativeSpan(options);\n\t\t\tconst originalEnd = span.end.bind(span);\n\t\t\tspan.end = (endTime, exit) => {\n\t\t\t\toriginalEnd(endTime, exit);\n\t\t\t\t// Guard: recording must never break tracing.\n\t\t\t\ttry {\n\t\t\t\t\tpushRecord(ring, recordFrom(span, endTime, exit));\n\t\t\t\t} catch {\n\t\t\t\t\t/* swallow — observability is best-effort */\n\t\t\t\t}\n\t\t\t};\n\t\t\treturn span;\n\t\t},\n\t});\n\n/** Build a `SpanStoreShape` over a fresh ring. The supervisor calls this so\n *  the ring is process-scoped. `capacity` is injectable for tests. */\nexport const makeSpanStore = (\n\tcapacity: number = DEFAULT_SPAN_CAPACITY,\n): Effect.Effect<SpanStoreShape> =>\n\tEffect.sync(() => {\n\t\tconst ring: Ring = { records: [], capacity };\n\n\t\tconst query: SpanStoreShape['query'] = (filter) =>\n\t\t\tEffect.sync(() => applySpanFilter(ring.records, filter, capacity));\n\n\t\tconst services: SpanStoreShape['services'] = Effect.sync(() => {\n\t\t\tconst seen = new Set<string>();\n\t\t\tfor (const r of ring.records) if (r.service !== null) seen.add(r.service);\n\t\t\treturn [...seen].sort();\n\t\t});\n\n\t\treturn SpanStore.of({ query, services, tracer: recordingTracer(ring) });\n\t});\n\n/** Pure filter application — exported for tests. Stored oldest-first; we\n *  return newest-first and cap to `limit`. */\nexport const applySpanFilter = (\n\trecords: ReadonlyArray<SpanRecord>,\n\tfilter: SpanFilter | undefined,\n\tcapacity: number,\n): ReadonlyArray<SpanRecord> => {\n\tconst serviceSet =\n\t\tfilter?.services && filter.services.length > 0 ? new Set(filter.services) : null;\n\tconst statusSet =\n\t\tfilter?.statuses && filter.statuses.length > 0 ? new Set(filter.statuses) : null;\n\tconst search = filter?.search?.trim().toLowerCase();\n\tconst since = filter?.sinceMillis;\n\tconst limit = filter?.limit ?? capacity;\n\n\tconst out: SpanRecord[] = [];\n\tfor (let i = records.length - 1; i >= 0 && out.length < limit; i -= 1) {\n\t\tconst r = records[i]!;\n\t\tif (serviceSet !== null && (r.service === null || !serviceSet.has(r.service))) continue;\n\t\tif (statusSet !== null && !statusSet.has(r.status)) continue;\n\t\tif (since !== undefined && r.startMillis < since) continue;\n\t\tif (\n\t\t\tsearch !== undefined &&\n\t\t\tsearch.length > 0 &&\n\t\t\t!r.name.toLowerCase().includes(search) &&\n\t\t\t!(r.service ?? '').toLowerCase().includes(search)\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tout.push(r);\n\t}\n\treturn out;\n};\n\n/** Layer form (default capacity) for callers that want the store via a Layer. */\nexport const layerSpanStore: Layer.Layer<SpanStore> = Layer.effect(SpanStore, makeSpanStore());\n"],"mappings":";;;;AAwEA,MAAa,wBAAwB;AAgBrC,IAAa,YAAb,cAA+B,QAAQ,SAAoC,CAC1E,gCACA,CAAC;AAWF,MAAM,cAAc,MAAY,WAA6B;AAC5D,MAAK,QAAQ,KAAK,OAAO;AACzB,KAAI,KAAK,QAAQ,SAAS,KAAK,SAG9B,MAAK,QAAQ,OAAO;;AAItB,MAAM,kBAAkB;AACxB,MAAM,iBAAiB,MAAsB,OAAO,IAAI,gBAAgB;;;;;;;;;;AAWxE,MAAM,qBAAqB;AAC3B,MAAM,iBAAiB,MAAc,eAA4D;CAChG,MAAM,SAAS,WAAW,IAAI,SAAS,OAAO;AAC9C,KAAI,OAAO,WAAW,YAAY,OAAO,SAAS,EAAG,QAAO;AAC5D,KAAI,KAAK,WAAW,mBAAmB,EAAE;EAGxC,MAAM,aADO,KAAK,MAAM,GACD,CAAC,MAAM,QAAQ,EAAE,CAAC;AACzC,MAAI,eAAe,KAAA,KAAa,WAAW,SAAS,EAAG,QAAO;;CAE/D,MAAM,OAAO,KAAK,MAAM,QAAQ,EAAE,CAAC;AACnC,QAAO,SAAS,KAAA,KAAa,KAAK,SAAS,KAAK,SAAS,OAAO,OAAO;;AAGxE,MAAM,qBAAqB,eAAqE;CAC/F,MAAM,MAA8B,EAAE;AACtC,MAAK,MAAM,CAAC,GAAG,MAAM,WACpB,KAAI,KAAK,OAAO,MAAM,WAAW,IAAI,OAAO,EAAE;AAE/C,QAAO;;;AAIR,MAAM,cACL,MACA,SACA,SACgB;CAChB,MAAM,SAAS,OAAO,eAAe,KAAK,OAAO;CACjD,MAAM,cAAc,cAAc,KAAK,UAAU;AACjD,QAAO;EACN,SAAS,KAAK;EACd,QAAQ,KAAK;EACb,UAAU,QAAQ,UAAU;EAC5B,MAAM,KAAK;EACX,SAAS,cAAc,KAAK,MAAM,KAAK,WAAW;EAClD;EACA,gBAAgB,KAAK,IAAI,GAAG,cAAc,QAAQ,GAAG,YAAY;EACjE,QAAQ,KAAK,UAAU,KAAK,GAAG,OAAO;EACtC,YAAY,kBAAkB,KAAK,WAAW;EAC9C;;;;;AAMF,MAAM,mBAAmB,SACxB,OAAO,KAAK,EACX,OAAO,YAAY;CAClB,MAAM,OAAO,IAAI,OAAO,WAAW,QAAQ;CAC3C,MAAM,cAAc,KAAK,IAAI,KAAK,KAAK;AACvC,MAAK,OAAO,SAAS,SAAS;AAC7B,cAAY,SAAS,KAAK;AAE1B,MAAI;AACH,cAAW,MAAM,WAAW,MAAM,SAAS,KAAK,CAAC;UAC1C;;AAIT,QAAO;GAER,CAAC;;;AAIH,MAAa,iBACZ,WAAmB,0BAEnB,OAAO,WAAW;CACjB,MAAM,OAAa;EAAE,SAAS,EAAE;EAAE;EAAU;CAE5C,MAAM,SAAkC,WACvC,OAAO,WAAW,gBAAgB,KAAK,SAAS,QAAQ,SAAS,CAAC;CAEnE,MAAM,WAAuC,OAAO,WAAW;EAC9D,MAAM,uBAAO,IAAI,KAAa;AAC9B,OAAK,MAAM,KAAK,KAAK,QAAS,KAAI,EAAE,YAAY,KAAM,MAAK,IAAI,EAAE,QAAQ;AACzE,SAAO,CAAC,GAAG,KAAK,CAAC,MAAM;GACtB;AAEF,QAAO,UAAU,GAAG;EAAE;EAAO;EAAU,QAAQ,gBAAgB,KAAK;EAAE,CAAC;EACtE;;;AAIH,MAAa,mBACZ,SACA,QACA,aAC+B;CAC/B,MAAM,aACL,QAAQ,YAAY,OAAO,SAAS,SAAS,IAAI,IAAI,IAAI,OAAO,SAAS,GAAG;CAC7E,MAAM,YACL,QAAQ,YAAY,OAAO,SAAS,SAAS,IAAI,IAAI,IAAI,OAAO,SAAS,GAAG;CAC7E,MAAM,SAAS,QAAQ,QAAQ,MAAM,CAAC,aAAa;CACnD,MAAM,QAAQ,QAAQ;CACtB,MAAM,QAAQ,QAAQ,SAAS;CAE/B,MAAM,MAAoB,EAAE;AAC5B,MAAK,IAAI,IAAI,QAAQ,SAAS,GAAG,KAAK,KAAK,IAAI,SAAS,OAAO,KAAK,GAAG;EACtE,MAAM,IAAI,QAAQ;AAClB,MAAI,eAAe,SAAS,EAAE,YAAY,QAAQ,CAAC,WAAW,IAAI,EAAE,QAAQ,EAAG;AAC/E,MAAI,cAAc,QAAQ,CAAC,UAAU,IAAI,EAAE,OAAO,CAAE;AACpD,MAAI,UAAU,KAAA,KAAa,EAAE,cAAc,MAAO;AAClD,MACC,WAAW,KAAA,KACX,OAAO,SAAS,KAChB,CAAC,EAAE,KAAK,aAAa,CAAC,SAAS,OAAO,IACtC,EAAE,EAAE,WAAW,IAAI,aAAa,CAAC,SAAS,OAAO,CAEjD;AAED,MAAI,KAAK,EAAE;;AAEZ,QAAO;;AAI8C,MAAM,OAAO,WAAW,eAAe,CAAC"}

package/dist/substrate/runtime/observability/spans.mjs

@@ -1,15 +1,12 @@
+import "../paths.mjs";
 import { Effect } from "effect";
 //#region src/substrate/runtime/observability/spans.ts
-/** Canonical span-attribute keys. Single source of truth for the
-*  observability vocabulary. */
+/** Canonical span-attribute keys. Engine-dimensional + http/process
+*  generic only. Plugin-domain keys belong on per-plugin `spans.ts`. */
 const SpanAttr = {
-	accountFundingFrom: "account.funding.from",
-	accountFundingTo: "account.funding.to",
-	accountName: "account.name",
 	app: "devstack.app",
 	stack: "devstack.stack",
 	network: "devstack.network",
-	coinType: "coin.type",
 	plugin: "devstack.plugin",
 	role: "devstack.role",
 	phase: "devstack.phase",
@@ -36,14 +33,17 @@ const SpanAttr = {
 	serviceName: "devstack.service.name",
 	stageAndSwapStagingPath: "stageAndSwap.stagingPath",
 	stageAndSwapTargetPath: "stageAndSwap.targetPath",
-	suiAutoTickIntervalMs: "sui.autoTick.intervalMs",
-	suiMode: "sui.mode",
-	walletToken: "wallet.token",
-	walletBearerValid: "wallet.auth.bearerValid",
-	walletLocalhostViteEnabled: "wallet.localhostViteEnabled",
-	walletOrigin: "wallet.origin",
-	walletTokenFile: "wallet.tokenFile",
-	walletUrl: "wallet.url"
+	cacheCorruption: "cache.corruption",
+	capabilitySinksKind: "capability-sinks.kind",
+	strategyKey: "strategy.key",
+	strategyAutoMounted: "strategy.autoMounted",
+	artifactPublisherNamespace: "artifactPublisher.namespace",
+	artifactPublisherChain: "artifactPublisher.chain",
+	artifactPublisherContentHash: "artifactPublisher.contentHash",
+	artifactPublisherPath: "artifactPublisher.path",
+	stackLockPath: "devstack.stack-lock.path",
+	stackLockTimeoutMillis: "devstack.stack-lock.timeoutMillis",
+	snapshotReservationPath: "devstack.snapshot-reservation.path"
 };
 /**
 * Wrap an Effect in a stack-scoped span. Sets `devstack.app`,

package/dist/substrate/runtime/observability/spans.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"spans.mjs","names":[],"sources":["../../../../src/substrate/runtime/observability/spans.ts"],"sourcesContent":["// Span propagation wrappers.\n//\n// Architecture § L0 Observability: \"span/annotation conventions\".\n// Centralises the attribute keys so every wrapped span uses the same\n// vocabulary — OTEL consumers can filter by `devstack.app`,\n// `devstack.stack`, `devstack.plugin`, `devstack.role` reliably.\n//\n// Discipline: no service names appear anywhere; only the four\n// engine-level dimensions. Plugins call `withPluginSpan` and pass\n// their `pluginKey` + `role`.\n\nimport { Effect } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { PluginRole } from '../../lifecycle.ts';\n\n/** Canonical span-attribute keys. Single source of truth for the\n *  observability vocabulary. */\nexport const SpanAttr = {\n\taccountFundingFrom: 'account.funding.from',\n\taccountFundingTo: 'account.funding.to',\n\taccountName: 'account.name',\n\tapp: 'devstack.app',\n\tstack: 'devstack.stack',\n\tnetwork: 'devstack.network',\n\tcoinType: 'coin.type',\n\tplugin: 'devstack.plugin',\n\trole: 'devstack.role',\n\tphase: 'devstack.phase',\n\tcontainerName: 'container.name',\n\tcontainerRole: 'container.role',\n\tevent: 'event.name',\n\terrorCode: 'error.code',\n\terrorCause: 'error.cause',\n\terrorMessage: 'error.message',\n\texitCode: 'process.exit.code',\n\texitSignal: 'process.exit.signal',\n\texitStatus: 'process.exit.status',\n\tendpointKey: 'devstack.endpoint.key',\n\thttpMethod: 'http.method',\n\thttpPath: 'http.path',\n\thttpUrl: 'http.url',\n\thost: 'server.address',\n\tlogTag: 'log.tag',\n\tport: 'server.port',\n\tcycleId: 'devstack.cycle.id',\n\top: 'devstack.op',\n\trequestId: 'devstack.request.id',\n\trosterHeartbeatIntervalMs: 'roster.heartbeat.intervalMs',\n\tserviceName: 'devstack.service.name',\n\tstageAndSwapStagingPath: 'stageAndSwap.stagingPath',\n\tstageAndSwapTargetPath: 'stageAndSwap.targetPath',\n\tsuiAutoTickIntervalMs: 'sui.autoTick.intervalMs',\n\tsuiMode: 'sui.mode',\n\twalletToken: 'wallet.token',\n\twalletBearerValid: 'wallet.auth.bearerValid',\n\twalletLocalhostViteEnabled: 'wallet.localhostViteEnabled',\n\twalletOrigin: 'wallet.origin',\n\twalletTokenFile: 'wallet.tokenFile',\n\twalletUrl: 'wallet.url',\n} as const;\n\nexport interface StackSpanContext {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly network: string;\n}\n\nexport interface PluginSpanContext extends StackSpanContext {\n\treadonly pluginKey: PluginKey;\n\treadonly role: PluginRole;\n}\n\n/**\n * Wrap an Effect in a stack-scoped span. Sets `devstack.app`,\n * `devstack.stack`, `devstack.network` attributes. Use at the\n * top-level engine entry points (boot, cycle start, supervisor\n * loop) — not inside per-plugin code (use `withPluginSpan` for that).\n */\nexport const withStackSpan =\n\t(name: string, ctx: StackSpanContext) =>\n\t<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n\t\teffect.pipe(\n\t\t\tEffect.withSpan(name, {\n\t\t\t\tattributes: {\n\t\t\t\t\t[SpanAttr.app]: ctx.app,\n\t\t\t\t\t[SpanAttr.stack]: ctx.stack,\n\t\t\t\t\t[SpanAttr.network]: ctx.network,\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n\n/**\n * Wrap an Effect in a plugin-scoped span. Inherits stack identity from\n * the surrounding Context (callers should compose with\n * `withStackSpan` at the top so the stack identity propagates).\n */\nexport const withPluginSpan =\n\t(name: string, ctx: PluginSpanContext) =>\n\t<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n\t\teffect.pipe(\n\t\t\tEffect.withSpan(name, {\n\t\t\t\tattributes: {\n\t\t\t\t\t[SpanAttr.app]: ctx.app,\n\t\t\t\t\t[SpanAttr.stack]: ctx.stack,\n\t\t\t\t\t[SpanAttr.network]: ctx.network,\n\t\t\t\t\t[SpanAttr.plugin]: ctx.pluginKey,\n\t\t\t\t\t[SpanAttr.role]: ctx.role,\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n\n/**\n * Annotate the current span with a phase marker. Cheap; safe to call\n * from anywhere. Used by the supervisor when transitioning a plugin\n * through acquire phases so the OTEL trace correlates with the\n * lifecycle stream.\n */\nexport const annotatePhase = (phase: string): Effect.Effect<void> =>\n\tEffect.annotateCurrentSpan({ [SpanAttr.phase]: phase });\n\n/**\n * Annotate the current span with the engine cycle id. Called once per\n * cycle at supervisor entry.\n */\nexport const annotateCycle = (cycleId: number): Effect.Effect<void> =>\n\tEffect.annotateCurrentSpan({ [SpanAttr.cycleId]: cycleId });\n\n/**\n * Annotate the current span with a subprocess `op` tag. Mirrors the\n * `CaptureError.op` field so a failure that originates in a captured\n * subprocess can be traced back to its span by `devstack.op`.\n */\nexport const annotateOp = (op: string): Effect.Effect<void> =>\n\tEffect.annotateCurrentSpan({ [SpanAttr.op]: op });\n"],"mappings":";;;;AAkBA,MAAa,WAAW;CACvB,oBAAoB;CACpB,kBAAkB;CAClB,aAAa;CACb,KAAK;CACL,OAAO;CACP,SAAS;CACT,UAAU;CACV,QAAQ;CACR,MAAM;CACN,OAAO;CACP,eAAe;CACf,eAAe;CACf,OAAO;CACP,WAAW;CACX,YAAY;CACZ,cAAc;CACd,UAAU;CACV,YAAY;CACZ,YAAY;CACZ,aAAa;CACb,YAAY;CACZ,UAAU;CACV,SAAS;CACT,MAAM;CACN,QAAQ;CACR,MAAM;CACN,SAAS;CACT,IAAI;CACJ,WAAW;CACX,2BAA2B;CAC3B,aAAa;CACb,yBAAyB;CACzB,wBAAwB;CACxB,uBAAuB;CACvB,SAAS;CACT,aAAa;CACb,mBAAmB;CACnB,4BAA4B;CAC5B,cAAc;CACd,iBAAiB;CACjB,WAAW;CACX;;;;;;;AAmBD,MAAa,iBACX,MAAc,SACL,WACT,OAAO,KACN,OAAO,SAAS,MAAM,EACrB,YAAY;EACV,SAAS,MAAM,IAAI;EACnB,SAAS,QAAQ,IAAI;EACrB,SAAS,UAAU,IAAI;CACxB,EACD,CAAC,CACF;;;;;;AAOH,MAAa,kBACX,MAAc,SACL,WACT,OAAO,KACN,OAAO,SAAS,MAAM,EACrB,YAAY;EACV,SAAS,MAAM,IAAI;EACnB,SAAS,QAAQ,IAAI;EACrB,SAAS,UAAU,IAAI;EACvB,SAAS,SAAS,IAAI;EACtB,SAAS,OAAO,IAAI;CACrB,EACD,CAAC,CACF;;;;;;;AAQH,MAAa,iBAAiB,UAC7B,OAAO,oBAAoB,GAAG,SAAS,QAAQ,OAAO,CAAC;;;;;;AAcxD,MAAa,cAAc,OAC1B,OAAO,oBAAoB,GAAG,SAAS,KAAK,IAAI,CAAC"}
+{"version":3,"file":"spans.mjs","names":[],"sources":["../../../../src/substrate/runtime/observability/spans.ts"],"sourcesContent":["// Span propagation wrappers.\n//\n// Architecture § L0 Observability: \"span/annotation conventions\".\n// Centralises the attribute keys so every wrapped span uses the same\n// vocabulary — OTEL consumers can filter by `devstack.app`,\n// `devstack.stack`, `devstack.plugin`, `devstack.role` reliably.\n//\n// Discipline: substrate-owned vocabulary carries ONLY engine-dimensional\n// keys (`devstack.*`, `error.*`, `process.exit.*`, `container.*`) plus\n// HTTP-generic keys (`http.*`, `server.*`). Plugin-domain keys\n// (`wallet.token`, `sui.mode`, `account.name`, etc.) live in\n// `src/plugins/<name>/spans.ts` next to the plugin that owns them; see\n// STYLE_GUIDE §16.\n\nimport { Effect } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { PluginRole } from '../../lifecycle.ts';\nimport { IdentityContext } from '../paths.ts';\n\n/** Canonical span-attribute keys. Engine-dimensional + http/process\n *  generic only. Plugin-domain keys belong on per-plugin `spans.ts`. */\nexport const SpanAttr = {\n\tapp: 'devstack.app',\n\tstack: 'devstack.stack',\n\tnetwork: 'devstack.network',\n\tplugin: 'devstack.plugin',\n\trole: 'devstack.role',\n\tphase: 'devstack.phase',\n\tcontainerName: 'container.name',\n\tcontainerRole: 'container.role',\n\tevent: 'event.name',\n\terrorCode: 'error.code',\n\terrorCause: 'error.cause',\n\terrorMessage: 'error.message',\n\texitCode: 'process.exit.code',\n\texitSignal: 'process.exit.signal',\n\texitStatus: 'process.exit.status',\n\tendpointKey: 'devstack.endpoint.key',\n\thttpMethod: 'http.method',\n\thttpPath: 'http.path',\n\thttpUrl: 'http.url',\n\thost: 'server.address',\n\tlogTag: 'log.tag',\n\tport: 'server.port',\n\tcycleId: 'devstack.cycle.id',\n\top: 'devstack.op',\n\trequestId: 'devstack.request.id',\n\trosterHeartbeatIntervalMs: 'roster.heartbeat.intervalMs',\n\tserviceName: 'devstack.service.name',\n\tstageAndSwapStagingPath: 'stageAndSwap.stagingPath',\n\tstageAndSwapTargetPath: 'stageAndSwap.targetPath',\n\tcacheCorruption: 'cache.corruption',\n\tcapabilitySinksKind: 'capability-sinks.kind',\n\tstrategyKey: 'strategy.key',\n\tstrategyAutoMounted: 'strategy.autoMounted',\n\tartifactPublisherNamespace: 'artifactPublisher.namespace',\n\tartifactPublisherChain: 'artifactPublisher.chain',\n\tartifactPublisherContentHash: 'artifactPublisher.contentHash',\n\tartifactPublisherPath: 'artifactPublisher.path',\n\tstackLockPath: 'devstack.stack-lock.path',\n\tstackLockTimeoutMillis: 'devstack.stack-lock.timeoutMillis',\n\tsnapshotReservationPath: 'devstack.snapshot-reservation.path',\n} as const;\n\nexport interface StackSpanContext {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly network: string;\n}\n\nexport interface PluginSpanContext extends StackSpanContext {\n\treadonly pluginKey: PluginKey;\n\treadonly role: PluginRole;\n}\n\n/**\n * Wrap an Effect in a stack-scoped span. Sets `devstack.app`,\n * `devstack.stack`, `devstack.network` attributes. Use at the\n * top-level engine entry points (boot, cycle start, supervisor\n * loop) — not inside per-plugin code (use `withPluginSpan` for that).\n */\nexport const withStackSpan =\n\t(name: string, ctx: StackSpanContext) =>\n\t<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n\t\teffect.pipe(\n\t\t\tEffect.withSpan(name, {\n\t\t\t\tattributes: {\n\t\t\t\t\t[SpanAttr.app]: ctx.app,\n\t\t\t\t\t[SpanAttr.stack]: ctx.stack,\n\t\t\t\t\t[SpanAttr.network]: ctx.network,\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n\n/**\n * Wrap an Effect in a plugin-scoped span. Inherits stack identity from\n * the surrounding Context (callers should compose with\n * `withStackSpan` at the top so the stack identity propagates).\n */\nexport const withPluginSpan =\n\t(name: string, ctx: PluginSpanContext) =>\n\t<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n\t\teffect.pipe(\n\t\t\tEffect.withSpan(name, {\n\t\t\t\tattributes: {\n\t\t\t\t\t[SpanAttr.app]: ctx.app,\n\t\t\t\t\t[SpanAttr.stack]: ctx.stack,\n\t\t\t\t\t[SpanAttr.network]: ctx.network,\n\t\t\t\t\t[SpanAttr.plugin]: ctx.pluginKey,\n\t\t\t\t\t[SpanAttr.role]: ctx.role,\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n\n/**\n * Annotate the current span with a phase marker. Cheap; safe to call\n * from anywhere. Used by the supervisor when transitioning a plugin\n * through acquire phases so the OTEL trace correlates with the\n * lifecycle stream.\n */\nexport const annotatePhase = (phase: string): Effect.Effect<void> =>\n\tEffect.annotateCurrentSpan({ [SpanAttr.phase]: phase });\n\n/**\n * Annotate the current span with the engine cycle id. Called once per\n * cycle at supervisor entry.\n */\nexport const annotateCycle = (cycleId: number): Effect.Effect<void> =>\n\tEffect.annotateCurrentSpan({ [SpanAttr.cycleId]: cycleId });\n\n/**\n * Annotate the current span with a subprocess `op` tag. Mirrors the\n * `CaptureError.op` field so a failure that originates in a captured\n * subprocess can be traced back to its span by `devstack.op`.\n */\nexport const annotateOp = (op: string): Effect.Effect<void> =>\n\tEffect.annotateCurrentSpan({ [SpanAttr.op]: op });\n\n/**\n * Canonical labels every `spanWithLabels` span carries. `plugin` is\n * caller-supplied (per-acquisition); `endpoint` + `op` are optional\n * canonical narrowers — anything plugin-specific goes through `extras`\n * so the OTEL namespace check (STYLE_GUIDE §16) still applies.\n */\nexport interface SpanLabels {\n\treadonly plugin: PluginKey | string;\n\treadonly endpoint?: string;\n\treadonly op?: string;\n}\n\n/**\n * Wrap an Effect in a span that pre-bakes the canonical identity\n * footprint — `devstack.app` + `devstack.stack` (read from the ambient\n * `IdentityContext`) + `devstack.plugin` from `labels.plugin`. Reach\n * for this on any span that needs to be filterable or groupable by\n * plugin on the dashboard (i.e. basically every span). Coexists with\n * raw `Effect.withSpan` — migration is incremental, not a flag day.\n *\n * Adoption prerequisite: this adds `IdentityContext` to the wrapped\n * effect's `R`. Only reach for it where `IdentityContext` is already in\n * scope (or the boot signature can be widened to carry it). Plugin\n * acquire/boot effects currently do NOT thread `IdentityContext` — they\n * set `devstack.plugin` directly via `Effect.withSpan` — so migrating\n * them needs the identity plumbed first. Note also that a span's\n * app/stack may legitimately differ from the ambient identity (e.g. the\n * `_per-app_` shared-stack sentinel in `managed-container.ts`), where\n * this helper is the wrong tool.\n */\nexport const spanWithLabels =\n\t(name: string, labels: SpanLabels, extras?: Record<string, unknown>) =>\n\t<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | IdentityContext> =>\n\t\tEffect.gen(function* () {\n\t\t\tconst identity = yield* IdentityContext;\n\t\t\tconst attributes: Record<string, unknown> = {\n\t\t\t\t[SpanAttr.app]: identity.app,\n\t\t\t\t[SpanAttr.stack]: identity.stack,\n\t\t\t\t[SpanAttr.plugin]: labels.plugin,\n\t\t\t\t...(labels.endpoint !== undefined ? { [SpanAttr.endpointKey]: labels.endpoint } : {}),\n\t\t\t\t...(labels.op !== undefined ? { [SpanAttr.op]: labels.op } : {}),\n\t\t\t\t...extras,\n\t\t\t};\n\t\t\treturn yield* effect.pipe(Effect.withSpan(name, { attributes }));\n\t\t});\n"],"mappings":";;;;;AAsBA,MAAa,WAAW;CACvB,KAAK;CACL,OAAO;CACP,SAAS;CACT,QAAQ;CACR,MAAM;CACN,OAAO;CACP,eAAe;CACf,eAAe;CACf,OAAO;CACP,WAAW;CACX,YAAY;CACZ,cAAc;CACd,UAAU;CACV,YAAY;CACZ,YAAY;CACZ,aAAa;CACb,YAAY;CACZ,UAAU;CACV,SAAS;CACT,MAAM;CACN,QAAQ;CACR,MAAM;CACN,SAAS;CACT,IAAI;CACJ,WAAW;CACX,2BAA2B;CAC3B,aAAa;CACb,yBAAyB;CACzB,wBAAwB;CACxB,iBAAiB;CACjB,qBAAqB;CACrB,aAAa;CACb,qBAAqB;CACrB,4BAA4B;CAC5B,wBAAwB;CACxB,8BAA8B;CAC9B,uBAAuB;CACvB,eAAe;CACf,wBAAwB;CACxB,yBAAyB;CACzB;;;;;;;AAmBD,MAAa,iBACX,MAAc,SACL,WACT,OAAO,KACN,OAAO,SAAS,MAAM,EACrB,YAAY;EACV,SAAS,MAAM,IAAI;EACnB,SAAS,QAAQ,IAAI;EACrB,SAAS,UAAU,IAAI;CACxB,EACD,CAAC,CACF;;;;;;AAOH,MAAa,kBACX,MAAc,SACL,WACT,OAAO,KACN,OAAO,SAAS,MAAM,EACrB,YAAY;EACV,SAAS,MAAM,IAAI;EACnB,SAAS,QAAQ,IAAI;EACrB,SAAS,UAAU,IAAI;EACvB,SAAS,SAAS,IAAI;EACtB,SAAS,OAAO,IAAI;CACrB,EACD,CAAC,CACF;;;;;;;AAQH,MAAa,iBAAiB,UAC7B,OAAO,oBAAoB,GAAG,SAAS,QAAQ,OAAO,CAAC;;;;;;AAcxD,MAAa,cAAc,OAC1B,OAAO,oBAAoB,GAAG,SAAS,KAAK,IAAI,CAAC"}

package/dist/substrate/runtime/observability/subprocess-capture.mjs

@@ -77,6 +77,6 @@ const capture = (spawner, cmd, opts) => {
 	}));
 };
 //#endregion
-export { capture };
+export { CaptureError, capture };
 
 //# sourceMappingURL=subprocess-capture.mjs.map

package/dist/substrate/runtime/passthrough-or-wrap.mjs

@@ -0,0 +1,33 @@
+import { Effect } from "effect";
+//#region src/substrate/runtime/passthrough-or-wrap.ts
+/** Internal: build the operator from a known-tag set + unknown
+*  wrapper. Shared by both the direct and curried entry points. */
+const buildPassthroughOrWrap = (knownTags, mkUnknown) => (self) => {
+	const known = new Set(knownTags);
+	return self.pipe(Effect.catch((err) => {
+		if (typeof err === "object" && err !== null && "_tag" in err && typeof err._tag === "string" && known.has(err._tag)) return Effect.fail(err);
+		return Effect.fail(mkUnknown(err));
+	}));
+};
+/** Operator that catches every error: lets through tagged errors whose
+*  `_tag` is in `knownTags`, wraps everything else through `mkUnknown`.
+*
+*  Use this for the outer plugin-pipeline catch where the aggregate E
+*  channel mixes plugin-typed errors with substrate-side unknowns. The
+*  output E channel is `KnownE | UnknownE` — callers parameterize
+*  `KnownE` at the call site (the runtime `_tag` check is the
+*  load-bearing part; the type parameter is documentation + a downstream
+*  narrowing aid).
+*
+*  Two call shapes:
+*  - Direct: `passthroughOrWrap<KnownE, UnknownE>(tags, mkUnknown)` —
+*    explicit on both type params.
+*  - Curried: `passthroughOrWrap.for<KnownE>()(tags, mkUnknown)` — pin
+*    `KnownE` up front so TS infers `UnknownE` from `mkUnknown`'s
+*    return type at the second call. Preferred when `KnownE` is a
+*    plugin-side union that doesn't appear in the args. */
+const passthroughOrWrap = Object.assign(buildPassthroughOrWrap, { for: () => (knownTags, mkUnknown) => buildPassthroughOrWrap(knownTags, mkUnknown) });
+//#endregion
+export { passthroughOrWrap };
+
+//# sourceMappingURL=passthrough-or-wrap.mjs.map

package/dist/substrate/runtime/passthrough-or-wrap.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"passthrough-or-wrap.mjs","names":[],"sources":["../../../src/substrate/runtime/passthrough-or-wrap.ts"],"sourcesContent":["// passthroughOrWrap — collapse the recurring \"let known tagged errors\n// through; wrap everything else into one canonical plugin-side error\"\n// shape that every plugin's outer pipeline implements.\n//\n// Plugins routinely compose `Effect.gen` bodies whose aggregate `E`\n// channel includes substrate-side errors with shapes the plugin author\n// doesn't statically know (artifact-publisher produce bodies, dependency\n// reads). `Effect.catchTags` requires a statically-known tagged union, so\n// the recurring pattern is either a long catchTags chain that re-fails\n// each known tag, or a runtime `_tag` discriminator check that walks the\n// known list and wraps the rest. Both shapes spell out the same logic in\n// 10-20 lines per plugin.\n//\n// This helper centralizes that: caller supplies the list of known tagged\n// `_tag` literals plus a `mkUnknown` constructor; helper returns an\n// Effect operator that lets known errors through unchanged (typed E\n// channel preserved at the call site) and wraps anything else through\n// `mkUnknown`.\n//\n// Distilled-doc § Invariants: already-typed errors must NOT be re-wrapped\n// by the catch-all unknown handler. Putting this in one place enforces\n// that invariant by construction.\n\nimport { Effect } from 'effect';\n\n/** Internal: build the operator from a known-tag set + unknown\n *  wrapper. Shared by both the direct and curried entry points. */\nconst buildPassthroughOrWrap =\n\t<KnownE extends { readonly _tag: string }, UnknownE>(\n\t\tknownTags: ReadonlyArray<KnownE['_tag']>,\n\t\tmkUnknown: (cause: unknown) => UnknownE,\n\t) =>\n\t<A, R, EIn = KnownE>(\n\t\tself: Effect.Effect<A, EIn, R>,\n\t): Effect.Effect<A, KnownE | UnknownE, R> => {\n\t\tconst known = new Set<string>(knownTags);\n\t\treturn self.pipe(\n\t\t\tEffect.catch(\n\t\t\t\t(err: unknown): Effect.Effect<never, KnownE | UnknownE> => {\n\t\t\t\t\tif (\n\t\t\t\t\t\ttypeof err === 'object' &&\n\t\t\t\t\t\terr !== null &&\n\t\t\t\t\t\t'_tag' in err &&\n\t\t\t\t\t\ttypeof (err as { _tag: unknown })._tag === 'string' &&\n\t\t\t\t\t\tknown.has((err as { _tag: string })._tag)\n\t\t\t\t\t) {\n\t\t\t\t\t\treturn Effect.fail(err as KnownE);\n\t\t\t\t\t}\n\t\t\t\t\treturn Effect.fail(mkUnknown(err));\n\t\t\t\t},\n\t\t\t),\n\t\t);\n\t};\n\n/** Operator that catches every error: lets through tagged errors whose\n *  `_tag` is in `knownTags`, wraps everything else through `mkUnknown`.\n *\n *  Use this for the outer plugin-pipeline catch where the aggregate E\n *  channel mixes plugin-typed errors with substrate-side unknowns. The\n *  output E channel is `KnownE | UnknownE` — callers parameterize\n *  `KnownE` at the call site (the runtime `_tag` check is the\n *  load-bearing part; the type parameter is documentation + a downstream\n *  narrowing aid).\n *\n *  Two call shapes:\n *  - Direct: `passthroughOrWrap<KnownE, UnknownE>(tags, mkUnknown)` —\n *    explicit on both type params.\n *  - Curried: `passthroughOrWrap.for<KnownE>()(tags, mkUnknown)` — pin\n *    `KnownE` up front so TS infers `UnknownE` from `mkUnknown`'s\n *    return type at the second call. Preferred when `KnownE` is a\n *    plugin-side union that doesn't appear in the args. */\nexport const passthroughOrWrap: {\n\t<KnownE extends { readonly _tag: string }, UnknownE>(\n\t\tknownTags: ReadonlyArray<KnownE['_tag']>,\n\t\tmkUnknown: (cause: unknown) => UnknownE,\n\t): <A, R, EIn = KnownE>(\n\t\tself: Effect.Effect<A, EIn, R>,\n\t) => Effect.Effect<A, KnownE | UnknownE, R>;\n\tfor: <KnownE extends { readonly _tag: string }>() => <UnknownE>(\n\t\tknownTags: ReadonlyArray<KnownE['_tag']>,\n\t\tmkUnknown: (cause: unknown) => UnknownE,\n\t) => <A, R, EIn = KnownE>(\n\t\tself: Effect.Effect<A, EIn, R>,\n\t) => Effect.Effect<A, KnownE | UnknownE, R>;\n} = Object.assign(buildPassthroughOrWrap, {\n\tfor:\n\t\t<KnownE extends { readonly _tag: string }>() =>\n\t\t<UnknownE>(\n\t\t\tknownTags: ReadonlyArray<KnownE['_tag']>,\n\t\t\tmkUnknown: (cause: unknown) => UnknownE,\n\t\t) =>\n\t\t\tbuildPassthroughOrWrap<KnownE, UnknownE>(knownTags, mkUnknown),\n});\n"],"mappings":";;;;AA2BA,MAAM,0BAEJ,WACA,eAGA,SAC4C;CAC5C,MAAM,QAAQ,IAAI,IAAY,UAAU;AACxC,QAAO,KAAK,KACX,OAAO,OACL,QAA0D;AAC1D,MACC,OAAO,QAAQ,YACf,QAAQ,QACR,UAAU,OACV,OAAQ,IAA0B,SAAS,YAC3C,MAAM,IAAK,IAAyB,KAAK,CAEzC,QAAO,OAAO,KAAK,IAAc;AAElC,SAAO,OAAO,KAAK,UAAU,IAAI,CAAC;GAEnC,CACD;;;;;;;;;;;;;;;;;;;AAoBH,MAAa,oBAaT,OAAO,OAAO,wBAAwB,EACzC,YAGE,WACA,cAEA,uBAAyC,WAAW,UAAU,EAChE,CAAC"}

package/dist/substrate/runtime/paths.d.mts

@@ -2,7 +2,7 @@ import { Identity } from "../identity.mjs";
 import { Context, Layer, Path } from "effect";
 
 //#region src/substrate/runtime/paths.d.ts
-declare const IdentityContext_base: Context.ServiceClass<IdentityContext, "@devstack-rewrite/substrate/Identity", Identity>;
+declare const IdentityContext_base: Context.ServiceClass<IdentityContext, "@devstack/substrate/Identity", Identity>;
 /**
  * Identity-bound. Same shape as `substrate/identity.ts`'s `Identity`,
  * but lifted into a Context service so path resolution can yield it

package/dist/substrate/runtime/paths.mjs

@@ -1,6 +1,6 @@
 import { Context, Effect, Layer, Path } from "effect";
 //#region src/substrate/runtime/paths.ts
-var RuntimeRoot = class extends Context.Service()("@devstack-rewrite/substrate/RuntimeRoot") {};
+var RuntimeRoot = class extends Context.Service()("@devstack/substrate/RuntimeRoot") {};
 /** Build a `RuntimeRoot` layer pinned to a literal path. */
 const layerRuntimeRoot = (root) => Layer.succeed(RuntimeRoot)({ root });
 /**
@@ -11,14 +11,14 @@ const layerRuntimeRoot = (root) => Layer.succeed(RuntimeRoot)({ root });
 * Boot wires this once (Identity is validated up front); the
 * resolver and every consumer reads from this single source.
 */
-var IdentityContext = class extends Context.Service()("@devstack-rewrite/substrate/Identity") {};
+var IdentityContext = class extends Context.Service()("@devstack/substrate/Identity") {};
 const layerIdentity = (identity) => Layer.succeed(IdentityContext)(identity);
 /**
 * The path resolver service. Yields `StackPaths` once per stack —
 * `Effect.cached`-friendly since `Identity` + `RuntimeRoot` are
 * boot-immutable.
 */
-var StackPathsService = class extends Context.Service()("@devstack-rewrite/substrate/StackPaths") {};
+var StackPathsService = class extends Context.Service()("@devstack/substrate/StackPaths") {};
 /**
 * Layer that materializes the resolver from `RuntimeRoot` +
 * `IdentityContext` + the Effect `Path` service. The cache helper
@@ -49,6 +49,7 @@ const layerStackPaths = Layer.effect(StackPathsService, Effect.gen(function* ()
 		snapshotDir: path.join(stackRoot, "snapshots"),
 		stackLockFile: path.join(stackRoot, "stack.lock"),
 		rosterFile: path.join(stackRoot, "roster.json"),
+		containerClaimsFile: path.join(stackRoot, "container-claims.json"),
 		snapshotReservationFile: path.join(stackRoot, "snapshot.reservation"),
 		cacheEntry,
 		cacheChainDir,

package/dist/substrate/runtime/paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"paths.mjs","names":[],"sources":["../../../src/substrate/runtime/paths.ts"],"sourcesContent":["// Unified path resolver.\n//\n// Architecture § \"What's collapsed\" — three path resolvers\n// (state-store, service-paths, snapshot) consolidate to one. This is\n// the L0 helper every disk-touching subsystem reaches for; nothing\n// else in the runtime package may compose `<root>/stacks/<stack>/...`\n// by hand.\n//\n// The resolver is a typed bundle: given an `Identity` and the\n// `RuntimeRoot`, it returns the closed set of paths the substrate\n// understands. Subsystems that need a sub-path inside one of those\n// (e.g. cache namespace + chain + content-hash) compose ON TOP of the\n// bundle's `cacheDir`, but they NEVER reach for\n// `path.join(root, 'stacks', stack)` themselves.\n\nimport { Context, Effect, Layer, Path } from 'effect';\n\nimport type { Identity } from '../identity.ts';\n\n/**\n * Runtime root — the on-disk base under which every stack's state\n * lives. Defaults to `.devstack`, but is injectable so tests pin to\n * a tempdir and parallel-stack tests pin to per-test prefixes.\n *\n * Held as a tagged service so the rest of the substrate can request\n * it without threading the string through every signature.\n */\nexport interface RuntimeRootShape {\n\treadonly root: string;\n}\n\nexport class RuntimeRoot extends Context.Service<RuntimeRoot, RuntimeRootShape>()(\n\t'@devstack-rewrite/substrate/RuntimeRoot',\n) {}\n\n/** Build a `RuntimeRoot` layer pinned to a literal path. */\nexport const layerRuntimeRoot = (root: string): Layer.Layer<RuntimeRoot> =>\n\tLayer.succeed(RuntimeRoot)({ root });\n\n/**\n * Identity-bound. Same shape as `substrate/identity.ts`'s `Identity`,\n * but lifted into a Context service so path resolution can yield it\n * without taking it as a function argument.\n *\n * Boot wires this once (Identity is validated up front); the\n * resolver and every consumer reads from this single source.\n */\nexport class IdentityContext extends Context.Service<IdentityContext, Identity>()(\n\t'@devstack-rewrite/substrate/Identity',\n) {}\n\nexport const layerIdentity = (identity: Identity): Layer.Layer<IdentityContext> =>\n\tLayer.succeed(IdentityContext)(identity);\n\n/**\n * Closed bundle the resolver returns. Three groups of paths:\n *\n *   - `stackRoot` and the cross-process artifacts (lock, roster,\n *     command channel, snapshot reservation) live directly under the stack\n *     directory. Cross-process safety lives here.\n *   - `stateFile` is the per-stack state-store JSON. ONE file per\n *     stack — schema-validated on read.\n *   - `cacheDir` is the parent directory; the cache subsystem\n *     composes `<cacheDir>/<namespace>/<chainId>/<contentHash>.json`\n *     via a helper on this resolver. Subsystems do NOT reach into\n *     `cacheDir` with their own `path.join` calls.\n */\nexport interface StackPaths {\n\treadonly stackRoot: string;\n\treadonly stateFile: string;\n\treadonly stateLockHint: string;\n\treadonly cacheDir: string;\n\treadonly snapshotDir: string;\n\treadonly stackLockFile: string;\n\treadonly rosterFile: string;\n\treadonly snapshotReservationFile: string;\n\t/**\n\t * Helper that composes the cache entry path from cache-key\n\t * components. The substrate folds the components together here so\n\t * that nothing else in the runtime tree builds cache paths.\n\t */\n\treadonly cacheEntry: (\n\t\tnamespace: string,\n\t\tchain: string,\n\t\tcontentHash: string,\n\t) => { readonly dir: string; readonly file: string };\n\t/** Helper that returns the cache namespace directory for a given\n\t *  namespace + chain — for `readDirectory` enumeration. */\n\treadonly cacheChainDir: (namespace: string, chain: string) => string;\n\t/** Helper that returns the cache namespace directory (across all\n\t *  chains) — for namespace-scoped enumeration. */\n\treadonly cacheNamespaceDir: (namespace: string) => string;\n}\n\n/**\n * The path resolver service. Yields `StackPaths` once per stack —\n * `Effect.cached`-friendly since `Identity` + `RuntimeRoot` are\n * boot-immutable.\n */\nexport class StackPathsService extends Context.Service<StackPathsService, StackPaths>()(\n\t'@devstack-rewrite/substrate/StackPaths',\n) {}\n\n/**\n * Layer that materializes the resolver from `RuntimeRoot` +\n * `IdentityContext` + the Effect `Path` service. The cache helper\n * uses `Path.join` so OS-correct separators round-trip on Windows\n * (defense-in-depth — devstack is posix-only in practice but the\n * cost of `Path.join` over template strings is zero).\n */\nexport const layerStackPaths: Layer.Layer<\n\tStackPathsService,\n\tnever,\n\tRuntimeRoot | IdentityContext | Path.Path\n> = Layer.effect(\n\tStackPathsService,\n\tEffect.gen(function* () {\n\t\tconst { root } = yield* RuntimeRoot;\n\t\tconst identity = yield* IdentityContext;\n\t\tconst path = yield* Path.Path;\n\t\tconst stackRoot = path.join(root, 'stacks', identity.stack);\n\t\tconst cacheDir = path.join(stackRoot, 'cache');\n\t\tconst cacheNamespaceDir = (namespace: string): string => path.join(cacheDir, namespace);\n\t\tconst cacheChainDir = (namespace: string, chain: string): string =>\n\t\t\tpath.join(cacheNamespaceDir(namespace), chain);\n\t\tconst cacheEntry = (\n\t\t\tnamespace: string,\n\t\t\tchain: string,\n\t\t\tcontentHash: string,\n\t\t): { readonly dir: string; readonly file: string } => {\n\t\t\tconst dir = cacheChainDir(namespace, chain);\n\t\t\treturn { dir, file: path.join(dir, `${contentHash}.json`) };\n\t\t};\n\t\treturn StackPathsService.of({\n\t\t\tstackRoot,\n\t\t\tstateFile: path.join(stackRoot, 'state.json'),\n\t\t\tstateLockHint: path.join(stackRoot, 'state.json.lock'),\n\t\t\tcacheDir,\n\t\t\tsnapshotDir: path.join(stackRoot, 'snapshots'),\n\t\t\tstackLockFile: path.join(stackRoot, 'stack.lock'),\n\t\t\trosterFile: path.join(stackRoot, 'roster.json'),\n\t\t\tsnapshotReservationFile: path.join(stackRoot, 'snapshot.reservation'),\n\t\t\tcacheEntry,\n\t\t\tcacheChainDir,\n\t\t\tcacheNamespaceDir,\n\t\t});\n\t}),\n);\n"],"mappings":";;AA+BA,IAAa,cAAb,cAAiC,QAAQ,SAAwC,CAChF,0CACA,CAAC;;AAGF,MAAa,oBAAoB,SAChC,MAAM,QAAQ,YAAY,CAAC,EAAE,MAAM,CAAC;;;;;;;;;AAUrC,IAAa,kBAAb,cAAqC,QAAQ,SAAoC,CAChF,uCACA,CAAC;AAEF,MAAa,iBAAiB,aAC7B,MAAM,QAAQ,gBAAgB,CAAC,SAAS;;;;;;AA+CzC,IAAa,oBAAb,cAAuC,QAAQ,SAAwC,CACtF,yCACA,CAAC;;;;;;;;AASF,MAAa,kBAIT,MAAM,OACT,mBACA,OAAO,IAAI,aAAa;CACvB,MAAM,EAAE,SAAS,OAAO;CACxB,MAAM,WAAW,OAAO;CACxB,MAAM,OAAO,OAAO,KAAK;CACzB,MAAM,YAAY,KAAK,KAAK,MAAM,UAAU,SAAS,MAAM;CAC3D,MAAM,WAAW,KAAK,KAAK,WAAW,QAAQ;CAC9C,MAAM,qBAAqB,cAA8B,KAAK,KAAK,UAAU,UAAU;CACvF,MAAM,iBAAiB,WAAmB,UACzC,KAAK,KAAK,kBAAkB,UAAU,EAAE,MAAM;CAC/C,MAAM,cACL,WACA,OACA,gBACqD;EACrD,MAAM,MAAM,cAAc,WAAW,MAAM;AAC3C,SAAO;GAAE;GAAK,MAAM,KAAK,KAAK,KAAK,GAAG,YAAY,OAAO;GAAE;;AAE5D,QAAO,kBAAkB,GAAG;EAC3B;EACA,WAAW,KAAK,KAAK,WAAW,aAAa;EAC7C,eAAe,KAAK,KAAK,WAAW,kBAAkB;EACtD;EACA,aAAa,KAAK,KAAK,WAAW,YAAY;EAC9C,eAAe,KAAK,KAAK,WAAW,aAAa;EACjD,YAAY,KAAK,KAAK,WAAW,cAAc;EAC/C,yBAAyB,KAAK,KAAK,WAAW,uBAAuB;EACrE;EACA;EACA;EACA,CAAC;EACD,CACF"}
+{"version":3,"file":"paths.mjs","names":[],"sources":["../../../src/substrate/runtime/paths.ts"],"sourcesContent":["// Unified path resolver.\n//\n// Architecture § \"What's collapsed\" — three path resolvers\n// (state-store, service-paths, snapshot) consolidate to one. This is\n// the L0 helper every disk-touching subsystem reaches for; nothing\n// else in the runtime package may compose `<root>/stacks/<stack>/...`\n// by hand.\n//\n// The resolver is a typed bundle: given an `Identity` and the\n// `RuntimeRoot`, it returns the closed set of paths the substrate\n// understands. Subsystems that need a sub-path inside one of those\n// (e.g. cache namespace + chain + content-hash) compose ON TOP of the\n// bundle's `cacheDir`, but they NEVER reach for\n// `path.join(root, 'stacks', stack)` themselves.\n\nimport { Context, Effect, Layer, Path } from 'effect';\n\nimport type { Identity } from '../identity.ts';\n\n/**\n * Runtime root — the on-disk base under which every stack's state\n * lives. Defaults to `.devstack`, but is injectable so tests pin to\n * a tempdir and parallel-stack tests pin to per-test prefixes.\n *\n * Held as a tagged service so the rest of the substrate can request\n * it without threading the string through every signature.\n */\nexport interface RuntimeRootShape {\n\treadonly root: string;\n}\n\nexport class RuntimeRoot extends Context.Service<RuntimeRoot, RuntimeRootShape>()(\n\t'@devstack/substrate/RuntimeRoot',\n) {}\n\n/** Build a `RuntimeRoot` layer pinned to a literal path. */\nexport const layerRuntimeRoot = (root: string): Layer.Layer<RuntimeRoot> =>\n\tLayer.succeed(RuntimeRoot)({ root });\n\n/**\n * Identity-bound. Same shape as `substrate/identity.ts`'s `Identity`,\n * but lifted into a Context service so path resolution can yield it\n * without taking it as a function argument.\n *\n * Boot wires this once (Identity is validated up front); the\n * resolver and every consumer reads from this single source.\n */\nexport class IdentityContext extends Context.Service<IdentityContext, Identity>()(\n\t'@devstack/substrate/Identity',\n) {}\n\nexport const layerIdentity = (identity: Identity): Layer.Layer<IdentityContext> =>\n\tLayer.succeed(IdentityContext)(identity);\n\n/**\n * Closed bundle the resolver returns. Three groups of paths:\n *\n *   - `stackRoot` and the cross-process artifacts (lock, roster,\n *     command channel, snapshot reservation) live directly under the stack\n *     directory. Cross-process safety lives here.\n *   - `stateFile` is the per-stack state-store JSON. ONE file per\n *     stack — schema-validated on read.\n *   - `cacheDir` is the parent directory; the cache subsystem\n *     composes `<cacheDir>/<namespace>/<chainId>/<contentHash>.json`\n *     via a helper on this resolver. Subsystems do NOT reach into\n *     `cacheDir` with their own `path.join` calls.\n */\nexport interface StackPaths {\n\treadonly stackRoot: string;\n\treadonly stateFile: string;\n\treadonly stateLockHint: string;\n\treadonly cacheDir: string;\n\treadonly snapshotDir: string;\n\treadonly stackLockFile: string;\n\treadonly rosterFile: string;\n\t/** Sibling of `rosterFile` — the per-container claim ledger that\n\t *  the roster module mutates under `stack.lock`. Composing this\n\t *  inside the substrate path resolver keeps the discipline \"nothing\n\t *  else builds cache/cross-process paths\" closed: the roster module\n\t *  reads this field rather than reconstructing\n\t *  `dirname(rosterFile) + 'container-claims.json'` itself. */\n\treadonly containerClaimsFile: string;\n\treadonly snapshotReservationFile: string;\n\t/**\n\t * Helper that composes the cache entry path from cache-key\n\t * components. The substrate folds the components together here so\n\t * that nothing else in the runtime tree builds cache paths.\n\t */\n\treadonly cacheEntry: (\n\t\tnamespace: string,\n\t\tchain: string,\n\t\tcontentHash: string,\n\t) => { readonly dir: string; readonly file: string };\n\t/** Helper that returns the cache namespace directory for a given\n\t *  namespace + chain — for `readDirectory` enumeration. */\n\treadonly cacheChainDir: (namespace: string, chain: string) => string;\n\t/** Helper that returns the cache namespace directory (across all\n\t *  chains) — for namespace-scoped enumeration. */\n\treadonly cacheNamespaceDir: (namespace: string) => string;\n}\n\n/**\n * The path resolver service. Yields `StackPaths` once per stack —\n * `Effect.cached`-friendly since `Identity` + `RuntimeRoot` are\n * boot-immutable.\n */\nexport class StackPathsService extends Context.Service<StackPathsService, StackPaths>()(\n\t'@devstack/substrate/StackPaths',\n) {}\n\n/**\n * Layer that materializes the resolver from `RuntimeRoot` +\n * `IdentityContext` + the Effect `Path` service. The cache helper\n * uses `Path.join` so OS-correct separators round-trip on Windows\n * (defense-in-depth — devstack is posix-only in practice but the\n * cost of `Path.join` over template strings is zero).\n */\nexport const layerStackPaths: Layer.Layer<\n\tStackPathsService,\n\tnever,\n\tRuntimeRoot | IdentityContext | Path.Path\n> = Layer.effect(\n\tStackPathsService,\n\tEffect.gen(function* () {\n\t\tconst { root } = yield* RuntimeRoot;\n\t\tconst identity = yield* IdentityContext;\n\t\tconst path = yield* Path.Path;\n\t\tconst stackRoot = path.join(root, 'stacks', identity.stack);\n\t\tconst cacheDir = path.join(stackRoot, 'cache');\n\t\tconst cacheNamespaceDir = (namespace: string): string => path.join(cacheDir, namespace);\n\t\tconst cacheChainDir = (namespace: string, chain: string): string =>\n\t\t\tpath.join(cacheNamespaceDir(namespace), chain);\n\t\tconst cacheEntry = (\n\t\t\tnamespace: string,\n\t\t\tchain: string,\n\t\t\tcontentHash: string,\n\t\t): { readonly dir: string; readonly file: string } => {\n\t\t\tconst dir = cacheChainDir(namespace, chain);\n\t\t\treturn { dir, file: path.join(dir, `${contentHash}.json`) };\n\t\t};\n\t\treturn StackPathsService.of({\n\t\t\tstackRoot,\n\t\t\tstateFile: path.join(stackRoot, 'state.json'),\n\t\t\tstateLockHint: path.join(stackRoot, 'state.json.lock'),\n\t\t\tcacheDir,\n\t\t\tsnapshotDir: path.join(stackRoot, 'snapshots'),\n\t\t\tstackLockFile: path.join(stackRoot, 'stack.lock'),\n\t\t\trosterFile: path.join(stackRoot, 'roster.json'),\n\t\t\tcontainerClaimsFile: path.join(stackRoot, 'container-claims.json'),\n\t\t\tsnapshotReservationFile: path.join(stackRoot, 'snapshot.reservation'),\n\t\t\tcacheEntry,\n\t\t\tcacheChainDir,\n\t\t\tcacheNamespaceDir,\n\t\t});\n\t}),\n);\n"],"mappings":";;AA+BA,IAAa,cAAb,cAAiC,QAAQ,SAAwC,CAChF,kCACA,CAAC;;AAGF,MAAa,oBAAoB,SAChC,MAAM,QAAQ,YAAY,CAAC,EAAE,MAAM,CAAC;;;;;;;;;AAUrC,IAAa,kBAAb,cAAqC,QAAQ,SAAoC,CAChF,+BACA,CAAC;AAEF,MAAa,iBAAiB,aAC7B,MAAM,QAAQ,gBAAgB,CAAC,SAAS;;;;;;AAsDzC,IAAa,oBAAb,cAAuC,QAAQ,SAAwC,CACtF,iCACA,CAAC;;;;;;;;AASF,MAAa,kBAIT,MAAM,OACT,mBACA,OAAO,IAAI,aAAa;CACvB,MAAM,EAAE,SAAS,OAAO;CACxB,MAAM,WAAW,OAAO;CACxB,MAAM,OAAO,OAAO,KAAK;CACzB,MAAM,YAAY,KAAK,KAAK,MAAM,UAAU,SAAS,MAAM;CAC3D,MAAM,WAAW,KAAK,KAAK,WAAW,QAAQ;CAC9C,MAAM,qBAAqB,cAA8B,KAAK,KAAK,UAAU,UAAU;CACvF,MAAM,iBAAiB,WAAmB,UACzC,KAAK,KAAK,kBAAkB,UAAU,EAAE,MAAM;CAC/C,MAAM,cACL,WACA,OACA,gBACqD;EACrD,MAAM,MAAM,cAAc,WAAW,MAAM;AAC3C,SAAO;GAAE;GAAK,MAAM,KAAK,KAAK,KAAK,GAAG,YAAY,OAAO;GAAE;;AAE5D,QAAO,kBAAkB,GAAG;EAC3B;EACA,WAAW,KAAK,KAAK,WAAW,aAAa;EAC7C,eAAe,KAAK,KAAK,WAAW,kBAAkB;EACtD;EACA,aAAa,KAAK,KAAK,WAAW,YAAY;EAC9C,eAAe,KAAK,KAAK,WAAW,aAAa;EACjD,YAAY,KAAK,KAAK,WAAW,cAAc;EAC/C,qBAAqB,KAAK,KAAK,WAAW,wBAAwB;EAClE,yBAAyB,KAAK,KAAK,WAAW,uBAAuB;EACrE;EACA;EACA;EACA,CAAC;EACD,CACF"}

package/dist/substrate/runtime/phase-preserving-produce.mjs

@@ -0,0 +1,40 @@
+import "../../primitives/artifact-publisher.mjs";
+import { Effect, Ref } from "effect";
+//#region src/substrate/runtime/phase-preserving-produce.ts
+/** Wrap a domain-typed `produce` Effect so the typed error survives the
+*  substrate's `ArtifactPublishError` boundary.
+*
+*  Inputs:
+*   - `produce`: the typed produce Effect (`<Produced, TypedError, R>`).
+*     This is the Effect the caller would otherwise place in
+*     `ArtifactSpec.produce` directly.
+*   - `wrapProduceError`: projects `TypedError` to `ArtifactPublishError`
+*     for the substrate-facing channel. Mirrors the `Effect.mapError`
+*     closure callers would write inline.
+*
+*  Returns `{ wrappedProduce, recoverTypedError }`:
+*   - `wrappedProduce`: the Effect to place in `ArtifactSpec.produce` —
+*     surfaces only `ArtifactPublishError` (substrate contract) but
+*     stashes the typed cause into the Ref before the wrap.
+*   - `recoverTypedError`: a `pipe`-able recovery step. Apply via
+*     `.pipe(recoverTypedError)` AFTER `publisher.publish(...)` to
+*     restore the typed error channel. `reason: 'produce-failed'` lifts
+*     the stashed typed error; other reasons propagate untouched. */
+const withPhasePreservingProduce = (params) => Effect.gen(function* () {
+	const stashed = yield* Ref.make(null);
+	const wrappedProduce = params.produce.pipe(Effect.tapError((err) => Ref.set(stashed, err)), Effect.mapError(params.wrapProduceError));
+	const recoverTypedError = (self) => self.pipe(Effect.catchTag("ArtifactPublishError", (err) => Effect.gen(function* () {
+		const seen = yield* Ref.get(stashed);
+		const typedErr = err;
+		if (seen !== null && typedErr.reason === "produce-failed") return yield* Effect.fail(seen);
+		return yield* Effect.fail(typedErr);
+	})));
+	return {
+		wrappedProduce,
+		recoverTypedError
+	};
+});
+//#endregion
+export { withPhasePreservingProduce };
+
+//# sourceMappingURL=phase-preserving-produce.mjs.map

package/dist/substrate/runtime/phase-preserving-produce.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-preserving-produce.mjs","names":[],"sources":["../../../src/substrate/runtime/phase-preserving-produce.ts"],"sourcesContent":["// withPhasePreservingProduce — substrate helper for the\n// \"Ref-stash typed error across ArtifactPublishError wrap\" pattern.\n//\n// Background: `ArtifactPublisher.publish` requires the `produce` Effect\n// to surface failures as `ArtifactPublishError` (substrate contract —\n// the substrate is name-blind, so domain-typed errors cannot reach the\n// substrate's failure channel). For most plugins this is fine: the\n// produce body's typed error is projected directly to\n// `artifactPublishError('produce-failed', message)` via `mapError` and\n// the plugin caller sees a generic ArtifactPublishError it then maps\n// back to its domain (e.g. deepbook's `mapArtifactError`).\n//\n// But the Action plugin needs to preserve the original typed error's\n// `phase` discriminator across the wrap: the user-supplied body Effect\n// emits `ActionError` with one of several `phase` literals\n// (`'sign' | 'parse' | …`), and consumers `catchTag('ActionError')`\n// expecting that `phase` to survive. The substrate's wrap would\n// uniformly stamp every failure as `phase: 'sign'`.\n//\n// This helper captures the pattern: stash the typed error in a Ref\n// before the mapError boundary, then recover it on the\n// `ArtifactPublishError` recovery seam. Only `reason: 'produce-failed'`\n// surfaces a stashed typed error — the substrate-side reasons\n// (`verify-exhausted`, `cache-corrupt`) have no upstream typed error\n// and propagate as ArtifactPublishError untouched.\n//\n// Boundary discipline: lives under `substrate/runtime/` because the\n// pattern is generic over any tagged typed error — no plugin-domain\n// shape leaks in. The single piece of plugin knowledge the helper\n// requires (the `wrapProduceError` projection) is passed in by the\n// caller.\n//\n// Currently consumed by the Action plugin (`plugins/action/service.ts`).\n// The Package plugin (`plugins/package/mode-local.ts:149-152`) has a\n// similar shape ripe for migration but has not yet adopted the helper —\n// migrate when the next package-plugin pass surfaces.\n\nimport { Effect, Ref } from 'effect';\n\nimport { type ArtifactPublishError } from '../../primitives/artifact-publisher.ts';\n\n/** Wrap a domain-typed `produce` Effect so the typed error survives the\n *  substrate's `ArtifactPublishError` boundary.\n *\n *  Inputs:\n *   - `produce`: the typed produce Effect (`<Produced, TypedError, R>`).\n *     This is the Effect the caller would otherwise place in\n *     `ArtifactSpec.produce` directly.\n *   - `wrapProduceError`: projects `TypedError` to `ArtifactPublishError`\n *     for the substrate-facing channel. Mirrors the `Effect.mapError`\n *     closure callers would write inline.\n *\n *  Returns `{ wrappedProduce, recoverTypedError }`:\n *   - `wrappedProduce`: the Effect to place in `ArtifactSpec.produce` —\n *     surfaces only `ArtifactPublishError` (substrate contract) but\n *     stashes the typed cause into the Ref before the wrap.\n *   - `recoverTypedError`: a `pipe`-able recovery step. Apply via\n *     `.pipe(recoverTypedError)` AFTER `publisher.publish(...)` to\n *     restore the typed error channel. `reason: 'produce-failed'` lifts\n *     the stashed typed error; other reasons propagate untouched. */\nexport const withPhasePreservingProduce = <Produced, TypedError, R>(params: {\n\treadonly produce: Effect.Effect<Produced, TypedError, R>;\n\treadonly wrapProduceError: (err: TypedError) => ArtifactPublishError;\n}): Effect.Effect<\n\t{\n\t\treadonly wrappedProduce: Effect.Effect<Produced, ArtifactPublishError, R>;\n\t\treadonly recoverTypedError: <A, E, RR>(\n\t\t\tself: Effect.Effect<A, E, RR>,\n\t\t) => Effect.Effect<A, TypedError | Exclude<E, ArtifactPublishError>, RR>;\n\t},\n\tnever,\n\tnever\n> =>\n\tEffect.gen(function* () {\n\t\t// Stash slot — typed `TypedError | null`. Set on `produce` failure\n\t\t// BEFORE the mapError boundary so the outer recovery can read it.\n\t\tconst stashed = yield* Ref.make<TypedError | null>(null);\n\n\t\tconst wrappedProduce: Effect.Effect<Produced, ArtifactPublishError, R> = params.produce.pipe(\n\t\t\t// Stash the typed error before the mapError boundary so the\n\t\t\t// outer recovery path can re-raise with the original tag\n\t\t\t// (and phase, for `ActionError`-style discriminators) intact.\n\t\t\tEffect.tapError((err) => Ref.set(stashed, err)),\n\t\t\tEffect.mapError(params.wrapProduceError),\n\t\t);\n\n\t\tconst recoverTypedError = <A, E, RR>(\n\t\t\tself: Effect.Effect<A, E, RR>,\n\t\t): Effect.Effect<A, TypedError | Exclude<E, ArtifactPublishError>, RR> =>\n\t\t\t(self as Effect.Effect<A, E | ArtifactPublishError, RR>).pipe(\n\t\t\t\t// Recover the stashed typed error if produce raised one.\n\t\t\t\t// `verify-exhausted` / `cache-corrupt` are substrate-side\n\t\t\t\t// signals with no upstream typed error — they propagate\n\t\t\t\t// untouched.\n\t\t\t\tEffect.catchTag('ArtifactPublishError', (err) =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tconst seen = yield* Ref.get(stashed);\n\t\t\t\t\t\tconst typedErr = err as ArtifactPublishError;\n\t\t\t\t\t\tif (seen !== null && typedErr.reason === 'produce-failed') {\n\t\t\t\t\t\t\treturn yield* Effect.fail(seen);\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn yield* Effect.fail(typedErr);\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t) as Effect.Effect<A, TypedError | Exclude<E, ArtifactPublishError>, RR>;\n\n\t\treturn { wrappedProduce, recoverTypedError };\n\t});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA4DA,MAAa,8BAAuD,WAanE,OAAO,IAAI,aAAa;CAGvB,MAAM,UAAU,OAAO,IAAI,KAAwB,KAAK;CAExD,MAAM,iBAAmE,OAAO,QAAQ,KAIvF,OAAO,UAAU,QAAQ,IAAI,IAAI,SAAS,IAAI,CAAC,EAC/C,OAAO,SAAS,OAAO,iBAAiB,CACxC;CAED,MAAM,qBACL,SAEC,KAAwD,KAKxD,OAAO,SAAS,yBAAyB,QACxC,OAAO,IAAI,aAAa;EACvB,MAAM,OAAO,OAAO,IAAI,IAAI,QAAQ;EACpC,MAAM,WAAW;AACjB,MAAI,SAAS,QAAQ,SAAS,WAAW,iBACxC,QAAO,OAAO,OAAO,KAAK,KAAK;AAEhC,SAAO,OAAO,OAAO,KAAK,SAAS;GAClC,CACF,CACD;AAEF,QAAO;EAAE;EAAgB;EAAmB;EAC3C"}

package/dist/substrate/runtime/port-broker/index.mjs

@@ -0,0 +1,3 @@
+import "../errors.mjs";
+import "./service.mjs";
+export {};