@mysten-incubation/devstack 0.0.0

package/dist/substrate/runtime/config-validation.mjs

@@ -0,0 +1,137 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.mjs";
+import { Effect, Schema } from "effect";
+//#region src/substrate/runtime/config-validation.ts
+var config_validation_exports = /* @__PURE__ */ __exportAll({
+	decodeConfig: () => decodeConfig,
+	decodeConfigSync: () => decodeConfigSync,
+	defineConfigError: () => defineConfigError,
+	expectNonEmptyArray: () => expectNonEmptyArray,
+	expectNonEmptyString: () => expectNonEmptyString,
+	expectOneOf: () => expectOneOf,
+	expectOptionalNonEmptyString: () => expectOptionalNonEmptyString,
+	expectOptionalPort: () => expectOptionalPort,
+	expectOptionalPositiveInteger: () => expectOptionalPositiveInteger,
+	expectPattern: () => expectPattern,
+	expectPort: () => expectPort,
+	expectPositiveFiniteNumber: () => expectPositiveFiniteNumber,
+	expectPositiveInteger: () => expectPositiveInteger,
+	expectStringRecord: () => expectStringRecord
+});
+const defineConfigError = (tag) => (issue) => ({
+	_tag: tag,
+	...issue
+});
+const fail = (mkError, issue) => {
+	throw mkError(issue);
+};
+const expectNonEmptyString = (value, options) => {
+	if (typeof value === "string" && value.length > 0) return value;
+	return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? "must be a non-empty string",
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+};
+const expectOptionalNonEmptyString = (value, options) => {
+	if (value === void 0) return void 0;
+	return expectNonEmptyString(value, options);
+};
+const expectPositiveInteger = (value, options) => {
+	if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+	return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? "must be a positive integer",
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+};
+const expectOptionalPositiveInteger = (value, options) => {
+	if (value === void 0) return void 0;
+	return expectPositiveInteger(value, options);
+};
+const expectPositiveFiniteNumber = (value, options) => {
+	if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+	return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? "must be a positive finite number",
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+};
+const expectPort = (value, options) => {
+	if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535) return value;
+	return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? "must be an integer between 1 and 65535",
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+};
+const expectOptionalPort = (value, options) => {
+	if (value === void 0) return void 0;
+	return expectPort(value, options);
+};
+const expectStringRecord = (value, options) => {
+	if (value === void 0) return {};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? "must be an object of string values",
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+	for (const [key, entry] of Object.entries(value)) {
+		if (key.length === 0) return fail(options.mkError, {
+			field: options.field,
+			message: "environment variable names must be non-empty",
+			...options.hint === void 0 ? {} : { hint: options.hint }
+		});
+		if (typeof entry !== "string") return fail(options.mkError, {
+			field: `${options.field}.${key}`,
+			message: "must be a string",
+			...options.hint === void 0 ? {} : { hint: options.hint }
+		});
+	}
+	return value;
+};
+const expectOneOf = (value, values, options) => {
+	if (typeof value === "string" && values.includes(value)) return value;
+	return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? `must be one of ${values.map((v) => `'${v}'`).join(", ")}`,
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+};
+const expectNonEmptyArray = (value, options) => {
+	if (Array.isArray(value) && value.length > 0) return value;
+	return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? "must be a non-empty array",
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+};
+const expectPattern = (value, pattern, options) => {
+	if (pattern.test(value)) return value;
+	return fail(options.mkError, {
+		field: options.field,
+		message: options.message ?? `must match ${pattern.source}`,
+		...options.hint === void 0 ? {} : { hint: options.hint }
+	});
+};
+const decodeConfig = (schema, value, options) => Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError((cause) => options.mkError({
+	field: options.field,
+	message: options.message ?? "failed to decode config value",
+	...options.hint === void 0 ? {} : { hint: options.hint },
+	cause
+})));
+const decodeConfigSync = (schema, value, options) => {
+	try {
+		return Schema.decodeUnknownSync(schema)(value);
+	} catch (cause) {
+		return fail(options.mkError, {
+			field: options.field,
+			message: options.message ?? "failed to decode config value",
+			...options.hint === void 0 ? {} : { hint: options.hint },
+			cause
+		});
+	}
+};
+//#endregion
+export { config_validation_exports, defineConfigError, expectNonEmptyArray, expectNonEmptyString, expectOneOf, expectOptionalNonEmptyString, expectOptionalPort, expectOptionalPositiveInteger, expectPositiveFiniteNumber, expectPositiveInteger, expectStringRecord };
+
+//# sourceMappingURL=config-validation.mjs.map

