@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/plugins/walrus/storage-nodes.mjs

@@ -1,8 +1,11 @@
+import { SpanAttr } from "../../substrate/runtime/observability/spans.mjs";
 import { ProbeTimeoutError, exitCodeProbeResult, waitForProbe } from "../../substrate/runtime/probes.mjs";
-import { ensureManagedContainer } from "../../substrate/runtime/managed-container.mjs";
 import { setCurrentPluginPhase } from "../../substrate/runtime/current-plugin.mjs";
+import { HOST_GATEWAY_EXTRA_HOSTS } from "../../substrate/runtime/host-gateway.mjs";
+import { ensureManagedContainer } from "../../substrate/runtime/managed-container.mjs";
 import { walrusDeployMountPaths } from "./deploy-paths.mjs";
 import { walrusPluginError } from "./errors.mjs";
+import { WalrusSpans } from "./spans.mjs";
 import { Duration, Effect, Scope } from "effect";
 /** Default per-node ready-probe timeout. */
 const DEFAULT_NODE_READY_TIMEOUT_MS = 6e4;
@@ -72,11 +75,16 @@ const NODE_READY_PROBE_INTERVAL_MS = 500;
 */
 const startStorageNodes = (runtime, spec) => Effect.gen(function* () {
 	if (spec.nodeCount < 1) return yield* Effect.fail(walrusPluginError("storage-node", `storage-nodes: nodeCount must be >= 1 (got ${spec.nodeCount})`));
+	if (spec.images.length !== spec.nodeCount) return yield* Effect.fail(walrusPluginError("storage-node", `storage-nodes: images length (${spec.images.length}) must equal nodeCount (${spec.nodeCount}) — one distinct per-node image tag is required for restore-safe commits`));
 	const outerScope = yield* Effect.scope;
 	const nodeStopScope = yield* Scope.fork(outerScope, "parallel");
 	const stopGraceSeconds = spec.stopGraceSeconds ?? 20;
 	const readyTimeout = Duration.millis(spec.readyTimeoutMs ?? 6e4);
-	const deployMount = walrusDeployMountPaths(spec.deployHostMountPath, "/opt/walrus/runtime");
+	const deployMount = walrusDeployMountPaths({
+		stackRoot: spec.stackRoot,
+		deployOutputDirHostPath: spec.deployHostMountPath,
+		mountTarget: "/opt/walrus/runtime"
+	});
 	const indices = Array.from({ length: spec.nodeCount }, (_, i) => i);
 	const bootOne = (i) => Effect.gen(function* () {
 		const containerIp = `${spec.subnetPrefix}.${10 + i}`;
@@ -94,7 +102,7 @@ const startStorageNodes = (runtime, spec) => Effect.gen(function* () {
 			role: `storage-node-${i}`,
 			spec: {
 				name: containerName,
-				image: spec.image,
+				image: spec.images[i],
 				recreate: "on-config-change",
 				configHash: storageNodeConfigHash({
 					deployConfigHash: spec.deployConfigHash,
@@ -111,7 +119,7 @@ const startStorageNodes = (runtime, spec) => Effect.gen(function* () {
 				},
 				stopGraceSeconds,
 				networkAttach: [spec.walrusNetworkName, spec.suiNetworkName],
-				extraHosts: { "host.docker.internal": "host-gateway" },
+				extraHosts: HOST_GATEWAY_EXTRA_HOSTS,
 				mounts: [{
 					source: deployMount.sourceHostPath,
 					target: deployMount.mountTarget,
@@ -138,16 +146,15 @@ const startStorageNodes = (runtime, spec) => Effect.gen(function* () {
 		return {
 			nodeIndex: i,
 			nodeId: `walrus-node-${i}`,
-			publicKey: `<bls-pubkey-storage-node-${i}>`,
 			publicHostname,
 			rpcUrl: `http://${publicHostname}:${WALRUS_ROUTER_PORT}`
 		};
 	}).pipe(Effect.withSpan(`devstack.plugin.walrus.storage-node-${i}.boot`, { attributes: {
-		"devstack.plugin": "walrus",
-		"walrus.node": i
+		[SpanAttr.plugin]: "walrus",
+		[WalrusSpans.node]: i
 	} }));
 	return { nodes: yield* Effect.all(indices.map(bootOne), { concurrency: "unbounded" }) };
-}).pipe(Effect.withSpan("devstack.plugin.walrus.storage-nodes.boot", { attributes: { "devstack.plugin": "walrus" } }));
+}).pipe(Effect.withSpan("devstack.plugin.walrus.storage-nodes.boot", { attributes: { [SpanAttr.plugin]: "walrus" } }));
 //#endregion
 export { DEFAULT_CONTAINER_API_PORT, DEFAULT_NODE_READY_TIMEOUT_MS, WALRUS_ROUTER_PORT, buildWalrusNetworkName, computePublicHostname, startStorageNodes };
 

package/dist/plugins/walrus/storage-nodes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"storage-nodes.mjs","names":[],"sources":["../../../src/plugins/walrus/storage-nodes.ts"],"sourcesContent":["// Walrus storage-node committee lifecycle.\n//\n// Distilled-doc reference (06-walrus.md §\"Capabilities CONSUMED\" +\n// §\"Lifecycle phase 4\"): N storage-node containers, pinned IPs on a\n// per-stack /24 docker network. Each node carries one Traefik route\n// via the `Routable` capability; the router binds host port 9185 once\n// globally and dispatches by `Host:` header.\n//\n// Substrate-side responsibilities:\n//   - `ContainerRuntime.ensureContainer` per node — content-addressed\n//     image, label tuple, recreate policy.\n//   - Parallel `Effect.all({concurrency: 'unbounded'})` over [0..N) —\n//     concurrent boot.\n//   - Per-node stop finalizer fires in a *forked parallel scope* so\n//     teardown collapses to ~max(grace) instead of summing graces\n//     (distilled-doc invariant 21 — \"StopFinalizerScope MUST be a\n//     forked parallel scope\").\n//\n// What we DON'T own here:\n//   - Plugin row narration.\n//   - The faucet-strategy registration — `faucet-strategy.ts`.\n//   - The deploy one-shot — `deploy.ts`.\n\nimport { Duration, Effect, Scope } from 'effect';\n\nimport type {\n\tContainerHandle,\n\tContainerRuntime,\n\tImageRef,\n} from '../../contracts/container-runtime.ts';\nimport {\n\tProbeTimeoutError,\n\texitCodeProbeResult,\n\twaitForProbe,\n} from '../../substrate/runtime/probes.ts';\nimport { setCurrentPluginPhase } from '../../substrate/runtime/current-plugin.ts';\nimport { ensureManagedContainer } from '../../substrate/runtime/managed-container.ts';\nimport { walrusDeployMountPaths } from './deploy-paths.ts';\nimport { walrusPluginError, type WalrusPluginError } from './errors.ts';\n\n/** Default per-node grace window. Storage nodes maintain RocksDB-\n *  backed state; need >10s to flush and checkpoint on `docker stop`.\n *  Distilled-doc invariant 22. */\nexport const DEFAULT_NODE_STOP_GRACE_SECONDS = 20;\n\n/** Default per-node ready-probe timeout. */\nexport const DEFAULT_NODE_READY_TIMEOUT_MS = 60_000;\n\n/** Distilled-doc invariant 9: the on-chain `public_port` value\n *  matches the global router entrypoint port. One canonical\n *  constant — opportunity #14 in the distilled doc was to deduplicate\n *  this across three files. */\nexport const WALRUS_ROUTER_PORT = 9185;\n\n/** Default container API port — each storage node binds this inside\n *  the container. Same value as the router port (the storage node's\n *  in-container bind matches the on-chain public_port). */\nexport const DEFAULT_CONTAINER_API_PORT = WALRUS_ROUTER_PORT;\n\n/** Per-node descriptor — what the plugin resolved value surfaces\n *  for downstream consumers (the `@mysten/walrus` SDK reads this). */\nexport interface WalrusStorageNode {\n\treadonly nodeIndex: number;\n\treadonly nodeId: string;\n\treadonly publicKey: string;\n\treadonly publicHostname: string;\n\treadonly rpcUrl: string;\n}\n\n/** Storage-node startup config — the plugin's local-cluster mode\n *  passes this in once per cluster boot. */\nexport interface StorageNodesSpec {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly walrusName: string;\n\treadonly image: ImageRef;\n\treadonly nodeCount: number;\n\t/** Pre-allocated /24 prefix from `subnetForStack`. Example:\n\t *  `'10.42.7'` (the third octet is hashed per stack). */\n\treadonly subnetPrefix: string;\n\treadonly containerApiPort: number;\n\treadonly walrusNetworkName: string;\n\treadonly suiNetworkName: string;\n\treadonly deployHostMountPath: string;\n\t/** Fingerprint of the deploy outputs mounted into each node. */\n\treadonly deployConfigHash: string;\n\treadonly stopGraceSeconds?: number;\n\treadonly readyTimeoutMs?: number;\n}\n\n/** Result of starting the committee — descriptors used by the\n *  plugin's resolved value. */\nexport interface StorageNodesAcquired {\n\treadonly nodes: ReadonlyArray<WalrusStorageNode>;\n}\n\n/** Distilled-doc invariant 1: pinned IPs start at `<prefix>.10`.\n *  Centralized so the deploy one-shot's `WALRUS_LISTENING_IPS` env\n *  var and the per-node `--ip` pin compute from one source. */\nexport const WALRUS_NODE_IP_BASE = 10;\n\n/** Compute the public hostname for one storage node. Mirrors\n *  v3's `routerHostname(identity, 'walrus-node-' + i)` shape\n *  (06-walrus.md §\"Routes registered\"). Main stack omits the stack\n *  segment; non-main inserts it after the service label. */\nexport const computePublicHostname = (app: string, stack: string, nodeIndex: number): string => {\n\tconst base = `walrus-node-${nodeIndex}.${app}.localhost`;\n\treturn stack === 'main' ? base : `walrus-node-${nodeIndex}.${stack}.${app}.localhost`;\n};\n\nexport const storageNodeConfigHash = (parts: {\n\treadonly deployConfigHash: string;\n\treadonly nodeIndex: number;\n\treadonly deploySourceHostPath: string;\n\treadonly deployMountTarget: string;\n\treadonly containerApiPort: number;\n\treadonly walrusNetworkName: string;\n\treadonly suiNetworkName: string;\n}): string =>\n\t[\n\t\tparts.deployConfigHash,\n\t\t`node=${parts.nodeIndex}`,\n\t\t`mount=${parts.deploySourceHostPath}->${parts.deployMountTarget}`,\n\t\t`api=${parts.containerApiPort}`,\n\t\t`net=${parts.walrusNetworkName},${parts.suiNetworkName}`,\n\t].join('|');\n\nexport const buildWalrusNetworkName = (app: string, stack: string, walrusName: string): string =>\n\t`devstack-${app}-${stack}-walrus-${walrusName}-net`;\n\n/** Per-node TCP ready-probe interval. */\nconst NODE_READY_PROBE_INTERVAL_MS = 500;\n\n/** Start the N-node committee.\n *\n *  Wiring (this body is the load-bearing path):\n *\n *    1. Defense-in-depth nodeCount guard.\n *    2. Fork a parallel-strategy child scope off the caller's scope so\n *       every node's `docker stop` finalizer fires concurrently on\n *       outer teardown — collapses shutdown wall-time from `N×grace` to\n *       `~max(grace)` (distilled-doc invariant 21).\n *    3. For each `i ∈ [0..N)`:\n *         a. `ensureContainer` on the wrapper image with pinned IP,\n *            label tuple, primary network attach (walrus net), recreate\n *            on config-change.\n *         b. TCP ready probe against `<publicHostname>:<routerPort>`\n *            with bounded retries until the outer `readyTimeoutMs`.\n *    4. Run [3] under `Effect.all({concurrency: 'unbounded'})` — boot\n *       parallelism collapses to ~max(perNode).\n *\n *  WHAT THE SUBSTRATE STILL OWES:\n *    - Secondary network attach (`Docker.networkConnect(suiNet)`).\n *      `EnsureContainerSpec.networkAttach` accepts an array, so passing\n *      `[walrusNet, suiNet]` would dual-home in one shot, but the\n *      runtime adapter currently treats the first entry as the primary\n *      and post-attaches the rest; the per-node pinned IP only attaches\n *      to the primary. The dual-home is documented inline below and\n *      relies on that adapter behavior. Storage nodes do not request\n *      faucet funds during boot; the secondary network is retained for\n *      future Sui-side in-network calls.\n *    - Per-node `networkAlias` (`walrus-node-<i>.localhost`). The\n *      contract doesn't expose alias plumbing yet; peer containers dial by\n *      container name, which docker DNS publishes. The architecture\n *      revision is tracked in `index.ts`.\n *    - Stop-grace duration propagation. The contract's `stop` takes a\n *      Duration but `ensureContainer` doesn't yet accept a default\n *      grace; the runtime adapter defaults to 10s. RocksDB needs 20s\n *      (distilled-doc invariant 22) — see opportunity below.\n */\nexport const startStorageNodes = (\n\truntime: ContainerRuntime,\n\tspec: StorageNodesSpec,\n): Effect.Effect<StorageNodesAcquired, WalrusPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tif (spec.nodeCount < 1) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'storage-node',\n\t\t\t\t\t`storage-nodes: nodeCount must be >= 1 (got ${spec.nodeCount})`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\t// Fork a parallel stop-scope. Per-node `ensureContainer` finalizers\n\t\t// fire here on outer teardown; closing the parallel scope races\n\t\t// the per-container `docker stop`s instead of summing them.\n\t\tconst outerScope = yield* Effect.scope;\n\t\tconst nodeStopScope = yield* Scope.fork(outerScope, 'parallel');\n\n\t\tconst stopGraceSeconds = spec.stopGraceSeconds ?? DEFAULT_NODE_STOP_GRACE_SECONDS;\n\t\tconst readyTimeout = Duration.millis(spec.readyTimeoutMs ?? DEFAULT_NODE_READY_TIMEOUT_MS);\n\t\tconst deployMount = walrusDeployMountPaths(spec.deployHostMountPath, '/opt/walrus/runtime');\n\n\t\tconst indices = Array.from({ length: spec.nodeCount }, (_, i) => i);\n\n\t\tconst bootOne = (i: number): Effect.Effect<WalrusStorageNode, WalrusPluginError, Scope.Scope> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst containerIp = `${spec.subnetPrefix}.${WALRUS_NODE_IP_BASE + i}`;\n\t\t\t\tconst containerName = `devstack-${spec.app}-${spec.stack}-walrus-${spec.walrusName}-node-${i}`;\n\t\t\t\tconst nodeHostname = `dryrun-node-${i}`;\n\t\t\t\tconst publicHostname = computePublicHostname(spec.app, spec.stack, i);\n\n\t\t\t\tyield* setCurrentPluginPhase(`creating storage-node-${i} container ${containerName}`);\n\t\t\t\t// Acquire under the forked parallel stop scope so the\n\t\t\t\t// finalizer (docker stop) joins the per-node fan-out race.\n\t\t\t\tconst ensureNode: Effect.Effect<ContainerHandle, WalrusPluginError, Scope.Scope> =\n\t\t\t\t\tensureManagedContainer<WalrusPluginError>({\n\t\t\t\t\t\truntime,\n\t\t\t\t\t\tidentity: { app: spec.app, stack: spec.stack },\n\t\t\t\t\t\tplugin: 'walrus',\n\t\t\t\t\t\trole: `storage-node-${i}`,\n\t\t\t\t\t\tspec: {\n\t\t\t\t\t\t\tname: containerName,\n\t\t\t\t\t\t\timage: spec.image,\n\t\t\t\t\t\t\trecreate: 'on-config-change',\n\t\t\t\t\t\t\tconfigHash: storageNodeConfigHash({\n\t\t\t\t\t\t\t\tdeployConfigHash: spec.deployConfigHash,\n\t\t\t\t\t\t\t\tnodeIndex: i,\n\t\t\t\t\t\t\t\tdeploySourceHostPath: deployMount.sourceHostPath,\n\t\t\t\t\t\t\t\tdeployMountTarget: deployMount.mountTarget,\n\t\t\t\t\t\t\t\tcontainerApiPort: spec.containerApiPort,\n\t\t\t\t\t\t\t\twalrusNetworkName: spec.walrusNetworkName,\n\t\t\t\t\t\t\t\tsuiNetworkName: spec.suiNetworkName,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\tenv: {\n\t\t\t\t\t\t\t\tHOSTNAME: nodeHostname,\n\t\t\t\t\t\t\t\tDEPLOY_OUTPUT_DIR: deployMount.outputDirInContainer,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\tstopGraceSeconds,\n\t\t\t\t\t\t\t// Primary network owns the pinned `--ip`; the\n\t\t\t\t\t\t\t// secondary attach gives docker DNS for the sui\n\t\t\t\t\t\t\t// network. The adapter treats [0] as primary.\n\t\t\t\t\t\t\tnetworkAttach: [spec.walrusNetworkName, spec.suiNetworkName],\n\t\t\t\t\t\t\t// `host-gateway` resolves `host.docker.internal` to\n\t\t\t\t\t\t\t// the host's loopback inside the container — Docker\n\t\t\t\t\t\t\t// Desktop wires this automatically on macOS/Windows\n\t\t\t\t\t\t\t// but native Linux Docker requires the explicit\n\t\t\t\t\t\t\t// `--add-host` flag. Storage nodes dial sui's\n\t\t\t\t\t\t\t// host-bound RPC + faucet via this hostname.\n\t\t\t\t\t\t\textraHosts: { 'host.docker.internal': 'host-gateway' },\n\t\t\t\t\t\t\tmounts: [\n\t\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\t\t// Mount the stack root and point the entrypoint at\n\t\t\t\t\t\t\t\t\t// the deploy child. Docker Desktop can reject\n\t\t\t\t\t\t\t\t\t// freshly-created nested bind sources immediately\n\t\t\t\t\t\t\t\t\t// after a wiped stack recreates them.\n\t\t\t\t\t\t\t\t\tsource: deployMount.sourceHostPath,\n\t\t\t\t\t\t\t\t\ttarget: deployMount.mountTarget,\n\t\t\t\t\t\t\t\t\treadonly: true,\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t},\n\t\t\t\t\t\tmapError: (cause) =>\n\t\t\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t\t\t'storage-node',\n\t\t\t\t\t\t\t\t`walrus storage-node-${i} (ip=${containerIp}) ensureContainer failed: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t\t\t{ cause },\n\t\t\t\t\t\t\t),\n\t\t\t\t\t});\n\t\t\t\tconst handle: ContainerHandle = yield* Scope.provide(ensureNode, nodeStopScope);\n\n\t\t\t\t// TCP ready probe. We exec a tiny `nc`-style probe inside\n\t\t\t\t// the container against its own listener — proves the\n\t\t\t\t// in-container HTTP server bound and is accepting before\n\t\t\t\t// declaring ready. `exec` only fails on daemon-level\n\t\t\t\t// errors; a non-zero exit code is treated as \"retry\"\n\t\t\t\t// (the same policy postgres uses for `pg_isready`).\n\t\t\t\tyield* setCurrentPluginPhase(\n\t\t\t\t\t`waiting for storage-node-${i} on 127.0.0.1:${spec.containerApiPort}`,\n\t\t\t\t);\n\t\t\t\tyield* waitForProbe({\n\t\t\t\t\tlabel: `walrus.storage-node.${i}`,\n\t\t\t\t\ttimeoutMs: Duration.toMillis(readyTimeout),\n\t\t\t\t\tintervalMs: NODE_READY_PROBE_INTERVAL_MS,\n\t\t\t\t\tprobe: () =>\n\t\t\t\t\t\truntime\n\t\t\t\t\t\t\t.exec(handle, [\n\t\t\t\t\t\t\t\t'sh',\n\t\t\t\t\t\t\t\t'-c',\n\t\t\t\t\t\t\t\t// busybox-style portable probe: open TCP, write\n\t\t\t\t\t\t\t\t// nothing, exit. `nc -z` is the common form.\n\t\t\t\t\t\t\t\t`nc -z 127.0.0.1 ${spec.containerApiPort} || exit 1`,\n\t\t\t\t\t\t\t])\n\t\t\t\t\t\t\t.pipe(Effect.map(exitCodeProbeResult)),\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.mapError((cause) => {\n\t\t\t\t\t\tif (cause instanceof ProbeTimeoutError) {\n\t\t\t\t\t\t\treturn walrusPluginError(\n\t\t\t\t\t\t\t\t'storage-node',\n\t\t\t\t\t\t\t\t`storage-node-${i} never became ready within ${Duration.toMillis(readyTimeout)}ms ` +\n\t\t\t\t\t\t\t\t\t`(container=${containerName}, probe=127.0.0.1:${spec.containerApiPort}, ` +\n\t\t\t\t\t\t\t\t\t`publicUrl=http://${publicHostname}:${WALRUS_ROUTER_PORT}). ` +\n\t\t\t\t\t\t\t\t\t`The container was created, but walrus-node did not bind its API port. ` +\n\t\t\t\t\t\t\t\t\t`Check the storage-node container logs for the faucet, WAL exchange, or ` +\n\t\t\t\t\t\t\t\t\t`walrus-node run step that stalled.`,\n\t\t\t\t\t\t\t\t{ cause: cause.lastError ?? cause.lastNotReady ?? cause },\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn walrusPluginError(\n\t\t\t\t\t\t\t'storage-node',\n\t\t\t\t\t\t\t`storage-node-${i} ready-probe exec failed: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t\t{ cause },\n\t\t\t\t\t\t);\n\t\t\t\t\t}),\n\t\t\t\t);\n\n\t\t\t\treturn {\n\t\t\t\t\tnodeIndex: i,\n\t\t\t\t\t// Stable node-id derived from name. The on-chain\n\t\t\t\t\t// public_key + bls12-381 keypair lives inside the\n\t\t\t\t\t// per-node keystore the deploy one-shot emitted;\n\t\t\t\t\t// this descriptor is the routing handle, not the\n\t\t\t\t\t// crypto identity. The SDK consumer reads the\n\t\t\t\t\t// public key off `packageConfig` rather than this\n\t\t\t\t\t// per-node descriptor.\n\t\t\t\t\tnodeId: `walrus-node-${i}`,\n\t\t\t\t\tpublicKey: `<bls-pubkey-storage-node-${i}>`,\n\t\t\t\t\tpublicHostname,\n\t\t\t\t\t// Router-fronted URL on the well-known walrus\n\t\t\t\t\t// entrypoint port — Traefik routes by Host: header.\n\t\t\t\t\trpcUrl: `http://${publicHostname}:${WALRUS_ROUTER_PORT}`,\n\t\t\t\t} satisfies WalrusStorageNode;\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan(`devstack.plugin.walrus.storage-node-${i}.boot`, {\n\t\t\t\t\tattributes: { 'devstack.plugin': 'walrus', 'walrus.node': i },\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst nodes = yield* Effect.all(indices.map(bootOne), {\n\t\t\tconcurrency: 'unbounded',\n\t\t});\n\n\t\treturn { nodes };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.walrus.storage-nodes.boot', {\n\t\t\tattributes: { 'devstack.plugin': 'walrus' },\n\t\t}),\n\t);\n"],"mappings":"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"}
+{"version":3,"file":"storage-nodes.mjs","names":[],"sources":["../../../src/plugins/walrus/storage-nodes.ts"],"sourcesContent":["// Walrus storage-node committee lifecycle.\n//\n// Distilled-doc reference (06-walrus.md §\"Capabilities CONSUMED\" +\n// §\"Lifecycle phase 4\"): N storage-node containers, pinned IPs on a\n// per-stack /24 docker network. Each node carries one Traefik route\n// via the `Routable` capability; the router binds host port 9185 once\n// globally and dispatches by `Host:` header.\n//\n// Substrate-side responsibilities:\n//   - `ContainerRuntime.ensureContainer` per node — content-addressed\n//     image, label tuple, recreate policy.\n//   - Parallel `Effect.all({concurrency: 'unbounded'})` over [0..N) —\n//     concurrent boot.\n//   - Per-node stop finalizer fires in a *forked parallel scope* so\n//     teardown collapses to ~max(grace) instead of summing graces\n//     (distilled-doc invariant 21 — \"StopFinalizerScope MUST be a\n//     forked parallel scope\").\n//\n// What we DON'T own here:\n//   - Plugin row narration.\n//   - The faucet-strategy registration — `faucet-strategy.ts`.\n//   - The deploy one-shot — `deploy.ts`.\n\nimport { Duration, Effect, Scope } from 'effect';\n\nimport type {\n\tContainerHandle,\n\tContainerRuntime,\n\tImageRef,\n} from '../../contracts/container-runtime.ts';\nimport {\n\tProbeTimeoutError,\n\texitCodeProbeResult,\n\twaitForProbe,\n} from '../../substrate/runtime/probes.ts';\nimport { setCurrentPluginPhase } from '../../substrate/runtime/current-plugin.ts';\nimport { ensureManagedContainer } from '../../substrate/runtime/managed-container.ts';\nimport { HOST_GATEWAY_EXTRA_HOSTS } from '../../substrate/runtime/host-gateway.ts';\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport { walrusDeployMountPaths } from './deploy-paths.ts';\nimport { walrusPluginError, type WalrusPluginError } from './errors.ts';\nimport { WalrusSpans } from './spans.ts';\n\n/** Default per-node grace window. Storage nodes maintain RocksDB-\n *  backed state; need >10s to flush and checkpoint on `docker stop`.\n *  Distilled-doc invariant 22. */\nexport const DEFAULT_NODE_STOP_GRACE_SECONDS = 20;\n\n/** Default per-node ready-probe timeout. */\nexport const DEFAULT_NODE_READY_TIMEOUT_MS = 60_000;\n\n/** Distilled-doc invariant 9: the on-chain `public_port` value\n *  matches the global router entrypoint port. One canonical\n *  constant — opportunity #14 in the distilled doc was to deduplicate\n *  this across three files. */\nexport const WALRUS_ROUTER_PORT = 9185;\n\n/** Default container API port — each storage node binds this inside\n *  the container. Same value as the router port (the storage node's\n *  in-container bind matches the on-chain public_port). */\nexport const DEFAULT_CONTAINER_API_PORT = WALRUS_ROUTER_PORT;\n\n/** Per-node descriptor — what the plugin resolved value surfaces\n *  for downstream consumers (the `@mysten/walrus` SDK reads this).\n *\n *  Note: no `publicKey` field. The per-node BLS12-381 keypair lives\n *  inside the per-node keystore the deploy one-shot emitted; the SDK\n *  consumer reads the public key off `packageConfig` rather than this\n *  routing-handle descriptor. */\nexport interface WalrusStorageNode {\n\treadonly nodeIndex: number;\n\treadonly nodeId: string;\n\treadonly publicHostname: string;\n\treadonly rpcUrl: string;\n}\n\n/** Storage-node startup config — the plugin's local-cluster mode\n *  passes this in once per cluster boot. */\nexport interface StorageNodesSpec {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly walrusName: string;\n\t/** One image ref PER node (`images[i]` for node `i`; length MUST equal\n\t *  `nodeCount`). Each node runs under its own tag so its committed writable\n\t *  layer (RocksDB slivers) promotes to a DISTINCT image on snapshot restore;\n\t *  a single shared tag collapses N committed layers -> 1 on the restore\n\t *  image-promote, orphaning N-1 nodes' blobs. */\n\treadonly images: ReadonlyArray<ImageRef>;\n\treadonly nodeCount: number;\n\t/** Pre-allocated /24 prefix from `subnetForStack`. Example:\n\t *  `'10.42.7'` (the third octet is hashed per stack). */\n\treadonly subnetPrefix: string;\n\treadonly containerApiPort: number;\n\treadonly walrusNetworkName: string;\n\treadonly suiNetworkName: string;\n\treadonly deployHostMountPath: string;\n\t/** On-disk per-stack root from `StackPathsService.stackRoot`. The\n\t *  walrus bind-mount is computed by `walrusDeployMountPaths` as\n\t *  `<stackRoot> -> <mountTarget>`; the deploy output dir MUST be a\n\t *  descendant. Threaded explicitly to remove the previous\n\t *  `dirname(dirname(dirname(...)))` walk-up footgun. */\n\treadonly stackRoot: string;\n\t/** Fingerprint of the deploy outputs mounted into each node. */\n\treadonly deployConfigHash: string;\n\treadonly stopGraceSeconds?: number;\n\treadonly readyTimeoutMs?: number;\n}\n\n/** Result of starting the committee — descriptors used by the\n *  plugin's resolved value. */\nexport interface StorageNodesAcquired {\n\treadonly nodes: ReadonlyArray<WalrusStorageNode>;\n}\n\n/** Distilled-doc invariant 1: pinned IPs start at `<prefix>.10`.\n *  Centralized so the deploy one-shot's `WALRUS_LISTENING_IPS` env\n *  var and the per-node `--ip` pin compute from one source. */\nexport const WALRUS_NODE_IP_BASE = 10;\n\n/** Compute the public hostname for one storage node. Mirrors\n *  v3's `routerHostname(identity, 'walrus-node-' + i)` shape\n *  (06-walrus.md §\"Routes registered\"). Main stack omits the stack\n *  segment; non-main inserts it after the service label. */\nexport const computePublicHostname = (app: string, stack: string, nodeIndex: number): string => {\n\tconst base = `walrus-node-${nodeIndex}.${app}.localhost`;\n\treturn stack === 'main' ? base : `walrus-node-${nodeIndex}.${stack}.${app}.localhost`;\n};\n\nexport const storageNodeConfigHash = (parts: {\n\treadonly deployConfigHash: string;\n\treadonly nodeIndex: number;\n\treadonly deploySourceHostPath: string;\n\treadonly deployMountTarget: string;\n\treadonly containerApiPort: number;\n\treadonly walrusNetworkName: string;\n\treadonly suiNetworkName: string;\n}): string =>\n\t[\n\t\tparts.deployConfigHash,\n\t\t`node=${parts.nodeIndex}`,\n\t\t`mount=${parts.deploySourceHostPath}->${parts.deployMountTarget}`,\n\t\t`api=${parts.containerApiPort}`,\n\t\t`net=${parts.walrusNetworkName},${parts.suiNetworkName}`,\n\t].join('|');\n\nexport const buildWalrusNetworkName = (app: string, stack: string, walrusName: string): string =>\n\t`devstack-${app}-${stack}-walrus-${walrusName}-net`;\n\n/** Per-node TCP ready-probe interval. */\nconst NODE_READY_PROBE_INTERVAL_MS = 500;\n\n/** Start the N-node committee.\n *\n *  Wiring (this body is the load-bearing path):\n *\n *    1. Defense-in-depth nodeCount guard.\n *    2. Fork a parallel-strategy child scope off the caller's scope so\n *       every node's `docker stop` finalizer fires concurrently on\n *       outer teardown — collapses shutdown wall-time from `N×grace` to\n *       `~max(grace)` (distilled-doc invariant 21).\n *    3. For each `i ∈ [0..N)`:\n *         a. `ensureContainer` on the wrapper image with pinned IP,\n *            label tuple, primary network attach (walrus net), recreate\n *            on config-change.\n *         b. TCP ready probe against `<publicHostname>:<routerPort>`\n *            with bounded retries until the outer `readyTimeoutMs`.\n *    4. Run [3] under `Effect.all({concurrency: 'unbounded'})` — boot\n *       parallelism collapses to ~max(perNode).\n *\n *  WHAT THE SUBSTRATE STILL OWES:\n *    - Secondary network attach (`Docker.networkConnect(suiNet)`).\n *      `EnsureContainerSpec.networkAttach` accepts an array, so passing\n *      `[walrusNet, suiNet]` would dual-home in one shot, but the\n *      runtime adapter currently treats the first entry as the primary\n *      and post-attaches the rest; the per-node pinned IP only attaches\n *      to the primary. The dual-home is documented inline below and\n *      relies on that adapter behavior. Storage nodes do not request\n *      faucet funds during boot; the secondary network is retained for\n *      future Sui-side in-network calls.\n *    - Per-node `networkAlias` (`walrus-node-<i>.localhost`). The\n *      contract doesn't expose alias plumbing yet; peer containers dial by\n *      container name, which docker DNS publishes. The architecture\n *      revision is tracked in `index.ts`.\n *    - Stop-grace duration propagation. The contract's `stop` takes a\n *      Duration but `ensureContainer` doesn't yet accept a default\n *      grace; the runtime adapter defaults to 10s. RocksDB needs 20s\n *      (distilled-doc invariant 22) — see opportunity below.\n */\nexport const startStorageNodes = (\n\truntime: ContainerRuntime,\n\tspec: StorageNodesSpec,\n): Effect.Effect<StorageNodesAcquired, WalrusPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tif (spec.nodeCount < 1) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'storage-node',\n\t\t\t\t\t`storage-nodes: nodeCount must be >= 1 (got ${spec.nodeCount})`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\tif (spec.images.length !== spec.nodeCount) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'storage-node',\n\t\t\t\t\t`storage-nodes: images length (${spec.images.length}) must equal nodeCount (${spec.nodeCount}) — one distinct per-node image tag is required for restore-safe commits`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\t// Fork a parallel stop-scope. Per-node `ensureContainer` finalizers\n\t\t// fire here on outer teardown; closing the parallel scope races\n\t\t// the per-container `docker stop`s instead of summing them.\n\t\t//\n\t\t// Cascade semantics (verified against effect-v4 `Scope.ts`\n\t\t// `fork` docs — \"Closing the parent closes the child with the\n\t\t// same exit value\"): when ANY `bootOne` fails (e.g. a ready-\n\t\t// probe times out on node i), `Effect.all` interrupts the rest;\n\t\t// the failure propagates up through the encompassing\n\t\t// `Effect.scoped` boundary which closes `outerScope`; that\n\t\t// cascade-closes `nodeStopScope`, running EVERY already-acquired\n\t\t// per-node `docker stop` finalizer in parallel. The probe is\n\t\t// intentionally OUTSIDE `Scope.provide(nodeStopScope)` — its\n\t\t// failures do NOT need their own finalizer attached to the\n\t\t// stop scope; the just-started container's finalizer is already\n\t\t// there from the `ensureNode` acquire that preceded the probe.\n\t\tconst outerScope = yield* Effect.scope;\n\t\tconst nodeStopScope = yield* Scope.fork(outerScope, 'parallel');\n\n\t\tconst stopGraceSeconds = spec.stopGraceSeconds ?? DEFAULT_NODE_STOP_GRACE_SECONDS;\n\t\tconst readyTimeout = Duration.millis(spec.readyTimeoutMs ?? DEFAULT_NODE_READY_TIMEOUT_MS);\n\t\tconst deployMount = walrusDeployMountPaths({\n\t\t\tstackRoot: spec.stackRoot,\n\t\t\tdeployOutputDirHostPath: spec.deployHostMountPath,\n\t\t\tmountTarget: '/opt/walrus/runtime',\n\t\t});\n\n\t\tconst indices = Array.from({ length: spec.nodeCount }, (_, i) => i);\n\n\t\tconst bootOne = (i: number): Effect.Effect<WalrusStorageNode, WalrusPluginError, Scope.Scope> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst containerIp = `${spec.subnetPrefix}.${WALRUS_NODE_IP_BASE + i}`;\n\t\t\t\tconst containerName = `devstack-${spec.app}-${spec.stack}-walrus-${spec.walrusName}-node-${i}`;\n\t\t\t\tconst nodeHostname = `dryrun-node-${i}`;\n\t\t\t\tconst publicHostname = computePublicHostname(spec.app, spec.stack, i);\n\n\t\t\t\tyield* setCurrentPluginPhase(`creating storage-node-${i} container ${containerName}`);\n\t\t\t\t// Acquire under the forked parallel stop scope so the\n\t\t\t\t// finalizer (docker stop) joins the per-node fan-out race.\n\t\t\t\tconst ensureNode: Effect.Effect<ContainerHandle, WalrusPluginError, Scope.Scope> =\n\t\t\t\t\tensureManagedContainer<WalrusPluginError>({\n\t\t\t\t\t\truntime,\n\t\t\t\t\t\tidentity: { app: spec.app, stack: spec.stack },\n\t\t\t\t\t\tplugin: 'walrus',\n\t\t\t\t\t\trole: `storage-node-${i}`,\n\t\t\t\t\t\tspec: {\n\t\t\t\t\t\t\tname: containerName,\n\t\t\t\t\t\t\t// Node `i`'s own image tag — distinct per node so its\n\t\t\t\t\t\t\t// committed RocksDB layer survives snapshot restore.\n\t\t\t\t\t\t\timage: spec.images[i]!,\n\t\t\t\t\t\t\trecreate: 'on-config-change',\n\t\t\t\t\t\t\tconfigHash: storageNodeConfigHash({\n\t\t\t\t\t\t\t\tdeployConfigHash: spec.deployConfigHash,\n\t\t\t\t\t\t\t\tnodeIndex: i,\n\t\t\t\t\t\t\t\tdeploySourceHostPath: deployMount.sourceHostPath,\n\t\t\t\t\t\t\t\tdeployMountTarget: deployMount.mountTarget,\n\t\t\t\t\t\t\t\tcontainerApiPort: spec.containerApiPort,\n\t\t\t\t\t\t\t\twalrusNetworkName: spec.walrusNetworkName,\n\t\t\t\t\t\t\t\tsuiNetworkName: spec.suiNetworkName,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\tenv: {\n\t\t\t\t\t\t\t\tHOSTNAME: nodeHostname,\n\t\t\t\t\t\t\t\tDEPLOY_OUTPUT_DIR: deployMount.outputDirInContainer,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\tstopGraceSeconds,\n\t\t\t\t\t\t\t// Primary network owns the pinned `--ip`; the\n\t\t\t\t\t\t\t// secondary attach gives docker DNS for the sui\n\t\t\t\t\t\t\t// network. The adapter treats [0] as primary.\n\t\t\t\t\t\t\tnetworkAttach: [spec.walrusNetworkName, spec.suiNetworkName],\n\t\t\t\t\t\t\t// Storage nodes dial sui's host-bound RPC + faucet via\n\t\t\t\t\t\t\t// `host.docker.internal`. See\n\t\t\t\t\t\t\t// substrate/runtime/host-gateway.ts for the platform\n\t\t\t\t\t\t\t// rationale (Docker Desktop auto-wires; native Linux\n\t\t\t\t\t\t\t// Docker requires the explicit `--add-host`).\n\t\t\t\t\t\t\textraHosts: HOST_GATEWAY_EXTRA_HOSTS,\n\t\t\t\t\t\t\tmounts: [\n\t\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\t\t// Mount the stack root and point the entrypoint at\n\t\t\t\t\t\t\t\t\t// the deploy child. Docker Desktop can reject\n\t\t\t\t\t\t\t\t\t// freshly-created nested bind sources immediately\n\t\t\t\t\t\t\t\t\t// after a wiped stack recreates them.\n\t\t\t\t\t\t\t\t\tsource: deployMount.sourceHostPath,\n\t\t\t\t\t\t\t\t\ttarget: deployMount.mountTarget,\n\t\t\t\t\t\t\t\t\treadonly: true,\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t},\n\t\t\t\t\t\tmapError: (cause) =>\n\t\t\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t\t\t'storage-node',\n\t\t\t\t\t\t\t\t`walrus storage-node-${i} (ip=${containerIp}) ensureContainer failed: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t\t\t{ cause },\n\t\t\t\t\t\t\t),\n\t\t\t\t\t});\n\t\t\t\tconst handle: ContainerHandle = yield* Scope.provide(ensureNode, nodeStopScope);\n\n\t\t\t\t// TCP ready probe. We exec a tiny `nc`-style probe inside\n\t\t\t\t// the container against its own listener — proves the\n\t\t\t\t// in-container HTTP server bound and is accepting before\n\t\t\t\t// declaring ready. `exec` only fails on daemon-level\n\t\t\t\t// errors; a non-zero exit code is treated as \"retry\"\n\t\t\t\t// (the same policy postgres uses for `pg_isready`).\n\t\t\t\tyield* setCurrentPluginPhase(\n\t\t\t\t\t`waiting for storage-node-${i} on 127.0.0.1:${spec.containerApiPort}`,\n\t\t\t\t);\n\t\t\t\tyield* waitForProbe({\n\t\t\t\t\tlabel: `walrus.storage-node.${i}`,\n\t\t\t\t\ttimeoutMs: Duration.toMillis(readyTimeout),\n\t\t\t\t\tintervalMs: NODE_READY_PROBE_INTERVAL_MS,\n\t\t\t\t\tprobe: () =>\n\t\t\t\t\t\truntime\n\t\t\t\t\t\t\t.exec(handle, [\n\t\t\t\t\t\t\t\t'sh',\n\t\t\t\t\t\t\t\t'-c',\n\t\t\t\t\t\t\t\t// busybox-style portable probe: open TCP, write\n\t\t\t\t\t\t\t\t// nothing, exit. `nc -z` is the common form.\n\t\t\t\t\t\t\t\t`nc -z 127.0.0.1 ${spec.containerApiPort} || exit 1`,\n\t\t\t\t\t\t\t])\n\t\t\t\t\t\t\t.pipe(Effect.map(exitCodeProbeResult)),\n\t\t\t\t}).pipe(\n\t\t\t\t\tEffect.mapError((cause) => {\n\t\t\t\t\t\tif (cause instanceof ProbeTimeoutError) {\n\t\t\t\t\t\t\treturn walrusPluginError(\n\t\t\t\t\t\t\t\t'storage-node',\n\t\t\t\t\t\t\t\t`storage-node-${i} never became ready within ${Duration.toMillis(readyTimeout)}ms ` +\n\t\t\t\t\t\t\t\t\t`(container=${containerName}, probe=127.0.0.1:${spec.containerApiPort}, ` +\n\t\t\t\t\t\t\t\t\t`publicUrl=http://${publicHostname}:${WALRUS_ROUTER_PORT}). ` +\n\t\t\t\t\t\t\t\t\t`The container was created, but walrus-node did not bind its API port. ` +\n\t\t\t\t\t\t\t\t\t`Check the storage-node container logs for the faucet, WAL exchange, or ` +\n\t\t\t\t\t\t\t\t\t`walrus-node run step that stalled.`,\n\t\t\t\t\t\t\t\t{ cause: cause.lastError ?? cause.lastNotReady ?? cause },\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn walrusPluginError(\n\t\t\t\t\t\t\t'storage-node',\n\t\t\t\t\t\t\t`storage-node-${i} ready-probe exec failed: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t\t{ cause },\n\t\t\t\t\t\t);\n\t\t\t\t\t}),\n\t\t\t\t);\n\n\t\t\t\treturn {\n\t\t\t\t\tnodeIndex: i,\n\t\t\t\t\t// Stable node-id derived from name. The on-chain\n\t\t\t\t\t// public_key + bls12-381 keypair lives inside the\n\t\t\t\t\t// per-node keystore the deploy one-shot emitted;\n\t\t\t\t\t// this descriptor is the routing handle, not the\n\t\t\t\t\t// crypto identity. The SDK consumer reads the\n\t\t\t\t\t// public key off `packageConfig` rather than this\n\t\t\t\t\t// per-node descriptor.\n\t\t\t\t\tnodeId: `walrus-node-${i}`,\n\t\t\t\t\tpublicHostname,\n\t\t\t\t\t// Router-fronted URL on the well-known walrus\n\t\t\t\t\t// entrypoint port — Traefik routes by Host: header.\n\t\t\t\t\trpcUrl: `http://${publicHostname}:${WALRUS_ROUTER_PORT}`,\n\t\t\t\t} satisfies WalrusStorageNode;\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan(`devstack.plugin.walrus.storage-node-${i}.boot`, {\n\t\t\t\t\tattributes: { [SpanAttr.plugin]: 'walrus', [WalrusSpans.node]: i },\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst nodes = yield* Effect.all(indices.map(bootOne), {\n\t\t\tconcurrency: 'unbounded',\n\t\t});\n\n\t\treturn { nodes };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.walrus.storage-nodes.boot', {\n\t\t\tattributes: { [SpanAttr.plugin]: 'walrus' },\n\t\t}),\n\t);\n"],"mappings":"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"}

package/dist/plugins/walrus/wal-swap.mjs

@@ -1,7 +1,40 @@
 import { walrusPluginError } from "./errors.mjs";
+import { WalrusSpans } from "./spans.mjs";
+import { signAndDispatch } from "../../substrate/runtime/sui-execute/sign-and-dispatch.mjs";
+import { formatExecutedFailure } from "../../substrate/runtime/sui-execute/index.mjs";
+import { SUI_FULL_COIN_TYPE } from "../account/funding.mjs";
+import "../account/index.mjs";
 import { Effect, Schema } from "effect";
 import { Transaction } from "@mysten/sui/transactions";
 //#region src/plugins/walrus/wal-swap.ts
+/** Conservative reserve held back from the gas coin for transaction
+*  gas itself. The swap call splits `paymentMist` off the gas coin
+*  via `tx.coin({ useGasCoin: true })`, so the on-chain balance must
+*  cover BOTH the payment AND a gas budget reserve. The exact gas
+*  budget is set by the SDK at build time; this reserve is a coarse
+*  upper bound used only by the pre-flight refusal — if the wire
+*  call proves the reserve is too small the SDK still surfaces the
+*  native `InsufficientGas` cause with the real numbers. */
+const WAL_SWAP_GAS_RESERVE_MIST = 50000000n;
+/** Read the account's SUI balance (best-effort). Returns `null` if the
+*  RPC throws or the response shape is unexpected — the pre-flight is
+*  a hint, not a hard gate. */
+const readSuiBalance = (sdk, owner) => Effect.promise(async () => {
+	try {
+		const response = await sdk.core.getBalance({
+			owner,
+			coinType: SUI_FULL_COIN_TYPE
+		});
+		const outer = typeof response === "object" && response !== null && "balance" in response ? response.balance : response;
+		const value = typeof outer === "object" && outer !== null && "balance" in outer ? outer.balance : outer;
+		if (typeof value === "bigint") return value;
+		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return BigInt(value);
+		if (typeof value === "string" && /^\d+$/.test(value)) return BigInt(value);
+		return null;
+	} catch {
+		return null;
+	}
+});
 const WalExchangeObjectShape = Schema.Struct({
 	objectId: Schema.String,
 	type: Schema.String
@@ -35,22 +68,32 @@ const buildWalSwapTransaction = (args) => {
 	tx.transferObjects([walCoin], tx.pure.address(args.recipientAddress));
 	return tx;
 };
-const swapAccountSuiForWal = (args) => args.account.withTransactionSigner((lockedSigner) => Effect.gen(function* () {
-	const tx = buildWalSwapTransaction({
-		signerAddress: args.account.address,
-		recipientAddress: args.recipientAddress,
-		exchange: args.exchange,
-		paymentMist: args.paymentMist
-	});
-	const txBytes = yield* Effect.tryPromise({
-		try: () => tx.build({ client: args.sdk.client }),
-		catch: (cause) => walrusPluginError("fund-wal", `walrus.fundWal: transaction serialization failed for account '${args.account.name}'.`, { cause })
+const swapAccountSuiForWal = (args) => Effect.gen(function* () {
+	const suiBalance = yield* readSuiBalance(args.sdk, args.account.address);
+	const required = args.paymentMist + WAL_SWAP_GAS_RESERVE_MIST;
+	if (suiBalance !== null && suiBalance < required) return yield* Effect.fail(walrusPluginError("fund-wal", `walrus.fundWal: account '${args.account.name}' (address=${args.account.address}) has insufficient SUI to swap ${args.paymentMist} for WAL — balance=${suiBalance} mist, required≥${required} mist (payment=${args.paymentMist} + gas reserve=${WAL_SWAP_GAS_RESERVE_MIST}). Top up the account's SUI funding before declaring the WAL funding entry.`));
+	return yield* signAndDispatch({
+		signerSource: args.account,
+		buildTxBytes: () => Effect.gen(function* () {
+			const tx = buildWalSwapTransaction({
+				signerAddress: args.account.address,
+				recipientAddress: args.recipientAddress,
+				exchange: args.exchange,
+				paymentMist: args.paymentMist
+			});
+			return yield* Effect.tryPromise({
+				try: () => tx.build({ client: args.sdk.client }),
+				catch: (cause) => walrusPluginError("fund-wal", `walrus.fundWal: transaction serialization failed for account '${args.account.name}'.`, { cause })
+			});
+		}),
+		mapSignError: (cause) => walrusPluginError("fund-wal", `walrus.fundWal: SUI -> WAL swap failed for ${args.recipientAddress} using account '${args.account.name}' (address=${args.account.address}) against exchange ${args.exchange.objectId}.`, { cause }),
+		onFailed: (failure) => Effect.fail(walrusPluginError("fund-wal", `walrus.fundWal: SUI -> WAL swap failed on-chain (exchange=${args.exchange.objectId}) ` + formatExecutedFailure(failure))),
+		onSuccess: (ok) => Effect.succeed({ digest: ok.digest })
 	});
-	return { digest: (yield* lockedSigner.signAndExecute(txBytes).pipe(Effect.mapError((cause) => walrusPluginError("fund-wal", `walrus.fundWal: SUI -> WAL swap failed for ${args.recipientAddress} using account '${args.account.name}' (address=${args.account.address}) against exchange ${args.exchange.objectId}.`, { cause })))).digest };
-})).pipe(Effect.withSpan("devstack.plugin.walrus.fundWal", { attributes: {
-	"walrus.fund.account": args.account.name,
-	"walrus.fund.address": args.recipientAddress,
-	"walrus.fund.exchange": args.exchange.objectId
+}).pipe(Effect.withSpan("devstack.plugin.walrus.fundWal", { attributes: {
+	[WalrusSpans.fundAccount]: args.account.name,
+	[WalrusSpans.fundAddress]: args.recipientAddress,
+	[WalrusSpans.fundExchange]: args.exchange.objectId
 } }));
 //#endregion
 export { resolveWalExchange, swapAccountSuiForWal };

package/dist/plugins/walrus/wal-swap.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"wal-swap.mjs","names":[],"sources":["../../../src/plugins/walrus/wal-swap.ts"],"sourcesContent":["import { Effect, Schema } from 'effect';\nimport { Transaction } from '@mysten/sui/transactions';\n\nimport type { ChainProbe } from '../../contracts/chain-probe.ts';\nimport type { AccountValue } from '../account/index.ts';\nimport { walrusPluginError, type WalrusPluginError } from './errors.ts';\n\nexport interface WalExchangeHandle {\n\treadonly objectId: string;\n\treadonly packageId: string;\n}\n\nexport type WalExchangeProbeKey = { readonly kind: 'object'; readonly objectId: string };\n\nexport interface WalSwapSdk {\n\treadonly client: unknown;\n}\n\nexport interface WalAccountSwapRequest {\n\treadonly account: AccountValue;\n\treadonly sdk: WalSwapSdk;\n\treadonly exchange: WalExchangeHandle;\n\treadonly recipientAddress: string;\n\treadonly paymentMist: bigint;\n}\n\nconst WalExchangeObjectShape = Schema.Struct({\n\tobjectId: Schema.String,\n\ttype: Schema.String,\n});\n\nexport const resolveWalExchange = (\n\tprobe: ChainProbe<WalExchangeProbeKey>,\n\texchangeObjectId: string | undefined,\n): Effect.Effect<WalExchangeHandle | null, WalrusPluginError> =>\n\tEffect.gen(function* () {\n\t\tif (exchangeObjectId === undefined) return null;\n\t\tconst found = yield* probe\n\t\t\t.get({ kind: 'object', objectId: exchangeObjectId }, WalExchangeObjectShape, 'lenient')\n\t\t\t.pipe(\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t'exchange',\n\t\t\t\t\t\t`walrus.exchange: failed to resolve exchange object ${exchangeObjectId}: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t{ cause },\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\tif (found === null) return null;\n\t\tconst packageId = found.type.split('::')[0];\n\t\tif (packageId === undefined || !packageId.startsWith('0x')) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'exchange',\n\t\t\t\t\t`walrus.exchange: unexpected exchange object type \"${found.type}\" — expected \"<pkg>::wal_exchange::Exchange\"`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\treturn { objectId: exchangeObjectId, packageId };\n\t});\n\nexport const buildWalSwapTransaction = (args: {\n\treadonly signerAddress: string;\n\treadonly recipientAddress: string;\n\treadonly exchange: WalExchangeHandle;\n\treadonly paymentMist: bigint;\n}): Transaction => {\n\tconst tx = new Transaction();\n\ttx.setSender(args.signerAddress);\n\tconst paymentCoin = tx.coin({\n\t\tbalance: args.paymentMist,\n\t\ttype: '0x2::sui::SUI',\n\t\tuseGasCoin: true,\n\t});\n\tconst walCoin = tx.moveCall({\n\t\ttarget: `${args.exchange.packageId}::wal_exchange::exchange_all_for_wal`,\n\t\targuments: [tx.object(args.exchange.objectId), paymentCoin],\n\t});\n\ttx.transferObjects([walCoin], tx.pure.address(args.recipientAddress));\n\treturn tx;\n};\n\ntype TransactionBuildClient = Parameters<Transaction['build']>[0] extends\n\t| { readonly client?: infer Client }\n\t| undefined\n\t? Client\n\t: never;\n\nexport const swapAccountSuiForWal = (\n\targs: WalAccountSwapRequest,\n): Effect.Effect<{ readonly digest: string }, WalrusPluginError> =>\n\targs.account\n\t\t.withTransactionSigner((lockedSigner) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst tx = buildWalSwapTransaction({\n\t\t\t\t\tsignerAddress: args.account.address,\n\t\t\t\t\trecipientAddress: args.recipientAddress,\n\t\t\t\t\texchange: args.exchange,\n\t\t\t\t\tpaymentMist: args.paymentMist,\n\t\t\t\t});\n\t\t\t\tconst txBytes = yield* Effect.tryPromise({\n\t\t\t\t\ttry: () =>\n\t\t\t\t\t\ttx.build({\n\t\t\t\t\t\t\tclient: args.sdk.client as TransactionBuildClient,\n\t\t\t\t\t\t}),\n\t\t\t\t\tcatch: (cause): WalrusPluginError =>\n\t\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t\t'fund-wal',\n\t\t\t\t\t\t\t`walrus.fundWal: transaction serialization failed for account '${args.account.name}'.`,\n\t\t\t\t\t\t\t{ cause },\n\t\t\t\t\t\t),\n\t\t\t\t});\n\t\t\t\tconst receipt = yield* lockedSigner\n\t\t\t\t\t.signAndExecute(txBytes)\n\t\t\t\t\t.pipe(\n\t\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t\t(cause): WalrusPluginError =>\n\t\t\t\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t\t\t\t'fund-wal',\n\t\t\t\t\t\t\t\t\t`walrus.fundWal: SUI -> WAL swap failed for ${args.recipientAddress} ` +\n\t\t\t\t\t\t\t\t\t\t`using account '${args.account.name}' (address=${args.account.address}) ` +\n\t\t\t\t\t\t\t\t\t\t`against exchange ${args.exchange.objectId}.`,\n\t\t\t\t\t\t\t\t\t{ cause },\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\treturn { digest: receipt.digest };\n\t\t\t}),\n\t\t)\n\t\t.pipe(\n\t\t\tEffect.withSpan('devstack.plugin.walrus.fundWal', {\n\t\t\t\tattributes: {\n\t\t\t\t\t'walrus.fund.account': args.account.name,\n\t\t\t\t\t'walrus.fund.address': args.recipientAddress,\n\t\t\t\t\t'walrus.fund.exchange': args.exchange.objectId,\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n"],"mappings":";;;;AA0BA,MAAM,yBAAyB,OAAO,OAAO;CAC5C,UAAU,OAAO;CACjB,MAAM,OAAO;CACb,CAAC;AAEF,MAAa,sBACZ,OACA,qBAEA,OAAO,IAAI,aAAa;AACvB,KAAI,qBAAqB,KAAA,EAAW,QAAO;CAC3C,MAAM,QAAQ,OAAO,MACnB,IAAI;EAAE,MAAM;EAAU,UAAU;EAAkB,EAAE,wBAAwB,UAAU,CACtF,KACA,OAAO,UAAU,UAChB,kBACC,YACA,sDAAsD,iBAAiB,IAAI,MAAM,OAAO,IAAI,MAAM,UAClG,EAAE,OAAO,CACT,CACD,CACD;AACF,KAAI,UAAU,KAAM,QAAO;CAC3B,MAAM,YAAY,MAAM,KAAK,MAAM,KAAK,CAAC;AACzC,KAAI,cAAc,KAAA,KAAa,CAAC,UAAU,WAAW,KAAK,CACzD,QAAO,OAAO,OAAO,KACpB,kBACC,YACA,qDAAqD,MAAM,KAAK,8CAChE,CACD;AAEF,QAAO;EAAE,UAAU;EAAkB;EAAW;EAC/C;AAEH,MAAa,2BAA2B,SAKrB;CAClB,MAAM,KAAK,IAAI,aAAa;AAC5B,IAAG,UAAU,KAAK,cAAc;CAChC,MAAM,cAAc,GAAG,KAAK;EAC3B,SAAS,KAAK;EACd,MAAM;EACN,YAAY;EACZ,CAAC;CACF,MAAM,UAAU,GAAG,SAAS;EAC3B,QAAQ,GAAG,KAAK,SAAS,UAAU;EACnC,WAAW,CAAC,GAAG,OAAO,KAAK,SAAS,SAAS,EAAE,YAAY;EAC3D,CAAC;AACF,IAAG,gBAAgB,CAAC,QAAQ,EAAE,GAAG,KAAK,QAAQ,KAAK,iBAAiB,CAAC;AACrE,QAAO;;AASR,MAAa,wBACZ,SAEA,KAAK,QACH,uBAAuB,iBACvB,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,wBAAwB;EAClC,eAAe,KAAK,QAAQ;EAC5B,kBAAkB,KAAK;EACvB,UAAU,KAAK;EACf,aAAa,KAAK;EAClB,CAAC;CACF,MAAM,UAAU,OAAO,OAAO,WAAW;EACxC,WACC,GAAG,MAAM,EACR,QAAQ,KAAK,IAAI,QACjB,CAAC;EACH,QAAQ,UACP,kBACC,YACA,iEAAiE,KAAK,QAAQ,KAAK,KACnF,EAAE,OAAO,CACT;EACF,CAAC;AAeF,QAAO,EAAE,SAAQ,OAdM,aACrB,eAAe,QAAQ,CACvB,KACA,OAAO,UACL,UACA,kBACC,YACA,8CAA8C,KAAK,iBAAiB,kBACjD,KAAK,QAAQ,KAAK,aAAa,KAAK,QAAQ,QAAQ,qBAClD,KAAK,SAAS,SAAS,IAC5C,EAAE,OAAO,CACT,CACF,CACD,EACuB,QAAQ;EAChC,CACF,CACA,KACA,OAAO,SAAS,kCAAkC,EACjD,YAAY;CACX,uBAAuB,KAAK,QAAQ;CACpC,uBAAuB,KAAK;CAC5B,wBAAwB,KAAK,SAAS;CACtC,EACD,CAAC,CACF"}
+{"version":3,"file":"wal-swap.mjs","names":[],"sources":["../../../src/plugins/walrus/wal-swap.ts"],"sourcesContent":["import { Effect, Schema } from 'effect';\nimport { Transaction } from '@mysten/sui/transactions';\n\nimport type { ChainProbe } from '../../contracts/chain-probe.ts';\nimport { formatExecutedFailure } from '../../substrate/runtime/sui-execute/index.ts';\nimport { signAndDispatch } from '../../substrate/runtime/sui-execute/sign-and-dispatch.ts';\nimport type { AccountValue } from '../account/index.ts';\nimport type { SuiSdkShim } from '../sui/index.ts';\nimport { SUI_FULL_COIN_TYPE } from '../account/index.ts';\nimport { walrusPluginError, type WalrusPluginError } from './errors.ts';\nimport { WalrusSpans } from './spans.ts';\n\n/** Conservative reserve held back from the gas coin for transaction\n *  gas itself. The swap call splits `paymentMist` off the gas coin\n *  via `tx.coin({ useGasCoin: true })`, so the on-chain balance must\n *  cover BOTH the payment AND a gas budget reserve. The exact gas\n *  budget is set by the SDK at build time; this reserve is a coarse\n *  upper bound used only by the pre-flight refusal — if the wire\n *  call proves the reserve is too small the SDK still surfaces the\n *  native `InsufficientGas` cause with the real numbers. */\nconst WAL_SWAP_GAS_RESERVE_MIST = 50_000_000n;\n\nexport interface WalExchangeHandle {\n\treadonly objectId: string;\n\treadonly packageId: string;\n}\n\nexport type WalExchangeProbeKey = { readonly kind: 'object'; readonly objectId: string };\n\nexport type WalSwapSdk = Pick<SuiSdkShim, 'client'> & {\n\treadonly core: Pick<SuiSdkShim['core'], 'getBalance'>;\n};\n\n/** Read the account's SUI balance (best-effort). Returns `null` if the\n *  RPC throws or the response shape is unexpected — the pre-flight is\n *  a hint, not a hard gate. */\nconst readSuiBalance = (\n\tsdk: WalSwapSdk,\n\towner: string,\n): Effect.Effect<bigint | null, never> =>\n\tEffect.promise(async () => {\n\t\ttry {\n\t\t\tconst response = await sdk.core.getBalance({ owner, coinType: SUI_FULL_COIN_TYPE });\n\t\t\tconst outer =\n\t\t\t\ttypeof response === 'object' && response !== null && 'balance' in response\n\t\t\t\t\t? (response as { readonly balance?: unknown }).balance\n\t\t\t\t\t: response;\n\t\t\tconst value =\n\t\t\t\ttypeof outer === 'object' && outer !== null && 'balance' in outer\n\t\t\t\t\t? (outer as { readonly balance?: unknown }).balance\n\t\t\t\t\t: outer;\n\t\t\tif (typeof value === 'bigint') return value;\n\t\t\tif (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)\n\t\t\t\treturn BigInt(value);\n\t\t\tif (typeof value === 'string' && /^\\d+$/.test(value)) return BigInt(value);\n\t\t\treturn null;\n\t\t} catch {\n\t\t\treturn null;\n\t\t}\n\t});\n\nexport interface WalAccountSwapRequest {\n\treadonly account: AccountValue;\n\treadonly sdk: WalSwapSdk;\n\treadonly exchange: WalExchangeHandle;\n\treadonly recipientAddress: string;\n\treadonly paymentMist: bigint;\n}\n\nconst WalExchangeObjectShape = Schema.Struct({\n\tobjectId: Schema.String,\n\ttype: Schema.String,\n});\n\nexport const resolveWalExchange = (\n\tprobe: ChainProbe<WalExchangeProbeKey>,\n\texchangeObjectId: string | undefined,\n): Effect.Effect<WalExchangeHandle | null, WalrusPluginError> =>\n\tEffect.gen(function* () {\n\t\tif (exchangeObjectId === undefined) return null;\n\t\tconst found = yield* probe\n\t\t\t.get({ kind: 'object', objectId: exchangeObjectId }, WalExchangeObjectShape, 'lenient')\n\t\t\t.pipe(\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t'exchange',\n\t\t\t\t\t\t`walrus.exchange: failed to resolve exchange object ${exchangeObjectId}: ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t{ cause },\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\tif (found === null) return null;\n\t\tconst packageId = found.type.split('::')[0];\n\t\tif (packageId === undefined || !packageId.startsWith('0x')) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'exchange',\n\t\t\t\t\t`walrus.exchange: unexpected exchange object type \"${found.type}\" — expected \"<pkg>::wal_exchange::Exchange\"`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\treturn { objectId: exchangeObjectId, packageId };\n\t});\n\nexport const buildWalSwapTransaction = (args: {\n\treadonly signerAddress: string;\n\treadonly recipientAddress: string;\n\treadonly exchange: WalExchangeHandle;\n\treadonly paymentMist: bigint;\n}): Transaction => {\n\tconst tx = new Transaction();\n\ttx.setSender(args.signerAddress);\n\tconst paymentCoin = tx.coin({\n\t\tbalance: args.paymentMist,\n\t\ttype: '0x2::sui::SUI',\n\t\tuseGasCoin: true,\n\t});\n\tconst walCoin = tx.moveCall({\n\t\ttarget: `${args.exchange.packageId}::wal_exchange::exchange_all_for_wal`,\n\t\targuments: [tx.object(args.exchange.objectId), paymentCoin],\n\t});\n\ttx.transferObjects([walCoin], tx.pure.address(args.recipientAddress));\n\treturn tx;\n};\n\nexport const swapAccountSuiForWal = (\n\targs: WalAccountSwapRequest,\n): Effect.Effect<{ readonly digest: string }, WalrusPluginError> =>\n\tEffect.gen(function* () {\n\t\t// Pre-flight gas-budget refusal — the swap splits `paymentMist`\n\t\t// off the gas coin via `tx.coin({ useGasCoin: true })`, so the\n\t\t// on-chain SUI balance must cover BOTH the payment AND a gas\n\t\t// reserve. Without this check the failure surfaces as an opaque\n\t\t// `Transaction.build` / chain-side `InsufficientGas` after the\n\t\t// wire call has already been attempted; the typed refusal here\n\t\t// names the numbers so the caller sees the real cause. The\n\t\t// balance read is best-effort — a `null` from the SDK falls\n\t\t// through to the wire call (the existing `mapSignError` /\n\t\t// `onFailed` paths still catch the chain-side failure).\n\t\tconst suiBalance = yield* readSuiBalance(args.sdk, args.account.address);\n\t\tconst required = args.paymentMist + WAL_SWAP_GAS_RESERVE_MIST;\n\t\tif (suiBalance !== null && suiBalance < required) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'fund-wal',\n\t\t\t\t\t`walrus.fundWal: account '${args.account.name}' (address=${args.account.address}) ` +\n\t\t\t\t\t\t`has insufficient SUI to swap ${args.paymentMist} for WAL — ` +\n\t\t\t\t\t\t`balance=${suiBalance} mist, required≥${required} mist ` +\n\t\t\t\t\t\t`(payment=${args.paymentMist} + gas reserve=${WAL_SWAP_GAS_RESERVE_MIST}). ` +\n\t\t\t\t\t\t`Top up the account's SUI funding before declaring the WAL funding entry.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\treturn yield* signAndDispatch({\n\t\t\tsignerSource: args.account,\n\t\t\tbuildTxBytes: () =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst tx = buildWalSwapTransaction({\n\t\t\t\t\t\tsignerAddress: args.account.address,\n\t\t\t\t\t\trecipientAddress: args.recipientAddress,\n\t\t\t\t\t\texchange: args.exchange,\n\t\t\t\t\t\tpaymentMist: args.paymentMist,\n\t\t\t\t\t});\n\t\t\t\t\treturn yield* Effect.tryPromise({\n\t\t\t\t\t\ttry: () => tx.build({ client: args.sdk.client }),\n\t\t\t\t\t\tcatch: (cause): WalrusPluginError =>\n\t\t\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t\t\t'fund-wal',\n\t\t\t\t\t\t\t\t`walrus.fundWal: transaction serialization failed for account '${args.account.name}'.`,\n\t\t\t\t\t\t\t\t{ cause },\n\t\t\t\t\t\t\t),\n\t\t\t\t\t});\n\t\t\t\t}),\n\t\t\tmapSignError: (cause): WalrusPluginError =>\n\t\t\t\twalrusPluginError(\n\t\t\t\t\t'fund-wal',\n\t\t\t\t\t`walrus.fundWal: SUI -> WAL swap failed for ${args.recipientAddress} ` +\n\t\t\t\t\t\t`using account '${args.account.name}' (address=${args.account.address}) ` +\n\t\t\t\t\t\t`against exchange ${args.exchange.objectId}.`,\n\t\t\t\t\t{ cause },\n\t\t\t\t),\n\t\t\tonFailed: (failure) =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t'fund-wal',\n\t\t\t\t\t\t`walrus.fundWal: SUI -> WAL swap failed on-chain ` +\n\t\t\t\t\t\t\t`(exchange=${args.exchange.objectId}) ` +\n\t\t\t\t\t\t\tformatExecutedFailure(failure),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\tonSuccess: (ok) => Effect.succeed({ digest: ok.digest }),\n\t\t});\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.walrus.fundWal', {\n\t\t\tattributes: {\n\t\t\t\t[WalrusSpans.fundAccount]: args.account.name,\n\t\t\t\t[WalrusSpans.fundAddress]: args.recipientAddress,\n\t\t\t\t[WalrusSpans.fundExchange]: args.exchange.objectId,\n\t\t\t},\n\t\t}),\n\t);\n"],"mappings":"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"}

package/dist/primitives/artifact-publisher.d.mts

@@ -1,4 +1,4 @@
-import { Effect, Schema, Scope } from "effect";
+import { Effect, Scope } from "effect";
 
 //#region src/primitives/artifact-publisher.d.ts
 /** Tagged error from a publish round. */

package/dist/primitives/artifact-publisher.mjs

@@ -0,0 +1,15 @@
+//#region src/primitives/artifact-publisher.ts
+/** Constructor for `ArtifactPublishError`. Centralising the literal
+*  shape (single `_tag` site, no `as const` ceremony at call sites)
+*  per STYLE_GUIDE §2: tagged errors expose a factory at every
+*  plugin/public boundary. Every plugin's `produce` /
+*  `Effect.mapError` path goes through this. */
+const artifactPublishError = (reason, detail) => ({
+	_tag: "ArtifactPublishError",
+	reason,
+	detail
+});
+//#endregion
+export { artifactPublishError };
+
+//# sourceMappingURL=artifact-publisher.mjs.map

package/dist/primitives/artifact-publisher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-publisher.mjs","names":[],"sources":["../../src/primitives/artifact-publisher.ts"],"sourcesContent":["// ArtifactPublisher — L0 substrate primitive (architecture §10).\n//\n// Unifies the discipline that recurs across many on-chain\n// produce/verify plugins (substrate must remain service-name-blind;\n// the plugin index is the authoritative list). cache → verify →\n// produce → register on EVERY cycle.\n//\n// This is callable from any plugin; there is NO plugin-side contract\n// to implement. Plugins pass in:\n//\n//   - a namespace + cache-key derivation,\n//   - a verify procedure (calls ChainProbe with a typed Schema,\n//     lenient mode),\n//   - a produce procedure (run on miss / verify-fail),\n//   - a register procedure (fires on EVERY cycle — hit AND miss).\n\nimport type { Effect, Scope } from 'effect';\n\nimport type { ChainId, ContentHash } from '../substrate/brand.ts';\n\n/** Lenient retry profile constants — shared with ChainProbe.\n *  Architecture: 15 attempts, 90s budget, 500ms initial, 1.5×\n *  backoff, [0.8, 1.2) jitter. */\nexport const LENIENT_RETRY_PROFILE = {\n\tattempts: 15,\n\ttotalBudgetMillis: 90_000,\n\tinitialMillis: 500,\n\tbackoffMultiplier: 1.5,\n\tjitterRange: [0.8, 1.2] as const,\n} as const;\n\n/** Input contract for ArtifactPublisher.publish. */\nexport interface ArtifactSpec<Produced, Verified> {\n\t/** Cache namespace — plugin-chosen, e.g. `package`. */\n\treadonly namespace: string;\n\t/** Chain identity — substrate folds into the cache key. */\n\treadonly chain: ChainId;\n\t/** Content-hash of canonical input bytes. */\n\treadonly contentHash: ContentHash;\n\t/** Verify probe — typed Schema; lenient mode. Returns null on\n\t *  not-found OR transient failure.\n\t *\n\t *  The substrate decodes the cached payload (if any) and passes it\n\t *  in as `cached`. Plugins that key their on-chain probe off a\n\t *  field of the cached payload (e.g. action's `digest`, package's\n\t *  `packageId`) read it from here directly — no in-process\n\t *  registry-hop required. Plugins that don't care about the\n\t *  cached payload ignore the parameter.\n\t *\n\t *  When the cache is empty (cold boot) OR decode failed\n\t *  (corruption) the substrate short-circuits to \"miss\" before\n\t *  invoking this; callers can therefore assume `cached` is\n\t *  defined on every call. */\n\treadonly verify: (cached: Produced) => Effect.Effect<Verified | null, never>;\n\t/** Produce procedure — runs on cache miss OR verify-fail. */\n\treadonly produce: Effect.Effect<Produced, ArtifactPublishError, Scope.Scope>;\n\t/** Register procedure — fires on EVERY cycle (hit AND miss). The\n\t *  substrate always hands back the decoded `Produced` payload (on\n\t *  cache hit) or the freshly produced one (on miss); the verify\n\t *  shape is a probe-only signal, never surfaced to callers. */\n\treadonly register: (artifact: Produced) => Effect.Effect<void, never>;\n}\n\n/** Tagged error from a publish round. */\nexport interface ArtifactPublishError {\n\treadonly _tag: 'ArtifactPublishError';\n\treadonly reason: 'produce-failed' | 'verify-exhausted' | 'cache-corrupt';\n\treadonly detail: string;\n}\n\n/** Constructor for `ArtifactPublishError`. Centralising the literal\n *  shape (single `_tag` site, no `as const` ceremony at call sites)\n *  per STYLE_GUIDE §2: tagged errors expose a factory at every\n *  plugin/public boundary. Every plugin's `produce` /\n *  `Effect.mapError` path goes through this. */\nexport const artifactPublishError = (\n\treason: ArtifactPublishError['reason'],\n\tdetail: string,\n): ArtifactPublishError => ({\n\t_tag: 'ArtifactPublishError',\n\treason,\n\tdetail,\n});\n\n/** The publisher service. Plugins call `publish`; substrate handles\n *  cache lookup, verify, produce-on-miss, idempotent register.\n *\n *  Returns the `Produced` payload on EVERY path:\n *  - cache hit + verify succeeds → the decoded cached `Produced`,\n *  - cache miss or verify-fail → the freshly produced `Produced`.\n *\n *  The `Verified` shape is a probe-only signal (drives the lenient\n *  null/non-null decision inside the substrate); it is never returned\n *  to plugin callers. Callers therefore type-narrow trivially against\n *  `Produced` and avoid the `'<sentinel>'` projection dance. */\nexport interface ArtifactPublisher {\n\treadonly publish: <Produced, Verified>(\n\t\tspec: ArtifactSpec<Produced, Verified>,\n\t) => Effect.Effect<Produced, ArtifactPublishError, Scope.Scope>;\n}\n"],"mappings":";;;;;;AA2EA,MAAa,wBACZ,QACA,YAC2B;CAC3B,MAAM;CACN;CACA;CACA"}

package/dist/runtime/docker/client.mjs

@@ -2,20 +2,32 @@ import { capture } from "../../substrate/runtime/observability/subprocess-captur
 import { Context, Effect, Layer } from "effect";
 import { ChildProcess } from "effect/unstable/process";
 //#region src/runtime/docker/client.ts
-var DockerHost = class extends Context.Service()("@devstack-rewrite/runtime-docker/DockerHost") {};
+var DockerHost = class extends Context.Service()("@devstack/runtime-docker/DockerHost") {};
 const layerDockerHostDefault = Layer.succeed(DockerHost)({});
 /** A spawner service exposing `spawn`. Held as a service so tests can
 *  inject a stub. In production this is `ChildProcessSpawner.make()`
 *  from `effect/unstable/process` (provided via `@effect/platform-node`). */
-var DockerSpawner = class extends Context.Service()("@devstack-rewrite/runtime-docker/DockerSpawner") {};
+var DockerSpawner = class extends Context.Service()("@devstack/runtime-docker/DockerSpawner") {};
 const buildEnv = (host) => {
 	const env = {};
 	if (host.dockerHost !== void 0) env.DOCKER_HOST = host.dockerHost;
 	return env;
 };
+/** Grace period between the scope-close SIGTERM and the escalation
+*  SIGKILL. Without `forceKillAfter` the Node spawner sends ONE SIGTERM
+*  on scope close and then waits indefinitely for the child to die — so
+*  a timeout-interrupt (see `exec.ts` / `dockerRunOneShot` `Effect.timeout`)
+*  blocks on scope-close if the docker CLI ignores SIGTERM. A few
+*  seconds lets a well-behaved CLI flush and exit cleanly before we
+*  force-kill the wedged case. */
+const KILL_GRACE = "5 seconds";
 /** Build a `ChildProcess.Command` from `(verb, ...args)`. The verb is
 *  separate so observability span attributes can pin the
-*  high-cardinality `args` separately from the `devstack.op` tag. */
+*  high-cardinality `args` separately from the `devstack.op` tag.
+*
+*  `forceKillAfter` makes scope-close termination escalate
+*  SIGTERM→SIGKILL so an interrupt (timeout) can't wedge on a docker CLI
+*  that ignores SIGTERM. */
 const dockerCommand = (host, verb, args, overrideEnv = {}) => {
 	const bin = host.bin ?? "docker";
 	const env = {
@@ -24,7 +36,8 @@ const dockerCommand = (host, verb, args, overrideEnv = {}) => {
 	};
 	return ChildProcess.make(bin, [verb, ...args], {
 		env,
-		extendEnv: true
+		extendEnv: true,
+		forceKillAfter: KILL_GRACE
 	});
 };
 /** Capture a docker invocation, fail on non-zero exit. Use when any

package/dist/runtime/docker/client.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"client.mjs","names":[],"sources":["../../../src/runtime/docker/client.ts"],"sourcesContent":["// Thin `docker` CLI wrapper.\n//\n// Every subprocess invocation flows through the L0 subprocess-capture\n// primitive (one capture function, one error class). This module owns:\n//\n//   - The argv constructor (`dockerArgv`).\n//   - The `DOCKER_HOST` env passthrough (architecture §7: one-daemon\n//     assumption, env override supported).\n//   - Two convenience verbs: `run` (capture-with-success-or-fail-by-exit)\n//     and `runOk` (capture, return CaptureResult regardless of exit so\n//     the caller can classify stderr). NO docker compose anywhere.\n//\n// No service names appear here. No stderr-pattern classification —\n// that's in `wrap.ts`. This file is mechanical argv + spawn.\n\nimport { Context, Effect, Layer } from 'effect';\nimport { ChildProcess } from 'effect/unstable/process';\nimport { ChildProcessSpawner } from 'effect/unstable/process';\n\nimport {\n\tcapture,\n\ttype CaptureError,\n\ttype CaptureOptions,\n\ttype CaptureResult,\n} from '../../substrate/runtime/observability/subprocess-capture.ts';\n\n// -----------------------------------------------------------------------------\n// Daemon-host configuration\n// -----------------------------------------------------------------------------\n\n/** Optional `DOCKER_HOST` override. When absent we let the docker CLI\n *  resolve its default socket (Unix: `/var/run/docker.sock`; macOS\n *  Desktop: `unix:///var/run/docker.sock`; remote daemon if the user\n *  set `DOCKER_HOST` in their own env). */\nexport interface DockerHostShape {\n\treadonly dockerHost?: string;\n\t/** Optional explicit binary path (default `docker`). Tests use\n\t *  this to point at a stub; otherwise we resolve via PATH. */\n\treadonly bin?: string;\n}\n\nexport class DockerHost extends Context.Service<DockerHost, DockerHostShape>()(\n\t'@devstack-rewrite/runtime-docker/DockerHost',\n) {}\n\nexport const layerDockerHostDefault: Layer.Layer<DockerHost> = Layer.succeed(DockerHost)({});\n\nexport const layerDockerHost = (shape: DockerHostShape): Layer.Layer<DockerHost> =>\n\tLayer.succeed(DockerHost)(shape);\n\n// -----------------------------------------------------------------------------\n// Spawner injection\n// -----------------------------------------------------------------------------\n\n/** A spawner service exposing `spawn`. Held as a service so tests can\n *  inject a stub. In production this is `ChildProcessSpawner.make()`\n *  from `effect/unstable/process` (provided via `@effect/platform-node`). */\nexport class DockerSpawner extends Context.Service<\n\tDockerSpawner,\n\tReturnType<typeof ChildProcessSpawner.make>\n>()('@devstack-rewrite/runtime-docker/DockerSpawner') {}\n\n// -----------------------------------------------------------------------------\n// Argv construction\n// -----------------------------------------------------------------------------\n\nconst buildEnv = (host: DockerHostShape): Record<string, string> => {\n\tconst env: Record<string, string> = {};\n\tif (host.dockerHost !== undefined) env.DOCKER_HOST = host.dockerHost;\n\treturn env;\n};\n\n/** Build a `ChildProcess.Command` from `(verb, ...args)`. The verb is\n *  separate so observability span attributes can pin the\n *  high-cardinality `args` separately from the `devstack.op` tag. */\nexport const dockerCommand = (\n\thost: DockerHostShape,\n\tverb: string,\n\targs: ReadonlyArray<string>,\n\toverrideEnv: Readonly<Record<string, string>> = {},\n): ChildProcess.Command => {\n\tconst bin = host.bin ?? 'docker';\n\tconst env = { ...buildEnv(host), ...overrideEnv };\n\treturn ChildProcess.make(bin, [verb, ...args], { env, extendEnv: true });\n};\n\n// -----------------------------------------------------------------------------\n// Capture verbs\n// -----------------------------------------------------------------------------\n\n/** Capture a docker invocation, fail on non-zero exit. Use when any\n *  non-zero exit is a failure case (most write operations). */\nexport const dockerRun = (\n\tverb: string,\n\targs: ReadonlyArray<string>,\n\topts?: Omit<CaptureOptions, 'op' | 'nonZeroIsFailure'>,\n): Effect.Effect<CaptureResult, CaptureError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst host = yield* DockerHost;\n\t\tconst spawner = yield* DockerSpawner;\n\t\treturn yield* capture(spawner, dockerCommand(host, verb, args), {\n\t\t\t...opts,\n\t\t\top: `docker.${verb}`,\n\t\t\tnonZeroIsFailure: true,\n\t\t});\n\t});\n\n/** Capture a docker invocation, return the `CaptureResult` regardless\n *  of exit. Use when the caller classifies stderr or wants the exit\n *  code (lifecycle state machine, inventory). */\nexport const dockerRunOk = (\n\tverb: string,\n\targs: ReadonlyArray<string>,\n\topts?: Omit<CaptureOptions, 'op' | 'nonZeroIsFailure'>,\n): Effect.Effect<CaptureResult, CaptureError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst host = yield* DockerHost;\n\t\tconst spawner = yield* DockerSpawner;\n\t\treturn yield* capture(spawner, dockerCommand(host, verb, args), {\n\t\t\t...opts,\n\t\t\top: `docker.${verb}`,\n\t\t\tnonZeroIsFailure: false,\n\t\t});\n\t});\n"],"mappings":";;;;AAyCA,IAAa,aAAb,cAAgC,QAAQ,SAAsC,CAC7E,8CACA,CAAC;AAEF,MAAa,yBAAkD,MAAM,QAAQ,WAAW,CAAC,EAAE,CAAC;;;;AAY5F,IAAa,gBAAb,cAAmC,QAAQ,SAGxC,CAAC,iDAAiD,CAAC;AAMtD,MAAM,YAAY,SAAkD;CACnE,MAAM,MAA8B,EAAE;AACtC,KAAI,KAAK,eAAe,KAAA,EAAW,KAAI,cAAc,KAAK;AAC1D,QAAO;;;;;AAMR,MAAa,iBACZ,MACA,MACA,MACA,cAAgD,EAAE,KACxB;CAC1B,MAAM,MAAM,KAAK,OAAO;CACxB,MAAM,MAAM;EAAE,GAAG,SAAS,KAAK;EAAE,GAAG;EAAa;AACjD,QAAO,aAAa,KAAK,KAAK,CAAC,MAAM,GAAG,KAAK,EAAE;EAAE;EAAK,WAAW;EAAM,CAAC;;;;AASzE,MAAa,aACZ,MACA,MACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;AAEpB,QAAO,OAAO,QAAQ,OADC,eACQ,cAAc,MAAM,MAAM,KAAK,EAAE;EAC/D,GAAG;EACH,IAAI,UAAU;EACd,kBAAkB;EAClB,CAAC;EACD;;;;AAKH,MAAa,eACZ,MACA,MACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;AAEpB,QAAO,OAAO,QAAQ,OADC,eACQ,cAAc,MAAM,MAAM,KAAK,EAAE;EAC/D,GAAG;EACH,IAAI,UAAU;EACd,kBAAkB;EAClB,CAAC;EACD"}
+{"version":3,"file":"client.mjs","names":[],"sources":["../../../src/runtime/docker/client.ts"],"sourcesContent":["// Thin `docker` CLI wrapper.\n//\n// Every subprocess invocation flows through the L0 subprocess-capture\n// primitive (one capture function, one error class). This module owns:\n//\n//   - The argv constructor (`dockerArgv`).\n//   - The `DOCKER_HOST` env passthrough (architecture §7: one-daemon\n//     assumption, env override supported).\n//   - Two convenience verbs: `run` (capture-with-success-or-fail-by-exit)\n//     and `runOk` (capture, return CaptureResult regardless of exit so\n//     the caller can classify stderr). NO docker compose anywhere.\n//\n// No service names appear here. No stderr-pattern classification —\n// that's in `wrap.ts`. This file is mechanical argv + spawn.\n\nimport { Context, Effect, Layer } from 'effect';\nimport { ChildProcess } from 'effect/unstable/process';\nimport { ChildProcessSpawner } from 'effect/unstable/process';\n\nimport {\n\tcapture,\n\ttype CaptureError,\n\ttype CaptureOptions,\n\ttype CaptureResult,\n} from '../../substrate/runtime/observability/subprocess-capture.ts';\n\n// -----------------------------------------------------------------------------\n// Daemon-host configuration\n// -----------------------------------------------------------------------------\n\n/** Optional `DOCKER_HOST` override. When absent we let the docker CLI\n *  resolve its default socket (Unix: `/var/run/docker.sock`; macOS\n *  Desktop: `unix:///var/run/docker.sock`; remote daemon if the user\n *  set `DOCKER_HOST` in their own env). */\nexport interface DockerHostShape {\n\treadonly dockerHost?: string;\n\t/** Optional explicit binary path (default `docker`). Tests use\n\t *  this to point at a stub; otherwise we resolve via PATH. */\n\treadonly bin?: string;\n}\n\nexport class DockerHost extends Context.Service<DockerHost, DockerHostShape>()(\n\t'@devstack/runtime-docker/DockerHost',\n) {}\n\nexport const layerDockerHostDefault: Layer.Layer<DockerHost> = Layer.succeed(DockerHost)({});\n\nexport const layerDockerHost = (shape: DockerHostShape): Layer.Layer<DockerHost> =>\n\tLayer.succeed(DockerHost)(shape);\n\n// -----------------------------------------------------------------------------\n// Spawner injection\n// -----------------------------------------------------------------------------\n\n/** A spawner service exposing `spawn`. Held as a service so tests can\n *  inject a stub. In production this is `ChildProcessSpawner.make()`\n *  from `effect/unstable/process` (provided via `@effect/platform-node`). */\nexport class DockerSpawner extends Context.Service<\n\tDockerSpawner,\n\tReturnType<typeof ChildProcessSpawner.make>\n>()('@devstack/runtime-docker/DockerSpawner') {}\n\n// -----------------------------------------------------------------------------\n// Argv construction\n// -----------------------------------------------------------------------------\n\nconst buildEnv = (host: DockerHostShape): Record<string, string> => {\n\tconst env: Record<string, string> = {};\n\tif (host.dockerHost !== undefined) env.DOCKER_HOST = host.dockerHost;\n\treturn env;\n};\n\n/** Grace period between the scope-close SIGTERM and the escalation\n *  SIGKILL. Without `forceKillAfter` the Node spawner sends ONE SIGTERM\n *  on scope close and then waits indefinitely for the child to die — so\n *  a timeout-interrupt (see `exec.ts` / `dockerRunOneShot` `Effect.timeout`)\n *  blocks on scope-close if the docker CLI ignores SIGTERM. A few\n *  seconds lets a well-behaved CLI flush and exit cleanly before we\n *  force-kill the wedged case. */\nconst KILL_GRACE = '5 seconds';\n\n/** Build a `ChildProcess.Command` from `(verb, ...args)`. The verb is\n *  separate so observability span attributes can pin the\n *  high-cardinality `args` separately from the `devstack.op` tag.\n *\n *  `forceKillAfter` makes scope-close termination escalate\n *  SIGTERM→SIGKILL so an interrupt (timeout) can't wedge on a docker CLI\n *  that ignores SIGTERM. */\nexport const dockerCommand = (\n\thost: DockerHostShape,\n\tverb: string,\n\targs: ReadonlyArray<string>,\n\toverrideEnv: Readonly<Record<string, string>> = {},\n): ChildProcess.Command => {\n\tconst bin = host.bin ?? 'docker';\n\tconst env = { ...buildEnv(host), ...overrideEnv };\n\treturn ChildProcess.make(bin, [verb, ...args], {\n\t\tenv,\n\t\textendEnv: true,\n\t\tforceKillAfter: KILL_GRACE,\n\t});\n};\n\n// -----------------------------------------------------------------------------\n// Capture verbs\n// -----------------------------------------------------------------------------\n\n/** Capture a docker invocation, fail on non-zero exit. Use when any\n *  non-zero exit is a failure case (most write operations). */\nexport const dockerRun = (\n\tverb: string,\n\targs: ReadonlyArray<string>,\n\topts?: Omit<CaptureOptions, 'op' | 'nonZeroIsFailure'>,\n): Effect.Effect<CaptureResult, CaptureError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst host = yield* DockerHost;\n\t\tconst spawner = yield* DockerSpawner;\n\t\treturn yield* capture(spawner, dockerCommand(host, verb, args), {\n\t\t\t...opts,\n\t\t\top: `docker.${verb}`,\n\t\t\tnonZeroIsFailure: true,\n\t\t});\n\t});\n\n/** Capture a docker invocation, return the `CaptureResult` regardless\n *  of exit. Use when the caller classifies stderr or wants the exit\n *  code (lifecycle state machine, inventory). */\nexport const dockerRunOk = (\n\tverb: string,\n\targs: ReadonlyArray<string>,\n\topts?: Omit<CaptureOptions, 'op' | 'nonZeroIsFailure'>,\n): Effect.Effect<CaptureResult, CaptureError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst host = yield* DockerHost;\n\t\tconst spawner = yield* DockerSpawner;\n\t\treturn yield* capture(spawner, dockerCommand(host, verb, args), {\n\t\t\t...opts,\n\t\t\top: `docker.${verb}`,\n\t\t\tnonZeroIsFailure: false,\n\t\t});\n\t});\n"],"mappings":";;;;AAyCA,IAAa,aAAb,cAAgC,QAAQ,SAAsC,CAC7E,sCACA,CAAC;AAEF,MAAa,yBAAkD,MAAM,QAAQ,WAAW,CAAC,EAAE,CAAC;;;;AAY5F,IAAa,gBAAb,cAAmC,QAAQ,SAGxC,CAAC,yCAAyC,CAAC;AAM9C,MAAM,YAAY,SAAkD;CACnE,MAAM,MAA8B,EAAE;AACtC,KAAI,KAAK,eAAe,KAAA,EAAW,KAAI,cAAc,KAAK;AAC1D,QAAO;;;;;;;;;AAUR,MAAM,aAAa;;;;;;;;AASnB,MAAa,iBACZ,MACA,MACA,MACA,cAAgD,EAAE,KACxB;CAC1B,MAAM,MAAM,KAAK,OAAO;CACxB,MAAM,MAAM;EAAE,GAAG,SAAS,KAAK;EAAE,GAAG;EAAa;AACjD,QAAO,aAAa,KAAK,KAAK,CAAC,MAAM,GAAG,KAAK,EAAE;EAC9C;EACA,WAAW;EACX,gBAAgB;EAChB,CAAC;;;;AASH,MAAa,aACZ,MACA,MACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;AAEpB,QAAO,OAAO,QAAQ,OADC,eACQ,cAAc,MAAM,MAAM,KAAK,EAAE;EAC/D,GAAG;EACH,IAAI,UAAU;EACd,kBAAkB;EAClB,CAAC;EACD;;;;AAKH,MAAa,eACZ,MACA,MACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;AAEpB,QAAO,OAAO,QAAQ,OADC,eACQ,cAAc,MAAM,MAAM,KAAK,EAAE;EAC/D,GAAG;EACH,IAAI,UAAU;EACd,kBAAkB;EAClB,CAAC;EACD"}