@mysten-incubation/devstack 0.0.0

package/dist/substrate/runtime/process-supervisor.mjs

@@ -0,0 +1,73 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.mjs";
+import { Effect } from "effect";
+import { spawn } from "node:child_process";
+//#region src/substrate/runtime/process-supervisor.ts
+var process_supervisor_exports = /* @__PURE__ */ __exportAll({
+	awaitManagedProcessReady: () => awaitManagedProcessReady,
+	awaitProcessExit: () => awaitProcessExit,
+	describeProcessExitStatus: () => describeProcessExitStatus,
+	getProcessExitStatus: () => getProcessExitStatus,
+	nodeProcessSpawner: () => nodeProcessSpawner,
+	onceProcessError: () => onceProcessError,
+	onceProcessExit: () => onceProcessExit,
+	terminateManagedProcess: () => terminateManagedProcess,
+	waitForProcessExitOrTimeout: () => waitForProcessExitOrTimeout
+});
+const nodeProcessSpawner = (command, args, options) => spawn(command, [...args], {
+	cwd: options.cwd,
+	env: options.env,
+	stdio: options.stdio,
+	detached: options.detached
+});
+const describeProcessExitStatus = (status) => {
+	if (status.code !== null) return `exit code ${status.code}`;
+	if (status.signal !== null) return `signal ${status.signal}`;
+	return "unknown exit status";
+};
+const onceProcessExit = (child) => new Promise((resolveExit) => {
+	child.once("exit", (code, signal) => resolveExit({
+		code,
+		signal
+	}));
+});
+const getProcessExitStatus = (child) => {
+	if (child.exitCode !== void 0 && child.exitCode !== null) return {
+		code: child.exitCode,
+		signal: null
+	};
+	if (child.signalCode !== void 0 && child.signalCode !== null) return {
+		code: null,
+		signal: child.signalCode
+	};
+	return null;
+};
+const awaitProcessExit = (child) => Promise.resolve(getProcessExitStatus(child) ?? onceProcessExit(child));
+const onceProcessError = (child) => new Promise((resolveError) => {
+	child.once("error", (cause) => resolveError(cause));
+});
+const waitForProcessExitOrTimeout = (child, timeoutMs) => Promise.race([onceProcessExit(child), new Promise((resolveTimeout) => setTimeout(() => resolveTimeout(null), timeoutMs))]);
+const signalManagedProcess = (child, signal, processGroup) => {
+	if (processGroup && process.platform !== "win32" && child.pid !== void 0) try {
+		process.kill(-child.pid, signal);
+		return;
+	} catch {}
+	child.kill(signal);
+};
+const terminateManagedProcess = (child, options) => Effect.gen(function* () {
+	const exited = waitForProcessExitOrTimeout(child, options.graceMs);
+	yield* Effect.sync(() => {
+		signalManagedProcess(child, "SIGTERM", options.processGroup === true);
+	});
+	if ((yield* Effect.promise(() => exited)) !== null) return;
+	if (options.onEscalate !== void 0) yield* options.onEscalate().pipe(Effect.ignore);
+	const killed = waitForProcessExitOrTimeout(child, options.killTimeoutMs ?? 1e3);
+	yield* Effect.sync(() => {
+		signalManagedProcess(child, "SIGKILL", options.processGroup === true);
+	});
+	yield* Effect.promise(() => killed);
+});
+const awaitManagedProcessReady = (options) => Effect.raceFirst(options.ready, Effect.raceFirst(Effect.promise(() => options.exit).pipe(Effect.flatMap((status) => Effect.fail(options.onExitBeforeReady(status)))), Effect.promise(() => options.processError).pipe(Effect.flatMap((cause) => Effect.fail(options.onProcessErrorBeforeReady(cause))))));
+//#endregion
+export { awaitManagedProcessReady, awaitProcessExit, describeProcessExitStatus, nodeProcessSpawner, onceProcessError, onceProcessExit, process_supervisor_exports, terminateManagedProcess };
+
+//# sourceMappingURL=process-supervisor.mjs.map