package/dist/substrate/runtime/config-validation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-validation.mjs","names":[],"sources":["../../../src/substrate/runtime/config-validation.ts"],"sourcesContent":["import { Effect, Schema } from 'effect';\n\nexport interface ConfigIssue {\n\treadonly field: string;\n\treadonly message: string;\n\treadonly hint?: string;\n\treadonly cause?: unknown;\n}\n\nexport type ConfigErrorFactory<E> = (issue: ConfigIssue) => E;\n\nexport const defineConfigError =\n\t<const Tag extends string>(tag: Tag) =>\n\t(issue: ConfigIssue): ConfigIssue & { readonly _tag: Tag } => ({\n\t\t_tag: tag,\n\t\t...issue,\n\t});\n\ninterface ValidatorOptions<E> {\n\treadonly field: string;\n\treadonly mkError: ConfigErrorFactory<E>;\n\treadonly message?: string;\n\treadonly hint?: string;\n}\n\nconst fail = <E>(mkError: ConfigErrorFactory<E>, issue: ConfigIssue): never => {\n\tthrow mkError(issue);\n};\n\nexport const expectNonEmptyString = <E>(value: unknown, options: ValidatorOptions<E>): string => {\n\tif (typeof value === 'string' && value.length > 0) return value;\n\treturn fail(options.mkError, {\n\t\tfield: options.field,\n\t\tmessage: options.message ?? 'must be a non-empty string',\n\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t});\n};\n\nexport const expectOptionalNonEmptyString = <E>(\n\tvalue: unknown,\n\toptions: ValidatorOptions<E>,\n): string | undefined => {\n\tif (value === undefined) return undefined;\n\treturn expectNonEmptyString(value, options);\n};\n\nexport const expectPositiveInteger = <E>(value: unknown, options: ValidatorOptions<E>): number => {\n\tif (typeof value === 'number' && Number.isInteger(value) && value > 0) return value;\n\treturn fail(options.mkError, {\n\t\tfield: options.field,\n\t\tmessage: options.message ?? 'must be a positive integer',\n\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t});\n};\n\nexport const expectOptionalPositiveInteger = <E>(\n\tvalue: unknown,\n\toptions: ValidatorOptions<E>,\n): number | undefined => {\n\tif (value === undefined) return undefined;\n\treturn expectPositiveInteger(value, options);\n};\n\nexport const expectPositiveFiniteNumber = <E>(\n\tvalue: unknown,\n\toptions: ValidatorOptions<E>,\n): number => {\n\tif (typeof value === 'number' && Number.isFinite(value) && value > 0) return value;\n\treturn fail(options.mkError, {\n\t\tfield: options.field,\n\t\tmessage: options.message ?? 'must be a positive finite number',\n\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t});\n};\n\nexport const expectPort = <E>(value: unknown, options: ValidatorOptions<E>): number => {\n\tif (typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 65_535) {\n\t\treturn value;\n\t}\n\treturn fail(options.mkError, {\n\t\tfield: options.field,\n\t\tmessage: options.message ?? 'must be an integer between 1 and 65535',\n\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t});\n};\n\nexport const expectOptionalPort = <E>(\n\tvalue: unknown,\n\toptions: ValidatorOptions<E>,\n): number | undefined => {\n\tif (value === undefined) return undefined;\n\treturn expectPort(value, options);\n};\n\nexport const expectStringRecord = <E>(\n\tvalue: unknown,\n\toptions: ValidatorOptions<E>,\n): Readonly<Record<string, string>> => {\n\tif (value === undefined) return {};\n\tif (typeof value !== 'object' || value === null || Array.isArray(value)) {\n\t\treturn fail(options.mkError, {\n\t\t\tfield: options.field,\n\t\t\tmessage: options.message ?? 'must be an object of string values',\n\t\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t\t});\n\t}\n\tfor (const [key, entry] of Object.entries(value)) {\n\t\tif (key.length === 0) {\n\t\t\treturn fail(options.mkError, {\n\t\t\t\tfield: options.field,\n\t\t\t\tmessage: 'environment variable names must be non-empty',\n\t\t\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t\t\t});\n\t\t}\n\t\tif (typeof entry !== 'string') {\n\t\t\treturn fail(options.mkError, {\n\t\t\t\tfield: `${options.field}.${key}`,\n\t\t\t\tmessage: 'must be a string',\n\t\t\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t\t\t});\n\t\t}\n\t}\n\treturn value as Readonly<Record<string, string>>;\n};\n\nexport const expectOneOf = <const Values extends ReadonlyArray<string>, E>(\n\tvalue: unknown,\n\tvalues: Values,\n\toptions: ValidatorOptions<E>,\n): Values[number] => {\n\tif (typeof value === 'string' && (values as ReadonlyArray<string>).includes(value)) {\n\t\treturn value as Values[number];\n\t}\n\treturn fail(options.mkError, {\n\t\tfield: options.field,\n\t\tmessage: options.message ?? `must be one of ${values.map((v) => `'${v}'`).join(', ')}`,\n\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t});\n};\n\nexport const expectNonEmptyArray = <T, E>(\n\tvalue: ReadonlyArray<T> | undefined,\n\toptions: ValidatorOptions<E>,\n): ReadonlyArray<T> => {\n\tif (Array.isArray(value) && value.length > 0) return value;\n\treturn fail(options.mkError, {\n\t\tfield: options.field,\n\t\tmessage: options.message ?? 'must be a non-empty array',\n\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t});\n};\n\nexport const expectPattern = <E>(\n\tvalue: string,\n\tpattern: RegExp,\n\toptions: ValidatorOptions<E>,\n): string => {\n\tif (pattern.test(value)) return value;\n\treturn fail(options.mkError, {\n\t\tfield: options.field,\n\t\tmessage: options.message ?? `must match ${pattern.source}`,\n\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t});\n};\n\nexport const decodeConfig = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\tvalue: unknown,\n\toptions: ValidatorOptions<E>,\n): Effect.Effect<S['Type'], E> =>\n\tSchema.decodeUnknownEffect(schema)(value).pipe(\n\t\tEffect.mapError((cause) =>\n\t\t\toptions.mkError({\n\t\t\t\tfield: options.field,\n\t\t\t\tmessage: options.message ?? 'failed to decode config value',\n\t\t\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t\t\t\tcause,\n\t\t\t}),\n\t\t),\n\t);\n\nexport const decodeConfigSync = <S extends Schema.Decoder<unknown>, E>(\n\tschema: S,\n\tvalue: unknown,\n\toptions: ValidatorOptions<E>,\n): S['Type'] => {\n\ttry {\n\t\treturn Schema.decodeUnknownSync(schema)(value);\n\t} catch (cause) {\n\t\treturn fail(options.mkError, {\n\t\t\tfield: options.field,\n\t\t\tmessage: options.message ?? 'failed to decode config value',\n\t\t\t...(options.hint === undefined ? {} : { hint: options.hint }),\n\t\t\tcause,\n\t\t});\n\t}\n};\n"],"mappings":"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"}

package/dist/substrate/runtime/context-helpers.mjs

@@ -0,0 +1,32 @@
+import { Context, Effect, Option } from "effect";
+//#region src/substrate/runtime/context-helpers.ts
+/**
+* Read an optional service from a `Context`, or fall back.
+*
+* The `pluginContext` at the supervisor boundary is typed
+* `Context.Context<never>` — the substrate is service-name-blind, so
+* the lookup widens internally to read the optional service.
+*
+* Used at sites where the fallback is a plain value.
+*/
+const getOrDefault = (ctx, tag, fallback) => {
+	const opt = Context.getOption(ctx, tag);
+	return Option.isSome(opt) ? opt.value : fallback;
+};
+/**
+* Effectful variant of `getOrDefault`. Same lookup; the fallback is
+* an `Effect` so it can build a Layer / acquire a scoped resource
+* only when the optional service isn't present.
+*
+* Used at the CapabilitySinks site — the fallback builds the default
+* sinks Layer; we only want to pay that cost when the caller didn't
+* pre-build one.
+*/
+const getOrDefaultEffect = (ctx, tag, fallback) => {
+	const opt = Context.getOption(ctx, tag);
+	return Option.isSome(opt) ? Effect.succeed(opt.value) : fallback;
+};
+//#endregion
+export { getOrDefault, getOrDefaultEffect };
+
+//# sourceMappingURL=context-helpers.mjs.map

package/dist/substrate/runtime/context-helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-helpers.mjs","names":[],"sources":["../../../src/substrate/runtime/context-helpers.ts"],"sourcesContent":["// Substrate context helpers — tiny utilities over `Context`.\n//\n// Closes one duplication: three sites in `supervisor.ts` open-coded the\n// `Context.getOption(ctx, tag)` + `Option.isSome ? value : fallback`\n// shape (Logger, RuntimeRoot, CapabilitySinks). The shape was always\n// the same — widen the supervisor's name-blind `pluginContext`, look\n// up an optional service, fall back when the caller didn't layer it\n// in. One helper, no drift.\n\nimport { Context, Effect, Option } from 'effect';\n\n/**\n * Read an optional service from a `Context`, or fall back.\n *\n * The `pluginContext` at the supervisor boundary is typed\n * `Context.Context<never>` — the substrate is service-name-blind, so\n * the lookup widens internally to read the optional service.\n *\n * Used at sites where the fallback is a plain value.\n */\nexport const getOrDefault = <S, I>(\n\tctx: Context.Context<never>,\n\ttag: Context.Key<I, S>,\n\tfallback: S,\n): S => {\n\tconst opt = Context.getOption(ctx as Context.Context<I>, tag);\n\treturn Option.isSome(opt) ? opt.value : fallback;\n};\n\n/**\n * Effectful variant of `getOrDefault`. Same lookup; the fallback is\n * an `Effect` so it can build a Layer / acquire a scoped resource\n * only when the optional service isn't present.\n *\n * Used at the CapabilitySinks site — the fallback builds the default\n * sinks Layer; we only want to pay that cost when the caller didn't\n * pre-build one.\n */\nexport const getOrDefaultEffect = <S, I, E, R>(\n\tctx: Context.Context<never>,\n\ttag: Context.Key<I, S>,\n\tfallback: Effect.Effect<S, E, R>,\n): Effect.Effect<S, E, R> => {\n\tconst opt = Context.getOption(ctx as Context.Context<I>, tag);\n\treturn Option.isSome(opt) ? Effect.succeed(opt.value) : fallback;\n};\n"],"mappings":";;;;;;;;;;;AAoBA,MAAa,gBACZ,KACA,KACA,aACO;CACP,MAAM,MAAM,QAAQ,UAAU,KAA2B,IAAI;AAC7D,QAAO,OAAO,OAAO,IAAI,GAAG,IAAI,QAAQ;;;;;;;;;;;AAYzC,MAAa,sBACZ,KACA,KACA,aAC4B;CAC5B,MAAM,MAAM,QAAQ,UAAU,KAA2B,IAAI;AAC7D,QAAO,OAAO,OAAO,IAAI,GAAG,OAAO,QAAQ,IAAI,MAAM,GAAG"}

