@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/plugins/sui/mode/shared-boot.mjs

@@ -1,9 +1,11 @@
 import { chainId } from "../../../substrate/brand.mjs";
-import { suiPluginError } from "../errors.mjs";
 import { waitForHttpEndpoint } from "../../../substrate/runtime/http-probe.mjs";
+import { suiConfigError, suiPluginError } from "../errors.mjs";
+import { formatUnknownError } from "../../../substrate/runtime/format-unknown-error.mjs";
+import { SuiSpans } from "../spans.mjs";
 import { makeSuiChainProbe } from "../chain-probe.mjs";
 import { toDockerHostGatewayUrl } from "./shared.mjs";
-import { Duration, Effect, Ref } from "effect";
+import { Duration, Effect, SynchronizedRef } from "effect";
 //#region src/plugins/sui/mode/shared-boot.ts
 /** Default chain-id fetch timeout. The wire latency is the dominant
 *  cost on real RPCs; 30 s is the documented ceiling. */
@@ -22,11 +24,11 @@ const fetchChainId = (sdkClient, opts) => {
 			if (!response.chainId) throw new Error("Chain identifier not found in service info");
 			return response.chainId;
 		}),
-		catch: (cause) => suiPluginError("chain-id-fetch", `sui chain-id fetch failed: ${stringifyCause(cause)}`, cause)
+		catch: (cause) => suiPluginError("chain-id-fetch", `sui chain-id fetch failed: ${formatUnknownError(cause)}`, cause)
 	}).pipe(Effect.timeoutOrElse({
 		duration: timeout,
 		orElse: () => Effect.fail(suiPluginError("chain-id-fetch", `sui chain-id fetch did not respond within ${timeoutMs}ms`))
-	}), Effect.tap((id) => Effect.annotateCurrentSpan({ "sui.chain": id })), Effect.withSpan(opts?.span ?? "devstack.plugin.sui.fetchChainId"));
+	}), Effect.tap((id) => Effect.annotateCurrentSpan({ [SuiSpans.chain]: id })), Effect.withSpan(opts?.span ?? "devstack.plugin.sui.fetchChainId"));
 };
 /** Per-attempt and total budget for the `waitForTransactionsReady`
 *  retry loop. The 2 s spacing matches the upstream sui-faucet's
@@ -50,7 +52,7 @@ const FAUCET_PROBE_RECIPIENT = "0x0000000000000000000000000000000000000000000000
 const buildWaitForTransactionsReady = (faucetUrl, opts) => Effect.gen(function* () {
 	const retrySpacing = opts?.retrySpacing ?? FUNDS_READY_RETRY_SPACING;
 	const timeout = opts?.timeout ?? FUNDS_READY_TIMEOUT;
-	const ref = yield* Ref.make(null);
+	const ref = yield* SynchronizedRef.make(null);
 	const makeProbe = () => waitForHttpEndpoint({
 		endpoint: `${faucetUrl}/v2/gas`,
 		timeoutMs: Duration.toMillis(timeout),
@@ -70,16 +72,10 @@ const buildWaitForTransactionsReady = (faucetUrl, opts) => Effect.gen(function*
 			}
 			return true;
 		}
-	}).pipe(Effect.mapError((cause) => suiPluginError("wait-funds-ready", `sui faucet at ${faucetUrl} did not become funds-transferable within ${Duration.toMillis(timeout)}ms (still returning body-level Failure or 5xx): ` + stringifyCause(cause), cause)));
+	}).pipe(Effect.mapError((cause) => suiPluginError("wait-funds-ready", `sui faucet at ${faucetUrl} did not become funds-transferable within ${Duration.toMillis(timeout)}ms (still returning body-level Failure or 5xx): ` + formatUnknownError(cause), cause)));
 	return {
-		wait: Effect.gen(function* () {
-			const existing = yield* Ref.get(ref);
-			if (existing !== null) return existing;
-			const cached = yield* Effect.cached(makeProbe());
-			yield* Ref.set(ref, cached);
-			return cached;
-		}).pipe(Effect.flatMap((eff) => eff)),
-		invalidate: Ref.set(ref, null)
+		wait: SynchronizedRef.modifyEffect(ref, (existing) => existing !== null ? Effect.succeed([existing, existing]) : Effect.cached(makeProbe()).pipe(Effect.map((cached) => [cached, cached]))).pipe(Effect.flatMap((eff) => eff)),
+		invalidate: SynchronizedRef.set(ref, null)
 	};
 });
 /** Trivially-succeeding gate. Used by faucet-less networks (live
@@ -88,103 +84,26 @@ const noopWaitForTransactionsReady = {
 	wait: Effect.void,
 	invalidate: Effect.void
 };
-const SUI_RPC_READ_TIMEOUT_MS = 1e4;
-const postJsonRpc = async (rpcUrl, method, params) => {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), SUI_RPC_READ_TIMEOUT_MS);
-	timeout.unref?.();
-	try {
-		const response = await fetch(rpcUrl, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify({
-				jsonrpc: "2.0",
-				id: 1,
-				method,
-				params
-			}),
-			signal: controller.signal
-		});
-		if (!response.ok) throw new Error(`Sui RPC HTTP ${response.status}`);
-		const payload = await response.json();
-		if (payload.error !== void 0) throw new Error(payload.error.message ?? JSON.stringify(payload.error));
-		if (payload.result === void 0) throw new Error(`Sui RPC ${method} returned no result`);
-		return payload.result;
-	} finally {
-		clearTimeout(timeout);
-	}
-};
-const normalizeJsonOwner = (owner) => {
-	if (owner === "Immutable") return {
-		$kind: "Immutable",
-		Immutable: true
-	};
-	if (typeof owner !== "object" || owner === null) return {
-		$kind: "Unknown",
-		Unknown: owner
-	};
-	const record = owner;
-	if (typeof record.AddressOwner === "string") return {
-		$kind: "AddressOwner",
-		AddressOwner: record.AddressOwner
-	};
-	if (record.ObjectOwner !== void 0) return {
-		$kind: "Parent",
-		Parent: record.ObjectOwner
-	};
-	if (record.Shared !== void 0) {
-		const initialSharedVersion = record.Shared.initialSharedVersion ?? record.Shared.initial_shared_version;
-		return {
-			$kind: "Shared",
-			Shared: { initialSharedVersion: String(initialSharedVersion) }
-		};
-	}
-	if (record.ConsensusAddressOwner !== void 0) return {
-		$kind: "ConsensusAddressOwner",
-		ConsensusAddressOwner: record.ConsensusAddressOwner
-	};
-	return {
-		$kind: "Unknown",
-		Unknown: owner
-	};
-};
-const getObjectViaJsonRpc = async (rpcUrl, args) => {
-	const showContent = args.include?.content === true || args.include?.json === true;
-	const data = (await postJsonRpc("" + rpcUrl, "sui_getObject", [args.objectId, {
-		showType: true,
-		showOwner: true,
-		showContent
-	}])).data;
-	if (data?.objectId === void 0) throw new Error(`object ${args.objectId} not found`);
-	const object = {
-		objectId: data.objectId,
-		version: String(data.version ?? ""),
-		type: data.type ?? "unknown",
-		owner: normalizeJsonOwner(data.owner),
-		...args.include?.json === true ? { json: data.content?.fields } : {},
-		...args.include?.content === true ? { content: data.content } : {}
-	};
-	return {
-		...object,
-		object
-	};
-};
 /** Build the `SuiSdkShim` over a constructed grpc client.
 *  Account/Coin/Wallet read through this seam, so we expose
 *  `executeTransaction` + `waitForTransaction` in addition to the
-*  read methods needed by the chain probe. */
-const makeSdkShim = (sdkClient, rpcUrl) => ({
+*  read methods needed by the chain probe.
+*
+*  Every read/write goes through `sdkClient.core.*` — the gRPC
+*  TransportMethods surface from `@mysten/sui`. JSON-RPC is
+*  deprecated; do not reintroduce it. */
+const makeSdkShim = (sdkClient) => ({
 	core: {
-		getObject: (args) => getObjectViaJsonRpc(rpcUrl, args),
+		getObject: (args) => sdkClient.core.getObject(args),
 		getTransaction: (args) => sdkClient.core.getTransaction(args),
 		getBalance: (args) => sdkClient.core.getBalance(args),
 		listCoins: (args) => sdkClient.core.listCoins(args),
-		executeTransaction: (args) => sdkClient.executeTransaction({
+		executeTransaction: (args) => sdkClient.core.executeTransaction({
 			transaction: args.transaction,
 			signatures: [...args.signatures],
 			...args.include !== void 0 ? { include: args.include } : {}
 		}),
-		waitForTransaction: (args) => sdkClient.waitForTransaction({
+		waitForTransaction: (args) => sdkClient.core.waitForTransaction({
 			digest: args.digest,
 			...args.timeout !== void 0 ? { timeout: args.timeout } : {}
 		})
@@ -198,10 +117,23 @@ const makeSdkShim = (sdkClient, rpcUrl) => ({
 *  `chain` is accepted as a bare string and branded to `ChainId` at
 *  this single boundary — every consumer downstream reads the
 *  branded shape so capability-key constructors (`chainProbe…`,
-*  `faucet…`) accept it without a cast. */
-const assembleSuiClient = (parts) => {
-	const sdkShim = makeSdkShim(parts.sdkClient, parts.sdkRpcUrl ?? parts.rpcUrl);
-	const chainProbe = makeSuiChainProbe(sdkShim, parts.chain);
+*  `faucet…`) accept it without a cast.
+*
+*  Returns an `Effect` on the `SuiConfigError` channel: the empty-chain
+*  guard must surface as a typed, `catchTag`-able failure. Calling it
+*  un-yielded as a sync function (as it once was) turned a thrown
+*  `SuiConfigError` into a DEFECT inside the mode-boot `Effect.gen`
+*  bodies — a hidden crash the channel could never recover (mirrors the
+*  fix already applied to `auto-tick.ts`; STYLE_GUIDE §2). */
+const assembleSuiClient = (parts) => Effect.gen(function* () {
+	if (typeof parts.chain !== "string" || parts.chain.length === 0) return yield* Effect.fail(suiConfigError({
+		field: "chain",
+		message: "sui.assembleSuiClient: chain id must be a non-empty string",
+		hint: "check fetchChainId / network resolver returned a real chain id"
+	}));
+	const chain = parts.chain;
+	const sdkShim = makeSdkShim(parts.sdkClient);
+	const chainProbe = makeSuiChainProbe(sdkShim, chain);
 	return {
 		client: {
 			sdk: sdkShim,
@@ -214,7 +146,7 @@ const assembleSuiClient = (parts) => {
 				faucetUrl: parts.faucetUrl === void 0 ? null : toDockerHostGatewayUrl(parts.faucetUrl),
 				graphqlUrl: parts.graphqlUrl === void 0 ? null : toDockerHostGatewayUrl(parts.graphqlUrl)
 			},
-			chain: chainId(parts.chain),
+			chain: chainId(chain),
 			waitForTransactionsReady: parts.waitForTransactionsReady,
 			chainProbe,
 			fork: null,
@@ -223,7 +155,7 @@ const assembleSuiClient = (parts) => {
 		sdkShim,
 		chainProbe
 	};
-};
+});
 /** Shape the resolved network record the boot builders all hand
 *  back. The substrate-network mapping is uniform per mode. Brands
 *  the raw chain string at this boundary so consumers downstream
@@ -239,15 +171,6 @@ const makeResolvedNetwork = (parts) => ({
 	...parts.checkpoint !== void 0 ? { checkpoint: parts.checkpoint } : {},
 	...parts.forkUpstream !== void 0 ? { forkUpstream: parts.forkUpstream } : {}
 });
-const stringifyCause = (cause) => {
-	if (cause instanceof Error) return cause.message;
-	if (typeof cause === "string") return cause;
-	try {
-		return JSON.stringify(cause);
-	} catch {
-		return String(cause);
-	}
-};
 //#endregion
 export { assembleSuiClient, buildWaitForTransactionsReady, fetchChainId, makeResolvedNetwork, noopWaitForTransactionsReady };
 

package/dist/plugins/sui/mode/shared-boot.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"shared-boot.mjs","names":["brandChainId"],"sources":["../../../../src/plugins/sui/mode/shared-boot.ts"],"sourcesContent":["// Sui plugin — boot helpers shared across local / external / live modes.\n//\n// What lives here (and why):\n//\n//   - `fetchChainId(client, opts?)` — bounded chain-id probe. The\n//     only readiness sentinel for external + live; local treats it\n//     as the chain-id capture step after the multi-probe gate has\n//     succeeded.\n//   - `buildWaitForTransactionsReady(faucetUrl, opts?)` — memoised\n//     funds-ready gate for faucet-bearing networks. `Effect.cached`\n//     with a manual-invalidation surface (the distilled-doc\n//     opportunity called out in `mode/shared.ts`).\n//   - `noopWaitForTransactionsReady` — trivially-succeeding gate for\n//     faucet-less networks (live mainnet, fork).\n//   - `assembleSuiClient(...)` — collapses the boilerplate that\n//     local/local-rpc/live all repeat (sdk shim + chainProbe + the\n//     `fork: null` discriminator).\n//\n// Why not jam this into `mode/local.ts`: external + live can't\n// import from `local.ts` without dragging the container-runtime\n// import path along; the helpers below are wire-only and have NO\n// substrate-context dependencies.\n\nimport { Duration, Effect, Ref, type Scope } from 'effect';\n\nimport type { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport type { ChainProbe } from '../../../contracts/chain-probe.ts';\nimport { chainId as brandChainId } from '../../../substrate/brand.ts';\nimport { waitForHttpEndpoint } from '../../../substrate/runtime/http-probe.ts';\nimport { makeSuiChainProbe, type SuiSdkShim, type SuiProbeKey } from '../chain-probe.ts';\nimport { suiPluginError, type SuiPluginError } from '../errors.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport { toDockerHostGatewayUrl, type SuiClient, type WaitForTransactionsReady } from './shared.ts';\n\n// ---------------------------------------------------------------------------\n// Chain-id fetch — bounded, typed-error\n// ---------------------------------------------------------------------------\n\n/** Default chain-id fetch timeout. The wire latency is the dominant\n *  cost on real RPCs; 30 s is the documented ceiling. */\nexport const DEFAULT_CHAIN_ID_TIMEOUT = Duration.seconds(30);\n\n/** Fetch the chain identifier off a constructed grpc client. The\n *  result is the bare string that downstream cache layers fold into\n *  their state-store keys. */\nexport const fetchChainId = (\n\tsdkClient: SuiGrpcClient,\n\topts?: { readonly timeout?: Duration.Duration; readonly span?: string },\n): Effect.Effect<string, SuiPluginError> => {\n\tconst timeout = opts?.timeout ?? DEFAULT_CHAIN_ID_TIMEOUT;\n\tconst timeoutMs = Duration.toMillis(timeout);\n\treturn Effect.tryPromise({\n\t\ttry: (signal) =>\n\t\t\tsdkClient.ledgerService\n\t\t\t\t.getServiceInfo({}, { abort: signal, timeout: timeoutMs })\n\t\t\t\t.response.then((response) => {\n\t\t\t\t\tif (!response.chainId) {\n\t\t\t\t\t\tthrow new Error('Chain identifier not found in service info');\n\t\t\t\t\t}\n\t\t\t\t\treturn response.chainId;\n\t\t\t\t}),\n\t\tcatch: (cause): SuiPluginError =>\n\t\t\tsuiPluginError(\n\t\t\t\t'chain-id-fetch',\n\t\t\t\t`sui chain-id fetch failed: ${stringifyCause(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t}).pipe(\n\t\tEffect.timeoutOrElse({\n\t\t\tduration: timeout,\n\t\t\torElse: (): Effect.Effect<string, SuiPluginError> =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t\t`sui chain-id fetch did not respond within ${timeoutMs}ms`,\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t}),\n\t\tEffect.tap((id: string) => Effect.annotateCurrentSpan({ 'sui.chain': id })),\n\t\tEffect.withSpan(opts?.span ?? 'devstack.plugin.sui.fetchChainId'),\n\t);\n};\n\n// ---------------------------------------------------------------------------\n// waitForTransactionsReady — memoised, with manual invalidation\n// ---------------------------------------------------------------------------\n\n/** Per-attempt and total budget for the `waitForTransactionsReady`\n *  retry loop. The 2 s spacing matches the upstream sui-faucet's\n *  internal cadence; the 90 s ceiling matches the v3 service's\n *  documented wall-clock. */\nconst FUNDS_READY_RETRY_SPACING = Duration.seconds(2);\nconst FUNDS_READY_TIMEOUT = Duration.seconds(90);\n\n/** Per-fetch deadline for the faucet probe POST. Bounded short so\n *  the outer retry loop hammers quickly. */\nconst PROBE_FETCH_TIMEOUT_MS = 3000;\n\n/** Probe recipient for the faucet funds-ready check. A literal\n *  zero-balance address so the real call doesn't pollute caller wallets;\n *  any well-formed address works. */\nconst FAUCET_PROBE_RECIPIENT = '0x0000000000000000000000000000000000000000000000000000000000000001';\n\n/**\n * Build the funds-transferable gate against a real HTTP faucet.\n * Memoised — first successful resolution sticks for the scope; the\n * manual `invalidate` surface clears the memo so long-running\n * supervisors can re-probe without a full restart.\n */\nexport const buildWaitForTransactionsReady = (\n\tfaucetUrl: string,\n\topts?: {\n\t\treadonly retrySpacing?: Duration.Duration;\n\t\treadonly timeout?: Duration.Duration;\n\t},\n): Effect.Effect<WaitForTransactionsReady, never, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst retrySpacing = opts?.retrySpacing ?? FUNDS_READY_RETRY_SPACING;\n\t\tconst timeout = opts?.timeout ?? FUNDS_READY_TIMEOUT;\n\t\tconst ref = yield* Ref.make<Effect.Effect<void, SuiPluginError> | null>(null);\n\n\t\tconst makeProbe = (): Effect.Effect<void, SuiPluginError> =>\n\t\t\twaitForHttpEndpoint({\n\t\t\t\tendpoint: `${faucetUrl}/v2/gas`,\n\t\t\t\ttimeoutMs: Duration.toMillis(timeout),\n\t\t\t\tintervalMs: Duration.toMillis(retrySpacing),\n\t\t\t\trequestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,\n\t\t\t\trequestInit: {\n\t\t\t\t\tmethod: 'POST',\n\t\t\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\tFixedAmountRequest: { recipient: FAUCET_PROBE_RECIPIENT },\n\t\t\t\t\t}),\n\t\t\t\t},\n\t\t\t\tvalidate: async (response) => {\n\t\t\t\t\tif (!response.ok) throw new Error(`faucet HTTP ${response.status}`);\n\t\t\t\t\tconst body = (await response.json()) as { status?: unknown };\n\t\t\t\t\tconst status = body.status;\n\t\t\t\t\tif (typeof status === 'object' && status !== null && 'Failure' in status) {\n\t\t\t\t\t\tconst failure = (status as { Failure: unknown }).Failure;\n\t\t\t\t\t\tthrow new Error(`faucet body: Failure ${JSON.stringify(failure)}`);\n\t\t\t\t\t}\n\t\t\t\t\treturn true;\n\t\t\t\t},\n\t\t\t}).pipe(\n\t\t\t\tEffect.mapError(\n\t\t\t\t\t(cause): SuiPluginError =>\n\t\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t\t'wait-funds-ready',\n\t\t\t\t\t\t\t`sui faucet at ${faucetUrl} did not become funds-transferable within ` +\n\t\t\t\t\t\t\t\t`${Duration.toMillis(timeout)}ms (still returning body-level Failure or 5xx): ` +\n\t\t\t\t\t\t\t\tstringifyCause(cause),\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\tconst getOrInit: Effect.Effect<Effect.Effect<void, SuiPluginError>> = Effect.gen(function* () {\n\t\t\tconst existing = yield* Ref.get(ref);\n\t\t\tif (existing !== null) return existing;\n\t\t\tconst cached = yield* Effect.cached(makeProbe());\n\t\t\tyield* Ref.set(ref, cached);\n\t\t\treturn cached;\n\t\t});\n\n\t\treturn {\n\t\t\twait: getOrInit.pipe(Effect.flatMap((eff) => eff)),\n\t\t\tinvalidate: Ref.set(ref, null),\n\t\t};\n\t});\n\n/** Trivially-succeeding gate. Used by faucet-less networks (live\n *  mainnet, fork — fork funds via impersonation, not HTTP). */\nexport const noopWaitForTransactionsReady: WaitForTransactionsReady = {\n\twait: Effect.void,\n\tinvalidate: Effect.void,\n};\n\nconst SUI_RPC_READ_TIMEOUT_MS = 10_000;\n\nconst postJsonRpc = async <A>(\n\trpcUrl: string,\n\tmethod: string,\n\tparams: ReadonlyArray<unknown>,\n): Promise<A> => {\n\tconst controller = new AbortController();\n\tconst timeout = setTimeout(() => controller.abort(), SUI_RPC_READ_TIMEOUT_MS);\n\ttimeout.unref?.();\n\ttry {\n\t\tconst response = await fetch(rpcUrl, {\n\t\t\tmethod: 'POST',\n\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\tbody: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),\n\t\t\tsignal: controller.signal,\n\t\t});\n\t\tif (!response.ok) throw new Error(`Sui RPC HTTP ${response.status}`);\n\t\tconst payload = (await response.json()) as {\n\t\t\treadonly result?: A;\n\t\t\treadonly error?: { readonly message?: string };\n\t\t};\n\t\tif (payload.error !== undefined) {\n\t\t\tthrow new Error(payload.error.message ?? JSON.stringify(payload.error));\n\t\t}\n\t\tif (payload.result === undefined) throw new Error(`Sui RPC ${method} returned no result`);\n\t\treturn payload.result;\n\t} finally {\n\t\tclearTimeout(timeout);\n\t}\n};\n\nconst normalizeJsonOwner = (owner: unknown): unknown => {\n\tif (owner === 'Immutable') return { $kind: 'Immutable', Immutable: true };\n\tif (typeof owner !== 'object' || owner === null) return { $kind: 'Unknown', Unknown: owner };\n\tconst record = owner as {\n\t\treadonly AddressOwner?: unknown;\n\t\treadonly ObjectOwner?: unknown;\n\t\treadonly Shared?: {\n\t\t\treadonly initial_shared_version?: unknown;\n\t\t\treadonly initialSharedVersion?: unknown;\n\t\t};\n\t\treadonly ConsensusAddressOwner?: unknown;\n\t};\n\tif (typeof record.AddressOwner === 'string') {\n\t\treturn { $kind: 'AddressOwner', AddressOwner: record.AddressOwner };\n\t}\n\tif (record.ObjectOwner !== undefined) {\n\t\treturn { $kind: 'Parent', Parent: record.ObjectOwner };\n\t}\n\tif (record.Shared !== undefined) {\n\t\tconst initialSharedVersion =\n\t\t\trecord.Shared.initialSharedVersion ?? record.Shared.initial_shared_version;\n\t\treturn {\n\t\t\t$kind: 'Shared',\n\t\t\tShared: { initialSharedVersion: String(initialSharedVersion) },\n\t\t};\n\t}\n\tif (record.ConsensusAddressOwner !== undefined) {\n\t\treturn { $kind: 'ConsensusAddressOwner', ConsensusAddressOwner: record.ConsensusAddressOwner };\n\t}\n\treturn { $kind: 'Unknown', Unknown: owner };\n};\n\nconst getObjectViaJsonRpc = async (\n\trpcUrl: string,\n\targs: {\n\t\treadonly objectId: string;\n\t\treadonly include?: {\n\t\t\treadonly content?: boolean;\n\t\t\treadonly json?: boolean;\n\t\t};\n\t},\n): Promise<unknown> => {\n\tconst showContent = args.include?.content === true || args.include?.json === true;\n\tconst result = await postJsonRpc<{\n\t\treadonly data?: {\n\t\t\treadonly objectId?: string;\n\t\t\treadonly version?: string | number;\n\t\t\treadonly type?: string;\n\t\t\treadonly owner?: unknown;\n\t\t\treadonly content?: {\n\t\t\t\treadonly fields?: unknown;\n\t\t\t};\n\t\t};\n\t}>('' + rpcUrl, 'sui_getObject', [\n\t\targs.objectId,\n\t\t{ showType: true, showOwner: true, showContent },\n\t]);\n\tconst data = result.data;\n\tif (data?.objectId === undefined) throw new Error(`object ${args.objectId} not found`);\n\tconst object = {\n\t\tobjectId: data.objectId,\n\t\tversion: String(data.version ?? ''),\n\t\ttype: data.type ?? 'unknown',\n\t\towner: normalizeJsonOwner(data.owner),\n\t\t...(args.include?.json === true ? { json: data.content?.fields } : {}),\n\t\t...(args.include?.content === true ? { content: data.content } : {}),\n\t};\n\treturn { ...object, object };\n};\n\n// ---------------------------------------------------------------------------\n// SuiClient assembly — collapses the per-mode boilerplate\n// ---------------------------------------------------------------------------\n\n/** Build the `SuiSdkShim` over a constructed grpc client.\n *  Account/Coin/Wallet read through this seam, so we expose\n *  `executeTransaction` + `waitForTransaction` in addition to the\n *  read methods needed by the chain probe. */\nexport const makeSdkShim = (sdkClient: SuiGrpcClient, rpcUrl: string): SuiSdkShim => ({\n\tcore: {\n\t\tgetObject: (args) => getObjectViaJsonRpc(rpcUrl, args),\n\t\tgetTransaction: (args) => sdkClient.core.getTransaction(args),\n\t\tgetBalance: (args) => sdkClient.core.getBalance(args),\n\t\tlistCoins: (args) => sdkClient.core.listCoins(args),\n\t\t// Extended surfaces — used by the account plugin's sign + execute\n\t\t// closure. Local mode keeps the `sdkClient.executeTransaction` /\n\t\t// `sdkClient.waitForTransaction` instance methods reachable on\n\t\t// the shim so consumers don't have to know about the grpc client\n\t\t// constructor. The SDK accepts a mutable `signatures: string[]`\n\t\t// shape; the shim's readonly signature is widened with a copy at\n\t\t// the boundary.\n\t\texecuteTransaction: (args) =>\n\t\t\tsdkClient.executeTransaction({\n\t\t\t\ttransaction: args.transaction,\n\t\t\t\tsignatures: [...args.signatures],\n\t\t\t\t...(args.include !== undefined ? { include: args.include } : {}),\n\t\t\t}),\n\t\twaitForTransaction: (args) =>\n\t\t\tsdkClient.waitForTransaction({\n\t\t\t\tdigest: args.digest,\n\t\t\t\t...(args.timeout !== undefined ? { timeout: args.timeout } : {}),\n\t\t\t}),\n\t},\n\t// Opaque client passthrough — the Package plugin's publish-tx\n\t// builder hands this to `Transaction.build({ client })`. The shim\n\t// layer doesn't type-narrow it; downstream consumers cast at the\n\t// `tx.build` call site (mirrors coin/mint.ts).\n\tclient: sdkClient,\n});\n\n/** Assemble a `SuiClient` from the per-mode building blocks. The\n *  `fork: null` discriminator is invariant for non-fork modes; the\n *  fork builder constructs its own client with the admin surface.\n *\n *  `chain` is accepted as a bare string and branded to `ChainId` at\n *  this single boundary — every consumer downstream reads the\n *  branded shape so capability-key constructors (`chainProbe…`,\n *  `faucet…`) accept it without a cast. */\nexport const assembleSuiClient = (parts: {\n\treadonly sdkClient: SuiGrpcClient;\n\treadonly chain: string;\n\treadonly rpcUrl: string;\n\treadonly sdkRpcUrl?: string;\n\treadonly faucetUrl?: string;\n\treadonly fundingFaucetUrl?: string;\n\treadonly graphqlUrl?: string;\n\treadonly waitForTransactionsReady: WaitForTransactionsReady;\n\t/** Image ref consumed by package's path (b) (`docker run --rm`)\n\t *  build path. `null` for modes that have no in-stack image\n\t *  (external + live). */\n\treadonly buildImage?: import('../../../contracts/container-runtime.ts').ImageRef | null;\n\t/** Container-reachable mirrors. Local mode resolves public URLs\n\t *  through the router but sibling containers still need direct\n\t *  host-gateway URLs during boot. */\n\treadonly hostGateway?: SuiClient['hostGateway'];\n}): {\n\treadonly client: SuiClient;\n\treadonly sdkShim: SuiSdkShim;\n\treadonly chainProbe: ChainProbe<SuiProbeKey>;\n} => {\n\tconst sdkShim = makeSdkShim(parts.sdkClient, parts.sdkRpcUrl ?? parts.rpcUrl);\n\tconst chainProbe = makeSuiChainProbe(sdkShim, parts.chain);\n\tconst client: SuiClient = {\n\t\tsdk: sdkShim,\n\t\trpcUrl: parts.rpcUrl,\n\t\tfaucetUrl: parts.faucetUrl ?? null,\n\t\tfundingFaucetUrl: parts.fundingFaucetUrl ?? parts.faucetUrl ?? null,\n\t\tgraphqlUrl: parts.graphqlUrl ?? null,\n\t\thostGateway: parts.hostGateway ?? {\n\t\t\trpcUrl: toDockerHostGatewayUrl(parts.rpcUrl),\n\t\t\tfaucetUrl: parts.faucetUrl === undefined ? null : toDockerHostGatewayUrl(parts.faucetUrl),\n\t\t\tgraphqlUrl: parts.graphqlUrl === undefined ? null : toDockerHostGatewayUrl(parts.graphqlUrl),\n\t\t},\n\t\tchain: brandChainId(parts.chain),\n\t\twaitForTransactionsReady: parts.waitForTransactionsReady,\n\t\tchainProbe,\n\t\tfork: null,\n\t\tbuildImage: parts.buildImage ?? null,\n\t};\n\treturn { client, sdkShim, chainProbe };\n};\n\n/** Shape the resolved network record the boot builders all hand\n *  back. The substrate-network mapping is uniform per mode. Brands\n *  the raw chain string at this boundary so consumers downstream\n *  (codegen, capabilities, walrus/seal deps) read a `ChainId` and\n *  don't re-wrap. */\nexport const makeResolvedNetwork = (parts: {\n\treadonly mode: ResolvedSuiNetwork['mode'];\n\treadonly chain: string;\n\treadonly rpc: string;\n\treadonly faucet?: string;\n\treadonly graphql?: string;\n\treadonly source: ResolvedSuiNetwork['source'];\n\treadonly checkpoint?: string;\n\treadonly forkUpstream?: ResolvedSuiNetwork['forkUpstream'];\n}): ResolvedSuiNetwork => ({\n\tmode: parts.mode,\n\tchain: brandChainId(parts.chain),\n\trpc: parts.rpc,\n\tsource: parts.source,\n\t...(parts.faucet !== undefined ? { faucet: parts.faucet } : {}),\n\t...(parts.graphql !== undefined ? { graphql: parts.graphql } : {}),\n\t...(parts.checkpoint !== undefined ? { checkpoint: parts.checkpoint } : {}),\n\t...(parts.forkUpstream !== undefined ? { forkUpstream: parts.forkUpstream } : {}),\n});\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nconst stringifyCause = (cause: unknown): string => {\n\tif (cause instanceof Error) return cause.message;\n\tif (typeof cause === 'string') return cause;\n\ttry {\n\t\treturn JSON.stringify(cause);\n\t} catch {\n\t\treturn String(cause);\n\t}\n};\n"],"mappings":"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"}
+{"version":3,"file":"shared-boot.mjs","names":["brandChainId"],"sources":["../../../../src/plugins/sui/mode/shared-boot.ts"],"sourcesContent":["// Sui plugin — boot helpers shared across local / external / live modes.\n//\n// What lives here (and why):\n//\n//   - `fetchChainId(client, opts?)` — bounded chain-id probe. The\n//     only readiness sentinel for external + live; local treats it\n//     as the chain-id capture step after the multi-probe gate has\n//     succeeded.\n//   - `buildWaitForTransactionsReady(faucetUrl, opts?)` — memoised\n//     funds-ready gate for faucet-bearing networks. `Effect.cached`\n//     with a manual-invalidation surface (the distilled-doc\n//     opportunity called out in `mode/shared.ts`).\n//   - `noopWaitForTransactionsReady` — trivially-succeeding gate for\n//     faucet-less networks (live mainnet, fork).\n//   - `assembleSuiClient(...)` — collapses the boilerplate that\n//     local/local-rpc/live all repeat (sdk shim + chainProbe + the\n//     `fork: null` discriminator).\n//\n// Why not jam this into `mode/local.ts`: external + live can't\n// import from `local.ts` without dragging the container-runtime\n// import path along; the helpers below are wire-only and have NO\n// substrate-context dependencies.\n\nimport { Duration, Effect, SynchronizedRef, type Scope } from 'effect';\n\nimport type { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport type { ChainProbe } from '../../../contracts/chain-probe.ts';\nimport { chainId as brandChainId } from '../../../substrate/brand.ts';\nimport { waitForHttpEndpoint } from '../../../substrate/runtime/http-probe.ts';\nimport { makeSuiChainProbe, type SuiSdkShim, type SuiProbeKey } from '../chain-probe.ts';\nimport {\n\tsuiConfigError,\n\tsuiPluginError,\n\ttype SuiConfigError,\n\ttype SuiPluginError,\n} from '../errors.ts';\nimport { formatUnknownError } from '../../../substrate/runtime/format-unknown-error.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport { SuiSpans } from '../spans.ts';\nimport { toDockerHostGatewayUrl, type SuiClient, type WaitForTransactionsReady } from './shared.ts';\n\n// ---------------------------------------------------------------------------\n// Chain-id fetch — bounded, typed-error\n// ---------------------------------------------------------------------------\n\n/** Default chain-id fetch timeout. The wire latency is the dominant\n *  cost on real RPCs; 30 s is the documented ceiling. */\nexport const DEFAULT_CHAIN_ID_TIMEOUT = Duration.seconds(30);\n\n/** Fetch the chain identifier off a constructed grpc client. The\n *  result is the bare string that downstream cache layers fold into\n *  their state-store keys. */\nexport const fetchChainId = (\n\tsdkClient: SuiGrpcClient,\n\topts?: { readonly timeout?: Duration.Duration; readonly span?: string },\n): Effect.Effect<string, SuiPluginError> => {\n\tconst timeout = opts?.timeout ?? DEFAULT_CHAIN_ID_TIMEOUT;\n\tconst timeoutMs = Duration.toMillis(timeout);\n\treturn Effect.tryPromise({\n\t\ttry: (signal) =>\n\t\t\tsdkClient.ledgerService\n\t\t\t\t.getServiceInfo({}, { abort: signal, timeout: timeoutMs })\n\t\t\t\t.response.then((response) => {\n\t\t\t\t\tif (!response.chainId) {\n\t\t\t\t\t\tthrow new Error('Chain identifier not found in service info');\n\t\t\t\t\t}\n\t\t\t\t\treturn response.chainId;\n\t\t\t\t}),\n\t\tcatch: (cause): SuiPluginError =>\n\t\t\tsuiPluginError(\n\t\t\t\t'chain-id-fetch',\n\t\t\t\t`sui chain-id fetch failed: ${formatUnknownError(cause)}`,\n\t\t\t\tcause,\n\t\t\t),\n\t}).pipe(\n\t\tEffect.timeoutOrElse({\n\t\t\tduration: timeout,\n\t\t\torElse: (): Effect.Effect<string, SuiPluginError> =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t\t`sui chain-id fetch did not respond within ${timeoutMs}ms`,\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t}),\n\t\tEffect.tap((id: string) => Effect.annotateCurrentSpan({ [SuiSpans.chain]: id })),\n\t\tEffect.withSpan(opts?.span ?? 'devstack.plugin.sui.fetchChainId'),\n\t);\n};\n\n// ---------------------------------------------------------------------------\n// waitForTransactionsReady — memoised, with manual invalidation\n// ---------------------------------------------------------------------------\n\n/** Per-attempt and total budget for the `waitForTransactionsReady`\n *  retry loop. The 2 s spacing matches the upstream sui-faucet's\n *  internal cadence; the 90 s ceiling matches the v3 service's\n *  documented wall-clock. */\nconst FUNDS_READY_RETRY_SPACING = Duration.seconds(2);\nconst FUNDS_READY_TIMEOUT = Duration.seconds(90);\n\n/** Per-fetch deadline for the faucet probe POST. Bounded short so\n *  the outer retry loop hammers quickly. */\nconst PROBE_FETCH_TIMEOUT_MS = 3000;\n\n/** Probe recipient for the faucet funds-ready check. A literal\n *  zero-balance address so the real call doesn't pollute caller wallets;\n *  any well-formed address works. */\nconst FAUCET_PROBE_RECIPIENT = '0x0000000000000000000000000000000000000000000000000000000000000001';\n\n/**\n * Build the funds-transferable gate against a real HTTP faucet.\n * Memoised — first successful resolution sticks for the scope; the\n * manual `invalidate` surface clears the memo so long-running\n * supervisors can re-probe without a full restart.\n */\nexport const buildWaitForTransactionsReady = (\n\tfaucetUrl: string,\n\topts?: {\n\t\treadonly retrySpacing?: Duration.Duration;\n\t\treadonly timeout?: Duration.Duration;\n\t},\n): Effect.Effect<WaitForTransactionsReady, never, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst retrySpacing = opts?.retrySpacing ?? FUNDS_READY_RETRY_SPACING;\n\t\tconst timeout = opts?.timeout ?? FUNDS_READY_TIMEOUT;\n\t\t// SynchronizedRef serialises the get-or-init transition so two\n\t\t// concurrent callers can't both observe `null` and both build\n\t\t// their own `Effect.cached` instance (CAS-style guard against\n\t\t// the build-once race).\n\t\tconst ref = yield* SynchronizedRef.make<Effect.Effect<void, SuiPluginError> | null>(null);\n\n\t\tconst makeProbe = (): Effect.Effect<void, SuiPluginError> =>\n\t\t\twaitForHttpEndpoint({\n\t\t\t\tendpoint: `${faucetUrl}/v2/gas`,\n\t\t\t\ttimeoutMs: Duration.toMillis(timeout),\n\t\t\t\tintervalMs: Duration.toMillis(retrySpacing),\n\t\t\t\trequestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,\n\t\t\t\trequestInit: {\n\t\t\t\t\tmethod: 'POST',\n\t\t\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\tFixedAmountRequest: { recipient: FAUCET_PROBE_RECIPIENT },\n\t\t\t\t\t}),\n\t\t\t\t},\n\t\t\t\tvalidate: async (response) => {\n\t\t\t\t\tif (!response.ok) throw new Error(`faucet HTTP ${response.status}`);\n\t\t\t\t\tconst body = (await response.json()) as { status?: unknown };\n\t\t\t\t\tconst status = body.status;\n\t\t\t\t\tif (typeof status === 'object' && status !== null && 'Failure' in status) {\n\t\t\t\t\t\tconst failure = (status as { Failure: unknown }).Failure;\n\t\t\t\t\t\tthrow new Error(`faucet body: Failure ${JSON.stringify(failure)}`);\n\t\t\t\t\t}\n\t\t\t\t\treturn true;\n\t\t\t\t},\n\t\t\t}).pipe(\n\t\t\t\tEffect.mapError(\n\t\t\t\t\t(cause): SuiPluginError =>\n\t\t\t\t\t\tsuiPluginError(\n\t\t\t\t\t\t\t'wait-funds-ready',\n\t\t\t\t\t\t\t`sui faucet at ${faucetUrl} did not become funds-transferable within ` +\n\t\t\t\t\t\t\t\t`${Duration.toMillis(timeout)}ms (still returning body-level Failure or 5xx): ` +\n\t\t\t\t\t\t\t\tformatUnknownError(cause),\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\t// `modifyEffect` atomically observes-then-updates inside a\n\t\t// serialised critical section: at most one fiber builds the\n\t\t// memoised probe, every other caller reads it back. This\n\t\t// closes the read-build-write race the plain Ref had.\n\t\tconst getOrInit: Effect.Effect<Effect.Effect<void, SuiPluginError>> =\n\t\t\tSynchronizedRef.modifyEffect(ref, (existing) =>\n\t\t\t\texisting !== null\n\t\t\t\t\t? Effect.succeed([existing, existing] as const)\n\t\t\t\t\t: Effect.cached(makeProbe()).pipe(Effect.map((cached) => [cached, cached] as const)),\n\t\t\t);\n\n\t\treturn {\n\t\t\twait: getOrInit.pipe(Effect.flatMap((eff) => eff)),\n\t\t\tinvalidate: SynchronizedRef.set(ref, null),\n\t\t};\n\t});\n\n/** Trivially-succeeding gate. Used by faucet-less networks (live\n *  mainnet, fork — fork funds via impersonation, not HTTP). */\nexport const noopWaitForTransactionsReady: WaitForTransactionsReady = {\n\twait: Effect.void,\n\tinvalidate: Effect.void,\n};\n\n// ---------------------------------------------------------------------------\n// SuiClient assembly — collapses the per-mode boilerplate\n// ---------------------------------------------------------------------------\n\n/** Build the `SuiSdkShim` over a constructed grpc client.\n *  Account/Coin/Wallet read through this seam, so we expose\n *  `executeTransaction` + `waitForTransaction` in addition to the\n *  read methods needed by the chain probe.\n *\n *  Every read/write goes through `sdkClient.core.*` — the gRPC\n *  TransportMethods surface from `@mysten/sui`. JSON-RPC is\n *  deprecated; do not reintroduce it. */\nexport const makeSdkShim = (sdkClient: SuiGrpcClient): SuiSdkShim => ({\n\tcore: {\n\t\tgetObject: (args) => sdkClient.core.getObject(args),\n\t\tgetTransaction: (args) => sdkClient.core.getTransaction(args),\n\t\tgetBalance: (args) => sdkClient.core.getBalance(args),\n\t\tlistCoins: (args) => sdkClient.core.listCoins(args),\n\t\t// Extended surfaces — used by the account plugin's sign + execute\n\t\t// closure. Routes through `client.core.*` (the cross-transport\n\t\t// canonical surface per STYLE_GUIDE §16). The SDK accepts a\n\t\t// mutable `signatures: string[]`; the shim's readonly signature\n\t\t// is widened with a copy at the boundary.\n\t\texecuteTransaction: (args) =>\n\t\t\tsdkClient.core.executeTransaction({\n\t\t\t\ttransaction: args.transaction,\n\t\t\t\tsignatures: [...args.signatures],\n\t\t\t\t...(args.include !== undefined ? { include: args.include } : {}),\n\t\t\t}),\n\t\twaitForTransaction: (args) =>\n\t\t\tsdkClient.core.waitForTransaction({\n\t\t\t\tdigest: args.digest,\n\t\t\t\t...(args.timeout !== undefined ? { timeout: args.timeout } : {}),\n\t\t\t}),\n\t},\n\t// Client passthrough — Package's publish-tx builder hands this to\n\t// `Transaction.build({ client })`; sibling plugins reach\n\t// `client.core.*` directly through this slot. Typed as\n\t// ClientWithCoreApi via SuiSdkShim.client.\n\tclient: sdkClient,\n});\n\n/** Assemble a `SuiClient` from the per-mode building blocks. The\n *  `fork: null` discriminator is invariant for non-fork modes; the\n *  fork builder constructs its own client with the admin surface.\n *\n *  `chain` is accepted as a bare string and branded to `ChainId` at\n *  this single boundary — every consumer downstream reads the\n *  branded shape so capability-key constructors (`chainProbe…`,\n *  `faucet…`) accept it without a cast.\n *\n *  Returns an `Effect` on the `SuiConfigError` channel: the empty-chain\n *  guard must surface as a typed, `catchTag`-able failure. Calling it\n *  un-yielded as a sync function (as it once was) turned a thrown\n *  `SuiConfigError` into a DEFECT inside the mode-boot `Effect.gen`\n *  bodies — a hidden crash the channel could never recover (mirrors the\n *  fix already applied to `auto-tick.ts`; STYLE_GUIDE §2). */\nexport const assembleSuiClient = (parts: {\n\treadonly sdkClient: SuiGrpcClient;\n\treadonly chain: string;\n\treadonly rpcUrl: string;\n\treadonly faucetUrl?: string;\n\treadonly fundingFaucetUrl?: string;\n\treadonly graphqlUrl?: string;\n\treadonly waitForTransactionsReady: WaitForTransactionsReady;\n\t/** Image ref consumed by package's path (b) (`docker run --rm`)\n\t *  build path. `null` for modes that have no in-stack image\n\t *  (external + live). */\n\treadonly buildImage?: import('../../../contracts/container-runtime.ts').ImageRef | null;\n\t/** Container-reachable mirrors. Local mode resolves public URLs\n\t *  through the router but sibling containers still need direct\n\t *  host-gateway URLs during boot. */\n\treadonly hostGateway?: SuiClient['hostGateway'];\n}): Effect.Effect<\n\t{\n\t\treadonly client: SuiClient;\n\t\treadonly sdkShim: SuiSdkShim;\n\t\treadonly chainProbe: ChainProbe<SuiProbeKey>;\n\t},\n\tSuiConfigError\n> =>\n\tEffect.gen(function* () {\n\t\t// Defense-in-depth — `fetchChainId` should never resolve to an\n\t\t// empty string (RPC rejects that earlier), but a branded empty\n\t\t// string would silently fold into every downstream cache key. A\n\t\t// caller-pinned `chain: ''` (e.g. `.live.custom({ chain: '' })`)\n\t\t// reaches here, so fail on the typed channel rather than throw.\n\t\tif (typeof parts.chain !== 'string' || parts.chain.length === 0) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tsuiConfigError({\n\t\t\t\t\tfield: 'chain',\n\t\t\t\t\tmessage: 'sui.assembleSuiClient: chain id must be a non-empty string',\n\t\t\t\t\thint: 'check fetchChainId / network resolver returned a real chain id',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst chain = parts.chain;\n\t\tconst sdkShim = makeSdkShim(parts.sdkClient);\n\t\tconst chainProbe = makeSuiChainProbe(sdkShim, chain);\n\t\tconst client: SuiClient = {\n\t\t\tsdk: sdkShim,\n\t\t\trpcUrl: parts.rpcUrl,\n\t\t\tfaucetUrl: parts.faucetUrl ?? null,\n\t\t\tfundingFaucetUrl: parts.fundingFaucetUrl ?? parts.faucetUrl ?? null,\n\t\t\tgraphqlUrl: parts.graphqlUrl ?? null,\n\t\t\thostGateway: parts.hostGateway ?? {\n\t\t\t\trpcUrl: toDockerHostGatewayUrl(parts.rpcUrl),\n\t\t\t\tfaucetUrl: parts.faucetUrl === undefined ? null : toDockerHostGatewayUrl(parts.faucetUrl),\n\t\t\t\tgraphqlUrl:\n\t\t\t\t\tparts.graphqlUrl === undefined ? null : toDockerHostGatewayUrl(parts.graphqlUrl),\n\t\t\t},\n\t\t\tchain: brandChainId(chain),\n\t\t\twaitForTransactionsReady: parts.waitForTransactionsReady,\n\t\t\tchainProbe,\n\t\t\tfork: null,\n\t\t\tbuildImage: parts.buildImage ?? null,\n\t\t};\n\t\treturn { client, sdkShim, chainProbe };\n\t});\n\n/** Shape the resolved network record the boot builders all hand\n *  back. The substrate-network mapping is uniform per mode. Brands\n *  the raw chain string at this boundary so consumers downstream\n *  (codegen, capabilities, walrus/seal deps) read a `ChainId` and\n *  don't re-wrap. */\nexport const makeResolvedNetwork = (parts: {\n\treadonly mode: ResolvedSuiNetwork['mode'];\n\treadonly chain: string;\n\treadonly rpc: string;\n\treadonly faucet?: string;\n\treadonly graphql?: string;\n\treadonly source: ResolvedSuiNetwork['source'];\n\treadonly checkpoint?: string;\n\treadonly forkUpstream?: ResolvedSuiNetwork['forkUpstream'];\n}): ResolvedSuiNetwork => ({\n\tmode: parts.mode,\n\tchain: brandChainId(parts.chain),\n\trpc: parts.rpc,\n\tsource: parts.source,\n\t...(parts.faucet !== undefined ? { faucet: parts.faucet } : {}),\n\t...(parts.graphql !== undefined ? { graphql: parts.graphql } : {}),\n\t...(parts.checkpoint !== undefined ? { checkpoint: parts.checkpoint } : {}),\n\t...(parts.forkUpstream !== undefined ? { forkUpstream: parts.forkUpstream } : {}),\n});\n"],"mappings":"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"}

package/dist/plugins/sui/mode/shared.d.mts

@@ -33,11 +33,7 @@ interface WaitForTransactionsReady {
 }
 /** Fork admin surface — mode-narrowed. Only the fork-mode factory's
  *  resolved value carries this; local/local-rpc/live values have a
- *  type-level `null`.
- *
- *  Distilled-doc opportunity: today's `Fiber` handle is discarded
- *  at the auto-tick call site; the `autoTickHandle` field below
- *  preserves it for a future cadence-change surface. */
+ *  type-level `null`. */
 interface ForkAdminSurface {
   readonly status: Effect.Effect<{
     readonly checkpoint: string;

package/dist/plugins/sui/mode/shared.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"shared.mjs","names":[],"sources":["../../../../src/plugins/sui/mode/shared.ts"],"sourcesContent":["// Shared shapes across mode builders.\n//\n// `SuiClient` is the resolved-value the plugin's `provides` tag\n// publishes — every consumer (Account, Coin, Wallet, Faucet,\n// Package, Codegen, Walrus/Seal/Deepbook fork variants) reads\n// THIS shape.\n//\n// Why one shape: distilled-doc finding — Sui's factory + builder\n// file is ~2000 LOC because the four per-network builders share\n// boilerplate (publish endpoints + fetch chain id + publish state)\n// but their bodies diverge in mode-specific ways. The redesign\n// bakes the seam in: the resolved value is uniform, the boot path\n// is mode-specific, and the admin surfaces narrow at the type\n// level (fork has `Sui.fork.advanceClock`; live does not).\n\nimport { Effect } from 'effect';\n\nimport type { SuiPluginError } from '../errors.ts';\nimport type { SuiSdkShim } from '../chain-probe.ts';\nimport type { ChainProbe } from '../../../contracts/chain-probe.ts';\nimport type { ImageRef } from '../../../contracts/container-runtime.ts';\nimport type { SuiProbeKey } from '../chain-probe.ts';\nimport type { ChainId } from '../../../substrate/brand.ts';\n\n/** Funds-ready strategy contributed by Sui. Mode-aware:\n *\n *   - local container — first call POSTs a real funding tx against\n *     the faucet, retrying on body-level {Failure} during the\n *     post-RPC / pre-fund window. Memoised after first success.\n *   - external w/ faucet — same as local container.\n *   - live testnet — same, but no retry needed (the public faucet\n *     is rate-limited differently).\n *   - live mainnet / faucet-less — trivially-succeeding no-op.\n *     (Architecture: \"no-faucet network has a trivially-succeeding\n *     funds-ready gate\" is a first-class property of the mode.)\n *   - fork — trivially-succeeding (impersonation funds, not\n *     faucet).\n *\n *  Distilled-doc opportunity: `Effect.cached` caches the first-call\n *  failure for the whole scope; add a manual-invalidation surface\n *  so a fork restart can re-probe. The shape below leaves room for\n *  that knob. */\nexport interface WaitForTransactionsReady {\n\treadonly wait: Effect.Effect<void, SuiPluginError>;\n\t/** Manual invalidation — clears the memoised result. The default\n\t *  built-in invalidates on plugin restart; this surface lets\n\t *  long-running supervisors invalidate without a full restart. */\n\treadonly invalidate: Effect.Effect<void>;\n}\n\n/** Fork admin surface — mode-narrowed. Only the fork-mode factory's\n *  resolved value carries this; local/local-rpc/live values have a\n *  type-level `null`.\n *\n *  Distilled-doc opportunity: today's `Fiber` handle is discarded\n *  at the auto-tick call site; the `autoTickHandle` field below\n *  preserves it for a future cadence-change surface. */\nexport interface ForkAdminSurface {\n\treadonly status: Effect.Effect<\n\t\t{ readonly checkpoint: string; readonly clock: number },\n\t\tSuiPluginError\n\t>;\n\treadonly advanceClock: (intervalMs: number) => Effect.Effect<void, SuiPluginError>;\n\treadonly advanceCheckpoint: Effect.Effect<void, SuiPluginError>;\n\treadonly impersonate: (\n\t\tsender: string,\n\t\ttx: unknown,\n\t) => Effect.Effect<\n\t\t{ readonly digest: string; readonly success: boolean; readonly raw: unknown },\n\t\tSuiPluginError\n\t>;\n}\n\n/** The resolved value Sui publishes via its resource id. */\nexport interface SuiClient {\n\t/** The SDK shim. Fork mode wraps this with the property-access\n\t *  blocklist (`fork-orchestration.wrapWithForkGuard`). */\n\treadonly sdk: SuiSdkShim;\n\t/** Host-reachable RPC URL for this resolved network. Local mode\n\t *  surfaces the router-fronted URL; direct boot/probe ports are\n\t *  available through `hostGateway` for sibling containers. */\n\treadonly rpcUrl: string;\n\t/** Host-reachable faucet base URL when this network has a faucet. */\n\treadonly faucetUrl: string | null;\n\t/** Faucet URL used by account funding strategies. Local mode keeps\n\t *  this on the direct validator port used by the funds-ready gate. */\n\treadonly fundingFaucetUrl: string | null;\n\t/** Host-reachable GraphQL URL when the mode exposes one. */\n\treadonly graphqlUrl: string | null;\n\t/** Container-reachable mirrors of the host URLs. Loopback hosts are\n\t *  rewritten to `host.docker.internal`; public URLs pass through. */\n\treadonly hostGateway: {\n\t\treadonly rpcUrl: string;\n\t\treadonly faucetUrl: string | null;\n\t\treadonly graphqlUrl: string | null;\n\t};\n\t/** Chain identity — downstream cache primitives fold this into\n\t *  their state-store keys so on-chain artifacts re-derive when\n\t *  the chain is wiped. Branded so consumers can hand it directly\n\t *  to `chainProbeCapabilityKey(chain)` / `faucetCapabilityKey(chain)`\n\t *  without a cast. */\n\treadonly chain: ChainId;\n\t/** Mode-aware funds-transferable gate; trivially-succeeding on\n\t *  faucet-less networks. */\n\treadonly waitForTransactionsReady: WaitForTransactionsReady;\n\t/** Schema-validated read surface. Folded into every consumer's\n\t *  context via `chain-probe:<chainId>` strategy lookup. */\n\treadonly chainProbe: ChainProbe<SuiProbeKey>;\n\t/** Fork-mode-only admin sub-surface. `null` for non-fork\n\t *  modes; the mode-narrowed factory namespace narrows this at\n\t *  the type level so consumers don't have to nullcheck. */\n\treadonly fork: ForkAdminSurface | null;\n\t/** Container image ref the Sui plugin built/pulled for its\n\t *  validator. Surfaced so cross-service consumers (Package's\n\t *  Move build, codegen's `summary` invocation) can spawn a\n\t *  one-shot container running the SAME sui binary without\n\t *  re-resolving the image. `null` for modes that have no\n\t *  in-stack container (external + live). */\n\treadonly buildImage: ImageRef | null;\n}\n\nexport const toDockerHostGatewayUrl = (url: string): string => {\n\tconst parsed = new URL(url);\n\tif (\n\t\tparsed.hostname === '127.0.0.1' ||\n\t\tparsed.hostname === 'localhost' ||\n\t\tparsed.hostname === '0.0.0.0' ||\n\t\tparsed.hostname === '::1' ||\n\t\tparsed.hostname === '[::1]'\n\t) {\n\t\tparsed.hostname = 'host.docker.internal';\n\t}\n\tconst rendered = parsed.toString();\n\treturn parsed.pathname === '/' && parsed.search === '' && parsed.hash === ''\n\t\t? rendered.slice(0, -1)\n\t\t: rendered;\n};\n"],"mappings":";;AAyHA,MAAa,0BAA0B,QAAwB;CAC9D,MAAM,SAAS,IAAI,IAAI,IAAI;AAC3B,KACC,OAAO,aAAa,eACpB,OAAO,aAAa,eACpB,OAAO,aAAa,aACpB,OAAO,aAAa,SACpB,OAAO,aAAa,QAEpB,QAAO,WAAW;CAEnB,MAAM,WAAW,OAAO,UAAU;AAClC,QAAO,OAAO,aAAa,OAAO,OAAO,WAAW,MAAM,OAAO,SAAS,KACvE,SAAS,MAAM,GAAG,GAAG,GACrB"}
+{"version":3,"file":"shared.mjs","names":[],"sources":["../../../../src/plugins/sui/mode/shared.ts"],"sourcesContent":["// Shared shapes across mode builders.\n//\n// `SuiClient` is the resolved-value the plugin's `provides` tag\n// publishes — every consumer (Account, Coin, Wallet, Faucet,\n// Package, Codegen, Walrus/Seal/Deepbook fork variants) reads\n// THIS shape.\n//\n// Why one shape: distilled-doc finding — Sui's factory + builder\n// file is ~2000 LOC because the four per-network builders share\n// boilerplate (publish endpoints + fetch chain id + publish state)\n// but their bodies diverge in mode-specific ways. The redesign\n// bakes the seam in: the resolved value is uniform, the boot path\n// is mode-specific, and the admin surfaces narrow at the type\n// level (fork has `Sui.fork.advanceClock`; live does not).\n\nimport { Effect } from 'effect';\n\nimport type { SuiPluginError } from '../errors.ts';\nimport type { SuiSdkShim } from '../chain-probe.ts';\nimport type { ChainProbe } from '../../../contracts/chain-probe.ts';\nimport type { ImageRef } from '../../../contracts/container-runtime.ts';\nimport type { SuiProbeKey } from '../chain-probe.ts';\nimport type { ChainId } from '../../../substrate/brand.ts';\n\n/** Funds-ready strategy contributed by Sui. Mode-aware:\n *\n *   - local container — first call POSTs a real funding tx against\n *     the faucet, retrying on body-level {Failure} during the\n *     post-RPC / pre-fund window. Memoised after first success.\n *   - external w/ faucet — same as local container.\n *   - live testnet — same, but no retry needed (the public faucet\n *     is rate-limited differently).\n *   - live mainnet / faucet-less — trivially-succeeding no-op.\n *     (Architecture: \"no-faucet network has a trivially-succeeding\n *     funds-ready gate\" is a first-class property of the mode.)\n *   - fork — trivially-succeeding (impersonation funds, not\n *     faucet).\n *\n *  Distilled-doc opportunity: `Effect.cached` caches the first-call\n *  failure for the whole scope; add a manual-invalidation surface\n *  so a fork restart can re-probe. The shape below leaves room for\n *  that knob. */\nexport interface WaitForTransactionsReady {\n\treadonly wait: Effect.Effect<void, SuiPluginError>;\n\t/** Manual invalidation — clears the memoised result. The default\n\t *  built-in invalidates on plugin restart; this surface lets\n\t *  long-running supervisors invalidate without a full restart. */\n\treadonly invalidate: Effect.Effect<void>;\n}\n\n/** Fork admin surface — mode-narrowed. Only the fork-mode factory's\n *  resolved value carries this; local/local-rpc/live values have a\n *  type-level `null`. */\nexport interface ForkAdminSurface {\n\treadonly status: Effect.Effect<\n\t\t{ readonly checkpoint: string; readonly clock: number },\n\t\tSuiPluginError\n\t>;\n\treadonly advanceClock: (intervalMs: number) => Effect.Effect<void, SuiPluginError>;\n\treadonly advanceCheckpoint: Effect.Effect<void, SuiPluginError>;\n\treadonly impersonate: (\n\t\tsender: string,\n\t\ttx: unknown,\n\t) => Effect.Effect<\n\t\t{ readonly digest: string; readonly success: boolean; readonly raw: unknown },\n\t\tSuiPluginError\n\t>;\n}\n\n/** The resolved value Sui publishes via its resource id. */\nexport interface SuiClient {\n\t/** The SDK shim. Fork mode wraps this with the property-access\n\t *  blocklist (`fork-orchestration.wrapWithForkGuard`). */\n\treadonly sdk: SuiSdkShim;\n\t/** Host-reachable RPC URL for this resolved network. Local mode\n\t *  surfaces the router-fronted URL; direct boot/probe ports are\n\t *  available through `hostGateway` for sibling containers. */\n\treadonly rpcUrl: string;\n\t/** Host-reachable faucet base URL when this network has a faucet. */\n\treadonly faucetUrl: string | null;\n\t/** Faucet URL used by account funding strategies. Local mode keeps\n\t *  this on the direct validator port used by the funds-ready gate. */\n\treadonly fundingFaucetUrl: string | null;\n\t/** Host-reachable GraphQL URL when the mode exposes one. */\n\treadonly graphqlUrl: string | null;\n\t/** Container-reachable mirrors of the host URLs. Loopback hosts are\n\t *  rewritten to `host.docker.internal`; public URLs pass through. */\n\treadonly hostGateway: {\n\t\treadonly rpcUrl: string;\n\t\treadonly faucetUrl: string | null;\n\t\treadonly graphqlUrl: string | null;\n\t};\n\t/** Chain identity — downstream cache primitives fold this into\n\t *  their state-store keys so on-chain artifacts re-derive when\n\t *  the chain is wiped. Branded so consumers can hand it directly\n\t *  to `chainProbeCapabilityKey(chain)` / `faucetCapabilityKey(chain)`\n\t *  without a cast. */\n\treadonly chain: ChainId;\n\t/** Mode-aware funds-transferable gate; trivially-succeeding on\n\t *  faucet-less networks. */\n\treadonly waitForTransactionsReady: WaitForTransactionsReady;\n\t/** Schema-validated read surface. Folded into every consumer's\n\t *  context via `chain-probe:<chainId>` strategy lookup. */\n\treadonly chainProbe: ChainProbe<SuiProbeKey>;\n\t/** Fork-mode-only admin sub-surface. `null` for non-fork\n\t *  modes; the mode-narrowed factory namespace narrows this at\n\t *  the type level so consumers don't have to nullcheck. */\n\treadonly fork: ForkAdminSurface | null;\n\t/** Container image ref the Sui plugin built/pulled for its\n\t *  validator. Surfaced so cross-service consumers (Package's\n\t *  Move build, codegen's `summary` invocation) can spawn a\n\t *  one-shot container running the SAME sui binary without\n\t *  re-resolving the image. `null` for modes that have no\n\t *  in-stack container (external + live). */\n\treadonly buildImage: ImageRef | null;\n}\n\nexport const toDockerHostGatewayUrl = (url: string): string => {\n\tconst parsed = new URL(url);\n\tif (\n\t\tparsed.hostname === '127.0.0.1' ||\n\t\tparsed.hostname === 'localhost' ||\n\t\tparsed.hostname === '0.0.0.0' ||\n\t\tparsed.hostname === '::1' ||\n\t\tparsed.hostname === '[::1]'\n\t) {\n\t\tparsed.hostname = 'host.docker.internal';\n\t}\n\tconst rendered = parsed.toString();\n\treturn parsed.pathname === '/' && parsed.search === '' && parsed.hash === ''\n\t\t? rendered.slice(0, -1)\n\t\t: rendered;\n};\n"],"mappings":";;AAqHA,MAAa,0BAA0B,QAAwB;CAC9D,MAAM,SAAS,IAAI,IAAI,IAAI;AAC3B,KACC,OAAO,aAAa,eACpB,OAAO,aAAa,eACpB,OAAO,aAAa,aACpB,OAAO,aAAa,SACpB,OAAO,aAAa,QAEpB,QAAO,WAAW;CAEnB,MAAM,WAAW,OAAO,UAAU;AAClC,QAAO,OAAO,aAAa,OAAO,OAAO,WAAW,MAAM,OAAO,SAAS,KACvE,SAAS,MAAM,GAAG,GAAG,GACrB"}

package/dist/plugins/sui/mode/spec.d.mts

@@ -60,6 +60,22 @@ interface SuiLiveOptions extends SuiCommonOptions {
    *  Omit to probe the RPC endpoint. */
   readonly chain?: string;
 }
+/** Fork-mode faucet config. Funds test accounts by impersonating a
+ *  large-reserve "whale" address on the forked upstream and transferring
+ *  SUI from it — there is no real faucet on a fork. Enabled by default
+ *  with a per-upstream default whale; the whale is auto-added to the
+ *  fork seed and validated at boot. */
+interface SuiForkFaucetOptions {
+  /** Address to impersonate as the funding source. Defaults to a known
+   *  large-reserve address for the upstream (see `FORK_DEFAULT_WHALE`).
+   *  Must hold a large single SUI coin in the fork. */
+  readonly whale?: string;
+  /** Upper bound on a single funding request (MIST). Guards against a
+   *  typo draining the whale. Default `1_000_000_000_000n` (1000 SUI). */
+  readonly perRequestCapMist?: bigint;
+  /** Disable the fork faucet entirely (default: enabled). */
+  readonly enabled?: boolean;
+}
 /** Fork mode — sui-fork binary mirroring a real chain at a
  *  checkpoint. */
 interface SuiForkOptions extends SuiCommonOptions {
@@ -86,6 +102,8 @@ interface SuiForkOptions extends SuiCommonOptions {
   readonly autoTick?: boolean | {
     readonly intervalMs: number;
   };
+  /** Impersonation-based faucet for funding test accounts. */
+  readonly faucet?: SuiForkFaucetOptions;
 }
 /** The discriminated union of all four mode option records. */
 type SuiOptions = SuiLocalOptions | SuiLocalRpcOptions | SuiLiveOptions | SuiForkOptions;

package/dist/plugins/sui/move-summary-runner.mjs

@@ -0,0 +1,207 @@
+import { capture } from "../../substrate/runtime/observability/subprocess-capture.mjs";
+import { ContainerRuntimeService } from "../../runtime/docker/service.mjs";
+import { CodegenBindingsFailed } from "../../orchestrators/codegen/errors.mjs";
+import { MoveSummaryRunnerService } from "../../orchestrators/codegen/bindings.mjs";
+import { copyLocalMoveDeps, shellQuote, suiCliImageBuildContext } from "../../substrate/runtime/sui-move-build/index.mjs";
+import { Effect, Layer } from "effect";
+import { basename, dirname, join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { cp, mkdir, mkdtemp, rm } from "node:fs/promises";
+//#region src/plugins/sui/move-summary-runner.ts
+const layerSuiMoveSummaryRunnerDocker = Layer.effect(MoveSummaryRunnerService, Effect.gen(function* () {
+	const runtime = yield* ContainerRuntimeService;
+	return MoveSummaryRunnerService.of({ runSummary: (input) => runSummaryViaDocker(runtime, input) });
+}));
+Layer.effect(MoveSummaryRunnerService, Effect.gen(function* () {
+	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+	return MoveSummaryRunnerService.of({ runSummary: ({ packageName, sourcePath }) => Effect.gen(function* () {
+		const scratchDir = yield* Effect.tryPromise({
+			try: () => mkdtemp(join(tmpdir(), "devstack-move-summary-")),
+			catch: (cause) => new CodegenBindingsFailed({
+				package: packageName,
+				sourcePath,
+				reason: "summary-failed",
+				hint: "Unable to create a temporary directory for Move summary output.",
+				cause
+			})
+		});
+		const summaryPath = join(scratchDir, "package");
+		const stagedPkg = join(scratchDir, "src");
+		const cleanupScratch = Effect.promise(() => rm(scratchDir, {
+			recursive: true,
+			force: true
+		})).pipe(Effect.ignore);
+		return {
+			packageName,
+			sourcePath,
+			summaryPath,
+			cleanupPath: scratchDir,
+			summaryJson: parseSummaryStdout((yield* Effect.gen(function* () {
+				yield* Effect.tryPromise({
+					try: async () => {
+						await mkdir(summaryPath, { recursive: true });
+						await cp(sourcePath, stagedPkg, { recursive: true });
+						await copyLocalMoveDeps(sourcePath, stagedPkg, dirname(stagedPkg));
+					},
+					catch: (cause) => new CodegenBindingsFailed({
+						package: packageName,
+						sourcePath,
+						reason: "summary-failed",
+						hint: "Unable to stage a disposable copy of the Move package for summary.",
+						cause
+					})
+				});
+				return yield* capture(spawner, ChildProcess.make("sui", [
+					"move",
+					"summary",
+					"--path",
+					".",
+					"--install-dir",
+					join(scratchDir, "install"),
+					"--output-directory",
+					join(summaryPath, "package_summaries")
+				], { cwd: stagedPkg }), {
+					op: `sui move summary (${sourcePath})`,
+					nonZeroIsFailure: true,
+					stdoutTruncate: Infinity,
+					stderrTruncate: 4e3
+				}).pipe(Effect.mapError((cause) => new CodegenBindingsFailed({
+					package: packageName,
+					sourcePath,
+					reason: "summary-failed",
+					hint: "Install the Sui CLI and ensure this Move package can run `sui move summary`.",
+					cause
+				})));
+			}).pipe(Effect.tapError(() => cleanupScratch))).stdout)
+		};
+	}) });
+}));
+const runSummaryViaDocker = (runtime, input) => Effect.scoped(Effect.gen(function* () {
+	const scratchDir = yield* makeSummaryScratch(input);
+	const summaryPath = join(scratchDir, "package");
+	const cleanupScratch = Effect.promise(() => rm(scratchDir, {
+		recursive: true,
+		force: true
+	})).pipe(Effect.ignore);
+	const result = yield* Effect.gen(function* () {
+		yield* prepareSummaryPackage(summaryPath, input);
+		const image = input.buildImage ?? (yield* resolveDefaultSummaryImage(runtime, input));
+		const moveHome = join(homedir(), ".move");
+		yield* ensureMoveHome(moveHome, input);
+		const packageDir = basename(input.sourcePath);
+		const stagedRoot = join(scratchDir, "src");
+		yield* stageSummarySource(input, join(stagedRoot, packageDir));
+		const command = [
+			"set -e",
+			`cleanup_summary() { status=\$?; chmod -R a+rwX /summary /workspace 2>/dev/null || true; chown -R ${typeof process.getuid === "function" ? process.getuid() : 0}:${typeof process.getgid === "function" ? process.getgid() : 0} /summary /workspace 2>/dev/null || true; exit "\$status"; }`,
+			"trap cleanup_summary EXIT",
+			"mkdir -p /summary/package_summaries",
+			`sui move summary --path /workspace/${shellQuote(packageDir)} --install-dir /tmp/devstack-move-summary-install --output-directory /summary/package_summaries`
+		].join("; ");
+		const run = yield* runtime.runOneShot({
+			image,
+			entrypoint: "sh",
+			argv: ["-c", command],
+			mounts: [
+				{
+					source: stagedRoot,
+					target: "/workspace"
+				},
+				{
+					source: summaryPath,
+					target: "/summary"
+				},
+				{
+					source: moveHome,
+					target: "/root/.move"
+				}
+			],
+			timeoutMillis: 5 * 6e4
+		}).pipe(Effect.mapError((cause) => new CodegenBindingsFailed({
+			package: input.packageName,
+			sourcePath: input.sourcePath,
+			reason: "summary-failed",
+			hint: "Docker runtime failed while running `sui move summary` for bindings codegen.",
+			cause
+		})));
+		if (run.exitCode !== 0) return yield* Effect.fail(new CodegenBindingsFailed({
+			package: input.packageName,
+			sourcePath: input.sourcePath,
+			reason: "summary-failed",
+			hint: `sui move summary exited ${run.exitCode}. stderr: ${run.stderr || "(empty)"}; stdout tail: ${run.stdout.slice(-400) || "(empty)"}`
+		}));
+		return run;
+	}).pipe(Effect.tapError(() => cleanupScratch));
+	return {
+		packageName: input.packageName,
+		sourcePath: input.sourcePath,
+		summaryPath,
+		cleanupPath: scratchDir,
+		summaryJson: parseSummaryStdout(result.stdout)
+	};
+}));
+const makeSummaryScratch = (input) => Effect.tryPromise({
+	try: () => mkdtemp(join(tmpdir(), "devstack-move-summary-")),
+	catch: (cause) => new CodegenBindingsFailed({
+		package: input.packageName,
+		sourcePath: input.sourcePath,
+		reason: "summary-failed",
+		hint: "Unable to create a temporary directory for Move summary output.",
+		cause
+	})
+});
+const prepareSummaryPackage = (summaryPath, input) => Effect.tryPromise({
+	try: () => mkdir(summaryPath, { recursive: true }).then(() => void 0),
+	catch: (cause) => new CodegenBindingsFailed({
+		package: input.packageName,
+		sourcePath: input.sourcePath,
+		reason: "summary-failed",
+		hint: "Unable to prepare a temporary Move summary output directory.",
+		cause
+	})
+});
+const stageSummarySource = (input, stagedPkg) => Effect.tryPromise({
+	try: async () => {
+		await mkdir(dirname(stagedPkg), { recursive: true });
+		await cp(input.sourcePath, stagedPkg, { recursive: true });
+		await copyLocalMoveDeps(input.sourcePath, stagedPkg, dirname(stagedPkg));
+	},
+	catch: (cause) => new CodegenBindingsFailed({
+		package: input.packageName,
+		sourcePath: input.sourcePath,
+		reason: "summary-failed",
+		hint: "Unable to stage a disposable copy of the Move package for summary.",
+		cause
+	})
+});
+const resolveDefaultSummaryImage = (runtime, input) => runtime.ensureImage(suiCliImageBuildContext()).pipe(Effect.mapError((cause) => new CodegenBindingsFailed({
+	package: input.packageName,
+	sourcePath: input.sourcePath,
+	reason: "summary-failed",
+	hint: "Unable to resolve the Sui CLI container image for Move bindings codegen.",
+	cause
+})));
+const ensureMoveHome = (moveHome, input) => Effect.tryPromise({
+	try: () => mkdir(moveHome, { recursive: true }),
+	catch: (cause) => new CodegenBindingsFailed({
+		package: input.packageName,
+		sourcePath: input.sourcePath,
+		reason: "summary-failed",
+		hint: `Unable to create Move cache mount source "${moveHome}".`,
+		cause
+	})
+}).pipe(Effect.asVoid);
+const parseSummaryStdout = (stdout) => {
+	const trimmed = stdout.trim();
+	if (trimmed.length === 0) return null;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return trimmed;
+	}
+};
+//#endregion
+export { layerSuiMoveSummaryRunnerDocker };
+
+//# sourceMappingURL=move-summary-runner.mjs.map