package/dist/substrate/runtime/process-supervisor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-supervisor.mjs","names":[],"sources":["../../../src/substrate/runtime/process-supervisor.ts"],"sourcesContent":["import { spawn } from 'node:child_process';\nimport type { Readable } from 'node:stream';\n\nimport { Effect } from 'effect';\n\nexport interface ManagedProcessExitStatus {\n\treadonly code: number | null;\n\treadonly signal: NodeJS.Signals | null;\n}\n\nexport interface ManagedProcessChild {\n\treadonly pid?: number;\n\treadonly stdout?: Readable | null;\n\treadonly stderr?: Readable | null;\n\treadonly exitCode?: number | null;\n\treadonly signalCode?: NodeJS.Signals | null;\n\tkill(signal?: NodeJS.Signals): boolean;\n\ton(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\ton(event: 'error', listener: (cause: Error) => void): this;\n\tonce(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\tonce(event: 'error', listener: (cause: Error) => void): this;\n\toff(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\toff(event: 'error', listener: (cause: Error) => void): this;\n}\n\nexport interface ManagedProcessSpawnOptions {\n\treadonly cwd: string;\n\treadonly env: NodeJS.ProcessEnv;\n\treadonly stdio: 'pipe';\n\treadonly detached?: boolean;\n}\n\nexport type ManagedProcessSpawner = (\n\tcommand: string,\n\targs: ReadonlyArray<string>,\n\toptions: ManagedProcessSpawnOptions,\n) => ManagedProcessChild;\n\nexport const nodeProcessSpawner: ManagedProcessSpawner = (command, args, options) =>\n\tspawn(command, [...args], {\n\t\tcwd: options.cwd,\n\t\tenv: options.env,\n\t\tstdio: options.stdio,\n\t\tdetached: options.detached,\n\t}) as ManagedProcessChild;\n\nexport const describeProcessExitStatus = (status: ManagedProcessExitStatus): string => {\n\tif (status.code !== null) return `exit code ${status.code}`;\n\tif (status.signal !== null) return `signal ${status.signal}`;\n\treturn 'unknown exit status';\n};\n\nexport const onceProcessExit = (child: ManagedProcessChild): Promise<ManagedProcessExitStatus> =>\n\tnew Promise((resolveExit) => {\n\t\tchild.once('exit', (code, signal) => resolveExit({ code, signal }));\n\t});\n\nexport const getProcessExitStatus = (\n\tchild: ManagedProcessChild,\n): ManagedProcessExitStatus | null => {\n\tif (child.exitCode !== undefined && child.exitCode !== null) {\n\t\treturn { code: child.exitCode, signal: null };\n\t}\n\tif (child.signalCode !== undefined && child.signalCode !== null) {\n\t\treturn { code: null, signal: child.signalCode };\n\t}\n\treturn null;\n};\n\nexport const awaitProcessExit = (child: ManagedProcessChild): Promise<ManagedProcessExitStatus> =>\n\tPromise.resolve(getProcessExitStatus(child) ?? onceProcessExit(child));\n\nexport const onceProcessError = (child: ManagedProcessChild): Promise<unknown> =>\n\tnew Promise((resolveError) => {\n\t\tchild.once('error', (cause) => resolveError(cause));\n\t});\n\nexport const waitForProcessExitOrTimeout = (\n\tchild: ManagedProcessChild,\n\ttimeoutMs: number,\n): Promise<ManagedProcessExitStatus | null> =>\n\tPromise.race([\n\t\tonceProcessExit(child),\n\t\tnew Promise<null>((resolveTimeout) => setTimeout(() => resolveTimeout(null), timeoutMs)),\n\t]);\n\nexport interface TerminateManagedProcessOptions {\n\treadonly graceMs: number;\n\treadonly killTimeoutMs?: number;\n\treadonly processGroup?: boolean;\n\treadonly onEscalate?: () => Effect.Effect<void>;\n}\n\nconst signalManagedProcess = (\n\tchild: ManagedProcessChild,\n\tsignal: NodeJS.Signals,\n\tprocessGroup: boolean,\n): void => {\n\tif (processGroup && process.platform !== 'win32' && child.pid !== undefined) {\n\t\ttry {\n\t\t\tprocess.kill(-child.pid, signal);\n\t\t\treturn;\n\t\t} catch {\n\t\t\t// Fall back to the direct child signal below. This covers races\n\t\t\t// where the group has already exited and tests with fake pids.\n\t\t}\n\t}\n\tchild.kill(signal);\n};\n\nexport const terminateManagedProcess = (\n\tchild: ManagedProcessChild,\n\toptions: TerminateManagedProcessOptions,\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst exited = waitForProcessExitOrTimeout(child, options.graceMs);\n\t\tyield* Effect.sync(() => {\n\t\t\tsignalManagedProcess(child, 'SIGTERM', options.processGroup === true);\n\t\t});\n\t\tconst first = yield* Effect.promise(() => exited);\n\t\tif (first !== null) return;\n\t\tif (options.onEscalate !== undefined) {\n\t\t\tyield* options.onEscalate().pipe(Effect.ignore);\n\t\t}\n\t\tconst killed = waitForProcessExitOrTimeout(child, options.killTimeoutMs ?? 1_000);\n\t\tyield* Effect.sync(() => {\n\t\t\tsignalManagedProcess(child, 'SIGKILL', options.processGroup === true);\n\t\t});\n\t\tyield* Effect.promise(() => killed);\n\t});\n\nexport interface AwaitManagedProcessReadyOptions<E, R = never> {\n\treadonly ready: Effect.Effect<void, E, R>;\n\treadonly exit: Promise<ManagedProcessExitStatus>;\n\treadonly processError: Promise<unknown>;\n\treadonly onExitBeforeReady: (status: ManagedProcessExitStatus) => E;\n\treadonly onProcessErrorBeforeReady: (cause: unknown) => E;\n}\n\nexport const awaitManagedProcessReady = <E, R = never>(\n\toptions: AwaitManagedProcessReadyOptions<E, R>,\n): Effect.Effect<void, E, R> =>\n\tEffect.raceFirst(\n\t\toptions.ready,\n\t\tEffect.raceFirst(\n\t\t\tEffect.promise(() => options.exit).pipe(\n\t\t\t\tEffect.flatMap((status) => Effect.fail(options.onExitBeforeReady(status))),\n\t\t\t),\n\t\t\tEffect.promise(() => options.processError).pipe(\n\t\t\t\tEffect.flatMap((cause) => Effect.fail(options.onProcessErrorBeforeReady(cause))),\n\t\t\t),\n\t\t),\n\t);\n"],"mappings":";;;;;;;;;;;;;;;AAsCA,MAAa,sBAA6C,SAAS,MAAM,YACxE,MAAM,SAAS,CAAC,GAAG,KAAK,EAAE;CACzB,KAAK,QAAQ;CACb,KAAK,QAAQ;CACb,OAAO,QAAQ;CACf,UAAU,QAAQ;CAClB,CAAC;AAEH,MAAa,6BAA6B,WAA6C;AACtF,KAAI,OAAO,SAAS,KAAM,QAAO,aAAa,OAAO;AACrD,KAAI,OAAO,WAAW,KAAM,QAAO,UAAU,OAAO;AACpD,QAAO;;AAGR,MAAa,mBAAmB,UAC/B,IAAI,SAAS,gBAAgB;AAC5B,OAAM,KAAK,SAAS,MAAM,WAAW,YAAY;EAAE;EAAM;EAAQ,CAAC,CAAC;EAClE;AAEH,MAAa,wBACZ,UACqC;AACrC,KAAI,MAAM,aAAa,KAAA,KAAa,MAAM,aAAa,KACtD,QAAO;EAAE,MAAM,MAAM;EAAU,QAAQ;EAAM;AAE9C,KAAI,MAAM,eAAe,KAAA,KAAa,MAAM,eAAe,KAC1D,QAAO;EAAE,MAAM;EAAM,QAAQ,MAAM;EAAY;AAEhD,QAAO;;AAGR,MAAa,oBAAoB,UAChC,QAAQ,QAAQ,qBAAqB,MAAM,IAAI,gBAAgB,MAAM,CAAC;AAEvE,MAAa,oBAAoB,UAChC,IAAI,SAAS,iBAAiB;AAC7B,OAAM,KAAK,UAAU,UAAU,aAAa,MAAM,CAAC;EAClD;AAEH,MAAa,+BACZ,OACA,cAEA,QAAQ,KAAK,CACZ,gBAAgB,MAAM,EACtB,IAAI,SAAe,mBAAmB,iBAAiB,eAAe,KAAK,EAAE,UAAU,CAAC,CACxF,CAAC;AASH,MAAM,wBACL,OACA,QACA,iBACU;AACV,KAAI,gBAAgB,QAAQ,aAAa,WAAW,MAAM,QAAQ,KAAA,EACjE,KAAI;AACH,UAAQ,KAAK,CAAC,MAAM,KAAK,OAAO;AAChC;SACO;AAKT,OAAM,KAAK,OAAO;;AAGnB,MAAa,2BACZ,OACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,SAAS,4BAA4B,OAAO,QAAQ,QAAQ;AAClE,QAAO,OAAO,WAAW;AACxB,uBAAqB,OAAO,WAAW,QAAQ,iBAAiB,KAAK;GACpE;AAEF,MAAI,OADiB,OAAO,cAAc,OAAO,MACnC,KAAM;AACpB,KAAI,QAAQ,eAAe,KAAA,EAC1B,QAAO,QAAQ,YAAY,CAAC,KAAK,OAAO,OAAO;CAEhD,MAAM,SAAS,4BAA4B,OAAO,QAAQ,iBAAiB,IAAM;AACjF,QAAO,OAAO,WAAW;AACxB,uBAAqB,OAAO,WAAW,QAAQ,iBAAiB,KAAK;GACpE;AACF,QAAO,OAAO,cAAc,OAAO;EAClC;AAUH,MAAa,4BACZ,YAEA,OAAO,UACN,QAAQ,OACR,OAAO,UACN,OAAO,cAAc,QAAQ,KAAK,CAAC,KAClC,OAAO,SAAS,WAAW,OAAO,KAAK,QAAQ,kBAAkB,OAAO,CAAC,CAAC,CAC1E,EACD,OAAO,cAAc,QAAQ,aAAa,CAAC,KAC1C,OAAO,SAAS,UAAU,OAAO,KAAK,QAAQ,0BAA0B,MAAM,CAAC,CAAC,CAChF,CACD,CACD"}

package/dist/substrate/runtime/projection/operational-endpoints.mjs

@@ -0,0 +1,44 @@
+import { endpointKey } from "../../brand.mjs";
+//#region src/substrate/runtime/projection/operational-endpoints.ts
+const SAFE_URL_FIELDS = {
+	url: "http",
+	rpcUrl: "rpc",
+	faucetUrl: "faucet",
+	graphqlUrl: "graphql"
+};
+const SENSITIVE_URL_FIELD = /pair|token|secret|password|private|bearer/i;
+const operationalEndpointEventsFromResolvedValue = (pluginKey, value, registeredAt, options = {}) => {
+	if (options.routablesPresent === true) return [];
+	if (value === null || typeof value !== "object") return [];
+	const record = value;
+	const events = [];
+	for (const [field, name] of Object.entries(SAFE_URL_FIELDS)) {
+		if (SENSITIVE_URL_FIELD.test(field)) continue;
+		const raw = record[field];
+		if (typeof raw !== "string" || !isHttpUrl(raw)) continue;
+		events.push({
+			tag: "endpoint.registered",
+			endpoint: {
+				endpointKey: endpointKey(`${pluginKey}:${field}`),
+				name,
+				url: raw,
+				displayUrl: null,
+				wireProtocol: "http",
+				registeredAt
+			}
+		});
+	}
+	return events;
+};
+const isHttpUrl = (value) => {
+	try {
+		const parsed = new URL(value);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+};
+//#endregion
+export { operationalEndpointEventsFromResolvedValue };
+
+//# sourceMappingURL=operational-endpoints.mjs.map

package/dist/substrate/runtime/projection/operational-endpoints.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-endpoints.mjs","names":[],"sources":["../../../../src/substrate/runtime/projection/operational-endpoints.ts"],"sourcesContent":["import { endpointKey, type PluginKey } from '../../brand.ts';\nimport type { EngineEvent } from '../../events.ts';\n\ntype EndpointRegisteredEvent = Extract<EngineEvent, { readonly tag: 'endpoint.registered' }>;\n\nconst SAFE_URL_FIELDS = {\n\turl: 'http',\n\trpcUrl: 'rpc',\n\tfaucetUrl: 'faucet',\n\tgraphqlUrl: 'graphql',\n} as const;\n\nconst SENSITIVE_URL_FIELD = /pair|token|secret|password|private|bearer/i;\n\nexport interface OperationalEndpointProjectionOptions {\n\t/** Routable capabilities are the authoritative public endpoint\n\t * source. Resolved-value URL scraping is only a fallback for\n\t * plugins with no router contribution, such as live/local-rpc\n\t * network modes. */\n\treadonly routablesPresent?: boolean;\n}\n\nexport const operationalEndpointEventsFromResolvedValue = (\n\tpluginKey: PluginKey,\n\tvalue: unknown,\n\tregisteredAt: number,\n\toptions: OperationalEndpointProjectionOptions = {},\n): ReadonlyArray<EndpointRegisteredEvent> => {\n\tif (options.routablesPresent === true) return [];\n\tif (value === null || typeof value !== 'object') return [];\n\tconst record = value as Readonly<Record<string, unknown>>;\n\tconst events: Array<EndpointRegisteredEvent> = [];\n\tfor (const [field, name] of Object.entries(SAFE_URL_FIELDS)) {\n\t\tif (SENSITIVE_URL_FIELD.test(field)) continue;\n\t\tconst raw = record[field];\n\t\tif (typeof raw !== 'string' || !isHttpUrl(raw)) continue;\n\t\tevents.push({\n\t\t\ttag: 'endpoint.registered',\n\t\t\tendpoint: {\n\t\t\t\tendpointKey: endpointKey(`${pluginKey}:${field}`),\n\t\t\t\tname,\n\t\t\t\turl: raw,\n\t\t\t\tdisplayUrl: null,\n\t\t\t\twireProtocol: 'http',\n\t\t\t\tregisteredAt,\n\t\t\t},\n\t\t});\n\t}\n\treturn events;\n};\n\nconst isHttpUrl = (value: string): boolean => {\n\ttry {\n\t\tconst parsed = new URL(value);\n\t\treturn parsed.protocol === 'http:' || parsed.protocol === 'https:';\n\t} catch {\n\t\treturn false;\n\t}\n};\n"],"mappings":";;AAKA,MAAM,kBAAkB;CACvB,KAAK;CACL,QAAQ;CACR,WAAW;CACX,YAAY;CACZ;AAED,MAAM,sBAAsB;AAU5B,MAAa,8CACZ,WACA,OACA,cACA,UAAgD,EAAE,KACN;AAC5C,KAAI,QAAQ,qBAAqB,KAAM,QAAO,EAAE;AAChD,KAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO,EAAE;CAC1D,MAAM,SAAS;CACf,MAAM,SAAyC,EAAE;AACjD,MAAK,MAAM,CAAC,OAAO,SAAS,OAAO,QAAQ,gBAAgB,EAAE;AAC5D,MAAI,oBAAoB,KAAK,MAAM,CAAE;EACrC,MAAM,MAAM,OAAO;AACnB,MAAI,OAAO,QAAQ,YAAY,CAAC,UAAU,IAAI,CAAE;AAChD,SAAO,KAAK;GACX,KAAK;GACL,UAAU;IACT,aAAa,YAAY,GAAG,UAAU,GAAG,QAAQ;IACjD;IACA,KAAK;IACL,YAAY;IACZ,cAAc;IACd;IACA;GACD,CAAC;;AAEH,QAAO;;AAGR,MAAM,aAAa,UAA2B;AAC7C,KAAI;EACH,MAAM,SAAS,IAAI,IAAI,MAAM;AAC7B,SAAO,OAAO,aAAa,WAAW,OAAO,aAAa;SACnD;AACP,SAAO"}

package/dist/substrate/runtime/projection/persisted.mjs

@@ -0,0 +1,195 @@
+import { decodeJsonTextSync } from "../runtime-decode.mjs";
+import { endpointKey, pluginKey } from "../../brand.mjs";
+import { atomicWriteJson } from "../atomic-write.mjs";
+import { Effect, Schema, Stream, SubscriptionRef } from "effect";
+import { existsSync, readFileSync } from "node:fs";
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
+//#region src/substrate/runtime/projection/persisted.ts
+const PROJECTION_SNAPSHOT_FILE_NAME = "projection.v3.json";
+const projectionSnapshotPath = (stackRoot) => `${stackRoot}/${PROJECTION_SNAPSHOT_FILE_NAME}`;
+const SeveritySchema = Schema.Literals([
+	"warn",
+	"error",
+	"fatal"
+]);
+const LogLevelSchema = Schema.Literals([
+	"info",
+	"warn",
+	"error"
+]);
+const LifecycleStatusSchema = Schema.Literals([
+	"pending",
+	"acquiring",
+	"ready",
+	"failed",
+	"stopping",
+	"stopped",
+	"done"
+]);
+const PluginRoleSchema = Schema.Literals(["service", "task"]);
+const CyclePhaseSchema = Schema.Literals([
+	"booting",
+	"running",
+	"restarting",
+	"shutting-down"
+]);
+const StructuredErrorSchema = Schema.Struct({
+	at: Schema.Number,
+	pluginKey: Schema.NullOr(Schema.String),
+	tag: Schema.String,
+	summary: Schema.String,
+	chain: Schema.Array(Schema.String),
+	severity: SeveritySchema
+});
+const EndpointSchema = Schema.Struct({
+	endpointKey: Schema.String,
+	name: Schema.String,
+	url: Schema.String,
+	displayUrl: Schema.NullOr(Schema.String),
+	wireProtocol: Schema.String,
+	registeredAt: Schema.Number
+});
+const AccountProjectionSchema = Schema.Struct({
+	key: Schema.String,
+	rowKey: Schema.NullOr(Schema.String),
+	name: Schema.String,
+	address: Schema.NullOr(Schema.String),
+	scheme: Schema.NullOr(Schema.Literals([
+		"ed25519",
+		"secp256k1",
+		"secp256r1"
+	])),
+	source: Schema.NullOr(Schema.Literals(["real", "impersonate"])),
+	funding: Schema.Struct({
+		status: Schema.Literals([
+			"pending",
+			"funded",
+			"skipped",
+			"failed",
+			"unknown"
+		]),
+		balanceMist: Schema.NullOr(Schema.String),
+		requestedMist: Schema.NullOr(Schema.String),
+		entries: Schema.optional(Schema.Array(Schema.Struct({
+			coin: Schema.String,
+			fullCoinType: Schema.String,
+			amount: Schema.String,
+			status: Schema.Literals(["funded", "skipped"])
+		})))
+	}),
+	walletVisible: Schema.Boolean,
+	updatedAt: Schema.Number
+});
+const PackageProjectionSchema = Schema.Struct({
+	key: Schema.String,
+	rowKey: Schema.NullOr(Schema.String),
+	name: Schema.String,
+	kind: Schema.Literals(["local", "known"]),
+	packageId: Schema.String,
+	upgradeCapId: Schema.NullOr(Schema.String),
+	mvrPlaceholder: Schema.String,
+	sourcePath: Schema.NullOr(Schema.String),
+	updatedAt: Schema.Number
+});
+const RowSchema = Schema.Struct({
+	key: Schema.String,
+	role: PluginRoleSchema,
+	status: LifecycleStatusSchema,
+	phase: Schema.NullOr(Schema.String),
+	lastError: Schema.NullOr(StructuredErrorSchema),
+	logTail: Schema.Struct({
+		lines: Schema.Array(Schema.String),
+		level: LogLevelSchema,
+		truncated: Schema.Boolean
+	}),
+	endpoints: Schema.Array(Schema.String),
+	selectiveRestartHighlight: Schema.Boolean
+});
+const BuildEntrySchema = Schema.Struct({
+	pluginKey: Schema.NullOr(Schema.String),
+	phase: Schema.String,
+	progress: Schema.String,
+	startedAt: Schema.Number
+});
+const SubscribableStateSchema = Schema.Struct({
+	identity: Schema.Struct({
+		app: Schema.String,
+		stack: Schema.String,
+		network: Schema.String
+	}),
+	cycle: Schema.Struct({
+		id: Schema.Number,
+		startedAt: Schema.Number,
+		phase: CyclePhaseSchema
+	}),
+	rows: Schema.Array(RowSchema),
+	endpoints: Schema.Array(EndpointSchema),
+	accounts: Schema.Array(AccountProjectionSchema),
+	packages: Schema.Array(PackageProjectionSchema),
+	errors: Schema.Array(StructuredErrorSchema),
+	lastEvent: Schema.Struct({
+		seq: Schema.Number,
+		at: Schema.Number
+	}),
+	stackBuild: Schema.Array(BuildEntrySchema)
+});
+const ProjectionSnapshotSchema = Schema.Struct({
+	version: Schema.Literal(3),
+	state: SubscribableStateSchema
+});
+const rebrandStructuredError = (error) => ({
+	...error,
+	pluginKey: error.pluginKey === null ? null : pluginKey(error.pluginKey)
+});
+const rebrandPersistedState = (state) => ({
+	...state,
+	rows: state.rows.map((row) => ({
+		...row,
+		key: pluginKey(row.key),
+		lastError: row.lastError === null ? null : rebrandStructuredError(row.lastError),
+		endpoints: row.endpoints.map(endpointKey)
+	})),
+	endpoints: state.endpoints.map((endpoint) => ({
+		...endpoint,
+		endpointKey: endpointKey(endpoint.endpointKey)
+	})),
+	accounts: state.accounts.map((account) => ({
+		...account,
+		key: account.key,
+		rowKey: account.rowKey === null ? null : pluginKey(account.rowKey)
+	})),
+	packages: state.packages.map((pkg) => ({
+		...pkg,
+		key: pkg.key,
+		rowKey: pkg.rowKey === null ? null : pluginKey(pkg.rowKey)
+	})),
+	errors: state.errors.map(rebrandStructuredError),
+	stackBuild: state.stackBuild.map((entry) => ({
+		...entry,
+		pluginKey: entry.pluginKey === null ? null : pluginKey(entry.pluginKey)
+	}))
+});
+const writeProjectionSnapshot = (stackRoot, state) => atomicWriteJson(projectionSnapshotPath(stackRoot), ProjectionSnapshotSchema, {
+	version: 3,
+	state
+}).pipe(Effect.provide(NodeFileSystem.layer), Effect.catch(() => Effect.void));
+const persistProjectionChanges = (stackRoot, ref) => Effect.gen(function* () {
+	yield* writeProjectionSnapshot(stackRoot, yield* SubscriptionRef.get(ref));
+	yield* Stream.runForEach(SubscriptionRef.changes(ref), (state) => writeProjectionSnapshot(stackRoot, state));
+});
+const readProjectionSnapshot = (stackRoot) => {
+	const path = projectionSnapshotPath(stackRoot);
+	if (!existsSync(path)) return null;
+	try {
+		return rebrandPersistedState(decodeJsonTextSync(ProjectionSnapshotSchema, readFileSync(path, "utf8"), {
+			source: path,
+			mkError: (issue) => issue
+		}).state);
+	} catch {
+		return null;
+	}
+};
+//#endregion
+export { persistProjectionChanges, readProjectionSnapshot, writeProjectionSnapshot };
+
+//# sourceMappingURL=persisted.mjs.map

package/dist/substrate/runtime/projection/persisted.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"persisted.mjs","names":[],"sources":["../../../../src/substrate/runtime/projection/persisted.ts"],"sourcesContent":["import { existsSync, readFileSync } from 'node:fs';\n\nimport { Effect, Schema, Stream, SubscriptionRef } from 'effect';\nimport * as NodeFileSystem from '@effect/platform-node/NodeFileSystem';\n\nimport type { SubscribableState } from '../../projection.ts';\nimport { endpointKey, pluginKey } from '../../brand.ts';\nimport { atomicWriteJson } from '../atomic-write.ts';\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\n\nexport const PROJECTION_SNAPSHOT_FILE_NAME = 'projection.v3.json';\n\nexport const projectionSnapshotPath = (stackRoot: string): string =>\n\t`${stackRoot}/${PROJECTION_SNAPSHOT_FILE_NAME}`;\n\nconst SeveritySchema = Schema.Literals(['warn', 'error', 'fatal']);\nconst LogLevelSchema = Schema.Literals(['info', 'warn', 'error']);\nconst LifecycleStatusSchema = Schema.Literals([\n\t'pending',\n\t'acquiring',\n\t'ready',\n\t'failed',\n\t'stopping',\n\t'stopped',\n\t'done',\n]);\nconst PluginRoleSchema = Schema.Literals(['service', 'task']);\nconst CyclePhaseSchema = Schema.Literals(['booting', 'running', 'restarting', 'shutting-down']);\n\nconst StructuredErrorSchema = Schema.Struct({\n\tat: Schema.Number,\n\tpluginKey: Schema.NullOr(Schema.String),\n\ttag: Schema.String,\n\tsummary: Schema.String,\n\tchain: Schema.Array(Schema.String),\n\tseverity: SeveritySchema,\n});\n\nconst EndpointSchema = Schema.Struct({\n\tendpointKey: Schema.String,\n\tname: Schema.String,\n\turl: Schema.String,\n\tdisplayUrl: Schema.NullOr(Schema.String),\n\twireProtocol: Schema.String,\n\tregisteredAt: Schema.Number,\n});\n\nconst AccountProjectionSchema = Schema.Struct({\n\tkey: Schema.String,\n\trowKey: Schema.NullOr(Schema.String),\n\tname: Schema.String,\n\taddress: Schema.NullOr(Schema.String),\n\tscheme: Schema.NullOr(Schema.Literals(['ed25519', 'secp256k1', 'secp256r1'])),\n\tsource: Schema.NullOr(Schema.Literals(['real', 'impersonate'])),\n\tfunding: Schema.Struct({\n\t\tstatus: Schema.Literals(['pending', 'funded', 'skipped', 'failed', 'unknown']),\n\t\tbalanceMist: Schema.NullOr(Schema.String),\n\t\trequestedMist: Schema.NullOr(Schema.String),\n\t\tentries: Schema.optional(\n\t\t\tSchema.Array(\n\t\t\t\tSchema.Struct({\n\t\t\t\t\tcoin: Schema.String,\n\t\t\t\t\tfullCoinType: Schema.String,\n\t\t\t\t\tamount: Schema.String,\n\t\t\t\t\tstatus: Schema.Literals(['funded', 'skipped']),\n\t\t\t\t}),\n\t\t\t),\n\t\t),\n\t}),\n\twalletVisible: Schema.Boolean,\n\tupdatedAt: Schema.Number,\n});\n\nconst PackageProjectionSchema = Schema.Struct({\n\tkey: Schema.String,\n\trowKey: Schema.NullOr(Schema.String),\n\tname: Schema.String,\n\tkind: Schema.Literals(['local', 'known']),\n\tpackageId: Schema.String,\n\tupgradeCapId: Schema.NullOr(Schema.String),\n\tmvrPlaceholder: Schema.String,\n\tsourcePath: Schema.NullOr(Schema.String),\n\tupdatedAt: Schema.Number,\n});\n\nconst RowSchema = Schema.Struct({\n\tkey: Schema.String,\n\trole: PluginRoleSchema,\n\tstatus: LifecycleStatusSchema,\n\tphase: Schema.NullOr(Schema.String),\n\tlastError: Schema.NullOr(StructuredErrorSchema),\n\tlogTail: Schema.Struct({\n\t\tlines: Schema.Array(Schema.String),\n\t\tlevel: LogLevelSchema,\n\t\ttruncated: Schema.Boolean,\n\t}),\n\tendpoints: Schema.Array(Schema.String),\n\tselectiveRestartHighlight: Schema.Boolean,\n});\n\nconst BuildEntrySchema = Schema.Struct({\n\tpluginKey: Schema.NullOr(Schema.String),\n\tphase: Schema.String,\n\tprogress: Schema.String,\n\tstartedAt: Schema.Number,\n});\n\nconst SubscribableStateSchema = Schema.Struct({\n\tidentity: Schema.Struct({\n\t\tapp: Schema.String,\n\t\tstack: Schema.String,\n\t\tnetwork: Schema.String,\n\t}),\n\tcycle: Schema.Struct({\n\t\tid: Schema.Number,\n\t\tstartedAt: Schema.Number,\n\t\tphase: CyclePhaseSchema,\n\t}),\n\trows: Schema.Array(RowSchema),\n\tendpoints: Schema.Array(EndpointSchema),\n\taccounts: Schema.Array(AccountProjectionSchema),\n\tpackages: Schema.Array(PackageProjectionSchema),\n\terrors: Schema.Array(StructuredErrorSchema),\n\tlastEvent: Schema.Struct({\n\t\tseq: Schema.Number,\n\t\tat: Schema.Number,\n\t}),\n\tstackBuild: Schema.Array(BuildEntrySchema),\n});\n\nexport const ProjectionSnapshotSchema = Schema.Struct({\n\tversion: Schema.Literal(3),\n\tstate: SubscribableStateSchema,\n});\n\ntype PersistedSubscribableState = Schema.Schema.Type<typeof SubscribableStateSchema>;\ntype PersistedStructuredError = PersistedSubscribableState['errors'][number];\n\nconst rebrandStructuredError = (error: PersistedStructuredError) => ({\n\t...error,\n\tpluginKey: error.pluginKey === null ? null : pluginKey(error.pluginKey),\n});\n\nconst rebrandPersistedState = (state: PersistedSubscribableState): SubscribableState => ({\n\t...state,\n\trows: state.rows.map((row) => ({\n\t\t...row,\n\t\tkey: pluginKey(row.key),\n\t\tlastError: row.lastError === null ? null : rebrandStructuredError(row.lastError),\n\t\tendpoints: row.endpoints.map(endpointKey),\n\t})),\n\tendpoints: state.endpoints.map((endpoint) => ({\n\t\t...endpoint,\n\t\tendpointKey: endpointKey(endpoint.endpointKey),\n\t})),\n\taccounts: state.accounts.map((account) => ({\n\t\t...account,\n\t\tkey: account.key as `account/${string}`,\n\t\trowKey: account.rowKey === null ? null : pluginKey(account.rowKey),\n\t})),\n\tpackages: state.packages.map((pkg) => ({\n\t\t...pkg,\n\t\tkey: pkg.key as `package/${string}`,\n\t\trowKey: pkg.rowKey === null ? null : pluginKey(pkg.rowKey),\n\t})),\n\terrors: state.errors.map(rebrandStructuredError),\n\tstackBuild: state.stackBuild.map((entry) => ({\n\t\t...entry,\n\t\tpluginKey: entry.pluginKey === null ? null : pluginKey(entry.pluginKey),\n\t})),\n});\n\nexport const writeProjectionSnapshot = (\n\tstackRoot: string,\n\tstate: SubscribableState,\n): Effect.Effect<void> =>\n\tatomicWriteJson(projectionSnapshotPath(stackRoot), ProjectionSnapshotSchema, {\n\t\tversion: 3 as const,\n\t\tstate,\n\t}).pipe(\n\t\tEffect.provide(NodeFileSystem.layer),\n\t\tEffect.catch(() => Effect.void),\n\t);\n\nexport const persistProjectionChanges = (\n\tstackRoot: string,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tyield* writeProjectionSnapshot(stackRoot, yield* SubscriptionRef.get(ref));\n\t\tyield* Stream.runForEach(SubscriptionRef.changes(ref), (state) =>\n\t\t\twriteProjectionSnapshot(stackRoot, state),\n\t\t);\n\t});\n\nexport const readProjectionSnapshot = (stackRoot: string): SubscribableState | null => {\n\tconst path = projectionSnapshotPath(stackRoot);\n\tif (!existsSync(path)) return null;\n\ttry {\n\t\tconst snapshot = decodeJsonTextSync(ProjectionSnapshotSchema, readFileSync(path, 'utf8'), {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t\treturn rebrandPersistedState(snapshot.state);\n\t} catch {\n\t\treturn null;\n\t}\n};\n"],"mappings":"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"}

package/dist/substrate/runtime/projection/state-ref.mjs

@@ -0,0 +1,48 @@
+import { SubscriptionRef } from "effect";
+//#region src/substrate/runtime/projection/state-ref.ts
+/**
+* Empty initial projection. Cycle starts at `id: 0`, `phase:
+* 'booting'`. Identity fields are placeholder; the engine MUST
+* replace via `update.ts::setIdentity` before any renderer is
+* notified of anything user-visible.
+*
+* The shape here is the entire contract the renderer sees — no
+* service names, no display vocabulary. If a future field needs
+* adding, the architecture-revision discipline kicks in via
+* `__ProjectionFieldsClosed`.
+*/
+const emptyProjection = () => ({
+	identity: {
+		app: "",
+		stack: "",
+		network: ""
+	},
+	cycle: {
+		id: 0,
+		startedAt: 0,
+		phase: "booting"
+	},
+	rows: [],
+	endpoints: [],
+	accounts: [],
+	packages: [],
+	errors: [],
+	lastEvent: {
+		seq: 0,
+		at: 0
+	},
+	stackBuild: []
+});
+/**
+* Create the subscribable projection ref. One per process.
+*
+* Engine cycle: the ref outlives the engine cycle. Stop-and-restart
+* keeps the same ref; only `cycle.id` increments. Renderers see a
+* continuous stream — that's the whole point of decoupling renderer
+* lifetime from engine cycle.
+*/
+const makeProjectionRef = () => SubscriptionRef.make(emptyProjection());
+//#endregion
+export { makeProjectionRef };
+
+//# sourceMappingURL=state-ref.mjs.map

package/dist/substrate/runtime/projection/state-ref.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-ref.mjs","names":[],"sources":["../../../../src/substrate/runtime/projection/state-ref.ts"],"sourcesContent":["// Subscribable projection state-ref.\n//\n// Architecture § Renderer § \"Subscribable projection — exact field\n// enumeration\" (G2) + § \"Renderer mount lifetime vs engine cycle\n// lifetime\" (decision #8). The state-ref is process-scoped (mounted\n// once); the engine cycle re-runs many times and never re-creates the\n// ref. The renderer subscribes once at mount; the engine updates\n// in-place across cycles.\n//\n// The projection's TypeScript shape is enforced closed by\n// `__ProjectionFieldsClosed` in `../../projection.ts`. Adding a\n// display-vocabulary field (`title`, `primary`, `extras`) at this\n// layer would fail to assign into `SubscribableState` — renderers\n// derive those from `rows[*].kind` + display rules.\n\nimport { Effect, SubscriptionRef } from 'effect';\n\nimport type {\n\tBuildEntry,\n\tAccountProjection,\n\tEndpoint,\n\tPackageProjection,\n\tRow,\n\tStructuredError,\n\tSubscribableState,\n} from '../../projection.ts';\n\n/**\n * Empty initial projection. Cycle starts at `id: 0`, `phase:\n * 'booting'`. Identity fields are placeholder; the engine MUST\n * replace via `update.ts::setIdentity` before any renderer is\n * notified of anything user-visible.\n *\n * The shape here is the entire contract the renderer sees — no\n * service names, no display vocabulary. If a future field needs\n * adding, the architecture-revision discipline kicks in via\n * `__ProjectionFieldsClosed`.\n */\nexport const emptyProjection = (): SubscribableState => ({\n\tidentity: { app: '', stack: '', network: '' },\n\tcycle: { id: 0, startedAt: 0, phase: 'booting' },\n\trows: [],\n\tendpoints: [],\n\taccounts: [],\n\tpackages: [],\n\terrors: [],\n\tlastEvent: { seq: 0, at: 0 },\n\tstackBuild: [],\n});\n\n/**\n * Create the subscribable projection ref. One per process.\n *\n * Engine cycle: the ref outlives the engine cycle. Stop-and-restart\n * keeps the same ref; only `cycle.id` increments. Renderers see a\n * continuous stream — that's the whole point of decoupling renderer\n * lifetime from engine cycle.\n */\nexport const makeProjectionRef = (): Effect.Effect<\n\tSubscriptionRef.SubscriptionRef<SubscribableState>\n> => SubscriptionRef.make(emptyProjection());\n\n/**\n * Compile-time guard: the projection shape MUST NOT contain display\n * vocabulary. These conditional types resolve to `never` (and would\n * fail to assign anywhere they're used) if `title`/`primary`/\n * `extras` were ever added to `SubscribableState` or `Row`.\n *\n * The architecture's invariant becomes a TS error at the boundary\n * — the projection layer can't be wired up if a renderer-display\n * concept leaks into the engine's data model.\n */\ntype _NoDisplayVocabAtTop = 'title' extends keyof SubscribableState\n\t? never\n\t: 'primary' extends keyof SubscribableState\n\t\t? never\n\t\t: 'extras' extends keyof SubscribableState\n\t\t\t? never\n\t\t\t: true;\ntype _NoDisplayVocabInRow = 'title' extends keyof Row\n\t? never\n\t: 'primary' extends keyof Row\n\t\t? never\n\t\t: 'extras' extends keyof Row\n\t\t\t? never\n\t\t\t: true;\nexport type __NoDisplayVocab = _NoDisplayVocabAtTop & _NoDisplayVocabInRow extends true\n\t? true\n\t: never;\n\n// Re-export the sub-types renderers reach for so they don't import\n// across the substrate boundary directly — `state-ref.ts` is the\n// renderer-facing entry point.\nexport type {\n\tAccountProjection,\n\tBuildEntry,\n\tEndpoint,\n\tPackageProjection,\n\tRow,\n\tStructuredError,\n\tSubscribableState,\n};\n"],"mappings":";;;;;;;;;;;;;AAsCA,MAAa,yBAA4C;CACxD,UAAU;EAAE,KAAK;EAAI,OAAO;EAAI,SAAS;EAAI;CAC7C,OAAO;EAAE,IAAI;EAAG,WAAW;EAAG,OAAO;EAAW;CAChD,MAAM,EAAE;CACR,WAAW,EAAE;CACb,UAAU,EAAE;CACZ,UAAU,EAAE;CACZ,QAAQ,EAAE;CACV,WAAW;EAAE,KAAK;EAAG,IAAI;EAAG;CAC5B,YAAY,EAAE;CACd;;;;;;;;;AAUD,MAAa,0BAER,gBAAgB,KAAK,iBAAiB,CAAC"}

package/dist/substrate/runtime/projection/update.mjs

@@ -0,0 +1,200 @@
+import { applyLifecycleFact, factFromEvent } from "../lifecycle/lifecycle-fact.mjs";
+import { SubscriptionRef } from "effect";
+//#region src/substrate/runtime/projection/update.ts
+/** Bounded buffer for the top-level errors list. */
+const MAX_ERRORS_KEPT = 100;
+/** Bounded buffer for the top-level build-entries list. */
+const MAX_BUILD_ENTRIES_KEPT = 200;
+/** Per-row bounded log-tail length. Architecture: default 100 lines. */
+const MAX_ROW_LOG_LINES = 100;
+/**
+* Pure projection reducer. One event in, one new state out. All field
+* writes preserve `readonly` invariants by constructing fresh
+* objects/arrays rather than mutating.
+*
+* The `tag` switch is exhaustive against `EngineEvent['tag']`; the
+* trailing `_exhaustive: never` causes TS to flag any new tag that
+* isn't handled here.
+*/
+const applyEvent = (state, event) => {
+	const withTouched = (next) => ({
+		...state,
+		...next,
+		lastEvent: {
+			seq: state.lastEvent.seq,
+			at: eventAt(event) ?? state.lastEvent.at
+		}
+	});
+	const fact = factFromEvent(event);
+	if (fact !== null) return withTouched({ rows: upsertRow(state.rows, fact.pluginKey, (row) => applyLifecycleFact(row, fact.delta)) });
+	switch (event.tag) {
+		case "lifecycle.statusChanged":
+		case "lifecycle.phaseSet": return withTouched({});
+		case "log.appended": return withTouched({ rows: upsertRow(state.rows, event.pluginKey, (row) => appendLogLine(row, event.line, event.level)) });
+		case "endpoint.registered": return withTouched({
+			endpoints: upsertEndpoint(state.endpoints, event.endpoint),
+			rows: attachEndpoint(state.rows, event.endpoint)
+		});
+		case "account.updated": return withTouched({ accounts: upsertAccount(state.accounts, event.account) });
+		case "package.updated": return withTouched({ packages: upsertPackage(state.packages, event.package) });
+		case "endpoint.released": return withTouched({});
+		case "strategy.registered":
+		case "strategy.unregistered":
+		case "manifest.flushed":
+		case "codegen.emitted":
+		case "snapshot.captureStarted":
+		case "snapshot.captureProgress":
+		case "snapshot.captureSkipped":
+		case "snapshot.captureFailed":
+		case "snapshot.captured":
+		case "snapshot.restored": return withTouched({});
+		case "shutdown.escalated": return withTouched({ cycle: {
+			...state.cycle,
+			phase: "shutting-down"
+		} });
+		case "error.reported": return withTouched({
+			errors: pushBounded(state.errors, event.error, MAX_ERRORS_KEPT),
+			rows: event.error.pluginKey ? upsertRow(state.rows, event.error.pluginKey, (row) => ({
+				...row,
+				lastError: event.error
+			})) : state.rows
+		});
+		case "build.statusChanged": return withTouched({ stackBuild: pushBounded(state.stackBuild, event.entry, MAX_BUILD_ENTRIES_KEPT) });
+		case "restart.requested": return withTouched({
+			cycle: {
+				...state.cycle,
+				phase: "restarting"
+			},
+			rows: event.target === "stack" ? state.rows.map((r) => ({
+				...r,
+				selectiveRestartHighlight: false
+			})) : state.rows.map((r) => r.key === event.target.pluginKey ? {
+				...r,
+				selectiveRestartHighlight: true
+			} : r)
+		});
+		case "restart.completed": return withTouched({
+			cycle: {
+				...state.cycle,
+				phase: "running"
+			},
+			rows: state.rows.map((r) => ({
+				...r,
+				selectiveRestartHighlight: false
+			}))
+		});
+		default: return state;
+	}
+};
+/**
+* Replace `identity` on the projection. Called once at boot per cycle;
+* does NOT change on hot-restart.
+*/
+const setIdentity = (state, identity) => ({
+	...state,
+	identity
+});
+const declareAccount = (state, account) => ({
+	...state,
+	accounts: upsertAccount(state.accounts, account)
+});
+/**
+* Apply an `EngineEvent` to the ref, bumping the sequence number
+* atomically. The seq is monotonic per process and survives cycle
+* boundaries.
+*
+* Uses `state.lastEvent.seq + 1` for monotonic per-process counts.
+*/
+const updateRef = (ref, event) => SubscriptionRef.update(ref, (state) => {
+	const next = applyEvent(state, event);
+	return {
+		...next,
+		lastEvent: {
+			seq: state.lastEvent.seq + 1,
+			at: next.lastEvent.at
+		}
+	};
+});
+const eventAt = (event) => {
+	if ("at" in event) return event.at;
+	switch (event.tag) {
+		case "endpoint.registered": return event.endpoint.registeredAt;
+		case "error.reported": return event.error.at;
+		case "build.statusChanged": return event.entry.startedAt;
+		default: return null;
+	}
+};
+const upsertRow = (rows, key, update) => {
+	const idx = rows.findIndex((r) => r.key === key);
+	if (idx === -1) return rows;
+	const next = rows.slice();
+	next[idx] = update(rows[idx]);
+	return next;
+};
+const appendLogLine = (row, line, level) => {
+	const nextLines = [...row.logTail.lines, line];
+	const truncated = nextLines.length > MAX_ROW_LOG_LINES;
+	const trimmed = truncated ? nextLines.slice(-MAX_ROW_LOG_LINES) : nextLines;
+	return {
+		...row,
+		logTail: {
+			lines: trimmed,
+			level: maxLevel(row.logTail.level, level),
+			truncated: row.logTail.truncated || truncated
+		}
+	};
+};
+const maxLevel = (a, b) => {
+	const rank = {
+		info: 0,
+		warn: 1,
+		error: 2
+	};
+	return rank[a] >= rank[b] ? a : b;
+};
+const upsertEndpoint = (endpoints, endpoint) => {
+	const idx = endpoints.findIndex((e) => e.endpointKey === endpoint.endpointKey);
+	if (idx === -1) return [...endpoints, endpoint];
+	const next = endpoints.slice();
+	next[idx] = endpoint;
+	return next;
+};
+const upsertAccount = (accounts, account) => {
+	const idx = accounts.findIndex((entry) => entry.key === account.key);
+	if (idx === -1) return [...accounts, account];
+	const next = accounts.slice();
+	next[idx] = {
+		...accounts[idx],
+		...account,
+		funding: {
+			...accounts[idx].funding,
+			...account.funding
+		}
+	};
+	return next;
+};
+const upsertPackage = (packages, pkg) => {
+	const idx = packages.findIndex((entry) => entry.key === pkg.key);
+	if (idx === -1) return [...packages, pkg];
+	const next = packages.slice();
+	next[idx] = {
+		...packages[idx],
+		...pkg
+	};
+	return next;
+};
+const attachEndpoint = (rows, endpoint) => {
+	const probableKey = endpoint.endpointKey;
+	return rows.map((row) => probableKey.startsWith(row.key) ? row.endpoints.includes(probableKey) ? row : {
+		...row,
+		endpoints: [...row.endpoints, probableKey]
+	} : row);
+};
+const pushBounded = (xs, value, max) => {
+	const next = [...xs, value];
+	return next.length > max ? next.slice(-max) : next;
+};
+//#endregion
+export { declareAccount, setIdentity, updateRef };
+
+//# sourceMappingURL=update.mjs.map