package/dist/substrate/runtime/cross-process/command-channel/channel.mjs

@@ -0,0 +1,128 @@
+import { decodeUnknownSync } from "../../runtime-decode.mjs";
+import { CommandRecordSchema, EventRecordSchema } from "./protocol.mjs";
+import { appendRecord, ensureFile, tailRecords } from "./file-channel.mjs";
+import { Effect, Option, Ref, Stream } from "effect";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+//#region src/substrate/runtime/cross-process/command-channel/channel.ts
+const COMMAND_CHANNEL_COMMANDS_FILE_NAME = "commands.ndjson";
+const COMMAND_CHANNEL_EVENTS_FILE_NAME = "events.ndjson";
+/** Build a `command-channel` paths bundle from a stackRoot dir. The
+*  files live next to the existing cross-process artifacts. */
+const commandChannelPaths = (stackRoot) => ({
+	commandsFile: `${stackRoot}/${COMMAND_CHANNEL_COMMANDS_FILE_NAME}`,
+	eventsFile: `${stackRoot}/${COMMAND_CHANNEL_EVENTS_FILE_NAME}`
+});
+const nextSeq = (state) => Ref.modify(state.seq, (n) => [n + 1, n + 1]);
+/**
+* Build the publisher half. The events Stream is scope-bound:
+* pass it through `Stream.runDrain` inside a `Scope.use` or fork it
+* with `Effect.forkScoped` so the tail polling cleans up.
+*/
+const makeCommandChannelPublisher = (paths) => Effect.gen(function* () {
+	yield* ensureFile(paths.commandsFile);
+	yield* ensureFile(paths.eventsFile);
+	const state = { seq: yield* Ref.make(0) };
+	const pid = process.pid;
+	const host = hostname();
+	const publish = (command) => Effect.gen(function* () {
+		const seq = yield* nextSeq(state);
+		const id = `${pid}-${seq}-${randomUUID().slice(0, 8)}`;
+		const record = {
+			protocol: 1,
+			seq,
+			id,
+			at: Date.now(),
+			publisherPid: pid,
+			publisherHostname: host,
+			command
+		};
+		yield* appendRecord(paths.commandsFile, record);
+		return { id };
+	});
+	const decodeEvent = (raw) => decodeUnknownSync(EventRecordSchema, raw, {
+		source: "command-channel event",
+		mkError: (issue) => issue
+	});
+	const events = tailRecords(paths.eventsFile, (raw) => decodeEvent(raw), { fromOffset: "current" });
+	const findReply = (id) => Stream.runHead(tailRecords(paths.eventsFile, (raw) => decodeEvent(raw), { fromOffset: "start" }).pipe(Stream.filter((rec) => (rec.kind === "ack" || rec.kind === "error") && rec.correlatesTo === id), Stream.take(1)));
+	const awaitCompletion = (id, options = {}) => {
+		const withScope = Effect.scoped(findReply(id));
+		return (options.timeoutMillis !== void 0 ? withScope.pipe(Effect.timeoutOption(`${options.timeoutMillis} millis`), Effect.map((outer) => Option.flatten(outer))) : withScope).pipe(Effect.map((reply) => {
+			const inner = Option.getOrNull(reply);
+			if (inner === null) return options.timeoutMillis !== void 0 ? {
+				ok: false,
+				message: "timed out waiting for ack"
+			} : {
+				ok: false,
+				message: "no reply"
+			};
+			if (inner.kind === "ack") return { ok: true };
+			return {
+				ok: false,
+				message: inner.detail ? `${inner.message}: ${inner.detail}` : inner.message
+			};
+		}));
+	};
+	return {
+		publish,
+		awaitCompletion,
+		events
+	};
+});
+const nextSubSeq = (state) => Ref.modify(state.seq, (n) => [n + 1, n + 1]);
+/** Build the supervisor half. The commands Stream is scope-bound. */
+const makeCommandChannelSubscriber = (paths, options = {}) => Effect.gen(function* () {
+	yield* ensureFile(paths.commandsFile);
+	yield* ensureFile(paths.eventsFile);
+	const state = { seq: yield* Ref.make(0) };
+	const decodeCommand = (raw) => decodeUnknownSync(CommandRecordSchema, raw, {
+		source: "command-channel command",
+		mkError: (issue) => issue
+	});
+	const commands = tailRecords(paths.commandsFile, (raw) => decodeCommand(raw), {
+		fromOffset: options.fromOffset ?? "current",
+		pollMillis: options.pollMillis
+	});
+	const writeEvent = (record) => appendRecord(paths.eventsFile, record);
+	const publishEvent = (event) => Effect.gen(function* () {
+		yield* writeEvent({
+			protocol: 1,
+			seq: yield* nextSubSeq(state),
+			at: Date.now(),
+			kind: "engine",
+			event
+		});
+	});
+	const ack = (correlatesTo, detail) => Effect.gen(function* () {
+		yield* writeEvent({
+			protocol: 1,
+			seq: yield* nextSubSeq(state),
+			at: Date.now(),
+			kind: "ack",
+			correlatesTo,
+			...detail !== void 0 ? { detail } : {}
+		});
+	});
+	const fail = (correlatesTo, message, detail) => Effect.gen(function* () {
+		yield* writeEvent({
+			protocol: 1,
+			seq: yield* nextSubSeq(state),
+			at: Date.now(),
+			kind: "error",
+			correlatesTo,
+			message,
+			...detail !== void 0 ? { detail } : {}
+		});
+	});
+	return {
+		commands,
+		publishEvent,
+		ack,
+		fail
+	};
+});
+//#endregion
+export { COMMAND_CHANNEL_COMMANDS_FILE_NAME, COMMAND_CHANNEL_EVENTS_FILE_NAME, commandChannelPaths, makeCommandChannelPublisher, makeCommandChannelSubscriber };
+
+//# sourceMappingURL=channel.mjs.map

