@mysten-incubation/devstack 0.1.0 → 0.2.0

package/dist/plugins/sui/mode/live.mjs

@@ -1,7 +1,5 @@
-import { SpanAttr } from "../../../substrate/runtime/observability/spans.mjs";
 import { suiPluginError } from "../errors.mjs";
 import { formatUnknownError } from "../../../substrate/runtime/format-unknown-error.mjs";
-import { SuiSpans } from "../spans.mjs";
 import { assembleSuiClient, buildWaitForTransactionsReady, fetchChainId, makeResolvedNetwork, noopWaitForTransactionsReady } from "./shared-boot.mjs";
 import { Duration, Effect } from "effect";
 import { SuiGrpcClient } from "@mysten/sui/grpc";
@@ -51,11 +49,6 @@ const resolveEndpoints = (opts) => {
 /** Build the live-mode boot Effect. */
 const bootLiveMode = (opts) => Effect.gen(function* () {
 	const endpoints = yield* resolveEndpoints(opts);
-	yield* Effect.annotateCurrentSpan({
-		[SuiSpans.liveNetwork]: opts.network,
-		[SuiSpans.liveRpcUrl]: endpoints.rpcUrl,
-		...endpoints.faucetUrl !== void 0 ? { [SuiSpans.liveFaucetUrl]: endpoints.faucetUrl } : {}
-	});
 	const sdkClient = yield* Effect.try({
 		try: () => new SuiGrpcClient({
 			baseUrl: endpoints.rpcUrl,
@@ -63,14 +56,11 @@ const bootLiveMode = (opts) => Effect.gen(function* () {
 		}),
 		catch: (cause) => suiPluginError("chain-id-fetch", `sui live mode: SuiGrpcClient construction failed for rpcUrl=${endpoints.rpcUrl}: ${formatUnknownError(cause)}`, cause)
 	});
-	const chain = opts.chain ?? (yield* fetchChainId(sdkClient, {
-		timeout: opts.readyTimeout ?? DEFAULT_LIVE_CHAIN_ID_TIMEOUT,
-		span: "devstack.plugin.sui.live.fetchChainId"
-	}));
+	const chainId = opts.chainId ?? (yield* fetchChainId(sdkClient, { timeout: opts.readyTimeout ?? DEFAULT_LIVE_CHAIN_ID_TIMEOUT }));
 	const waitForTransactionsReady = endpoints.faucetUrl !== void 0 ? yield* buildWaitForTransactionsReady(endpoints.faucetUrl) : noopWaitForTransactionsReady;
 	const { client } = yield* assembleSuiClient({
 		sdkClient,
-		chain,
+		chainId,
 		rpcUrl: endpoints.rpcUrl,
 		...endpoints.faucetUrl !== void 0 ? { faucetUrl: endpoints.faucetUrl } : {},
 		...endpoints.graphqlUrl !== void 0 ? { graphqlUrl: endpoints.graphqlUrl } : {},
@@ -79,7 +69,7 @@ const bootLiveMode = (opts) => Effect.gen(function* () {
 	return {
 		resolved: makeResolvedNetwork({
 			mode: "live",
-			chain,
+			chainId,
 			rpc: endpoints.rpcUrl,
 			source: opts.rpcUrl === void 0 && opts.faucetUrl === void 0 && opts.graphqlUrl === void 0 ? "default" : "config",
 			...endpoints.faucetUrl !== void 0 ? { faucet: endpoints.faucetUrl } : {},
@@ -87,10 +77,7 @@ const bootLiveMode = (opts) => Effect.gen(function* () {
 		}),
 		client
 	};
-}).pipe(Effect.withSpan("devstack.plugin.sui.live.boot", { attributes: {
-	[SpanAttr.plugin]: "sui",
-	[SuiSpans.mode]: "live"
-} }));
+});
 //#endregion
 export { bootLiveMode };
 

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

@@ -1 +1 @@
-{"version":3,"file":"live.mjs","names":[],"sources":["../../../../src/plugins/sui/mode/live.ts"],"sourcesContent":["// Sui plugin — live mode (testnet / mainnet / devnet / custom).\n//\n// Wraps a public or caller-provided Sui RPC. Testnet has a faucet;\n// mainnet has none; custom may or may not.\n//\n// What's hard:\n//   - No ready probe is meaningful (the public chain is always\n//     up); chain-id fetch IS the only sentinel with a bounded\n//     timeout.\n//   - Faucet-less networks (mainnet) need a \"no-op\" funds-ready\n//     gate so downstream callers don't have to branch.\n//   - The KnownPackage substrate contributions are wired here so\n//     wallet-standard / MVR / known-deployment lookups find the\n//     right published ids.\n//\n// Live mode contributes a `ChainProbe` and a `Codegenable` — but NO\n// managed container, NO `Routable`, and the\n// build container is forced to the host CLI path (no in-stack\n// build image). The latter is flagged in the distilled-doc Open\n// questions as a candidate to revisit.\n//\n// Boot sequence:\n//\n//   1. Resolve `rpcUrl` / `faucetUrl` / `graphqlUrl` from caller\n//      overrides, then fall back to `LIVE_DEFAULTS` for known nets.\n//      `custom` requires `rpcUrl` — surface a typed refusal if\n//      omitted.\n//   2. Construct `SuiGrpcClient` against the resolved URL with the\n//      matching `network:` discriminator (so MVR / wallet-standard\n//      hints route correctly).\n//   3. Fetch chain id (the only readiness sentinel for live).\n//   4. Build `waitForTransactionsReady`:\n//        - mainnet: trivially-succeeding no-op (no faucet exists).\n//        - testnet/devnet/custom-with-faucet: real HTTP probe.\n//        - custom-without-faucet: no-op.\n\nimport { Duration, Effect, type Scope } from 'effect';\n\nimport { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport { SpanAttr } from '../../../substrate/runtime/observability/spans.ts';\nimport { suiPluginError, type SuiConfigError, type SuiPluginError } 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 type { SuiClient } from './shared.ts';\nimport {\n\tassembleSuiClient,\n\tbuildWaitForTransactionsReady,\n\tfetchChainId,\n\tmakeResolvedNetwork,\n\tnoopWaitForTransactionsReady,\n} from './shared-boot.ts';\nimport type { SuiLiveOptions } from './spec.ts';\n\n/** Default chain-id fetch timeout for live RPCs. */\nexport const DEFAULT_LIVE_CHAIN_ID_TIMEOUT = Duration.seconds(30);\n\n/** Default RPC endpoints per known network. `custom` requires the\n *  caller to supply `rpcUrl`. */\nexport const LIVE_DEFAULTS = {\n\ttestnet: {\n\t\trpcUrl: 'https://fullnode.testnet.sui.io:443',\n\t\tfaucetUrl: 'https://faucet.testnet.sui.io',\n\t\tgraphqlUrl: 'https://sui-testnet.mystenlabs.com/graphql',\n\t},\n\tmainnet: {\n\t\trpcUrl: 'https://fullnode.mainnet.sui.io:443',\n\t\tfaucetUrl: undefined as string | undefined,\n\t\tgraphqlUrl: 'https://sui-mainnet.mystenlabs.com/graphql',\n\t},\n\tdevnet: {\n\t\trpcUrl: 'https://fullnode.devnet.sui.io:443',\n\t\tfaucetUrl: 'https://faucet.devnet.sui.io',\n\t\tgraphqlUrl: undefined as string | undefined,\n\t},\n} as const;\n\n/** Resolved live-mode boot artifacts. */\nexport interface LiveModeBootResult {\n\treadonly resolved: ResolvedSuiNetwork;\n\treadonly client: SuiClient;\n}\n\ninterface ResolvedLiveEndpoints {\n\treadonly rpcUrl: string;\n\treadonly faucetUrl: string | undefined;\n\treadonly graphqlUrl: string | undefined;\n\treadonly sdkNetwork: 'mainnet' | 'testnet' | 'devnet' | 'localnet';\n}\n\n/** Resolve endpoints from caller overrides + the known-network table.\n *  Order: caller-provided wins; otherwise the LIVE_DEFAULTS row for\n *  the requested network. `custom` MUST carry an explicit `rpcUrl`. */\nconst resolveEndpoints = (\n\topts: SuiLiveOptions,\n): Effect.Effect<ResolvedLiveEndpoints, SuiPluginError> => {\n\tif (opts.network === 'custom') {\n\t\tif (opts.rpcUrl === undefined) {\n\t\t\treturn Effect.fail(\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t`sui live mode: network='custom' requires opts.rpcUrl. ` +\n\t\t\t\t\t\t`Use suiFor(network).live.custom({rpcUrl: ...}) or pass network='testnet'|'mainnet'|'devnet' to use the built-in defaults.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\treturn Effect.succeed({\n\t\t\trpcUrl: opts.rpcUrl,\n\t\t\tfaucetUrl: opts.faucetUrl,\n\t\t\tgraphqlUrl: opts.graphqlUrl,\n\t\t\t// SDK accepts arbitrary strings under the `(string & {})`\n\t\t\t// branch; `localnet` is the closest semantic for a custom\n\t\t\t// caller-defined live target.\n\t\t\tsdkNetwork: 'localnet',\n\t\t});\n\t}\n\tconst defaults = LIVE_DEFAULTS[opts.network];\n\treturn Effect.succeed({\n\t\trpcUrl: opts.rpcUrl ?? defaults.rpcUrl,\n\t\tfaucetUrl: opts.faucetUrl ?? defaults.faucetUrl,\n\t\tgraphqlUrl: opts.graphqlUrl ?? defaults.graphqlUrl,\n\t\tsdkNetwork: opts.network,\n\t});\n};\n\n/** Build the live-mode boot Effect. */\nexport const bootLiveMode = (\n\topts: SuiLiveOptions,\n): Effect.Effect<LiveModeBootResult, SuiPluginError | SuiConfigError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// ----- 1. Resolve endpoints ------------------------------------------\n\t\tconst endpoints = yield* resolveEndpoints(opts);\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[SuiSpans.liveNetwork]: opts.network,\n\t\t\t[SuiSpans.liveRpcUrl]: endpoints.rpcUrl,\n\t\t\t...(endpoints.faucetUrl !== undefined\n\t\t\t\t? { [SuiSpans.liveFaucetUrl]: endpoints.faucetUrl }\n\t\t\t\t: {}),\n\t\t});\n\n\t\t// ----- 2. Construct the grpc client ----------------------------------\n\t\tconst sdkClient = yield* Effect.try({\n\t\t\ttry: () =>\n\t\t\t\tnew SuiGrpcClient({\n\t\t\t\t\tbaseUrl: endpoints.rpcUrl,\n\t\t\t\t\tnetwork: endpoints.sdkNetwork,\n\t\t\t\t}),\n\t\t\tcatch: (cause): SuiPluginError =>\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t`sui live mode: SuiGrpcClient construction failed for rpcUrl=${endpoints.rpcUrl}: ${formatUnknownError(cause)}`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t});\n\n\t\t// ----- 3. Resolve chain id -------------------------------------------\n\t\tconst chain =\n\t\t\topts.chain ??\n\t\t\t(yield* fetchChainId(sdkClient, {\n\t\t\t\ttimeout: opts.readyTimeout ?? DEFAULT_LIVE_CHAIN_ID_TIMEOUT,\n\t\t\t\tspan: 'devstack.plugin.sui.live.fetchChainId',\n\t\t\t}));\n\n\t\t// ----- 4. Build waitForTransactionsReady -----------------------------\n\t\t// Mainnet: no faucet exists, gate is a no-op. testnet/devnet/\n\t\t// custom-with-faucet: real HTTP probe (rate-limited by upstream,\n\t\t// but the wire shape is identical to localnet).\n\t\tconst waitForTransactionsReady =\n\t\t\tendpoints.faucetUrl !== undefined\n\t\t\t\t? yield* buildWaitForTransactionsReady(endpoints.faucetUrl)\n\t\t\t\t: noopWaitForTransactionsReady;\n\n\t\t// ----- 5. Assemble + return ------------------------------------------\n\t\tconst { client } = yield* assembleSuiClient({\n\t\t\tsdkClient,\n\t\t\tchain,\n\t\t\trpcUrl: endpoints.rpcUrl,\n\t\t\t...(endpoints.faucetUrl !== undefined ? { faucetUrl: endpoints.faucetUrl } : {}),\n\t\t\t...(endpoints.graphqlUrl !== undefined ? { graphqlUrl: endpoints.graphqlUrl } : {}),\n\t\t\twaitForTransactionsReady,\n\t\t});\n\t\tconst resolved = makeResolvedNetwork({\n\t\t\tmode: 'live',\n\t\t\tchain,\n\t\t\trpc: endpoints.rpcUrl,\n\t\t\t// `source: 'default'` when we pulled from LIVE_DEFAULTS;\n\t\t\t// `'config'` when the caller passed an override. The\n\t\t\t// distinction matters for the doctor's \"where did this\n\t\t\t// value come from\" surface.\n\t\t\tsource:\n\t\t\t\topts.rpcUrl === undefined && opts.faucetUrl === undefined && opts.graphqlUrl === undefined\n\t\t\t\t\t? 'default'\n\t\t\t\t\t: 'config',\n\t\t\t...(endpoints.faucetUrl !== undefined ? { faucet: endpoints.faucetUrl } : {}),\n\t\t\t...(endpoints.graphqlUrl !== undefined ? { graphql: endpoints.graphqlUrl } : {}),\n\t\t});\n\n\t\treturn { resolved, client };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.sui.live.boot', {\n\t\t\tattributes: { [SpanAttr.plugin]: 'sui', [SuiSpans.mode]: 'live' },\n\t\t}),\n\t);\n"],"mappings":";;;;;;;;;AAwDA,MAAa,gCAAgC,SAAS,QAAQ,GAAG;;;AAIjE,MAAa,gBAAgB;CAC5B,SAAS;EACR,QAAQ;EACR,WAAW;EACX,YAAY;EACZ;CACD,SAAS;EACR,QAAQ;EACR,WAAW,KAAA;EACX,YAAY;EACZ;CACD,QAAQ;EACP,QAAQ;EACR,WAAW;EACX,YAAY,KAAA;EACZ;CACD;;;;AAkBD,MAAM,oBACL,SAC0D;AAC1D,KAAI,KAAK,YAAY,UAAU;AAC9B,MAAI,KAAK,WAAW,KAAA,EACnB,QAAO,OAAO,KACb,eACC,kBACA,kLAEA,CACD;AAEF,SAAO,OAAO,QAAQ;GACrB,QAAQ,KAAK;GACb,WAAW,KAAK;GAChB,YAAY,KAAK;GAIjB,YAAY;GACZ,CAAC;;CAEH,MAAM,WAAW,cAAc,KAAK;AACpC,QAAO,OAAO,QAAQ;EACrB,QAAQ,KAAK,UAAU,SAAS;EAChC,WAAW,KAAK,aAAa,SAAS;EACtC,YAAY,KAAK,cAAc,SAAS;EACxC,YAAY,KAAK;EACjB,CAAC;;;AAIH,MAAa,gBACZ,SAEA,OAAO,IAAI,aAAa;CAEvB,MAAM,YAAY,OAAO,iBAAiB,KAAK;AAE/C,QAAO,OAAO,oBAAoB;GAChC,SAAS,cAAc,KAAK;GAC5B,SAAS,aAAa,UAAU;EACjC,GAAI,UAAU,cAAc,KAAA,IACzB,GAAG,SAAS,gBAAgB,UAAU,WAAW,GACjD,EAAE;EACL,CAAC;CAGF,MAAM,YAAY,OAAO,OAAO,IAAI;EACnC,WACC,IAAI,cAAc;GACjB,SAAS,UAAU;GACnB,SAAS,UAAU;GACnB,CAAC;EACH,QAAQ,UACP,eACC,kBACA,+DAA+D,UAAU,OAAO,IAAI,mBAAmB,MAAM,IAC7G,MACA;EACF,CAAC;CAGF,MAAM,QACL,KAAK,UACJ,OAAO,aAAa,WAAW;EAC/B,SAAS,KAAK,gBAAgB;EAC9B,MAAM;EACN,CAAC;CAMH,MAAM,2BACL,UAAU,cAAc,KAAA,IACrB,OAAO,8BAA8B,UAAU,UAAU,GACzD;CAGJ,MAAM,EAAE,WAAW,OAAO,kBAAkB;EAC3C;EACA;EACA,QAAQ,UAAU;EAClB,GAAI,UAAU,cAAc,KAAA,IAAY,EAAE,WAAW,UAAU,WAAW,GAAG,EAAE;EAC/E,GAAI,UAAU,eAAe,KAAA,IAAY,EAAE,YAAY,UAAU,YAAY,GAAG,EAAE;EAClF;EACA,CAAC;AAiBF,QAAO;EAAE,UAhBQ,oBAAoB;GACpC,MAAM;GACN;GACA,KAAK,UAAU;GAKf,QACC,KAAK,WAAW,KAAA,KAAa,KAAK,cAAc,KAAA,KAAa,KAAK,eAAe,KAAA,IAC9E,YACA;GACJ,GAAI,UAAU,cAAc,KAAA,IAAY,EAAE,QAAQ,UAAU,WAAW,GAAG,EAAE;GAC5E,GAAI,UAAU,eAAe,KAAA,IAAY,EAAE,SAAS,UAAU,YAAY,GAAG,EAAE;GAC/E,CAEgB;EAAE;EAAQ;EAC1B,CAAC,KACF,OAAO,SAAS,iCAAiC,EAChD,YAAY;EAAG,SAAS,SAAS;EAAQ,SAAS,OAAO;CAAQ,EACjE,CAAC,CACF"}
+{"version":3,"file":"live.mjs","names":[],"sources":["../../../../src/plugins/sui/mode/live.ts"],"sourcesContent":["// Sui plugin — live mode (testnet / mainnet / devnet / custom).\n//\n// Wraps a public or caller-provided Sui RPC. Testnet has a faucet;\n// mainnet has none; custom may or may not.\n//\n// What's hard:\n//   - No ready probe is meaningful (the public chain is always\n//     up); chain-id fetch IS the only sentinel with a bounded\n//     timeout.\n//   - Faucet-less networks (mainnet) need a \"no-op\" funds-ready\n//     gate so downstream callers don't have to branch.\n//   - The KnownPackage substrate contributions are wired here so\n//     wallet-standard / MVR / known-deployment lookups find the\n//     right published ids.\n//\n// Live mode contributes a `ChainProbe` and a `Codegenable` — but NO\n// managed container, NO `Routable`, and the\n// build container is forced to the host CLI path (no in-stack\n// build image). The latter is flagged in the distilled-doc Open\n// questions as a candidate to revisit.\n//\n// Boot sequence:\n//\n//   1. Resolve `rpcUrl` / `faucetUrl` / `graphqlUrl` from caller\n//      overrides, then fall back to `LIVE_DEFAULTS` for known nets.\n//      `custom` requires `rpcUrl` — surface a typed refusal if\n//      omitted.\n//   2. Construct `SuiGrpcClient` against the resolved URL with the\n//      matching `network:` discriminator (so MVR / wallet-standard\n//      hints route correctly).\n//   3. Fetch chain id (the only readiness sentinel for live).\n//   4. Build `waitForTransactionsReady`:\n//        - mainnet: trivially-succeeding no-op (no faucet exists).\n//        - testnet/devnet/custom-with-faucet: real HTTP probe.\n//        - custom-without-faucet: no-op.\n\nimport { Duration, Effect, type Scope } from 'effect';\n\nimport { SuiGrpcClient } from '@mysten/sui/grpc';\n\nimport { suiPluginError, type SuiConfigError, type SuiPluginError } from '../errors.ts';\nimport { formatUnknownError } from '../../../substrate/runtime/format-unknown-error.ts';\nimport type { ResolvedSuiNetwork } from '../network-resolver.ts';\nimport type { SuiClient } from './shared.ts';\nimport {\n\tassembleSuiClient,\n\tbuildWaitForTransactionsReady,\n\tfetchChainId,\n\tmakeResolvedNetwork,\n\tnoopWaitForTransactionsReady,\n} from './shared-boot.ts';\nimport type { SuiLiveOptions } from './spec.ts';\n\n/** Default chain-id fetch timeout for live RPCs. */\nexport const DEFAULT_LIVE_CHAIN_ID_TIMEOUT = Duration.seconds(30);\n\n/** Default RPC endpoints per known network. `custom` requires the\n *  caller to supply `rpcUrl`. */\nexport const LIVE_DEFAULTS = {\n\ttestnet: {\n\t\trpcUrl: 'https://fullnode.testnet.sui.io:443',\n\t\tfaucetUrl: 'https://faucet.testnet.sui.io',\n\t\tgraphqlUrl: 'https://sui-testnet.mystenlabs.com/graphql',\n\t},\n\tmainnet: {\n\t\trpcUrl: 'https://fullnode.mainnet.sui.io:443',\n\t\tfaucetUrl: undefined as string | undefined,\n\t\tgraphqlUrl: 'https://sui-mainnet.mystenlabs.com/graphql',\n\t},\n\tdevnet: {\n\t\trpcUrl: 'https://fullnode.devnet.sui.io:443',\n\t\tfaucetUrl: 'https://faucet.devnet.sui.io',\n\t\tgraphqlUrl: undefined as string | undefined,\n\t},\n} as const;\n\n/** Resolved live-mode boot artifacts. */\nexport interface LiveModeBootResult {\n\treadonly resolved: ResolvedSuiNetwork;\n\treadonly client: SuiClient;\n}\n\ninterface ResolvedLiveEndpoints {\n\treadonly rpcUrl: string;\n\treadonly faucetUrl: string | undefined;\n\treadonly graphqlUrl: string | undefined;\n\treadonly sdkNetwork: 'mainnet' | 'testnet' | 'devnet' | 'localnet';\n}\n\n/** Resolve endpoints from caller overrides + the known-network table.\n *  Order: caller-provided wins; otherwise the LIVE_DEFAULTS row for\n *  the requested network. `custom` MUST carry an explicit `rpcUrl`. */\nconst resolveEndpoints = (\n\topts: SuiLiveOptions,\n): Effect.Effect<ResolvedLiveEndpoints, SuiPluginError> => {\n\tif (opts.network === 'custom') {\n\t\tif (opts.rpcUrl === undefined) {\n\t\t\treturn Effect.fail(\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t`sui live mode: network='custom' requires opts.rpcUrl. ` +\n\t\t\t\t\t\t`Use suiFor(network).live.custom({rpcUrl: ...}) or pass network='testnet'|'mainnet'|'devnet' to use the built-in defaults.`,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\treturn Effect.succeed({\n\t\t\trpcUrl: opts.rpcUrl,\n\t\t\tfaucetUrl: opts.faucetUrl,\n\t\t\tgraphqlUrl: opts.graphqlUrl,\n\t\t\t// SDK accepts arbitrary strings under the `(string & {})`\n\t\t\t// branch; `localnet` is the closest semantic for a custom\n\t\t\t// caller-defined live target.\n\t\t\tsdkNetwork: 'localnet',\n\t\t});\n\t}\n\tconst defaults = LIVE_DEFAULTS[opts.network];\n\treturn Effect.succeed({\n\t\trpcUrl: opts.rpcUrl ?? defaults.rpcUrl,\n\t\tfaucetUrl: opts.faucetUrl ?? defaults.faucetUrl,\n\t\tgraphqlUrl: opts.graphqlUrl ?? defaults.graphqlUrl,\n\t\tsdkNetwork: opts.network,\n\t});\n};\n\n/** Build the live-mode boot Effect. */\nexport const bootLiveMode = (\n\topts: SuiLiveOptions,\n): Effect.Effect<LiveModeBootResult, SuiPluginError | SuiConfigError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// ----- 1. Resolve endpoints ------------------------------------------\n\t\tconst endpoints = yield* resolveEndpoints(opts);\n\n\t\t// ----- 2. Construct the grpc client ----------------------------------\n\t\tconst sdkClient = yield* Effect.try({\n\t\t\ttry: () =>\n\t\t\t\tnew SuiGrpcClient({\n\t\t\t\t\tbaseUrl: endpoints.rpcUrl,\n\t\t\t\t\tnetwork: endpoints.sdkNetwork,\n\t\t\t\t}),\n\t\t\tcatch: (cause): SuiPluginError =>\n\t\t\t\tsuiPluginError(\n\t\t\t\t\t'chain-id-fetch',\n\t\t\t\t\t`sui live mode: SuiGrpcClient construction failed for rpcUrl=${endpoints.rpcUrl}: ${formatUnknownError(cause)}`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t});\n\n\t\t// ----- 3. Resolve chain id -------------------------------------------\n\t\tconst chainId =\n\t\t\topts.chainId ??\n\t\t\t(yield* fetchChainId(sdkClient, {\n\t\t\t\ttimeout: opts.readyTimeout ?? DEFAULT_LIVE_CHAIN_ID_TIMEOUT,\n\t\t\t}));\n\n\t\t// ----- 4. Build waitForTransactionsReady -----------------------------\n\t\t// Mainnet: no faucet exists, gate is a no-op. testnet/devnet/\n\t\t// custom-with-faucet: real HTTP probe (rate-limited by upstream,\n\t\t// but the wire shape is identical to localnet).\n\t\tconst waitForTransactionsReady =\n\t\t\tendpoints.faucetUrl !== undefined\n\t\t\t\t? yield* buildWaitForTransactionsReady(endpoints.faucetUrl)\n\t\t\t\t: noopWaitForTransactionsReady;\n\n\t\t// ----- 5. Assemble + return ------------------------------------------\n\t\tconst { client } = yield* assembleSuiClient({\n\t\t\tsdkClient,\n\t\t\tchainId,\n\t\t\trpcUrl: endpoints.rpcUrl,\n\t\t\t...(endpoints.faucetUrl !== undefined ? { faucetUrl: endpoints.faucetUrl } : {}),\n\t\t\t...(endpoints.graphqlUrl !== undefined ? { graphqlUrl: endpoints.graphqlUrl } : {}),\n\t\t\twaitForTransactionsReady,\n\t\t});\n\t\tconst resolved = makeResolvedNetwork({\n\t\t\tmode: 'live',\n\t\t\tchainId,\n\t\t\trpc: endpoints.rpcUrl,\n\t\t\t// `source: 'default'` when we pulled from LIVE_DEFAULTS;\n\t\t\t// `'config'` when the caller passed an override. The\n\t\t\t// distinction matters for the doctor's \"where did this\n\t\t\t// value come from\" surface.\n\t\t\tsource:\n\t\t\t\topts.rpcUrl === undefined && opts.faucetUrl === undefined && opts.graphqlUrl === undefined\n\t\t\t\t\t? 'default'\n\t\t\t\t\t: 'config',\n\t\t\t...(endpoints.faucetUrl !== undefined ? { faucet: endpoints.faucetUrl } : {}),\n\t\t\t...(endpoints.graphqlUrl !== undefined ? { graphql: endpoints.graphqlUrl } : {}),\n\t\t});\n\n\t\treturn { resolved, client };\n\t});\n"],"mappings":";;;;;;;AAsDA,MAAa,gCAAgC,SAAS,QAAQ,EAAE;;;AAIhE,MAAa,gBAAgB;CAC5B,SAAS;EACR,QAAQ;EACR,WAAW;EACX,YAAY;CACb;CACA,SAAS;EACR,QAAQ;EACR,WAAW,KAAA;EACX,YAAY;CACb;CACA,QAAQ;EACP,QAAQ;EACR,WAAW;EACX,YAAY,KAAA;CACb;AACD;;;;AAkBA,MAAM,oBACL,SAC0D;CAC1D,IAAI,KAAK,YAAY,UAAU;EAC9B,IAAI,KAAK,WAAW,KAAA,GACnB,OAAO,OAAO,KACb,eACC,kBACA,iLAED,CACD;EAED,OAAO,OAAO,QAAQ;GACrB,QAAQ,KAAK;GACb,WAAW,KAAK;GAChB,YAAY,KAAK;GAIjB,YAAY;EACb,CAAC;CACF;CACA,MAAM,WAAW,cAAc,KAAK;CACpC,OAAO,OAAO,QAAQ;EACrB,QAAQ,KAAK,UAAU,SAAS;EAChC,WAAW,KAAK,aAAa,SAAS;EACtC,YAAY,KAAK,cAAc,SAAS;EACxC,YAAY,KAAK;CAClB,CAAC;AACF;;AAGA,MAAa,gBACZ,SAEA,OAAO,IAAI,aAAa;CAEvB,MAAM,YAAY,OAAO,iBAAiB,IAAI;CAG9C,MAAM,YAAY,OAAO,OAAO,IAAI;EACnC,WACC,IAAI,cAAc;GACjB,SAAS,UAAU;GACnB,SAAS,UAAU;EACpB,CAAC;EACF,QAAQ,UACP,eACC,kBACA,+DAA+D,UAAU,OAAO,IAAI,mBAAmB,KAAK,KAC5G,KACD;CACF,CAAC;CAGD,MAAM,UACL,KAAK,YACJ,OAAO,aAAa,WAAW,EAC/B,SAAS,KAAK,gBAAgB,8BAC/B,CAAC;CAMF,MAAM,2BACL,UAAU,cAAc,KAAA,IACrB,OAAO,8BAA8B,UAAU,SAAS,IACxD;CAGJ,MAAM,EAAE,WAAW,OAAO,kBAAkB;EAC3C;EACA;EACA,QAAQ,UAAU;EAClB,GAAI,UAAU,cAAc,KAAA,IAAY,EAAE,WAAW,UAAU,UAAU,IAAI,CAAC;EAC9E,GAAI,UAAU,eAAe,KAAA,IAAY,EAAE,YAAY,UAAU,WAAW,IAAI,CAAC;EACjF;CACD,CAAC;CAiBD,OAAO;EAAE,UAhBQ,oBAAoB;GACpC,MAAM;GACN;GACA,KAAK,UAAU;GAKf,QACC,KAAK,WAAW,KAAA,KAAa,KAAK,cAAc,KAAA,KAAa,KAAK,eAAe,KAAA,IAC9E,YACA;GACJ,GAAI,UAAU,cAAc,KAAA,IAAY,EAAE,QAAQ,UAAU,UAAU,IAAI,CAAC;GAC3E,GAAI,UAAU,eAAe,KAAA,IAAY,EAAE,SAAS,UAAU,WAAW,IAAI,CAAC;EAC/E,CAEgB;EAAG;CAAO;AAC3B,CAAC"}

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

@@ -0,0 +1 @@
+import { Duration, Effect, Scope } from "effect";

package/dist/plugins/sui/mode/local.mjs

@@ -1,27 +1,39 @@
-import { SpanAttr } from "../../../substrate/runtime/observability/spans.mjs";
 import { setCurrentPluginPhase } from "../../../substrate/runtime/current-plugin.mjs";
-import { DEFAULT_SUI_CLI_VERSION, suiCliImageBuildContext } from "../../../substrate/runtime/sui-move-build/index.mjs";
+import { waitForProbe } from "../../../substrate/runtime/probes.mjs";
+import { suiCliImageBuildContext } from "../move/index.mjs";
 import { renderUrl, routedHostname } from "../../../substrate/runtime/routed-url.mjs";
 import { waitForHttpEndpoint } from "../../../substrate/runtime/http-probe.mjs";
 import { SUI_FAUCET_ENDPOINT_NAME, SUI_FAUCET_ENTRYPOINT_PORT, SUI_GRAPHQL_ENDPOINT_NAME, SUI_GRAPHQL_ENTRYPOINT_PORT, SUI_RPC_ENTRYPOINT_PORT } from "../routable.mjs";
 import { ensureManagedContainer } from "../../../substrate/runtime/managed-container.mjs";
 import { suiPluginError } from "../errors.mjs";
 import { formatUnknownError } from "../../../substrate/runtime/format-unknown-error.mjs";
-import { SuiSpans } from "../spans.mjs";
+import { SuiLogAttr } from "../log-attrs.mjs";
 import { toDockerHostGatewayUrl } from "./shared.mjs";
 import { assembleSuiClient, buildWaitForTransactionsReady, fetchChainId, makeResolvedNetwork } from "./shared-boot.mjs";
 import { Duration, Effect } from "effect";
 import { SuiGrpcClient } from "@mysten/sui/grpc";
 //#region src/plugins/sui/mode/local.ts
-/** Default ready-probe timeout for localnet. The validator's cold
-*  start runs genesis + faucet bootstrap; 60 s is the documented
-*  ceiling. */
-const DEFAULT_LOCAL_READY_TIMEOUT = Duration.seconds(60);
-/** Default sui validator binary version pinned by the vendored
-*  `images/sui/` Dockerfile. The build arg `SUI_VERSION` is threaded
-*  through to the release-tarball URL. Bump in lockstep with matching
-*  Walrus / Seal versions (else the Move package ABIs drift). */
-const DEFAULT_SUI_VERSION = DEFAULT_SUI_CLI_VERSION;
+/** Default ready-probe timeout for localnet.
+*
+*  The pinned sui-tools image carries the embedded-fullnode resume fix
+*  (sui #26884), so BOTH the validator AND the embedded fullnode resume
+*  from their persisted dbs on every `sui start` — there is no per-boot
+*  genesis re-sync. (Pre-#26884, each `sui start` minted the fullnode a
+*  fresh key + empty db and it re-synced the whole chain from seq=0 at
+*  ~50x realtime; that band no longer exists.) So both bands satisfy the
+*  catch-up gate almost immediately:
+*
+*    - cold boot — genesis + faucet bootstrap; empty store, live cadence
+*      from the first sample.
+*    - warm restart / snapshot restore — both nodes resume from disk;
+*      the head is already at the persisted tip, so it stabilizes at
+*      once.
+*
+*  180s is therefore generous headroom, not a re-sync budget: the gate
+*  satisfies in a couple of polls on a healthy boot, and the timeout only
+*  bounds a genuinely wedged boot (gRPC bound but head never stabilizing
+*  → typed `grpc-probe` error). */
+const DEFAULT_LOCAL_READY_TIMEOUT = Duration.seconds(180);
 const CONTAINER_RPC_PORT = SUI_RPC_ENTRYPOINT_PORT;
 const CONTAINER_FAUCET_PORT = SUI_FAUCET_ENTRYPOINT_PORT;
 const CONTAINER_GRAPHQL_PORT = SUI_GRAPHQL_ENTRYPOINT_PORT;
@@ -33,6 +45,10 @@ const DOCKER_PUBLISH_HOST = "0.0.0.0";
 *  hung fetch would block the outer ready deadline with no signal
 *  about which probe wedged. */
 const PROBE_FETCH_TIMEOUT_MS = 3e3;
+/** Role label for sui's owned GraphQL-indexer postgres sidecar. Shared
+*  const so the container label (in `bootPostgresSidecar`'s caller) and
+*  the snapshotable capture tuple agree exactly. */
+const SUI_INDEXER_DB_ROLE = "indexer-db";
 /**
 * Build the local-mode boot Effect.
 *
@@ -43,85 +59,89 @@ const PROBE_FETCH_TIMEOUT_MS = 3e3;
 *
 * `{pull}`, `{build}`, and vendored-build image branches are wired.
 */
-const bootLocalMode = (runtime, identity, portBroker, opts) => Effect.gen(function* () {
+const bootLocalMode = (runtime, identity, portBroker, opts, indexer, prebuiltImage) => Effect.gen(function* () {
 	yield* setCurrentPluginPhase("resolving Sui local image");
-	const image = yield* resolveImage(runtime, identity, opts);
+	const image = prebuiltImage ?? (yield* resolveImage(runtime, identity, opts));
 	yield* setCurrentPluginPhase("creating Sui validator container");
 	const { handle, ports } = yield* ensureLocalValidatorContainer(runtime, portBroker, image, {
 		app: identity.app,
 		stack: identity.stack,
 		plugin: "sui",
 		role: "validator"
-	}, `devstack-${identity.app}-${identity.stack}-sui-validator`, opts);
+	}, `devstack-${identity.app}-${identity.stack}-sui-validator`, opts, indexer);
+	const graphqlEnabled = indexer !== void 0;
 	const publishedPorts = resolvePublishedPortMapping(ports, handle.ports);
 	const directRpcUrl = `http://127.0.0.1:${publishedPorts[0].hostPort}`;
 	const directFaucetUrl = `http://127.0.0.1:${publishedPorts[1].hostPort}`;
 	const directGraphqlUrl = `http://127.0.0.1:${publishedPorts[2].hostPort}`;
 	const rpcUrl = yield* routedSuiUrl(identity, "rpc", SUI_RPC_ENTRYPOINT_PORT);
 	const faucetUrl = yield* routedSuiUrl(identity, SUI_FAUCET_ENDPOINT_NAME, SUI_FAUCET_ENTRYPOINT_PORT);
-	const graphqlUrl = yield* routedSuiUrl(identity, SUI_GRAPHQL_ENDPOINT_NAME, SUI_GRAPHQL_ENTRYPOINT_PORT);
+	const graphqlUrl = graphqlEnabled ? yield* routedSuiUrl(identity, SUI_GRAPHQL_ENDPOINT_NAME, SUI_GRAPHQL_ENTRYPOINT_PORT) : void 0;
 	const readyTimeout = opts.readyTimeout ?? DEFAULT_LOCAL_READY_TIMEOUT;
-	yield* setCurrentPluginPhase("waiting for Sui RPC, faucet, and GraphQL");
-	yield* waitForReady(directRpcUrl, directFaucetUrl, directGraphqlUrl, readyTimeout).pipe(Effect.annotateLogs({ [SuiSpans.container]: handle.name }));
 	const sdkClient = new SuiGrpcClient({
 		baseUrl: directRpcUrl,
 		network: "localnet"
 	});
+	yield* setCurrentPluginPhase(graphqlEnabled ? "waiting for Sui gRPC, faucet, and GraphQL" : "waiting for Sui gRPC and faucet");
+	yield* waitForReady(sdkClient, directRpcUrl, directFaucetUrl, graphqlEnabled ? directGraphqlUrl : void 0, readyTimeout).pipe(Effect.annotateLogs({ [SuiLogAttr.container]: handle.name }));
+	yield* setCurrentPluginPhase("waiting for Sui checkpoint head to stabilize");
+	yield* waitForCheckpointCatchUp(sdkClient, directRpcUrl, readyTimeout).pipe(Effect.annotateLogs({ [SuiLogAttr.container]: handle.name }));
 	yield* setCurrentPluginPhase("fetching Sui chain id");
-	const chain = yield* fetchChainId(sdkClient, { span: "devstack.plugin.sui.local.fetchChainId" });
+	const chainId = yield* fetchChainId(sdkClient);
 	yield* setCurrentPluginPhase("preparing Sui funds-ready gate");
+	const waitForTransactionsReady = yield* buildWaitForTransactionsReady(directFaucetUrl);
 	const { client } = yield* assembleSuiClient({
 		sdkClient,
-		chain,
+		chainId,
 		rpcUrl,
 		faucetUrl,
 		fundingFaucetUrl: directFaucetUrl,
-		graphqlUrl,
-		waitForTransactionsReady: yield* buildWaitForTransactionsReady(directFaucetUrl),
+		...graphqlUrl !== void 0 ? { graphqlUrl } : {},
+		waitForTransactionsReady,
 		buildImage: image,
 		hostGateway: {
 			rpcUrl: toDockerHostGatewayUrl(directRpcUrl),
 			faucetUrl: toDockerHostGatewayUrl(directFaucetUrl),
-			graphqlUrl: toDockerHostGatewayUrl(directGraphqlUrl)
+			graphqlUrl: graphqlEnabled ? toDockerHostGatewayUrl(directGraphqlUrl) : null
 		}
 	});
 	return {
 		resolved: makeResolvedNetwork({
 			mode: "local",
-			chain,
+			chainId,
 			rpc: rpcUrl,
 			faucet: faucetUrl,
-			graphql: graphqlUrl,
+			...graphqlUrl !== void 0 ? { graphql: graphqlUrl } : {},
 			source: "default"
 		}),
 		client
 	};
-}).pipe(Effect.withSpan("devstack.plugin.sui.local.boot", { attributes: { [SpanAttr.plugin]: "sui" } }));
+});
 const resolveImage = (runtime, identity, opts) => Effect.gen(function* () {
 	if (opts.image && "pull" in opts.image) {
 		const pullRef = opts.image.pull;
 		if (runtime.pullImage === void 0) return yield* Effect.fail(suiPluginError("image-build", `sui local mode cannot pull image '${pullRef}' because the configured container runtime does not expose image pulls.`));
 		return yield* runtime.pullImage(pullRef).pipe(Effect.mapError((cause) => suiPluginError("image-build", `sui local mode failed to pull image '${pullRef}': ${cause.reason}: ${cause.detail}`, cause)));
 	}
-	const version = opts.version ?? DEFAULT_SUI_VERSION;
 	const owner = {
 		app: identity.app,
 		stack: identity.stack,
 		plugin: "sui",
 		role: "validator"
 	};
+	const vendored = suiCliImageBuildContext();
 	const buildCtx = opts.image && "build" in opts.image ? {
 		contextPath: opts.image.build.context,
 		dockerfile: opts.image.build.dockerfile ?? "Dockerfile",
-		buildArgs: { SUI_VERSION: version },
+		buildArgs: vendored.buildArgs,
 		owner
 	} : {
-		...suiCliImageBuildContext(version),
+		...vendored,
 		owner
 	};
 	return yield* runtime.ensureImage(buildCtx).pipe(Effect.mapError((cause) => suiPluginError("image-build", `sui image build failed: ${cause.reason}: ${cause.detail}`, cause)));
-}).pipe(Effect.withSpan("devstack.plugin.sui.local.resolveImage"));
-const ensureLocalValidatorContainer = (runtime, portBroker, image, labels, containerName, opts) => Effect.gen(function* () {
+});
+const ensureLocalValidatorContainer = (runtime, portBroker, image, labels, containerName, opts, indexer) => Effect.gen(function* () {
 	const reusablePorts = opts.ports === void 0 ? yield* findReusablePortMapping(runtime, labels, containerName) : void 0;
 	if (reusablePorts !== void 0) return yield* ensureLocalValidatorContainerAttempt({
 		runtime,
@@ -130,6 +150,7 @@ const ensureLocalValidatorContainer = (runtime, portBroker, image, labels, conta
 		labels,
 		containerName,
 		opts,
+		indexer,
 		ports: reusablePorts,
 		attempt: 0,
 		reconciliation: "adopt-existing"
@@ -141,6 +162,7 @@ const ensureLocalValidatorContainer = (runtime, portBroker, image, labels, conta
 		labels,
 		containerName,
 		opts,
+		indexer,
 		attempt: 0,
 		reconciliation: opts.ports ? "exact" : "adopt-existing"
 	});
@@ -161,8 +183,13 @@ const ensureLocalValidatorContainerAttempt = (params) => ensureManagedContainer(
 		image: params.image,
 		recreate: "on-failure",
 		stopGraceSeconds: 30,
+		stopSignal: "SIGINT",
 		ports: params.ports,
-		portBindingReconciliation: params.reconciliation
+		portBindingReconciliation: params.reconciliation,
+		...params.indexer !== void 0 ? {
+			networkAttach: [params.indexer.network],
+			env: { DEVSTACK_SUI_INDEXER_URL: params.indexer.url }
+		} : {}
 	},
 	mapError: (cause) => cause
 }).pipe(Effect.map((handle) => ({
@@ -237,58 +264,173 @@ const allocatePort = (portBroker, owner, preferredPort, label) => {
 	}) : Effect.fail(cause)), Effect.mapError((cause) => suiPluginError("port-allocate", `sui local mode: failed to allocate ${label} host port (preferred ${hint ?? "auto"}): ${cause.detail}`, cause)));
 	return allocate(preferredPort);
 };
-/** Coordinated readiness gate. Both RPC + faucet must respond within
-*  the outer deadline; each probe has its own per-fetch deadline so a
+/** Coordinated readiness gate. RPC + faucet must respond within the
+*  outer deadline; GraphQL is probed only when enabled (gated on the
+*  external indexer). Each probe has its own per-fetch deadline so a
 *  wedged endpoint surfaces by name. */
-const waitForReady = (rpcUrl, faucetUrl, graphqlUrl, readyTimeout) => Effect.gen(function* () {
+const waitForReady = (sdkClient, rpcUrl, faucetUrl, graphqlUrl, readyTimeout) => Effect.gen(function* () {
 	const readyTimeoutMs = Duration.toMillis(readyTimeout);
-	const rpcProbe = waitForHttpEndpoint({
-		endpoint: rpcUrl,
+	const grpcProbe = waitForProbe({
+		label: `${rpcUrl} (gRPC service info)`,
 		timeoutMs: readyTimeoutMs,
 		intervalMs: 1e3,
-		requestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
-		requestInit: {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify({
-				jsonrpc: "2.0",
-				id: 1,
-				method: "sui_getLatestCheckpointSequenceNumber",
-				params: []
-			})
-		},
-		validate: async (response) => {
-			if (!response.ok) return false;
-			const body = await response.json();
-			return typeof body.result === "string" || typeof body.result === "number";
-		}
-	}).pipe(Effect.mapError((cause) => suiPluginError("rpc-probe", `sui local mode: RPC endpoint ${rpcUrl} did not become ready within ${readyTimeoutMs}ms: ${formatUnknownError(cause)}`, cause)), Effect.withSpan("devstack.plugin.sui.local.probe.rpc"));
+		attemptTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
+		probe: () => fetchServiceInfo(sdkClient, PROBE_FETCH_TIMEOUT_MS).pipe(Effect.map((info) => info.chainId !== void 0 || info.checkpointHeight !== void 0 ? true : {
+			ready: false,
+			detail: { reason: "missing-service-info" }
+		}))
+	}).pipe(Effect.mapError((cause) => suiPluginError("grpc-probe", `sui local mode: gRPC endpoint ${rpcUrl} did not become ready within ${readyTimeoutMs}ms: ${formatUnknownError(cause)}`, cause)));
 	const faucetProbe = waitForHttpEndpoint({
 		endpoint: faucetUrl,
 		timeoutMs: readyTimeoutMs,
 		intervalMs: 1e3,
 		requestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
 		validate: (response) => response.status < 500
-	}).pipe(Effect.mapError((cause) => suiPluginError("faucet-probe", `sui local mode: faucet endpoint ${faucetUrl} did not become ready within ${readyTimeoutMs}ms: ${formatUnknownError(cause)}`, cause)), Effect.withSpan("devstack.plugin.sui.local.probe.faucet"));
-	const graphqlProbe = waitForHttpEndpoint({
+	}).pipe(Effect.mapError((cause) => suiPluginError("faucet-probe", `sui local mode: faucet endpoint ${faucetUrl} did not become ready within ${readyTimeoutMs}ms: ${formatUnknownError(cause)}`, cause)));
+	const graphqlProbe = graphqlUrl === void 0 ? [] : [waitForHttpEndpoint({
 		endpoint: graphqlUrl,
 		timeoutMs: readyTimeoutMs,
 		intervalMs: 1e3,
 		requestTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
 		validate: (response) => response.status < 500
-	}).pipe(Effect.mapError((cause) => suiPluginError("graphql-probe", `sui local mode: GraphQL endpoint ${graphqlUrl} did not become ready within ${readyTimeoutMs}ms: ${formatUnknownError(cause)}`, cause)), Effect.withSpan("devstack.plugin.sui.local.probe.graphql"));
+	}).pipe(Effect.mapError((cause) => suiPluginError("graphql-probe", `sui local mode: GraphQL endpoint ${graphqlUrl} did not become ready within ${readyTimeoutMs}ms: ${formatUnknownError(cause)}`, cause)))];
 	yield* Effect.all([
-		rpcProbe,
+		grpcProbe,
 		faucetProbe,
-		graphqlProbe
+		...graphqlProbe
 	], { concurrency: "unbounded" }).pipe(Effect.asVoid);
-}).pipe(Effect.withSpan("devstack.plugin.sui.local.waitForReady"));
+});
+/** Poll interval for the head-stabilization gate. With the #26884 resume
+*  fix there is no routine re-sync, but a 1s interval still samples a wide
+*  enough window to tell any transient fast burst (hundreds/poll) apart
+*  from live cadence (a handful/poll) before declaring the head stable. */
+const CATCH_UP_POLL_INTERVAL_MS = 1e3;
+/** Per-poll delta at or below which the head is considered to be moving
+*  at LIVE cadence rather than fast-replay cadence. Localnet's narwhal/
+*  bullshark consensus produces only a few checkpoints per second when
+*  idle; replay produces hundreds per `CATCH_UP_POLL_INTERVAL_MS`. A
+*  threshold of 25 sits well above live idle cadence and far below the
+*  replay rate, so it cannot mistake live ticking for replay. */
+const CATCH_UP_LIVE_CADENCE_DELTA = 25;
+/** Number of CONSECUTIVE live-cadence polls required before declaring
+*  caught-up. Two consecutive small deltas rules out the moment replay
+*  briefly stalls (e.g. a GC pause) from being read as caught-up: a
+*  paused replay shows one small delta then resumes with a large one,
+*  so it never strings two together. A genuinely caught-up validator
+*  holds small deltas indefinitely. */
+const CATCH_UP_STABLE_POLLS_REQUIRED = 2;
+const fetchServiceInfo = (sdkClient, timeoutMs) => Effect.tryPromise({
+	try: (signal) => sdkClient.ledgerService.getServiceInfo({}, {
+		abort: signal,
+		timeout: timeoutMs
+	}).response,
+	catch: (cause) => cause
+});
+/** Fetch the latest checkpoint height via the gRPC service-info surface.
+*  Returns the number, or `undefined` when the listener answered but did
+*  not include a safely numeric checkpoint height. */
+const fetchLatestCheckpoint = (sdkClient) => fetchServiceInfo(sdkClient, PROBE_FETCH_TIMEOUT_MS).pipe(Effect.map((body) => {
+	if (body.checkpointHeight === void 0) return void 0;
+	const checkpoint = Number(body.checkpointHeight);
+	return Number.isSafeInteger(checkpoint) ? checkpoint : void 0;
+}));
+/** Build the stateful cadence evaluator the catch-up gate feeds samples
+*  into. Pure + injectable so the cadence logic is unit-testable without
+*  a live validator. Each `step(sample)` consumes one
+*  gRPC service-info checkpoint-height reading:
+*
+*    - `undefined` (listener answered, result unparseable) resets the
+*      stability streak.
+*    - the FIRST numeric sample only establishes a baseline (its delta is
+*      `+Infinity`), so the gate always takes at least two samples before
+*      it can declare caught-up — cheap on cold boot, correct on restore.
+*    - a NEGATIVE delta (the head regressed — mid-re-sync / reset) resets
+*      the streak; it is NOT counted as live cadence even though it is
+*      `<= CATCH_UP_LIVE_CADENCE_DELTA`.
+*    - a delta in `[0, CATCH_UP_LIVE_CADENCE_DELTA]` counts toward the
+*      live-cadence streak; a larger delta (fast replay) resets it.
+*    - `CATCH_UP_STABLE_POLLS_REQUIRED` consecutive live-cadence deltas →
+*      caught-up. */
+const makeCatchUpEvaluator = (opts) => {
+	const liveCadenceDelta = opts?.liveCadenceDelta ?? CATCH_UP_LIVE_CADENCE_DELTA;
+	const stablePollsRequired = opts?.stablePollsRequired ?? CATCH_UP_STABLE_POLLS_REQUIRED;
+	let previous;
+	let stablePolls = 0;
+	return {
+		step: (sample) => {
+			if (sample === void 0) {
+				stablePolls = 0;
+				return {
+					caughtUp: false,
+					detail: { reason: "unparseable-checkpoint" }
+				};
+			}
+			const delta = previous === void 0 ? Number.POSITIVE_INFINITY : sample - previous;
+			previous = sample;
+			if (delta < 0) {
+				stablePolls = 0;
+				return {
+					caughtUp: false,
+					detail: {
+						current: sample,
+						delta,
+						stablePolls,
+						regressed: true
+					}
+				};
+			}
+			if (delta <= liveCadenceDelta) stablePolls += 1;
+			else stablePolls = 0;
+			if (stablePolls >= stablePollsRequired) return { caughtUp: true };
+			return {
+				caughtUp: false,
+				detail: {
+					current: sample,
+					delta,
+					stablePolls
+				}
+			};
+		},
+		last: () => previous
+	};
+};
+/** Head-stabilization gate.
+*
+*  Polls the gRPC service-info checkpoint height and treats the head as
+*  stable once the per-poll delta is at live cadence (`<= CATCH_UP_LIVE_
+*  CADENCE_DELTA`/poll) and HOLDS there for `CATCH_UP_STABLE_POLLS_
+*  REQUIRED` consecutive polls. With the #26884 resume fix both nodes
+*  resume from disk, so there is no genesis re-sync to wait out: cold and
+*  warm/restore boots alike are at live cadence from the first samples
+*  and satisfy in a couple of polls. The fast-replay reset branch in the
+*  evaluator is retained as a cheap guard for any transient burst rather
+*  than a routine restart band.
+*
+*  A wedged boot (gRPC bound but head never stabilizing) lapses the outer
+*  deadline → typed `grpc-probe` error rather than hanging forever. */
+const waitForCheckpointCatchUp = (sdkClient, rpcUrl, readyTimeout) => Effect.gen(function* () {
+	const readyTimeoutMs = Duration.toMillis(readyTimeout);
+	const evaluator = makeCatchUpEvaluator();
+	return yield* waitForProbe({
+		label: `${rpcUrl} (checkpoint catch-up)`,
+		timeoutMs: readyTimeoutMs,
+		intervalMs: CATCH_UP_POLL_INTERVAL_MS,
+		attemptTimeoutMs: PROBE_FETCH_TIMEOUT_MS,
+		probe: () => fetchLatestCheckpoint(sdkClient).pipe(Effect.map((current) => {
+			const verdict = evaluator.step(current);
+			return verdict.caughtUp ? true : {
+				ready: false,
+				detail: verdict.detail
+			};
+		}))
+	}).pipe(Effect.mapError((cause) => suiPluginError("grpc-probe", `sui local mode: checkpoint head did not stabilize within ${readyTimeoutMs}ms (last seq=${evaluator.last() ?? "n/a"}). With the #26884 resume fix both nodes resume from disk, so the head should reach live cadence almost immediately; a stall here points to a wedged boot, not a re-sync: ${formatUnknownError(cause)}`, cause)));
+});
 const routedSuiUrl = (identity, endpointName, port) => routedHostname(identity, endpointName).pipe(Effect.map((hostname) => renderUrl({
 	protocol: "http",
 	hostname,
 	port
 })), Effect.mapError((cause) => suiPluginError("container-start", `sui local mode: failed to construct router URL for ${endpointName}: ${cause.detail}`, cause)));
 //#endregion
-export { bootLocalMode };
+export { SUI_INDEXER_DB_ROLE, bootLocalMode, resolveImage };
 
 //# sourceMappingURL=local.mjs.map