package/dist/substrate/runtime/cross-process/command-channel/channel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.mjs","names":["nodeHostname"],"sources":["../../../../../src/substrate/runtime/cross-process/command-channel/channel.ts"],"sourcesContent":["// High-level cross-process command channel.\n//\n// Two halves built on the same `commands.ndjson` + `events.ndjson` pair:\n//\n//   - Publisher side (CLI / TUI / programmable API caller): appends to\n//     `commands.ndjson`; tails `events.ndjson` so it can correlate\n//     ack/error replies AND surface incoming engine events (for `logs`\n//     and `status --watch`-style verbs).\n//\n//   - Supervisor side: tails `commands.ndjson` to receive incoming\n//     intents; appends to `events.ndjson` to broadcast engine events\n//     and ack/error replies.\n//\n// Both halves are scope-bound — the underlying poll fiber is forked\n// into the surrounding Scope and stops when the Scope closes.\n\nimport { hostname as nodeHostname } from 'node:os';\nimport { randomUUID } from 'node:crypto';\n\nimport { Effect, Option, Ref, Stream, Scope } from 'effect';\n\nimport type { EngineCommand } from '../../../events.ts';\nimport { decodeUnknownSync } from '../../runtime-decode.ts';\nimport { type CommandChannelError, appendRecord, ensureFile, tailRecords } from './file-channel.ts';\nimport {\n\tCOMMAND_CHANNEL_PROTOCOL_VERSION,\n\tCommandRecordSchema,\n\tEventRecordSchema,\n\ttype CommandRecord,\n\ttype EventRecord,\n} from './protocol.ts';\n\nexport interface CommandChannelPaths {\n\treadonly commandsFile: string;\n\treadonly eventsFile: string;\n}\n\nexport const COMMAND_CHANNEL_COMMANDS_FILE_NAME = 'commands.ndjson';\nexport const COMMAND_CHANNEL_EVENTS_FILE_NAME = 'events.ndjson';\n\n/** Build a `command-channel` paths bundle from a stackRoot dir. The\n *  files live next to the existing cross-process artifacts. */\nexport const commandChannelPaths = (stackRoot: string): CommandChannelPaths => ({\n\tcommandsFile: `${stackRoot}/${COMMAND_CHANNEL_COMMANDS_FILE_NAME}`,\n\teventsFile: `${stackRoot}/${COMMAND_CHANNEL_EVENTS_FILE_NAME}`,\n});\n\n// -----------------------------------------------------------------------------\n// Publisher side\n// -----------------------------------------------------------------------------\n\nexport interface PublishedCommand {\n\t/** Per-record id used to correlate `ack` / `error` replies. */\n\treadonly id: string;\n}\n\n/**\n * Publisher half: append a typed command, optionally await its\n * corresponding ack/error reply.\n *\n * `publish(cmd)` writes one record and returns the id; the caller can\n * then `awaitCompletion(id)` to block until the supervisor either acks\n * or errors. `awaitCompletion` is a separate seam so verbs that don't\n * need correlation (TUI-style fire-and-forget) skip the wait.\n */\nexport interface CommandChannelPublisher {\n\treadonly publish: (\n\t\tcommand: EngineCommand,\n\t) => Effect.Effect<PublishedCommand, CommandChannelError>;\n\treadonly awaitCompletion: (\n\t\tid: string,\n\t\toptions?: { readonly timeoutMillis?: number },\n\t) => Effect.Effect<\n\t\t{ readonly ok: true } | { readonly ok: false; readonly message: string },\n\t\tCommandChannelError\n\t>;\n\treadonly events: Stream.Stream<EventRecord, CommandChannelError, Scope.Scope>;\n}\n\ninterface PublisherState {\n\treadonly seq: Ref.Ref<number>;\n}\n\nconst nextSeq = (state: PublisherState): Effect.Effect<number> =>\n\tRef.modify(state.seq, (n) => [n + 1, n + 1]);\n\n/**\n * Build the publisher half. The events Stream is scope-bound:\n * pass it through `Stream.runDrain` inside a `Scope.use` or fork it\n * with `Effect.forkScoped` so the tail polling cleans up.\n */\nexport const makeCommandChannelPublisher = (\n\tpaths: CommandChannelPaths,\n): Effect.Effect<CommandChannelPublisher, CommandChannelError> =>\n\tEffect.gen(function* () {\n\t\tyield* ensureFile(paths.commandsFile);\n\t\tyield* ensureFile(paths.eventsFile);\n\t\tconst state: PublisherState = { seq: yield* Ref.make(0) };\n\t\tconst pid = process.pid;\n\t\tconst host = nodeHostname();\n\n\t\tconst publish = (\n\t\t\tcommand: EngineCommand,\n\t\t): Effect.Effect<PublishedCommand, CommandChannelError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst seq = yield* nextSeq(state);\n\t\t\t\tconst id = `${pid}-${seq}-${randomUUID().slice(0, 8)}`;\n\t\t\t\tconst record: CommandRecord = {\n\t\t\t\t\tprotocol: COMMAND_CHANNEL_PROTOCOL_VERSION,\n\t\t\t\t\tseq,\n\t\t\t\t\tid,\n\t\t\t\t\tat: Date.now(),\n\t\t\t\t\tpublisherPid: pid,\n\t\t\t\t\tpublisherHostname: host,\n\t\t\t\t\tcommand,\n\t\t\t\t};\n\t\t\t\tyield* appendRecord(paths.commandsFile, record);\n\t\t\t\treturn { id };\n\t\t\t});\n\n\t\tconst decodeEvent = (raw: unknown): EventRecord =>\n\t\t\tdecodeUnknownSync(EventRecordSchema, raw, {\n\t\t\t\tsource: 'command-channel event',\n\t\t\t\tmkError: (issue) => issue,\n\t\t\t});\n\n\t\tconst events: Stream.Stream<EventRecord, CommandChannelError, Scope.Scope> = tailRecords(\n\t\t\tpaths.eventsFile,\n\t\t\t(raw) => decodeEvent(raw),\n\t\t\t{ fromOffset: 'current' },\n\t\t);\n\n\t\tconst findReply = (\n\t\t\tid: string,\n\t\t): Effect.Effect<\n\t\t\tOption.Option<Extract<EventRecord, { kind: 'ack' | 'error' }>>,\n\t\t\tCommandChannelError,\n\t\t\tScope.Scope\n\t\t> =>\n\t\t\t// Start at 'start' so awaitCompletion picks up an ack that\n\t\t\t// landed before the await call attached. The filter by id is\n\t\t\t// the actual correlation; replaying old records is cheap.\n\t\t\tStream.runHead(\n\t\t\t\ttailRecords(paths.eventsFile, (raw) => decodeEvent(raw), {\n\t\t\t\t\tfromOffset: 'start',\n\t\t\t\t}).pipe(\n\t\t\t\t\tStream.filter(\n\t\t\t\t\t\t(rec): rec is Extract<EventRecord, { kind: 'ack' | 'error' }> =>\n\t\t\t\t\t\t\t(rec.kind === 'ack' || rec.kind === 'error') && rec.correlatesTo === id,\n\t\t\t\t\t),\n\t\t\t\t\tStream.take(1),\n\t\t\t\t),\n\t\t\t);\n\n\t\tconst awaitCompletion = (\n\t\t\tid: string,\n\t\t\toptions: { readonly timeoutMillis?: number } = {},\n\t\t): Effect.Effect<\n\t\t\t{ readonly ok: true } | { readonly ok: false; readonly message: string },\n\t\t\tCommandChannelError\n\t\t> => {\n\t\t\tconst withScope = Effect.scoped(findReply(id));\n\t\t\tconst final =\n\t\t\t\toptions.timeoutMillis !== undefined\n\t\t\t\t\t? withScope.pipe(\n\t\t\t\t\t\t\tEffect.timeoutOption(`${options.timeoutMillis} millis`),\n\t\t\t\t\t\t\tEffect.map((outer) => Option.flatten(outer)),\n\t\t\t\t\t\t)\n\t\t\t\t\t: withScope;\n\t\t\treturn final.pipe(\n\t\t\t\tEffect.map((reply) => {\n\t\t\t\t\tconst inner = Option.getOrNull(reply);\n\t\t\t\t\tif (inner === null) {\n\t\t\t\t\t\treturn options.timeoutMillis !== undefined\n\t\t\t\t\t\t\t? { ok: false as const, message: 'timed out waiting for ack' }\n\t\t\t\t\t\t\t: { ok: false as const, message: 'no reply' };\n\t\t\t\t\t}\n\t\t\t\t\tif (inner.kind === 'ack') return { ok: true as const };\n\t\t\t\t\treturn {\n\t\t\t\t\t\tok: false as const,\n\t\t\t\t\t\tmessage: inner.detail ? `${inner.message}: ${inner.detail}` : inner.message,\n\t\t\t\t\t};\n\t\t\t\t}),\n\t\t\t);\n\t\t};\n\n\t\treturn { publish, awaitCompletion, events };\n\t});\n\n// -----------------------------------------------------------------------------\n// Supervisor side\n// -----------------------------------------------------------------------------\n\nexport interface CommandChannelSubscriberOptions {\n\t/** From which offset to start reading commands. Defaults to `current`\n\t *  so a freshly-booted supervisor doesn't replay queued intents from\n\t *  before it was alive. */\n\treadonly fromOffset?: 'start' | 'current';\n\treadonly pollMillis?: number;\n}\n\n/** Tail incoming commands. The supervisor wires its event hub through\n *  `publishEvent` so engine events appear on the events file. */\nexport interface CommandChannelSubscriber {\n\treadonly commands: Stream.Stream<CommandRecord, CommandChannelError, Scope.Scope>;\n\treadonly publishEvent: (event: unknown) => Effect.Effect<void, CommandChannelError>;\n\treadonly ack: (correlatesTo: string, detail?: string) => Effect.Effect<void, CommandChannelError>;\n\treadonly fail: (\n\t\tcorrelatesTo: string,\n\t\tmessage: string,\n\t\tdetail?: string,\n\t) => Effect.Effect<void, CommandChannelError>;\n}\n\ninterface SubscriberState {\n\treadonly seq: Ref.Ref<number>;\n}\n\nconst nextSubSeq = (state: SubscriberState): Effect.Effect<number> =>\n\tRef.modify(state.seq, (n) => [n + 1, n + 1]);\n\n/** Build the supervisor half. The commands Stream is scope-bound. */\nexport const makeCommandChannelSubscriber = (\n\tpaths: CommandChannelPaths,\n\toptions: CommandChannelSubscriberOptions = {},\n): Effect.Effect<CommandChannelSubscriber, CommandChannelError> =>\n\tEffect.gen(function* () {\n\t\tyield* ensureFile(paths.commandsFile);\n\t\tyield* ensureFile(paths.eventsFile);\n\t\tconst state: SubscriberState = { seq: yield* Ref.make(0) };\n\n\t\tconst decodeCommand = (raw: unknown): CommandRecord =>\n\t\t\tdecodeUnknownSync(CommandRecordSchema, raw, {\n\t\t\t\tsource: 'command-channel command',\n\t\t\t\tmkError: (issue) => issue,\n\t\t\t});\n\n\t\tconst commands: Stream.Stream<CommandRecord, CommandChannelError, Scope.Scope> = tailRecords(\n\t\t\tpaths.commandsFile,\n\t\t\t(raw) => decodeCommand(raw),\n\t\t\t{\n\t\t\t\tfromOffset: options.fromOffset ?? 'current',\n\t\t\t\tpollMillis: options.pollMillis,\n\t\t\t},\n\t\t);\n\n\t\tconst writeEvent = (record: EventRecord): Effect.Effect<void, CommandChannelError> =>\n\t\t\tappendRecord(paths.eventsFile, record);\n\n\t\tconst publishEvent = (event: unknown): Effect.Effect<void, CommandChannelError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst seq = yield* nextSubSeq(state);\n\t\t\t\tyield* writeEvent({\n\t\t\t\t\tprotocol: COMMAND_CHANNEL_PROTOCOL_VERSION,\n\t\t\t\t\tseq,\n\t\t\t\t\tat: Date.now(),\n\t\t\t\t\tkind: 'engine',\n\t\t\t\t\tevent,\n\t\t\t\t});\n\t\t\t});\n\n\t\tconst ack = (correlatesTo: string, detail?: string): Effect.Effect<void, CommandChannelError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst seq = yield* nextSubSeq(state);\n\t\t\t\tyield* writeEvent({\n\t\t\t\t\tprotocol: COMMAND_CHANNEL_PROTOCOL_VERSION,\n\t\t\t\t\tseq,\n\t\t\t\t\tat: Date.now(),\n\t\t\t\t\tkind: 'ack',\n\t\t\t\t\tcorrelatesTo,\n\t\t\t\t\t...(detail !== undefined ? { detail } : {}),\n\t\t\t\t});\n\t\t\t});\n\n\t\tconst fail = (\n\t\t\tcorrelatesTo: string,\n\t\t\tmessage: string,\n\t\t\tdetail?: string,\n\t\t): Effect.Effect<void, CommandChannelError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst seq = yield* nextSubSeq(state);\n\t\t\t\tyield* writeEvent({\n\t\t\t\t\tprotocol: COMMAND_CHANNEL_PROTOCOL_VERSION,\n\t\t\t\t\tseq,\n\t\t\t\t\tat: Date.now(),\n\t\t\t\t\tkind: 'error',\n\t\t\t\t\tcorrelatesTo,\n\t\t\t\t\tmessage,\n\t\t\t\t\t...(detail !== undefined ? { detail } : {}),\n\t\t\t\t});\n\t\t\t});\n\n\t\treturn { commands, publishEvent, ack, fail };\n\t});\n"],"mappings":"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"}

package/dist/substrate/runtime/cross-process/command-channel/file-channel.mjs

@@ -0,0 +1,136 @@
+import { parseJsonText } from "../../runtime-decode.mjs";
+import { acquireStackLock } from "../stack-lock.mjs";
+import { runtimeControlLockPathForChannelFile } from "./runtime-control-lock.mjs";
+import { Data, Effect, Stream } from "effect";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+//#region src/substrate/runtime/cross-process/command-channel/file-channel.ts
+/** Tagged failure for any I/O error during append. */
+var CommandChannelIoError = class extends Data.TaggedError("CommandChannelIoError") {};
+/** Tagged failure when a tailed line cannot be decoded against the
+*  record schema. The malformed line is preserved so consumers can
+*  surface it for debugging without spamming retries. */
+var CommandChannelDecodeError = class extends Data.TaggedError("CommandChannelDecodeError") {};
+const withRuntimeControlLock = (path, stage, effect) => Effect.scoped(Effect.gen(function* () {
+	yield* acquireStackLock(runtimeControlLockPathForChannelFile(path)).pipe(Effect.mapError((cause) => new CommandChannelIoError({
+		path,
+		stage,
+		cause
+	})));
+	return yield* effect;
+}));
+/** Ensure the file exists. Idempotent. Creates parent dir if needed. */
+const ensureFile = (path) => withRuntimeControlLock(path, "init", Effect.try({
+	try: () => {
+		mkdirSync(dirname(path), { recursive: true });
+		if (!existsSync(path)) writeFileSync(path, "", { flag: "a" });
+	},
+	catch: (cause) => new CommandChannelIoError({
+		path,
+		stage: "init",
+		cause
+	})
+}));
+/** Append one record as a single NDJSON line. The trailing newline
+*  ensures the next writer's append starts a fresh record. */
+const appendRecord = (path, record) => withRuntimeControlLock(path, "append", Effect.try({
+	try: () => {
+		mkdirSync(dirname(path), { recursive: true });
+		appendFileSync(path, `${JSON.stringify(record)}\n`, { flag: "a" });
+	},
+	catch: (cause) => new CommandChannelIoError({
+		path,
+		stage: "append",
+		cause
+	})
+}));
+const decodeLine = (path, line, decode) => parseJsonText(line, {
+	source: path,
+	mkError: (issue) => new CommandChannelDecodeError({
+		path,
+		line,
+		cause: issue.cause ?? issue
+	})
+}).pipe(Effect.flatMap((parsed) => Effect.try({
+	try: () => decode(parsed),
+	catch: (cause) => new CommandChannelDecodeError({
+		path,
+		line,
+		cause
+	})
+})));
+/** Read newly-appended bytes from `state.offset` to current EOF. Updates
+*  `state` in place. Returns the freshly-completed lines. A trailing
+*  partial line (no newline yet) is preserved in `state.partial` and
+*  prepended on the next poll. */
+const drainNewLines = (path, state) => Effect.try({
+	try: () => {
+		if (!existsSync(path)) return [];
+		const stat = statSync(path);
+		if (stat.size <= state.offset) return [];
+		const grow = stat.size - state.offset;
+		const fd = openSync(path, "r");
+		try {
+			const buf = Buffer.alloc(grow);
+			readSync(fd, buf, 0, grow, state.offset);
+			state.offset = stat.size;
+			const parts = (state.partial + buf.toString("utf8")).split("\n");
+			state.partial = parts.pop() ?? "";
+			return parts.filter((l) => l.length > 0);
+		} finally {
+			closeSync(fd);
+		}
+	},
+	catch: (cause) => new CommandChannelIoError({
+		path,
+		stage: "read",
+		cause
+	})
+});
+/** Tail a file as a Stream of decoded records. The Stream is bound to
+*  the surrounding Scope: when the Scope closes, polling stops.
+*
+*  - `fromOffset === 'current'` skips existing content; starts at EOF.
+*  - `fromOffset === 'start'` replays every existing record then tails.
+*  - `fromOffset === number` resumes from a known byte offset.
+*
+*  Decode errors are surfaced as Stream failures with the offending
+*  line attached so the consumer can pick a retry / skip policy.
+*
+*  The poll loop uses `Effect.sleep` between iterations, so cooperative
+*  scheduling is preserved (no busy loop).
+*/
+const tailRecords = (path, decode, options = {}) => Stream.unwrap(Effect.gen(function* () {
+	const pollMillis = options.pollMillis ?? 50;
+	yield* ensureFile(path);
+	const state = {
+		offset: yield* Effect.try({
+			try: () => {
+				if (options.fromOffset === "start" || options.fromOffset === void 0) return 0;
+				if (options.fromOffset === "current") return existsSync(path) ? statSync(path).size : 0;
+				return options.fromOffset;
+			},
+			catch: (cause) => new CommandChannelIoError({
+				path,
+				stage: "stat",
+				cause
+			})
+		}),
+		partial: ""
+	};
+	const pollOne = Effect.gen(function* () {
+		const lines = yield* drainNewLines(path, state);
+		if (lines.length === 0) {
+			yield* Effect.sleep(`${pollMillis} millis`);
+			return [];
+		}
+		const decoded = [];
+		for (const line of lines) decoded.push(yield* decodeLine(path, line, decode));
+		return decoded;
+	});
+	return Stream.fromEffectRepeat(pollOne).pipe(Stream.flatMap((records) => Stream.fromIterable(records)));
+}));
+//#endregion
+export { appendRecord, ensureFile, tailRecords };
+
+//# sourceMappingURL=file-channel.mjs.map

package/dist/substrate/runtime/cross-process/command-channel/file-channel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-channel.mjs","names":[],"sources":["../../../../../src/substrate/runtime/cross-process/command-channel/file-channel.ts"],"sourcesContent":["// Append-only NDJSON channel.\n//\n// One-record-per-line, atomic append via `fs.appendFileSync` with\n// `flag: 'a'` (POSIX guarantees the write is atomic for buffers under\n// PIPE_BUF; one JSON line is comfortably under that on every platform\n// we run). The tail-reader polls via offset bookkeeping — `fs.watch`\n// is unreliable across platforms for \"file grew\" notifications\n// (especially over NFS, which the cross-process protocol must remain\n// safe on per architecture § Cross-process safety protocol).\n//\n// Records are framed by a literal newline. A partial trailing line\n// (writer mid-flight when reader observed) is buffered until the next\n// poll iteration completes the line.\n\nimport {\n\tappendFileSync,\n\tcloseSync,\n\texistsSync,\n\tmkdirSync,\n\topenSync,\n\treadSync,\n\tstatSync,\n\twriteFileSync,\n} from 'node:fs';\nimport { dirname } from 'node:path';\n\nimport { Data, Effect, Scope, Stream } from 'effect';\n\nimport { parseJsonText } from '../../runtime-decode.ts';\nimport { acquireStackLock } from '../stack-lock.ts';\nimport { runtimeControlLockPathForChannelFile } from './runtime-control-lock.ts';\n\n/** Tagged failure for any I/O error during append. */\nexport class CommandChannelIoError extends Data.TaggedError('CommandChannelIoError')<{\n\treadonly path: string;\n\treadonly stage: 'append' | 'open' | 'read' | 'stat' | 'init';\n\treadonly cause: unknown;\n}> {}\n\n/** Tagged failure when a tailed line cannot be decoded against the\n *  record schema. The malformed line is preserved so consumers can\n *  surface it for debugging without spamming retries. */\nexport class CommandChannelDecodeError extends Data.TaggedError('CommandChannelDecodeError')<{\n\treadonly path: string;\n\treadonly line: string;\n\treadonly cause: unknown;\n}> {}\n\nexport type CommandChannelError = CommandChannelIoError | CommandChannelDecodeError;\n\n/** Default tail poll interval. Chosen to be small enough for\n *  interactive CLI responsiveness (a `down` ack returns within ~50ms)\n *  while staying out of the way of process schedulers. */\nexport const DEFAULT_TAIL_POLL_MILLIS = 50;\n\nconst withRuntimeControlLock = <A>(\n\tpath: string,\n\tstage: CommandChannelIoError['stage'],\n\teffect: Effect.Effect<A, CommandChannelIoError>,\n): Effect.Effect<A, CommandChannelIoError> =>\n\tEffect.scoped(\n\t\tEffect.gen(function* () {\n\t\t\tyield* acquireStackLock(runtimeControlLockPathForChannelFile(path)).pipe(\n\t\t\t\tEffect.mapError((cause) => new CommandChannelIoError({ path, stage, cause })),\n\t\t\t);\n\t\t\treturn yield* effect;\n\t\t}),\n\t);\n\n/** Ensure the file exists. Idempotent. Creates parent dir if needed. */\nexport const ensureFile = (path: string): Effect.Effect<void, CommandChannelIoError> =>\n\twithRuntimeControlLock(\n\t\tpath,\n\t\t'init',\n\t\tEffect.try({\n\t\t\ttry: () => {\n\t\t\t\tmkdirSync(dirname(path), { recursive: true });\n\t\t\t\tif (!existsSync(path)) {\n\t\t\t\t\twriteFileSync(path, '', { flag: 'a' });\n\t\t\t\t}\n\t\t\t},\n\t\t\tcatch: (cause) => new CommandChannelIoError({ path, stage: 'init', cause }),\n\t\t}),\n\t);\n\n/** Append one record as a single NDJSON line. The trailing newline\n *  ensures the next writer's append starts a fresh record. */\nexport const appendRecord = (\n\tpath: string,\n\trecord: unknown,\n): Effect.Effect<void, CommandChannelIoError> =>\n\twithRuntimeControlLock(\n\t\tpath,\n\t\t'append',\n\t\tEffect.try({\n\t\t\ttry: () => {\n\t\t\t\tmkdirSync(dirname(path), { recursive: true });\n\t\t\t\tappendFileSync(path, `${JSON.stringify(record)}\\n`, { flag: 'a' });\n\t\t\t},\n\t\t\tcatch: (cause) => new CommandChannelIoError({ path, stage: 'append', cause }),\n\t\t}),\n\t);\n\n/** A line decoder. The channel I/O layer stays schema-agnostic so\n *  callers can pick their own wire schema without this generic\n *  carrying a `Schema.Decoder<unknown>` constraint. */\nexport type LineDecoder<A> = (raw: unknown) => A;\n\nconst decodeLine = <A>(\n\tpath: string,\n\tline: string,\n\tdecode: LineDecoder<A>,\n): Effect.Effect<A, CommandChannelDecodeError> =>\n\tparseJsonText(line, {\n\t\tsource: path,\n\t\tmkError: (issue) => new CommandChannelDecodeError({ path, line, cause: issue.cause ?? issue }),\n\t}).pipe(\n\t\tEffect.flatMap((parsed) =>\n\t\t\tEffect.try({\n\t\t\t\ttry: () => decode(parsed),\n\t\t\t\tcatch: (cause) => new CommandChannelDecodeError({ path, line, cause }),\n\t\t\t}),\n\t\t),\n\t);\n\n/** Read the entire current contents into structured records. Useful at\n *  startup to backfill state, and as a test seam. */\nexport const readAllRecords = <A>(\n\tpath: string,\n\tdecode: LineDecoder<A>,\n): Effect.Effect<ReadonlyArray<A>, CommandChannelError> =>\n\tEffect.gen(function* () {\n\t\tif (!existsSync(path)) return [];\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => {\n\t\t\t\tconst fd = openSync(path, 'r');\n\t\t\t\ttry {\n\t\t\t\t\tconst { size } = statSync(path);\n\t\t\t\t\tconst buf = Buffer.alloc(size);\n\t\t\t\t\treadSync(fd, buf, 0, size, 0);\n\t\t\t\t\treturn buf.toString('utf8');\n\t\t\t\t} finally {\n\t\t\t\t\tcloseSync(fd);\n\t\t\t\t}\n\t\t\t},\n\t\t\tcatch: (cause) => new CommandChannelIoError({ path, stage: 'read', cause }),\n\t\t});\n\t\tconst lines = raw.split('\\n').filter((l) => l.length > 0);\n\t\tconst out: A[] = [];\n\t\tfor (const line of lines) {\n\t\t\tout.push(yield* decodeLine(path, line, decode));\n\t\t}\n\t\treturn out;\n\t});\n\ninterface TailState {\n\toffset: number;\n\tpartial: string;\n}\n\n/** Read newly-appended bytes from `state.offset` to current EOF. Updates\n *  `state` in place. Returns the freshly-completed lines. A trailing\n *  partial line (no newline yet) is preserved in `state.partial` and\n *  prepended on the next poll. */\nconst drainNewLines = (\n\tpath: string,\n\tstate: TailState,\n): Effect.Effect<ReadonlyArray<string>, CommandChannelIoError> =>\n\tEffect.try({\n\t\ttry: () => {\n\t\t\tif (!existsSync(path)) return [];\n\t\t\tconst stat = statSync(path);\n\t\t\tif (stat.size <= state.offset) return [];\n\t\t\tconst grow = stat.size - state.offset;\n\t\t\tconst fd = openSync(path, 'r');\n\t\t\ttry {\n\t\t\t\tconst buf = Buffer.alloc(grow);\n\t\t\t\treadSync(fd, buf, 0, grow, state.offset);\n\t\t\t\tstate.offset = stat.size;\n\t\t\t\tconst chunk = state.partial + buf.toString('utf8');\n\t\t\t\tconst parts = chunk.split('\\n');\n\t\t\t\tstate.partial = parts.pop() ?? '';\n\t\t\t\treturn parts.filter((l) => l.length > 0);\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t},\n\t\tcatch: (cause) => new CommandChannelIoError({ path, stage: 'read', cause }),\n\t});\n\n/** Tail a file as a Stream of decoded records. The Stream is bound to\n *  the surrounding Scope: when the Scope closes, polling stops.\n *\n *  - `fromOffset === 'current'` skips existing content; starts at EOF.\n *  - `fromOffset === 'start'` replays every existing record then tails.\n *  - `fromOffset === number` resumes from a known byte offset.\n *\n *  Decode errors are surfaced as Stream failures with the offending\n *  line attached so the consumer can pick a retry / skip policy.\n *\n *  The poll loop uses `Effect.sleep` between iterations, so cooperative\n *  scheduling is preserved (no busy loop).\n */\nexport const tailRecords = <A>(\n\tpath: string,\n\tdecode: LineDecoder<A>,\n\toptions: {\n\t\treadonly fromOffset?: 'start' | 'current' | number;\n\t\treadonly pollMillis?: number;\n\t} = {},\n): Stream.Stream<A, CommandChannelError, Scope.Scope> =>\n\tStream.unwrap(\n\t\tEffect.gen(function* () {\n\t\t\tconst pollMillis = options.pollMillis ?? DEFAULT_TAIL_POLL_MILLIS;\n\t\t\tyield* ensureFile(path);\n\t\t\tconst initialOffset = yield* Effect.try({\n\t\t\t\ttry: () => {\n\t\t\t\t\tif (options.fromOffset === 'start' || options.fromOffset === undefined) {\n\t\t\t\t\t\treturn 0;\n\t\t\t\t\t}\n\t\t\t\t\tif (options.fromOffset === 'current') {\n\t\t\t\t\t\treturn existsSync(path) ? statSync(path).size : 0;\n\t\t\t\t\t}\n\t\t\t\t\treturn options.fromOffset;\n\t\t\t\t},\n\t\t\t\tcatch: (cause) => new CommandChannelIoError({ path, stage: 'stat', cause }),\n\t\t\t});\n\t\t\tconst state: TailState = { offset: initialOffset, partial: '' };\n\t\t\tconst pollOne: Effect.Effect<ReadonlyArray<A>, CommandChannelError> = Effect.gen(\n\t\t\t\tfunction* () {\n\t\t\t\t\tconst lines = yield* drainNewLines(path, state);\n\t\t\t\t\tif (lines.length === 0) {\n\t\t\t\t\t\tyield* Effect.sleep(`${pollMillis} millis`);\n\t\t\t\t\t\treturn [] as ReadonlyArray<A>;\n\t\t\t\t\t}\n\t\t\t\t\tconst decoded: A[] = [];\n\t\t\t\t\tfor (const line of lines) {\n\t\t\t\t\t\tdecoded.push(yield* decodeLine(path, line, decode));\n\t\t\t\t\t}\n\t\t\t\t\treturn decoded as ReadonlyArray<A>;\n\t\t\t\t},\n\t\t\t);\n\t\t\treturn Stream.fromEffectRepeat(pollOne).pipe(\n\t\t\t\tStream.flatMap((records) => Stream.fromIterable(records)),\n\t\t\t);\n\t\t}),\n\t);\n"],"mappings":"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"}

package/dist/substrate/runtime/cross-process/command-channel/protocol.mjs

@@ -0,0 +1,49 @@
+import { Schema } from "effect";
+/** Per-record envelope written to `commands.ndjson`. */
+const CommandRecordSchema = Schema.Struct({
+	protocol: Schema.Literal(1),
+	seq: Schema.Number,
+	id: Schema.String,
+	at: Schema.Number,
+	publisherPid: Schema.Number,
+	publisherHostname: Schema.String,
+	command: Schema.Unknown
+});
+/** Per-record envelope written to `events.ndjson`. The supervisor emits
+*  one record per `EngineEvent` plus synthetic `ack` / `error`
+*  responses when the inner handler reports completion or failure for a
+*  correlatable command.
+*
+*  `correlatesTo` carries the originating `CommandRecord.id` for `ack`
+*  / `error`. Other event kinds (engine events) carry `null`.
+*/
+const EventRecordSchema = Schema.Union([
+	Schema.Struct({
+		protocol: Schema.Literal(1),
+		seq: Schema.Number,
+		at: Schema.Number,
+		kind: Schema.Literal("engine"),
+		event: Schema.Unknown
+	}),
+	Schema.Struct({
+		protocol: Schema.Literal(1),
+		seq: Schema.Number,
+		at: Schema.Number,
+		kind: Schema.Literal("ack"),
+		correlatesTo: Schema.String,
+		detail: Schema.optional(Schema.String)
+	}),
+	Schema.Struct({
+		protocol: Schema.Literal(1),
+		seq: Schema.Number,
+		at: Schema.Number,
+		kind: Schema.Literal("error"),
+		correlatesTo: Schema.String,
+		message: Schema.String,
+		detail: Schema.optional(Schema.String)
+	})
+]);
+//#endregion
+export { CommandRecordSchema, EventRecordSchema };
+
+//# sourceMappingURL=protocol.mjs.map

package/dist/substrate/runtime/cross-process/command-channel/protocol.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.mjs","names":[],"sources":["../../../../../src/substrate/runtime/cross-process/command-channel/protocol.ts"],"sourcesContent":["// Cross-process command channel — wire protocol.\n//\n// Architecture § Cross-process safety protocol § Command channel:\n//   The CLI / TUI / programmable API publish typed commands to a\n//   running supervisor; the supervisor publishes typed events back. The\n//   channel is filesystem-backed (append-only NDJSON) so a peer\n//   process can attach without IPC handshakes.\n//\n// Two files live under `<stackRoot>/`:\n//   - `commands.ndjson`  — caller appends; supervisor tails.\n//   - `events.ndjson`    — supervisor appends; callers tail.\n//\n// Each record is one JSON object per line, schema-versioned for forward\n// compatibility. Records carry a monotonically increasing sequence\n// number (per file) plus a per-record id that the publisher uses to\n// correlate event replies (e.g. `down` publishes a command, then waits\n// for an `event` carrying `correlatesTo: <same id>`).\n//\n// `EngineCommand` / `EngineEvent` payloads are NOT re-decoded on the\n// wire: the publisher API accepts typed commands, and both payload\n// kinds round-trip faithfully through JSON (closed string-tag-\n// discriminated unions with JSON-safe payloads). The channel validates\n// the envelope (`protocol`, `seq`, `id`, `correlatesTo`) and treats\n// the inner payload as `Schema.Unknown`. A future hardening pass can\n// promote the inner payloads to typed schemas without changing this\n// file's contract.\n\nimport { Schema } from 'effect';\n\n/** Protocol version. Bump on incompatible record-shape changes. */\nexport const COMMAND_CHANNEL_PROTOCOL_VERSION = 1 as const;\n\n/** Per-record envelope written to `commands.ndjson`. */\nexport const CommandRecordSchema = Schema.Struct({\n\tprotocol: Schema.Literal(COMMAND_CHANNEL_PROTOCOL_VERSION),\n\tseq: Schema.Number,\n\tid: Schema.String,\n\tat: Schema.Number,\n\tpublisherPid: Schema.Number,\n\tpublisherHostname: Schema.String,\n\tcommand: Schema.Unknown,\n});\n\nexport type CommandRecord = Schema.Schema.Type<typeof CommandRecordSchema>;\n\n/** Per-record envelope written to `events.ndjson`. The supervisor emits\n *  one record per `EngineEvent` plus synthetic `ack` / `error`\n *  responses when the inner handler reports completion or failure for a\n *  correlatable command.\n *\n *  `correlatesTo` carries the originating `CommandRecord.id` for `ack`\n *  / `error`. Other event kinds (engine events) carry `null`.\n */\nexport const EventRecordSchema = Schema.Union([\n\tSchema.Struct({\n\t\tprotocol: Schema.Literal(COMMAND_CHANNEL_PROTOCOL_VERSION),\n\t\tseq: Schema.Number,\n\t\tat: Schema.Number,\n\t\tkind: Schema.Literal('engine'),\n\t\tevent: Schema.Unknown,\n\t}),\n\tSchema.Struct({\n\t\tprotocol: Schema.Literal(COMMAND_CHANNEL_PROTOCOL_VERSION),\n\t\tseq: Schema.Number,\n\t\tat: Schema.Number,\n\t\tkind: Schema.Literal('ack'),\n\t\tcorrelatesTo: Schema.String,\n\t\tdetail: Schema.optional(Schema.String),\n\t}),\n\tSchema.Struct({\n\t\tprotocol: Schema.Literal(COMMAND_CHANNEL_PROTOCOL_VERSION),\n\t\tseq: Schema.Number,\n\t\tat: Schema.Number,\n\t\tkind: Schema.Literal('error'),\n\t\tcorrelatesTo: Schema.String,\n\t\tmessage: Schema.String,\n\t\tdetail: Schema.optional(Schema.String),\n\t}),\n]);\n\nexport type EventRecord = Schema.Schema.Type<typeof EventRecordSchema>;\n"],"mappings":";;AAiCA,MAAa,sBAAsB,OAAO,OAAO;CAChD,UAAU,OAAO,QAAA,EAAyC;CAC1D,KAAK,OAAO;CACZ,IAAI,OAAO;CACX,IAAI,OAAO;CACX,cAAc,OAAO;CACrB,mBAAmB,OAAO;CAC1B,SAAS,OAAO;CAChB,CAAC;;;;;;;;;AAYF,MAAa,oBAAoB,OAAO,MAAM;CAC7C,OAAO,OAAO;EACb,UAAU,OAAO,QAAA,EAAyC;EAC1D,KAAK,OAAO;EACZ,IAAI,OAAO;EACX,MAAM,OAAO,QAAQ,SAAS;EAC9B,OAAO,OAAO;EACd,CAAC;CACF,OAAO,OAAO;EACb,UAAU,OAAO,QAAA,EAAyC;EAC1D,KAAK,OAAO;EACZ,IAAI,OAAO;EACX,MAAM,OAAO,QAAQ,MAAM;EAC3B,cAAc,OAAO;EACrB,QAAQ,OAAO,SAAS,OAAO,OAAO;EACtC,CAAC;CACF,OAAO,OAAO;EACb,UAAU,OAAO,QAAA,EAAyC;EAC1D,KAAK,OAAO;EACZ,IAAI,OAAO;EACX,MAAM,OAAO,QAAQ,QAAQ;EAC7B,cAAc,OAAO;EACrB,SAAS,OAAO;EAChB,QAAQ,OAAO,SAAS,OAAO,OAAO;EACtC,CAAC;CACF,CAAC"}

package/dist/substrate/runtime/cross-process/command-channel/runtime-control-lock.mjs

@@ -0,0 +1,9 @@
+import { dirname } from "node:path";
+//#region src/substrate/runtime/cross-process/command-channel/runtime-control-lock.ts
+const RUNTIME_CONTROL_LOCK_FILE_SUFFIX = ".runtime-control.lock";
+const runtimeControlLockPathForStackRoot = (stackRoot) => `${stackRoot}${RUNTIME_CONTROL_LOCK_FILE_SUFFIX}`;
+const runtimeControlLockPathForChannelFile = (path) => runtimeControlLockPathForStackRoot(dirname(path));
+//#endregion
+export { runtimeControlLockPathForChannelFile, runtimeControlLockPathForStackRoot };
+
+//# sourceMappingURL=runtime-control-lock.mjs.map

package/dist/substrate/runtime/cross-process/command-channel/runtime-control-lock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-control-lock.mjs","names":[],"sources":["../../../../../src/substrate/runtime/cross-process/command-channel/runtime-control-lock.ts"],"sourcesContent":["import { dirname } from 'node:path';\n\nexport const RUNTIME_CONTROL_LOCK_FILE_SUFFIX = '.runtime-control.lock';\n\nexport const runtimeControlLockPathForStackRoot = (stackRoot: string): string =>\n\t`${stackRoot}${RUNTIME_CONTROL_LOCK_FILE_SUFFIX}`;\n\nexport const runtimeControlLockPathForChannelFile = (path: string): string =>\n\truntimeControlLockPathForStackRoot(dirname(path));\n"],"mappings":";;AAEA,MAAa,mCAAmC;AAEhD,MAAa,sCAAsC,cAClD,GAAG,YAAY;AAEhB,MAAa,wCAAwC,SACpD,mCAAmC,QAAQ,KAAK,CAAC"}