@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/plugins/sui/chain-probe.mjs

@@ -1,47 +1,7 @@
 import { decodeUnknown } from "../../substrate/runtime/runtime-decode.mjs";
-import { Effect, Schema } from "effect";
+import { formatUnknownError } from "../../substrate/runtime/format-unknown-error.mjs";
+import { Effect } from "effect";
 //#region src/plugins/sui/chain-probe.ts
-/** Validated subset of `client.core.getObject(...).object`. We
-*  narrow to the fields verify probes actually consult — the SDK
-*  exposes more (digest, content, json, display) but those are
-*  out of scope here. */
-const ObjectOwnerSchema = Schema.Union([
-	Schema.Struct({
-		$kind: Schema.Literal("AddressOwner"),
-		AddressOwner: Schema.String
-	}),
-	Schema.Struct({
-		$kind: Schema.Literal("Shared"),
-		Shared: Schema.Struct({ initialSharedVersion: Schema.String })
-	}),
-	Schema.Struct({
-		$kind: Schema.Literal("Immutable"),
-		Immutable: Schema.Literal(true)
-	}),
-	Schema.Struct({
-		$kind: Schema.Literal("ConsensusAddressOwner"),
-		ConsensusAddressOwner: Schema.Unknown
-	}),
-	Schema.Struct({
-		$kind: Schema.Literal("Parent"),
-		Parent: Schema.Unknown
-	}),
-	Schema.Struct({
-		$kind: Schema.Literal("Unknown"),
-		Unknown: Schema.Unknown
-	})
-]);
-/** Validated SDK response shape: `{ object: { objectId, type, ... } }`.
-*  Substrate-redesign note: today's code validates `version` as a
-*  string but it's semantically a bigint — branded type recommendation
-*  carried in the Opportunities section. */
-const SuiObjectShapeSchema = Schema.Struct({
-	objectId: Schema.String,
-	type: Schema.String,
-	version: Schema.String,
-	owner: ObjectOwnerSchema
-});
-Schema.Struct({ object: SuiObjectShapeSchema });
 /** Construct the chain-probe instance for a resolved Sui client +
 *  chain id. The result implements the contract's `ChainProbe<Key>`
 *  shape; the Sui plugin emits this via a StrategyContributorDecl
@@ -53,7 +13,7 @@ const makeSuiChainProbe = (sdk, chain) => ({ get: (key, schema, mode) => Effect.
 			_tag: "ChainProbeError",
 			reason: isNotFound(cause) ? "not-found" : "transient",
 			chain,
-			detail: stringifyCause(cause)
+			detail: formatUnknownError(cause)
 		})
 	}).pipe(Effect.catch((err) => mode === "lenient" && (err.reason === "not-found" || err.reason === "transient") ? Effect.succeed(null) : Effect.fail(err)));
 	if (raw === null) return null;
@@ -65,7 +25,7 @@ const makeSuiChainProbe = (sdk, chain) => ({ get: (key, schema, mode) => Effect.
 			_tag: "ChainProbeError",
 			reason: "decode-failed",
 			chain,
-			detail: stringifyCause(issue.cause ?? issue)
+			detail: formatUnknownError(issue.cause ?? issue)
 		})
 	});
 }) });
@@ -81,22 +41,32 @@ const projectTransactionPayload = (raw) => {
 	if (envelope.$kind === "FailedTransaction") return envelope.FailedTransaction ?? null;
 	return raw;
 };
-/** Heuristic: SDK errors carrying "not found" / "Not exist" in
-*  the message are treated as not-found; everything else is
-*  transient. The substrate's lenient-retry profile re-runs the
-*  probe on a transient bucket; not-found is terminal. */
+/** Heuristic: SDK errors carrying object/transaction-shape "not found"
+*  markers are treated as terminal not-found; everything else is
+*  transient. The substrate's lenient-retry profile re-runs the probe
+*  on a transient bucket; not-found is terminal.
+*
+*  Limitation: `@mysten/sui` does NOT surface a structured status code
+*  on its SDK errors — the substrate only sees an `Error` message. We
+*  therefore narrow the substring matches as much as possible to avoid
+*  misclassifying network-layer "endpoint does not exist" or generic
+*  "not found" prose as terminal:
+*
+*  - We require the matched phrase to refer to the OBJECT or
+*    TRANSACTION rather than the endpoint. Concretely we look for the
+*    SDK's canonical "object not found" / "object does not exist" /
+*    "no such object" wording and the equivalent "transaction not
+*    found" / "transaction does not exist" wording.
+*  - We DO NOT match the bare substring "not found" alone (that
+*    catches "endpoint does not exist", DNS prose, etc. — all of
+*    which are network-layer transients).
+*
+*  If `@mysten/sui` surfaces a structured error class with an
+*  `httpStatus` (or equivalent) in the future, swap this for an
+*  exact 404 / -32000 check. */
 const isNotFound = (cause) => {
 	const msg = cause?.message?.toLowerCase() ?? "";
-	return msg.includes("not found") || msg.includes("does not exist") || msg.includes("no such object") || msg.includes("not exist");
-};
-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);
-	}
+	return /\bobject\b.*\bnot found\b/u.test(msg) || /\bobject\b.*\bdoes not exist\b/u.test(msg) || /\bno such object\b/u.test(msg) || /\btransaction\b.*\bnot found\b/u.test(msg) || /\btransaction\b.*\bdoes not exist\b/u.test(msg);
 };
 //#endregion
 export { makeSuiChainProbe };

package/dist/plugins/sui/chain-probe.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"chain-probe.mjs","names":[],"sources":["../../../src/plugins/sui/chain-probe.ts"],"sourcesContent":["// Sui plugin — ChainProbe capability implementation.\n//\n// Architecture §9: ChainProbe is a contract, NOT a primitive. Sui\n// provides the only in-tree implementation; the substrate dispatches\n// to it via the StrategyContributor registry under\n// `chain-probe:<chainId>`.\n//\n// Lenient mode: returns null for both \"not found\" AND transient RPC\n// failure — verify pipelines re-derive on the next cycle rather than\n// fail boot. Strict mode: distinguishes via tagged error.\n//\n// Why lenient is the default in this plugin's wiring: artifact publisher verify is\n// the dominant consumer; artifact publisher's lenient-retry profile (15 attempts,\n// 90s budget) is calibrated against lenient semantics. A strict\n// surface exists for explicit \"I want to know if the chain is\n// reachable\" callers (the doctor command, debugging).\n\nimport { Effect, Schema } from 'effect';\n\nimport type {\n\tChainProbe,\n\tChainProbeError,\n\tChainProbeMode,\n\tChainProbeSchema,\n} from '../../contracts/chain-probe.ts';\nimport { decodeUnknown } from '../../substrate/runtime/runtime-decode.ts';\n\n/**\n * Sui's chain-key shape — discriminated so the probe can dispatch\n * between object reads, tx reads, and the (forthcoming) batch\n * variant on one method.\n */\nexport type SuiProbeKey =\n\t| { readonly kind: 'object'; readonly objectId: string }\n\t| { readonly kind: 'transaction'; readonly digest: string };\n\n/** Validated subset of `client.core.getObject(...).object`. We\n *  narrow to the fields verify probes actually consult — the SDK\n *  exposes more (digest, content, json, display) but those are\n *  out of scope here. */\nconst ObjectOwnerSchema = Schema.Union([\n\tSchema.Struct({\n\t\t$kind: Schema.Literal('AddressOwner'),\n\t\tAddressOwner: Schema.String,\n\t}),\n\tSchema.Struct({\n\t\t$kind: Schema.Literal('Shared'),\n\t\tShared: Schema.Struct({ initialSharedVersion: Schema.String }),\n\t}),\n\tSchema.Struct({\n\t\t$kind: Schema.Literal('Immutable'),\n\t\tImmutable: Schema.Literal(true),\n\t}),\n\tSchema.Struct({\n\t\t$kind: Schema.Literal('ConsensusAddressOwner'),\n\t\tConsensusAddressOwner: Schema.Unknown,\n\t}),\n\tSchema.Struct({\n\t\t$kind: Schema.Literal('Parent'),\n\t\tParent: Schema.Unknown,\n\t}),\n\tSchema.Struct({\n\t\t$kind: Schema.Literal('Unknown'),\n\t\tUnknown: Schema.Unknown,\n\t}),\n]);\n\n/** Validated SDK response shape: `{ object: { objectId, type, ... } }`.\n *  Substrate-redesign note: today's code validates `version` as a\n *  string but it's semantically a bigint — branded type recommendation\n *  carried in the Opportunities section. */\nexport const SuiObjectShapeSchema = Schema.Struct({\n\tobjectId: Schema.String,\n\ttype: Schema.String,\n\tversion: Schema.String,\n\towner: ObjectOwnerSchema,\n});\n\nexport const SuiGetObjectResponseSchema = Schema.Struct({\n\tobject: SuiObjectShapeSchema,\n});\n\n/** Plugin-internal SDK shim — the type the plugin's acquire body\n *  hands to the probe factory + the account's sign/execute closure.\n *  Kept narrow so we don't pull `@mysten/sui` types into the substrate.\n *\n *  Exposes the four surfaces consumers actually use:\n *\n *    - `getObject` / `getTransaction` — the lenient chain probe.\n *    - `executeTransaction` — the account plugin's submit path\n *      (txBytes + caller-signed signatures).\n *    - `waitForTransaction` — post-submit finality wait.\n *\n *  Plus an OPAQUE `client` field — the underlying `SuiGrpcClient`\n *  reference. The package plugin's publish-tx builder hands this to\n *  `Transaction.build({ client })` (the SDK resolves gas + object\n *  versions through it). We type as `unknown` so the substrate stays\n *  free of a direct `@mysten/sui/client` type import; the consumer\n *  casts at the boundary (mirrors the same opacity decision in the\n *  Coin plugin's `MintSdkShim.client`). */\nexport interface SuiSdkShim {\n\treadonly core: {\n\t\treadonly getObject: (args: {\n\t\t\treadonly objectId: string;\n\t\t\treadonly include?: {\n\t\t\t\treadonly content?: boolean;\n\t\t\t\treadonly json?: boolean;\n\t\t\t};\n\t\t}) => Promise<unknown>;\n\t\treadonly getTransaction: (args: { readonly digest: string }) => Promise<unknown>;\n\t\treadonly getBalance: (args: {\n\t\t\treadonly owner: string;\n\t\t\treadonly coinType?: string;\n\t\t}) => Promise<unknown>;\n\t\treadonly listCoins: (args: {\n\t\t\treadonly owner: string;\n\t\t\treadonly coinType?: string;\n\t\t\treadonly limit?: number;\n\t\t\treadonly cursor?: string | null;\n\t\t}) => Promise<{\n\t\t\treadonly objects: ReadonlyArray<{\n\t\t\t\treadonly objectId: string;\n\t\t\t\treadonly version: string;\n\t\t\t\treadonly digest: string;\n\t\t\t\treadonly balance: string;\n\t\t\t}>;\n\t\t\treadonly hasNextPage: boolean;\n\t\t\treadonly cursor: string | null;\n\t\t}>;\n\t\treadonly executeTransaction: (args: {\n\t\t\treadonly transaction: Uint8Array;\n\t\t\treadonly signatures: ReadonlyArray<string>;\n\t\t\treadonly include?: {\n\t\t\t\treadonly effects?: boolean;\n\t\t\t\treadonly objectTypes?: boolean;\n\t\t\t};\n\t\t}) => Promise<unknown>;\n\t\treadonly waitForTransaction: (args: {\n\t\t\treadonly digest: string;\n\t\t\treadonly timeout?: number;\n\t\t}) => Promise<unknown>;\n\t};\n\t/** Opaque client reference for `Transaction.build({ client })`.\n\t *  The Sui barrel wires the resolved `SuiGrpcClient` through; the\n\t *  shim layer doesn't type-narrow it (mirrors `MintSdkShim.client`). */\n\treadonly client: unknown;\n}\n\n/** Construct the chain-probe instance for a resolved Sui client +\n *  chain id. The result implements the contract's `ChainProbe<Key>`\n *  shape; the Sui plugin emits this via a StrategyContributorDecl\n *  keyed by `chain-probe:<chainId>`. */\nexport const makeSuiChainProbe = (sdk: SuiSdkShim, chain: string): ChainProbe<SuiProbeKey> => ({\n\tget: <Shape>(\n\t\tkey: SuiProbeKey,\n\t\tschema: ChainProbeSchema<Shape>,\n\t\tmode: ChainProbeMode,\n\t): Effect.Effect<Shape | null, ChainProbeError> =>\n\t\tEffect.gen(function* () {\n\t\t\tconst raw: unknown = yield* Effect.tryPromise({\n\t\t\t\ttry: () =>\n\t\t\t\t\tkey.kind === 'object'\n\t\t\t\t\t\t? sdk.core.getObject({ objectId: key.objectId })\n\t\t\t\t\t\t: sdk.core.getTransaction({ digest: key.digest }),\n\t\t\t\tcatch: (cause): ChainProbeError => ({\n\t\t\t\t\t_tag: 'ChainProbeError',\n\t\t\t\t\treason: isNotFound(cause) ? 'not-found' : 'transient',\n\t\t\t\t\tchain,\n\t\t\t\t\tdetail: stringifyCause(cause),\n\t\t\t\t}),\n\t\t\t}).pipe(\n\t\t\t\t// Lenient mode coerces both not-found and transient into a\n\t\t\t\t// null result. Strict mode lets the error propagate.\n\t\t\t\tEffect.catch(\n\t\t\t\t\t(err): Effect.Effect<unknown, ChainProbeError> =>\n\t\t\t\t\t\tmode === 'lenient' && (err.reason === 'not-found' || err.reason === 'transient')\n\t\t\t\t\t\t\t? Effect.succeed(null)\n\t\t\t\t\t\t\t: Effect.fail(err),\n\t\t\t\t),\n\t\t\t);\n\t\t\tif (raw === null) return null;\n\t\t\tconst payload = projectProbePayload(key, raw);\n\t\t\tif (payload === null) return null;\n\n\t\t\t// Decode against the caller-supplied Schema. A decode failure\n\t\t\t// is structured (NOT silent undefined) — this is the\n\t\t\t// load-bearing learning from deepbook.\n\t\t\tconst decoded = yield* decodeUnknown(schema, payload, {\n\t\t\t\tsource: `chain probe ${chain}`,\n\t\t\t\tmkError: (issue): ChainProbeError => ({\n\t\t\t\t\t_tag: 'ChainProbeError',\n\t\t\t\t\treason: 'decode-failed',\n\t\t\t\t\tchain,\n\t\t\t\t\tdetail: stringifyCause(issue.cause ?? issue),\n\t\t\t\t}),\n\t\t\t});\n\t\t\treturn decoded;\n\t\t}),\n});\n\nconst projectProbePayload = (key: SuiProbeKey, raw: unknown): unknown | null => {\n\tif (key.kind === 'transaction') return projectTransactionPayload(raw);\n\tif (typeof raw !== 'object' || raw === null || !('object' in raw)) return raw;\n\n\treturn (raw as { readonly object?: unknown }).object ?? null;\n};\n\nconst projectTransactionPayload = (raw: unknown): unknown | null => {\n\tif (typeof raw !== 'object' || raw === null) return raw;\n\tconst envelope = raw as {\n\t\treadonly $kind?: 'Transaction' | 'FailedTransaction';\n\t\treadonly Transaction?: unknown;\n\t\treadonly FailedTransaction?: unknown;\n\t};\n\tif (envelope.$kind === 'Transaction') return envelope.Transaction ?? null;\n\tif (envelope.$kind === 'FailedTransaction') return envelope.FailedTransaction ?? null;\n\treturn raw;\n};\n\n/** Heuristic: SDK errors carrying \"not found\" / \"Not exist\" in\n *  the message are treated as not-found; everything else is\n *  transient. The substrate's lenient-retry profile re-runs the\n *  probe on a transient bucket; not-found is terminal. */\nconst isNotFound = (cause: unknown): boolean => {\n\tconst msg = (cause as { message?: string })?.message?.toLowerCase() ?? '';\n\treturn (\n\t\tmsg.includes('not found') ||\n\t\tmsg.includes('does not exist') ||\n\t\tmsg.includes('no such object') ||\n\t\tmsg.includes('not exist')\n\t);\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":";;;;;;;AAwCA,MAAM,oBAAoB,OAAO,MAAM;CACtC,OAAO,OAAO;EACb,OAAO,OAAO,QAAQ,eAAe;EACrC,cAAc,OAAO;EACrB,CAAC;CACF,OAAO,OAAO;EACb,OAAO,OAAO,QAAQ,SAAS;EAC/B,QAAQ,OAAO,OAAO,EAAE,sBAAsB,OAAO,QAAQ,CAAC;EAC9D,CAAC;CACF,OAAO,OAAO;EACb,OAAO,OAAO,QAAQ,YAAY;EAClC,WAAW,OAAO,QAAQ,KAAK;EAC/B,CAAC;CACF,OAAO,OAAO;EACb,OAAO,OAAO,QAAQ,wBAAwB;EAC9C,uBAAuB,OAAO;EAC9B,CAAC;CACF,OAAO,OAAO;EACb,OAAO,OAAO,QAAQ,SAAS;EAC/B,QAAQ,OAAO;EACf,CAAC;CACF,OAAO,OAAO;EACb,OAAO,OAAO,QAAQ,UAAU;EAChC,SAAS,OAAO;EAChB,CAAC;CACF,CAAC;;;;;AAMF,MAAa,uBAAuB,OAAO,OAAO;CACjD,UAAU,OAAO;CACjB,MAAM,OAAO;CACb,SAAS,OAAO;CAChB,OAAO;CACP,CAAC;AAEwC,OAAO,OAAO,EACvD,QAAQ,sBACR,CAAC;;;;;AAwEF,MAAa,qBAAqB,KAAiB,WAA4C,EAC9F,MACC,KACA,QACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAe,OAAO,OAAO,WAAW;EAC7C,WACC,IAAI,SAAS,WACV,IAAI,KAAK,UAAU,EAAE,UAAU,IAAI,UAAU,CAAC,GAC9C,IAAI,KAAK,eAAe,EAAE,QAAQ,IAAI,QAAQ,CAAC;EACnD,QAAQ,WAA4B;GACnC,MAAM;GACN,QAAQ,WAAW,MAAM,GAAG,cAAc;GAC1C;GACA,QAAQ,eAAe,MAAM;GAC7B;EACD,CAAC,CAAC,KAGF,OAAO,OACL,QACA,SAAS,cAAc,IAAI,WAAW,eAAe,IAAI,WAAW,eACjE,OAAO,QAAQ,KAAK,GACpB,OAAO,KAAK,IAAI,CACpB,CACD;AACD,KAAI,QAAQ,KAAM,QAAO;CACzB,MAAM,UAAU,oBAAoB,KAAK,IAAI;AAC7C,KAAI,YAAY,KAAM,QAAO;AAc7B,QAAO,OATgB,cAAc,QAAQ,SAAS;EACrD,QAAQ,eAAe;EACvB,UAAU,WAA4B;GACrC,MAAM;GACN,QAAQ;GACR;GACA,QAAQ,eAAe,MAAM,SAAS,MAAM;GAC5C;EACD,CAAC;EAED,EACH;AAED,MAAM,uBAAuB,KAAkB,QAAiC;AAC/E,KAAI,IAAI,SAAS,cAAe,QAAO,0BAA0B,IAAI;AACrE,KAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,YAAY,KAAM,QAAO;AAE1E,QAAQ,IAAsC,UAAU;;AAGzD,MAAM,6BAA6B,QAAiC;AACnE,KAAI,OAAO,QAAQ,YAAY,QAAQ,KAAM,QAAO;CACpD,MAAM,WAAW;AAKjB,KAAI,SAAS,UAAU,cAAe,QAAO,SAAS,eAAe;AACrE,KAAI,SAAS,UAAU,oBAAqB,QAAO,SAAS,qBAAqB;AACjF,QAAO;;;;;;AAOR,MAAM,cAAc,UAA4B;CAC/C,MAAM,MAAO,OAAgC,SAAS,aAAa,IAAI;AACvE,QACC,IAAI,SAAS,YAAY,IACzB,IAAI,SAAS,iBAAiB,IAC9B,IAAI,SAAS,iBAAiB,IAC9B,IAAI,SAAS,YAAY;;AAI3B,MAAM,kBAAkB,UAA2B;AAClD,KAAI,iBAAiB,MAAO,QAAO,MAAM;AACzC,KAAI,OAAO,UAAU,SAAU,QAAO;AACtC,KAAI;AACH,SAAO,KAAK,UAAU,MAAM;SACrB;AACP,SAAO,OAAO,MAAM"}
+{"version":3,"file":"chain-probe.mjs","names":[],"sources":["../../../src/plugins/sui/chain-probe.ts"],"sourcesContent":["// Sui plugin — ChainProbe capability implementation.\n//\n// Architecture §9: ChainProbe is a contract, NOT a primitive. Sui\n// provides the only in-tree implementation; the substrate dispatches\n// to it via the StrategyContributor registry under\n// `chain-probe:<chainId>`.\n//\n// Lenient mode: returns null for both \"not found\" AND transient RPC\n// failure — verify pipelines re-derive on the next cycle rather than\n// fail boot. Strict mode: distinguishes via tagged error.\n//\n// Why lenient is the default in this plugin's wiring: artifact publisher verify is\n// the dominant consumer; artifact publisher's lenient-retry profile (15 attempts,\n// 90s budget) is calibrated against lenient semantics. A strict\n// surface exists for explicit \"I want to know if the chain is\n// reachable\" callers (the doctor command, debugging).\n\nimport { Effect } from 'effect';\nimport type { ClientWithCoreApi } from '@mysten/sui/client';\n\nimport type {\n\tChainProbe,\n\tChainProbeError,\n\tChainProbeMode,\n\tChainProbeSchema,\n} from '../../contracts/chain-probe.ts';\nimport { decodeUnknown } from '../../substrate/runtime/runtime-decode.ts';\nimport { formatUnknownError } from '../../substrate/runtime/format-unknown-error.ts';\n\n/**\n * Sui's chain-key shape — discriminated so the probe can dispatch\n * between object reads, tx reads, and the (forthcoming) batch\n * variant on one method.\n */\nexport type SuiProbeKey =\n\t| { readonly kind: 'object'; readonly objectId: string }\n\t| { readonly kind: 'transaction'; readonly digest: string };\n\n// Note: this probe decodes against the CALLER-supplied `schema`\n// argument (see `makeSuiChainProbe`), never a local literal. Earlier\n// revisions also exported `SuiObjectShapeSchema` /\n// `SuiGetObjectResponseSchema` to \"document the SDK shape\", but they\n// had zero consumers (the contract's `ChainProbeSchema<Shape>` is what\n// validates), so per STYLE_GUIDE §5 (no orphan exports) they were\n// removed. Re-add a concrete object schema only if a caller actually\n// decodes through it.\n\n/** Plugin-internal SDK shim — the type the plugin's acquire body\n *  hands to the probe factory + the account's sign/execute closure.\n *  Kept narrow so we don't pull `@mysten/sui` types into the substrate.\n *\n *  Exposes the four surfaces consumers actually use:\n *\n *    - `getObject` / `getTransaction` — the lenient chain probe.\n *    - `executeTransaction` — the account plugin's submit path\n *      (txBytes + caller-signed signatures).\n *    - `waitForTransaction` — post-submit finality wait.\n *\n *  Plus an OPAQUE `client` field — the underlying `SuiGrpcClient`\n *  reference. The package plugin's publish-tx builder hands this to\n *  `Transaction.build({ client })` (the SDK resolves gas + object\n *  versions through it). We type as `unknown` so the substrate stays\n *  free of a direct `@mysten/sui/client` type import; the consumer\n *  casts at the boundary (mirrors the same opacity decision in the\n *  Coin plugin's `MintSdkShim.client`). */\nexport interface SuiSdkShim {\n\treadonly core: {\n\t\treadonly getObject: (args: {\n\t\t\treadonly objectId: string;\n\t\t\treadonly include?: {\n\t\t\t\treadonly content?: boolean;\n\t\t\t\treadonly json?: boolean;\n\t\t\t};\n\t\t}) => Promise<unknown>;\n\t\treadonly getTransaction: (args: { readonly digest: string }) => Promise<unknown>;\n\t\treadonly getBalance: (args: {\n\t\t\treadonly owner: string;\n\t\t\treadonly coinType?: string;\n\t\t}) => Promise<unknown>;\n\t\treadonly listCoins: (args: {\n\t\t\treadonly owner: string;\n\t\t\treadonly coinType?: string;\n\t\t\treadonly limit?: number;\n\t\t\treadonly cursor?: string | null;\n\t\t}) => Promise<{\n\t\t\treadonly objects: ReadonlyArray<{\n\t\t\t\treadonly objectId: string;\n\t\t\t\treadonly version: string;\n\t\t\t\treadonly digest: string;\n\t\t\t\treadonly balance: string;\n\t\t\t}>;\n\t\t\treadonly hasNextPage: boolean;\n\t\t\treadonly cursor: string | null;\n\t\t}>;\n\t\treadonly executeTransaction: (args: {\n\t\t\treadonly transaction: Uint8Array;\n\t\t\treadonly signatures: ReadonlyArray<string>;\n\t\t\treadonly include?: {\n\t\t\t\treadonly effects?: boolean;\n\t\t\t\treadonly objectTypes?: boolean;\n\t\t\t};\n\t\t}) => Promise<unknown>;\n\t\treadonly waitForTransaction: (args: {\n\t\t\treadonly digest: string;\n\t\t\treadonly timeout?: number;\n\t\t}) => Promise<unknown>;\n\t};\n\t/** Client reference for `Transaction.build({ client })` and every\n\t *  `client.core.*` call. The Sui barrel wires the resolved\n\t *  `SuiGrpcClient` through; consumers cast no further. */\n\treadonly client: ClientWithCoreApi;\n}\n\n/** Construct the chain-probe instance for a resolved Sui client +\n *  chain id. The result implements the contract's `ChainProbe<Key>`\n *  shape; the Sui plugin emits this via a StrategyContributorDecl\n *  keyed by `chain-probe:<chainId>`. */\nexport const makeSuiChainProbe = (sdk: SuiSdkShim, chain: string): ChainProbe<SuiProbeKey> => ({\n\tget: <Shape>(\n\t\tkey: SuiProbeKey,\n\t\tschema: ChainProbeSchema<Shape>,\n\t\tmode: ChainProbeMode,\n\t): Effect.Effect<Shape | null, ChainProbeError> =>\n\t\tEffect.gen(function* () {\n\t\t\tconst raw: unknown = yield* Effect.tryPromise({\n\t\t\t\ttry: () =>\n\t\t\t\t\tkey.kind === 'object'\n\t\t\t\t\t\t? sdk.core.getObject({ objectId: key.objectId })\n\t\t\t\t\t\t: sdk.core.getTransaction({ digest: key.digest }),\n\t\t\t\tcatch: (cause): ChainProbeError => ({\n\t\t\t\t\t_tag: 'ChainProbeError',\n\t\t\t\t\treason: isNotFound(cause) ? 'not-found' : 'transient',\n\t\t\t\t\tchain,\n\t\t\t\t\tdetail: formatUnknownError(cause),\n\t\t\t\t}),\n\t\t\t}).pipe(\n\t\t\t\t// Lenient mode coerces both not-found and transient into a\n\t\t\t\t// null result. Strict mode lets the error propagate.\n\t\t\t\tEffect.catch(\n\t\t\t\t\t(err): Effect.Effect<unknown, ChainProbeError> =>\n\t\t\t\t\t\tmode === 'lenient' && (err.reason === 'not-found' || err.reason === 'transient')\n\t\t\t\t\t\t\t? Effect.succeed(null)\n\t\t\t\t\t\t\t: Effect.fail(err),\n\t\t\t\t),\n\t\t\t);\n\t\t\tif (raw === null) return null;\n\t\t\tconst payload = projectProbePayload(key, raw);\n\t\t\tif (payload === null) return null;\n\n\t\t\t// Decode against the caller-supplied Schema. A decode failure\n\t\t\t// is structured (NOT silent undefined) — this is the\n\t\t\t// load-bearing learning from deepbook.\n\t\t\tconst decoded = yield* decodeUnknown(schema, payload, {\n\t\t\t\tsource: `chain probe ${chain}`,\n\t\t\t\tmkError: (issue): ChainProbeError => ({\n\t\t\t\t\t_tag: 'ChainProbeError',\n\t\t\t\t\treason: 'decode-failed',\n\t\t\t\t\tchain,\n\t\t\t\t\tdetail: formatUnknownError(issue.cause ?? issue),\n\t\t\t\t}),\n\t\t\t});\n\t\t\treturn decoded;\n\t\t}),\n});\n\nconst projectProbePayload = (key: SuiProbeKey, raw: unknown): unknown | null => {\n\tif (key.kind === 'transaction') return projectTransactionPayload(raw);\n\tif (typeof raw !== 'object' || raw === null || !('object' in raw)) return raw;\n\n\treturn (raw as { readonly object?: unknown }).object ?? null;\n};\n\nconst projectTransactionPayload = (raw: unknown): unknown | null => {\n\tif (typeof raw !== 'object' || raw === null) return raw;\n\tconst envelope = raw as {\n\t\treadonly $kind?: 'Transaction' | 'FailedTransaction';\n\t\treadonly Transaction?: unknown;\n\t\treadonly FailedTransaction?: unknown;\n\t};\n\tif (envelope.$kind === 'Transaction') return envelope.Transaction ?? null;\n\tif (envelope.$kind === 'FailedTransaction') return envelope.FailedTransaction ?? null;\n\treturn raw;\n};\n\n/** Heuristic: SDK errors carrying object/transaction-shape \"not found\"\n *  markers are treated as terminal not-found; everything else is\n *  transient. The substrate's lenient-retry profile re-runs the probe\n *  on a transient bucket; not-found is terminal.\n *\n *  Limitation: `@mysten/sui` does NOT surface a structured status code\n *  on its SDK errors — the substrate only sees an `Error` message. We\n *  therefore narrow the substring matches as much as possible to avoid\n *  misclassifying network-layer \"endpoint does not exist\" or generic\n *  \"not found\" prose as terminal:\n *\n *  - We require the matched phrase to refer to the OBJECT or\n *    TRANSACTION rather than the endpoint. Concretely we look for the\n *    SDK's canonical \"object not found\" / \"object does not exist\" /\n *    \"no such object\" wording and the equivalent \"transaction not\n *    found\" / \"transaction does not exist\" wording.\n *  - We DO NOT match the bare substring \"not found\" alone (that\n *    catches \"endpoint does not exist\", DNS prose, etc. — all of\n *    which are network-layer transients).\n *\n *  If `@mysten/sui` surfaces a structured error class with an\n *  `httpStatus` (or equivalent) in the future, swap this for an\n *  exact 404 / -32000 check. */\nconst isNotFound = (cause: unknown): boolean => {\n\tconst msg = (cause as { message?: string })?.message?.toLowerCase() ?? '';\n\treturn (\n\t\t// SDK-side `getObject` / `getTransaction` not-found markers.\n\t\t/\\bobject\\b.*\\bnot found\\b/u.test(msg) ||\n\t\t/\\bobject\\b.*\\bdoes not exist\\b/u.test(msg) ||\n\t\t/\\bno such object\\b/u.test(msg) ||\n\t\t// SDK-side `getTransaction` not-found markers — terminal for\n\t\t// this probe (the queried digest will never materialise).\n\t\t/\\btransaction\\b.*\\bnot found\\b/u.test(msg) ||\n\t\t/\\btransaction\\b.*\\bdoes not exist\\b/u.test(msg)\n\t);\n};\n"],"mappings":";;;;;;;;AAqHA,MAAa,qBAAqB,KAAiB,WAA4C,EAC9F,MACC,KACA,QACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAe,OAAO,OAAO,WAAW;EAC7C,WACC,IAAI,SAAS,WACV,IAAI,KAAK,UAAU,EAAE,UAAU,IAAI,UAAU,CAAC,GAC9C,IAAI,KAAK,eAAe,EAAE,QAAQ,IAAI,QAAQ,CAAC;EACnD,QAAQ,WAA4B;GACnC,MAAM;GACN,QAAQ,WAAW,MAAM,GAAG,cAAc;GAC1C;GACA,QAAQ,mBAAmB,MAAM;GACjC;EACD,CAAC,CAAC,KAGF,OAAO,OACL,QACA,SAAS,cAAc,IAAI,WAAW,eAAe,IAAI,WAAW,eACjE,OAAO,QAAQ,KAAK,GACpB,OAAO,KAAK,IAAI,CACpB,CACD;AACD,KAAI,QAAQ,KAAM,QAAO;CACzB,MAAM,UAAU,oBAAoB,KAAK,IAAI;AAC7C,KAAI,YAAY,KAAM,QAAO;AAc7B,QAAO,OATgB,cAAc,QAAQ,SAAS;EACrD,QAAQ,eAAe;EACvB,UAAU,WAA4B;GACrC,MAAM;GACN,QAAQ;GACR;GACA,QAAQ,mBAAmB,MAAM,SAAS,MAAM;GAChD;EACD,CAAC;EAED,EACH;AAED,MAAM,uBAAuB,KAAkB,QAAiC;AAC/E,KAAI,IAAI,SAAS,cAAe,QAAO,0BAA0B,IAAI;AACrE,KAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,EAAE,YAAY,KAAM,QAAO;AAE1E,QAAQ,IAAsC,UAAU;;AAGzD,MAAM,6BAA6B,QAAiC;AACnE,KAAI,OAAO,QAAQ,YAAY,QAAQ,KAAM,QAAO;CACpD,MAAM,WAAW;AAKjB,KAAI,SAAS,UAAU,cAAe,QAAO,SAAS,eAAe;AACrE,KAAI,SAAS,UAAU,oBAAqB,QAAO,SAAS,qBAAqB;AACjF,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA0BR,MAAM,cAAc,UAA4B;CAC/C,MAAM,MAAO,OAAgC,SAAS,aAAa,IAAI;AACvE,QAEC,6BAA6B,KAAK,IAAI,IACtC,kCAAkC,KAAK,IAAI,IAC3C,sBAAsB,KAAK,IAAI,IAG/B,kCAAkC,KAAK,IAAI,IAC3C,uCAAuC,KAAK,IAAI"}

package/dist/plugins/sui/codegen.mjs

@@ -1,5 +1,26 @@
 import { Effect } from "effect";
 //#region src/plugins/sui/codegen.ts
+/** Aggregate projection: fold the emitted `suiNetwork` shape into
+*  the cross-plugin `services.ts` aggregate at `services.sui`. The
+*  orchestrator stays plugin-name-blind; this projector owns the
+*  `{ rpc, faucet, graphql }` shape decision. */
+const projectSuiNetworkServices = (exported) => {
+	const network = exported["suiNetwork"];
+	if (typeof network !== "object" || network === null) return null;
+	const record = network;
+	const rpcUrl = stringField(record, "rpcUrl");
+	const faucetUrl = stringField(record, "faucetUrl");
+	const graphqlUrl = stringField(record, "graphqlUrl");
+	return { sui: {
+		rpc: { url: rpcUrl ?? "" },
+		faucet: faucetUrl === null ? null : { url: faucetUrl },
+		graphql: graphqlUrl === null ? null : { url: graphqlUrl }
+	} };
+};
+const stringField = (record, key) => {
+	const value = record[key];
+	return typeof value === "string" && value.length > 0 ? value : null;
+};
 /** Construct the Codegenable contribution. Emit is byte-deterministic
 *  on unchanged input (architecture: no mtime churn on no-op
 *  cycles). */
@@ -7,6 +28,11 @@ const makeCodegenable = (resolved) => ({
 	kind: "codegenable",
 	emitterName: "sui-network",
 	outputPath: "sui/network.ts",
+	aggregate: {
+		kind: "sui-network",
+		bucket: "services.ts",
+		project: projectSuiNetworkServices
+	},
 	emit: (ctx) => Effect.sync(() => {
 		const bindings = {
 			chain: resolved.chain,

package/dist/plugins/sui/codegen.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/sui/codegen.ts"],"sourcesContent":["// Sui plugin — Codegenable contribution.\n//\n// Architecture §6: plugins emit typed `CodegenableDecl`s; the\n// codegen orchestrator stages files into the user's source tree\n// WITHOUT naming the plugin. Sui's contribution is network\n// metadata: the active RPC endpoint, the chain id, and (when\n// applicable) the resolved known-package ids.\n//\n// Downstream consumers — chain-aware code (e.g. SDK boots, wallet\n// pickers, frontend RPC selectors) — `import { suiNetwork } from\n// '<staging>/sui/network'`; the generated module owns that exported\n// value's type.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\nimport type { ResolvedSuiNetwork } from './network-resolver.ts';\n\n/** The typed shape the emitted file exports. */\nexport interface SuiNetworkBindings {\n\treadonly chain: string;\n\treadonly mode: 'local' | 'local-rpc' | 'live' | 'fork';\n\treadonly rpcUrl: string;\n\treadonly faucetUrl: string | null;\n\treadonly graphqlUrl: string | null;\n\t/** Fork-only — upstream identity for known-package lookups. */\n\treadonly forkUpstream: string | null;\n}\n\n/** Construct the Codegenable contribution. Emit is byte-deterministic\n *  on unchanged input (architecture: no mtime churn on no-op\n *  cycles). */\nexport const makeCodegenable = (resolved: ResolvedSuiNetwork): CodegenableDecl<'sui-network'> => ({\n\tkind: 'codegenable',\n\temitterName: 'sui-network',\n\toutputPath: 'sui/network.ts',\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tconst bindings: SuiNetworkBindings = {\n\t\t\t\tchain: resolved.chain,\n\t\t\t\tmode: resolved.mode,\n\t\t\t\trpcUrl: resolved.rpc,\n\t\t\t\tfaucetUrl: resolved.faucet ?? null,\n\t\t\t\tgraphqlUrl: resolved.graphql ?? null,\n\t\t\t\tforkUpstream: resolved.forkUpstream ?? null,\n\t\t\t};\n\t\t\tctx.exportConst('suiNetwork', bindings);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;AAgCA,MAAa,mBAAmB,cAAkE;CACjG,MAAM;CACN,aAAa;CACb,YAAY;CACZ,OAAO,QACN,OAAO,WAAW;EACjB,MAAM,WAA+B;GACpC,OAAO,SAAS;GAChB,MAAM,SAAS;GACf,QAAQ,SAAS;GACjB,WAAW,SAAS,UAAU;GAC9B,YAAY,SAAS,WAAW;GAChC,cAAc,SAAS,gBAAgB;GACvC;AACD,MAAI,YAAY,cAAc,SAAS;AACvC,SAAO,IAAI,MAAM;GAChB;CACH"}
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/sui/codegen.ts"],"sourcesContent":["// Sui plugin — Codegenable contribution.\n//\n// Architecture §6: plugins emit typed `CodegenableDecl`s; the\n// codegen orchestrator stages files into the user's source tree\n// WITHOUT naming the plugin. Sui's contribution is network\n// metadata: the active RPC endpoint, the chain id, and (when\n// applicable) the resolved known-package ids.\n//\n// Downstream consumers — chain-aware code (e.g. SDK boots, wallet\n// pickers, frontend RPC selectors) — `import { suiNetwork } from\n// '<staging>/sui/network'`; the generated module owns that exported\n// value's type.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\nimport type { ResolvedSuiNetwork } from './network-resolver.ts';\n\n/** The typed shape the emitted file exports. */\nexport interface SuiNetworkBindings {\n\treadonly chain: string;\n\treadonly mode: 'local' | 'local-rpc' | 'live' | 'fork';\n\treadonly rpcUrl: string;\n\treadonly faucetUrl: string | null;\n\treadonly graphqlUrl: string | null;\n\t/** Fork-only — upstream identity for known-package lookups. */\n\treadonly forkUpstream: string | null;\n}\n\n/** Aggregate projection: fold the emitted `suiNetwork` shape into\n *  the cross-plugin `services.ts` aggregate at `services.sui`. The\n *  orchestrator stays plugin-name-blind; this projector owns the\n *  `{ rpc, faucet, graphql }` shape decision. */\nconst projectSuiNetworkServices = (\n\texported: Readonly<Record<string, unknown>>,\n): Readonly<Record<string, unknown>> | null => {\n\tconst network = exported['suiNetwork'];\n\tif (typeof network !== 'object' || network === null) return null;\n\tconst record = network as Readonly<Record<string, unknown>>;\n\tconst rpcUrl = stringField(record, 'rpcUrl');\n\tconst faucetUrl = stringField(record, 'faucetUrl');\n\tconst graphqlUrl = stringField(record, 'graphqlUrl');\n\treturn {\n\t\tsui: {\n\t\t\trpc: { url: rpcUrl ?? '' },\n\t\t\tfaucet: faucetUrl === null ? null : { url: faucetUrl },\n\t\t\tgraphql: graphqlUrl === null ? null : { url: graphqlUrl },\n\t\t},\n\t};\n};\n\nconst stringField = (record: Readonly<Record<string, unknown>>, key: string): string | null => {\n\tconst value = record[key];\n\treturn typeof value === 'string' && value.length > 0 ? value : null;\n};\n\n/** Construct the Codegenable contribution. Emit is byte-deterministic\n *  on unchanged input (architecture: no mtime churn on no-op\n *  cycles). */\nexport const makeCodegenable = (resolved: ResolvedSuiNetwork): CodegenableDecl<'sui-network'> => ({\n\tkind: 'codegenable',\n\temitterName: 'sui-network',\n\toutputPath: 'sui/network.ts',\n\taggregate: {\n\t\tkind: 'sui-network',\n\t\tbucket: 'services.ts',\n\t\tproject: projectSuiNetworkServices,\n\t},\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tconst bindings: SuiNetworkBindings = {\n\t\t\t\tchain: resolved.chain,\n\t\t\t\tmode: resolved.mode,\n\t\t\t\trpcUrl: resolved.rpc,\n\t\t\t\tfaucetUrl: resolved.faucet ?? null,\n\t\t\t\tgraphqlUrl: resolved.graphql ?? null,\n\t\t\t\tforkUpstream: resolved.forkUpstream ?? null,\n\t\t\t};\n\t\t\tctx.exportConst('suiNetwork', bindings);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;;AAiCA,MAAM,6BACL,aAC8C;CAC9C,MAAM,UAAU,SAAS;AACzB,KAAI,OAAO,YAAY,YAAY,YAAY,KAAM,QAAO;CAC5D,MAAM,SAAS;CACf,MAAM,SAAS,YAAY,QAAQ,SAAS;CAC5C,MAAM,YAAY,YAAY,QAAQ,YAAY;CAClD,MAAM,aAAa,YAAY,QAAQ,aAAa;AACpD,QAAO,EACN,KAAK;EACJ,KAAK,EAAE,KAAK,UAAU,IAAI;EAC1B,QAAQ,cAAc,OAAO,OAAO,EAAE,KAAK,WAAW;EACtD,SAAS,eAAe,OAAO,OAAO,EAAE,KAAK,YAAY;EACzD,EACD;;AAGF,MAAM,eAAe,QAA2C,QAA+B;CAC9F,MAAM,QAAQ,OAAO;AACrB,QAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;;;;;AAMhE,MAAa,mBAAmB,cAAkE;CACjG,MAAM;CACN,aAAa;CACb,YAAY;CACZ,WAAW;EACV,MAAM;EACN,QAAQ;EACR,SAAS;EACT;CACD,OAAO,QACN,OAAO,WAAW;EACjB,MAAM,WAA+B;GACpC,OAAO,SAAS;GAChB,MAAM,SAAS;GACf,QAAQ,SAAS;GACjB,WAAW,SAAS,UAAU;GAC9B,YAAY,SAAS,WAAW;GAChC,cAAc,SAAS,gBAAgB;GACvC;AACD,MAAI,YAAY,cAAc,SAAS;AACvC,SAAO,IAAI,MAAM;GAChB;CACH"}

package/dist/plugins/sui/errors.d.mts

@@ -40,35 +40,8 @@ interface ForkUnsupportedError {
   readonly surface: string;
   readonly hint: string;
 }
-/** Raised when fork meta-config drifts between supervisor boots.
- *  Carries previous + current snapshots so the doctor / TUI can
- *  diff them. Consumed inside Sui's fork acquire — does NOT cross
- *  plugin boundaries (the recipe is "wipe and re-apply"). */
-interface SeedManifestMismatchError {
-  readonly _tag: 'SeedManifestMismatchError';
-  readonly previous: {
-    readonly upstream: string;
-    readonly checkpoint?: string;
-    readonly configHash: string;
-  };
-  readonly current: {
-    readonly upstream: string;
-    readonly checkpoint?: string;
-    readonly configHash: string;
-  };
-  readonly hint: string;
-}
-/** Raised when the funds-ready gate times out against a real
- *  faucet. Plugin-internal — Sui contributes this strategy and
- *  consumes its own error. */
-interface SuiFundsReadyError {
-  readonly _tag: 'SuiFundsReadyError';
-  readonly attempts: number;
-  readonly lastBody?: string;
-  readonly hint: string;
-}
 /** Union of every error a Sui-plugin caller may encounter. */
-type SuiError = SuiPluginError | SuiCliError | SuiConfigError | ForkUnsupportedError | SeedManifestMismatchError | SuiFundsReadyError;
+type SuiError = SuiPluginError | SuiCliError | SuiConfigError | ForkUnsupportedError;
 //#endregion
-export { ForkUnsupportedError, SeedManifestMismatchError, SuiCliError, SuiConfigError, SuiError, SuiFundsReadyError, SuiPluginError };
+export { ForkUnsupportedError, SuiCliError, SuiConfigError, SuiError, SuiPluginError };
 //# sourceMappingURL=errors.d.mts.map

package/dist/plugins/sui/errors.mjs

@@ -18,9 +18,7 @@ const SUI_ERROR_TAGS = [
 	"SuiPluginError",
 	"SuiCliError",
 	"SuiConfigError",
-	"ForkUnsupportedError",
-	"SeedManifestMismatchError",
-	"SuiFundsReadyError"
+	"ForkUnsupportedError"
 ];
 //#endregion
 export { SUI_ERROR_TAGS, forkUnsupportedError, suiConfigError, suiPluginError };

package/dist/plugins/sui/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/sui/errors.ts"],"sourcesContent":["// Sui plugin — typed errors.\n//\n// Distilled-doc finding: today's codebase centralises EVERY tagged\n// error in one engine file, but consumer boundaries cross service\n// lines. The architecture lets us redistribute: errors raised AND\n// consumed inside the Sui plugin live here. Cross-service errors\n// (`ForkIncompatibleError`, `SeedManifestMismatchError`) live with\n// the plugin that consumes them — Walrus/Seal/Deepbook own\n// `ForkIncompatibleError`; the seed-manifest error stays here\n// because Sui's fork acquire is the only raise site AND the only\n// consumer.\n//\n// Effect v4: errors are plain interfaces with a `_tag` discriminator\n// — we don't subclass an Effect base class; `Effect.catchTag` /\n// `catchTags` match on `_tag` literal. See architecture § Effect.\n\nimport { defineConfigError, type ConfigIssue } from '../../substrate/runtime/config-validation.ts';\n\n/** Phases for `SuiError`. Closed sum — keeps the cause-walker's\n *  display table small. Add a phase only after editing the\n *  catalog in the plugin doc. */\nexport type SuiPhase =\n\t| 'image-build'\n\t| 'port-allocate'\n\t| 'container-start'\n\t| 'rpc-probe'\n\t| 'faucet-probe'\n\t| 'graphql-probe'\n\t| 'fork-status-probe'\n\t| 'chain-id-fetch'\n\t| 'wait-funds-ready'\n\t| 'fork-impersonate'\n\t| 'fork-advance-clock'\n\t| 'fork-advance-checkpoint'\n\t| 'fork-lock'\n\t| 'fork-data-dir'\n\t| 'move-build'\n\t| 'move-publish';\n\n/** Generic Sui plugin error. Raised by the plugin's acquire body\n *  and its admin surface (`advanceClock`, `impersonate`, …). */\nexport interface SuiPluginError {\n\treadonly _tag: 'SuiPluginError';\n\treadonly phase: SuiPhase;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const suiPluginError = (\n\tphase: SuiPhase,\n\tmessage: string,\n\tcause?: unknown,\n): SuiPluginError => ({ _tag: 'SuiPluginError', phase, message, cause });\n\nexport interface SuiConfigError extends ConfigIssue {\n\treadonly _tag: 'SuiConfigError';\n}\n\nexport const suiConfigError = defineConfigError('SuiConfigError');\n\n/** Move-build / sui-cli error. Carries the sub-process capture\n *  envelope (exit + stderr + stdout). The plugin doc lists 11\n *  shell-shaped phases today; we tighten to a much smaller set\n *  and use `op` as a free-form column.\n *\n *  Stub: the closed-vs-open phase decision is deferred to the\n *  cli-driver implementation pass. */\nexport interface SuiCliError {\n\treadonly _tag: 'SuiCliError';\n\treadonly op: 'build' | 'publish' | 'summary' | 'scrub' | 'spawn';\n\treadonly exitCode?: number;\n\treadonly stderr?: string;\n\treadonly stdout?: string;\n\treadonly cause?: unknown;\n}\n\nexport const suiCliError = (\n\top: SuiCliError['op'],\n\tparts: Omit<SuiCliError, '_tag' | 'op'>,\n): SuiCliError => ({ _tag: 'SuiCliError', op, ...parts });\n\n/** Synchronous refusal raised by the fork SDK guard. The guard\n *  intercepts at property-access time so the wire call never\n *  happens — failing fast lets callers branch on this without\n *  awaiting a transport-level reject. */\nexport interface ForkUnsupportedError {\n\treadonly _tag: 'ForkUnsupportedError';\n\treadonly surface: string;\n\treadonly hint: string;\n}\n\nexport const forkUnsupportedError = (surface: string, hint: string): ForkUnsupportedError => ({\n\t_tag: 'ForkUnsupportedError',\n\tsurface,\n\thint,\n});\n\n/** Raised when fork meta-config drifts between supervisor boots.\n *  Carries previous + current snapshots so the doctor / TUI can\n *  diff them. Consumed inside Sui's fork acquire — does NOT cross\n *  plugin boundaries (the recipe is \"wipe and re-apply\"). */\nexport interface SeedManifestMismatchError {\n\treadonly _tag: 'SeedManifestMismatchError';\n\treadonly previous: {\n\t\treadonly upstream: string;\n\t\treadonly checkpoint?: string;\n\t\treadonly configHash: string;\n\t};\n\treadonly current: {\n\t\treadonly upstream: string;\n\t\treadonly checkpoint?: string;\n\t\treadonly configHash: string;\n\t};\n\treadonly hint: string;\n}\n\n/** Raised when the funds-ready gate times out against a real\n *  faucet. Plugin-internal — Sui contributes this strategy and\n *  consumes its own error. */\nexport interface SuiFundsReadyError {\n\treadonly _tag: 'SuiFundsReadyError';\n\treadonly attempts: number;\n\treadonly lastBody?: string;\n\treadonly hint: string;\n}\n\n/** Union of every error a Sui-plugin caller may encounter. */\nexport type SuiError =\n\t| SuiPluginError\n\t| SuiCliError\n\t| SuiConfigError\n\t| ForkUnsupportedError\n\t| SeedManifestMismatchError\n\t| SuiFundsReadyError;\n\n/** Error tags this plugin contributes — surfaced to the cause\n *  walker via `PluginErrorContribution`. */\nexport const SUI_ERROR_TAGS: ReadonlyArray<SuiError['_tag']> = [\n\t'SuiPluginError',\n\t'SuiCliError',\n\t'SuiConfigError',\n\t'ForkUnsupportedError',\n\t'SeedManifestMismatchError',\n\t'SuiFundsReadyError',\n] as const;\n"],"mappings":";;AAgDA,MAAa,kBACZ,OACA,SACA,WACqB;CAAE,MAAM;CAAkB;CAAO;CAAS;CAAO;AAMvE,MAAa,iBAAiB,kBAAkB,iBAAiB;AAiCjE,MAAa,wBAAwB,SAAiB,UAAwC;CAC7F,MAAM;CACN;CACA;CACA;;;AA0CD,MAAa,iBAAkD;CAC9D;CACA;CACA;CACA;CACA;CACA;CACA"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/sui/errors.ts"],"sourcesContent":["// Sui plugin — typed errors.\n//\n// Distilled-doc finding: today's codebase centralises EVERY tagged\n// error in one engine file, but consumer boundaries cross service\n// lines. The architecture lets us redistribute: errors raised AND\n// consumed inside the Sui plugin live here. Cross-service errors\n// (`ForkIncompatibleError`) live with the plugin that consumes them\n// — Walrus/Seal/Deepbook own `ForkIncompatibleError`.\n//\n// Effect v4: errors are plain interfaces with a `_tag` discriminator\n// — we don't subclass an Effect base class; `Effect.catchTag` /\n// `catchTags` match on `_tag` literal. See architecture § Effect.\n\nimport { defineConfigError, type ConfigIssue } from '../../substrate/runtime/config-validation.ts';\n\n/** Phases for `SuiError`. Closed sum — keeps the cause-walker's\n *  display table small. Add a phase only after editing the\n *  catalog in the plugin doc. */\nexport type SuiPhase =\n\t| 'image-build'\n\t| 'port-allocate'\n\t| 'container-start'\n\t| 'rpc-probe'\n\t| 'faucet-probe'\n\t| 'graphql-probe'\n\t| 'fork-status-probe'\n\t| 'chain-id-fetch'\n\t| 'wait-funds-ready'\n\t| 'fork-impersonate'\n\t| 'fork-advance-clock'\n\t| 'fork-advance-checkpoint'\n\t| 'fork-lock'\n\t| 'fork-data-dir'\n\t| 'move-build'\n\t| 'move-publish';\n\n/** Generic Sui plugin error. Raised by the plugin's acquire body\n *  and its admin surface (`advanceClock`, `impersonate`, …). */\nexport interface SuiPluginError {\n\treadonly _tag: 'SuiPluginError';\n\treadonly phase: SuiPhase;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const suiPluginError = (\n\tphase: SuiPhase,\n\tmessage: string,\n\tcause?: unknown,\n): SuiPluginError => ({ _tag: 'SuiPluginError', phase, message, cause });\n\nexport interface SuiConfigError extends ConfigIssue {\n\treadonly _tag: 'SuiConfigError';\n}\n\nexport const suiConfigError = defineConfigError('SuiConfigError');\n\n/** Move-build / sui-cli error. Carries the sub-process capture\n *  envelope (exit + stderr + stdout). The plugin doc lists 11\n *  shell-shaped phases today; we tighten to a much smaller set\n *  and use `op` as a free-form column.\n *\n *  Stub: the closed-vs-open phase decision is deferred to the\n *  cli-driver implementation pass. */\nexport interface SuiCliError {\n\treadonly _tag: 'SuiCliError';\n\treadonly op: 'build' | 'publish' | 'summary' | 'scrub' | 'spawn';\n\treadonly exitCode?: number;\n\treadonly stderr?: string;\n\treadonly stdout?: string;\n\treadonly cause?: unknown;\n}\n\nexport const suiCliError = (\n\top: SuiCliError['op'],\n\tparts: Omit<SuiCliError, '_tag' | 'op'>,\n): SuiCliError => ({ _tag: 'SuiCliError', op, ...parts });\n\n/** Synchronous refusal raised by the fork SDK guard. The guard\n *  intercepts at property-access time so the wire call never\n *  happens — failing fast lets callers branch on this without\n *  awaiting a transport-level reject. */\nexport interface ForkUnsupportedError {\n\treadonly _tag: 'ForkUnsupportedError';\n\treadonly surface: string;\n\treadonly hint: string;\n}\n\nexport const forkUnsupportedError = (surface: string, hint: string): ForkUnsupportedError => ({\n\t_tag: 'ForkUnsupportedError',\n\tsurface,\n\thint,\n});\n\n/** Union of every error a Sui-plugin caller may encounter. */\nexport type SuiError =\n\t| SuiPluginError\n\t| SuiCliError\n\t| SuiConfigError\n\t| ForkUnsupportedError;\n\n/** Error tags this plugin contributes — surfaced to the cause\n *  walker via `PluginErrorContribution`. */\nexport const SUI_ERROR_TAGS: ReadonlyArray<SuiError['_tag']> = [\n\t'SuiPluginError',\n\t'SuiCliError',\n\t'SuiConfigError',\n\t'ForkUnsupportedError',\n] as const;\n"],"mappings":";;AA6CA,MAAa,kBACZ,OACA,SACA,WACqB;CAAE,MAAM;CAAkB;CAAO;CAAS;CAAO;AAMvE,MAAa,iBAAiB,kBAAkB,iBAAiB;AAiCjE,MAAa,wBAAwB,SAAiB,UAAwC;CAC7F,MAAM;CACN;CACA;CACA;;;AAWD,MAAa,iBAAkD;CAC9D;CACA;CACA;CACA;CACA"}

package/dist/plugins/sui/fork-faucet-strategy.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/plugins/sui/fork-faucet-strategy.mjs

@@ -0,0 +1,55 @@
+import { leaseKey } from "../../substrate/runtime/lease-broker/service.mjs";
+import "../../substrate/runtime/lease-broker/index.mjs";
+import { formatUnknownError } from "../../substrate/runtime/format-unknown-error.mjs";
+import { SuiSpans } from "./spans.mjs";
+import { FORK_IMPERSONATION_GAS_BUDGET, buildForkImpersonationTransactionBytes, selectSufficientForkCoin } from "./fork-transaction.mjs";
+import { faucetBodyError } from "../faucet/errors.mjs";
+import "../faucet/index.mjs";
+import { Effect } from "effect";
+import { Transaction } from "@mysten/sui/transactions";
+//#region src/plugins/sui/fork-faucet-strategy.ts
+const sentinelUrl = (whale) => `fork-impersonation://${whale}`;
+const bodyError = (whale, address, amount, message) => faucetBodyError({
+	url: sentinelUrl(whale),
+	address,
+	amount,
+	status: 0,
+	reason: "failure-status",
+	message
+});
+const withSerialization = (serialization, effect) => {
+	if (serialization === void 0) return effect;
+	return Effect.scoped(Effect.gen(function* () {
+		yield* serialization.broker.acquire(leaseKey(serialization.key), serialization.owner);
+		yield* effect;
+	})).pipe(Effect.withSpan("devstack.plugin.sui.forkFaucet.serializedRequest", { attributes: {
+		[SuiSpans.localFaucetLeaseKey]: serialization.key,
+		[SuiSpans.localFaucetLeaseOwner]: serialization.owner
+	} }));
+};
+/** Build a SUI fork-faucet strategy that funds via whale impersonation. */
+const suiForkFaucetStrategy = (opts) => ({ request: ({ address, amount }) => {
+	const gasClient = opts.sdk.core;
+	const mapErr = (cause) => bodyError(opts.whale, address, amount, `sui fork faucet: ${cause.message}`);
+	const transfer = Effect.gen(function* () {
+		if (amount <= 0n) return;
+		if (amount > opts.perRequestCapMist) return yield* Effect.fail(bodyError(opts.whale, address, amount, `sui fork faucet: requested ${amount} MIST exceeds the per-request cap ${opts.perRequestCapMist} MIST (whale ${opts.whale}).`));
+		const { coin } = yield* selectSufficientForkCoin(gasClient, opts.whale, amount + FORK_IMPERSONATION_GAS_BUDGET).pipe(Effect.mapError(mapErr));
+		const tx = new Transaction();
+		tx.setSender(opts.whale);
+		const [funded] = tx.splitCoins(tx.gas, [tx.pure.u64(amount)]);
+		tx.transferObjects([funded], address);
+		const bytes = yield* buildForkImpersonationTransactionBytes(tx, opts.whale, gasClient, coin).pipe(Effect.mapError(mapErr));
+		const submitted = yield* opts.fork.impersonate(opts.whale, bytes).pipe(Effect.mapError(mapErr));
+		if (!submitted.success) return yield* Effect.fail(bodyError(opts.whale, address, amount, `sui fork faucet: impersonation tx ${submitted.digest} failed on-chain.`));
+		yield* Effect.tryPromise({
+			try: () => opts.sdk.core.waitForTransaction({ digest: submitted.digest }),
+			catch: (cause) => bodyError(opts.whale, address, amount, `sui fork faucet: waitForTransaction(${submitted.digest}) failed: ${formatUnknownError(cause)}`)
+		});
+	});
+	return withSerialization(opts.serialization, transfer).pipe(Effect.withSpan("devstack.plugin.sui.forkFaucet.request", { attributes: { [SuiSpans.forkFaucetWhale]: opts.whale } }));
+} });
+//#endregion
+export { suiForkFaucetStrategy };
+
+//# sourceMappingURL=fork-faucet-strategy.mjs.map

package/dist/plugins/sui/fork-faucet-strategy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork-faucet-strategy.mjs","names":[],"sources":["../../../src/plugins/sui/fork-faucet-strategy.ts"],"sourcesContent":["// SUI fork-faucet strategy — impersonation-based funding.\n//\n// Fork networks have no real faucet. This strategy funds a recipient by\n// IMPERSONATING a large-reserve \"whale\" address on the forked upstream\n// and transferring SUI from it: it builds `splitCoins(tx.gas, [amount])`\n// + `transferObjects([coin], recipient)` with the whale as sender, runs\n// it through the SAME impersonation path the package/action plugins use\n// (`buildForkImpersonationTransactionBytes` -> `fork.impersonate`, with\n// empty signatures), and waits for finality.\n//\n// It is registered into the `faucet:request:<chainId>` strategy registry\n// from `sui/index.ts` exactly like the local-faucet HTTP strategy, so\n// ephemeral-account auto-funding and cross-cutting SUI funding \"just\n// work\" in fork mode. (Dependency direction faucet <- sui: the sui\n// plugin imports the faucet contract/error types, never the reverse.)\n//\n// Error channel: account funding only catches FaucetUnreachable |\n// FaucetExhausted | FaucetBodyError (see account/funding.ts). The\n// impersonation path fails with SuiPluginError, so every internal\n// failure is mapped to FaucetBodyError here — otherwise it would escape\n// funding's `catchTags` and surface as an unhandled error.\n//\n// Concurrency: every request selects one sufficient whale SUI coin as\n// both gas payment and split source. Concurrent requests would race the\n// same coin version, so requests serialize on a chain-scoped lease.\n\nimport { Effect } from 'effect';\n\nimport { Transaction } from '@mysten/sui/transactions';\n\nimport { formatUnknownError } from '../../substrate/runtime/format-unknown-error.ts';\nimport { leaseKey, type LeaseBroker } from '../../substrate/runtime/lease-broker/index.ts';\nimport { faucetBodyError, type FaucetBodyError, type FaucetStrategy } from '../faucet/index.ts';\n\nimport type { SuiSdkShim } from './chain-probe.ts';\nimport type { SuiPluginError } from './errors.ts';\nimport {\n\tFORK_IMPERSONATION_GAS_BUDGET,\n\tbuildForkImpersonationTransactionBytes,\n\tselectSufficientForkCoin,\n\ttype ForkImpersonationGasClient,\n} from './fork-transaction.ts';\nimport type { ForkAdminSurface } from './mode/shared.ts';\nimport { SuiSpans } from './spans.ts';\n\n/** Serialization for the shared whale funding coin (mirrors\n *  `SuiLocalFaucetSerialization` in `local-faucet-strategy.ts`). */\nexport interface SuiForkFaucetSerialization {\n\treadonly broker: LeaseBroker;\n\treadonly key: string;\n\treadonly owner: string;\n}\n\nexport interface SuiForkFaucetStrategyOptions {\n\t/** Address impersonated as the funding source. Must hold a large SUI\n\t *  coin in the fork (auto-seeded + validated at boot). */\n\treadonly whale: string;\n\t/** Fork admin surface (`client.fork`) — submits the impersonation tx. */\n\treadonly fork: ForkAdminSurface;\n\t/** SDK shim (`client.sdk`) — `.core` selects the whale gas coin and\n\t *  waits for finality. */\n\treadonly sdk: SuiSdkShim;\n\t/** Upper bound per request (MIST). Requests above this are rejected. */\n\treadonly perRequestCapMist: bigint;\n\t/** Serialize requests so concurrent funds don't race the whale coin. */\n\treadonly serialization?: SuiForkFaucetSerialization;\n}\n\nconst sentinelUrl = (whale: string): string => `fork-impersonation://${whale}`;\n\nconst bodyError = (\n\twhale: string,\n\taddress: string,\n\tamount: bigint,\n\tmessage: string,\n): FaucetBodyError =>\n\tfaucetBodyError({\n\t\turl: sentinelUrl(whale),\n\t\taddress,\n\t\tamount,\n\t\tstatus: 0,\n\t\treason: 'failure-status',\n\t\tmessage,\n\t});\n\nconst withSerialization = (\n\tserialization: SuiForkFaucetSerialization | undefined,\n\teffect: Effect.Effect<void, FaucetBodyError>,\n): Effect.Effect<void, FaucetBodyError> => {\n\tif (serialization === undefined) {\n\t\treturn effect;\n\t}\n\treturn Effect.scoped(\n\t\tEffect.gen(function* () {\n\t\t\tyield* serialization.broker.acquire(leaseKey(serialization.key), serialization.owner);\n\t\t\tyield* effect;\n\t\t}),\n\t).pipe(\n\t\tEffect.withSpan('devstack.plugin.sui.forkFaucet.serializedRequest', {\n\t\t\tattributes: {\n\t\t\t\t[SuiSpans.localFaucetLeaseKey]: serialization.key,\n\t\t\t\t[SuiSpans.localFaucetLeaseOwner]: serialization.owner,\n\t\t\t},\n\t\t}),\n\t);\n};\n\n/** Build a SUI fork-faucet strategy that funds via whale impersonation. */\nexport const suiForkFaucetStrategy = (opts: SuiForkFaucetStrategyOptions): FaucetStrategy => ({\n\trequest: ({ address, amount }) => {\n\t\tconst gasClient: ForkImpersonationGasClient = opts.sdk.core;\n\t\t// Internal SuiPluginError -> FaucetBodyError so account funding's\n\t\t// catchTags handle it; carry the actionable root message through.\n\t\tconst mapErr = (cause: SuiPluginError): FaucetBodyError =>\n\t\t\tbodyError(opts.whale, address, amount, `sui fork faucet: ${cause.message}`);\n\n\t\tconst transfer = Effect.gen(function* () {\n\t\t\tif (amount <= 0n) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (amount > opts.perRequestCapMist) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tbodyError(\n\t\t\t\t\t\topts.whale,\n\t\t\t\t\t\taddress,\n\t\t\t\t\t\tamount,\n\t\t\t\t\t\t`sui fork faucet: requested ${amount} MIST exceeds the per-request cap ` +\n\t\t\t\t\t\t\t`${opts.perRequestCapMist} MIST (whale ${opts.whale}).`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\t// A sufficient whale SUI coin (first past any dust) pays gas AND sources the split, so\n\t\t\t// it must cover amount + the impersonation gas budget.\n\t\t\tconst { coin } = yield* selectSufficientForkCoin(\n\t\t\t\tgasClient,\n\t\t\t\topts.whale,\n\t\t\t\tamount + FORK_IMPERSONATION_GAS_BUDGET,\n\t\t\t).pipe(Effect.mapError(mapErr));\n\n\t\t\tconst tx = new Transaction();\n\t\t\ttx.setSender(opts.whale);\n\t\t\tconst [funded] = tx.splitCoins(tx.gas, [tx.pure.u64(amount)]);\n\t\t\ttx.transferObjects([funded], address);\n\n\t\t\tconst bytes = yield* buildForkImpersonationTransactionBytes(\n\t\t\t\ttx,\n\t\t\t\topts.whale,\n\t\t\t\tgasClient,\n\t\t\t\tcoin,\n\t\t\t).pipe(Effect.mapError(mapErr));\n\n\t\t\tconst submitted = yield* opts.fork\n\t\t\t\t.impersonate(opts.whale, bytes)\n\t\t\t\t.pipe(Effect.mapError(mapErr));\n\t\t\tif (!submitted.success) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tbodyError(\n\t\t\t\t\t\topts.whale,\n\t\t\t\t\t\taddress,\n\t\t\t\t\t\tamount,\n\t\t\t\t\t\t`sui fork faucet: impersonation tx ${submitted.digest} failed on-chain.`,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tyield* Effect.tryPromise({\n\t\t\t\ttry: () => opts.sdk.core.waitForTransaction({ digest: submitted.digest }),\n\t\t\t\tcatch: (cause): FaucetBodyError =>\n\t\t\t\t\tbodyError(\n\t\t\t\t\t\topts.whale,\n\t\t\t\t\t\taddress,\n\t\t\t\t\t\tamount,\n\t\t\t\t\t\t`sui fork faucet: waitForTransaction(${submitted.digest}) failed: ${formatUnknownError(cause)}`,\n\t\t\t\t\t),\n\t\t\t});\n\t\t});\n\n\t\treturn withSerialization(opts.serialization, transfer).pipe(\n\t\t\tEffect.withSpan('devstack.plugin.sui.forkFaucet.request', {\n\t\t\t\tattributes: { [SuiSpans.forkFaucetWhale]: opts.whale },\n\t\t\t}),\n\t\t);\n\t},\n});\n"],"mappings":";;;;;;;;;;AAoEA,MAAM,eAAe,UAA0B,wBAAwB;AAEvE,MAAM,aACL,OACA,SACA,QACA,YAEA,gBAAgB;CACf,KAAK,YAAY,MAAM;CACvB;CACA;CACA,QAAQ;CACR,QAAQ;CACR;CACA,CAAC;AAEH,MAAM,qBACL,eACA,WAC0C;AAC1C,KAAI,kBAAkB,KAAA,EACrB,QAAO;AAER,QAAO,OAAO,OACb,OAAO,IAAI,aAAa;AACvB,SAAO,cAAc,OAAO,QAAQ,SAAS,cAAc,IAAI,EAAE,cAAc,MAAM;AACrF,SAAO;GACN,CACF,CAAC,KACD,OAAO,SAAS,oDAAoD,EACnE,YAAY;GACV,SAAS,sBAAsB,cAAc;GAC7C,SAAS,wBAAwB,cAAc;EAChD,EACD,CAAC,CACF;;;AAIF,MAAa,yBAAyB,UAAwD,EAC7F,UAAU,EAAE,SAAS,aAAa;CACjC,MAAM,YAAwC,KAAK,IAAI;CAGvD,MAAM,UAAU,UACf,UAAU,KAAK,OAAO,SAAS,QAAQ,oBAAoB,MAAM,UAAU;CAE5E,MAAM,WAAW,OAAO,IAAI,aAAa;AACxC,MAAI,UAAU,GACb;AAED,MAAI,SAAS,KAAK,kBACjB,QAAO,OAAO,OAAO,KACpB,UACC,KAAK,OACL,SACA,QACA,8BAA8B,OAAO,oCACjC,KAAK,kBAAkB,eAAe,KAAK,MAAM,IACrD,CACD;EAKF,MAAM,EAAE,SAAS,OAAO,yBACvB,WACA,KAAK,OACL,SAAS,8BACT,CAAC,KAAK,OAAO,SAAS,OAAO,CAAC;EAE/B,MAAM,KAAK,IAAI,aAAa;AAC5B,KAAG,UAAU,KAAK,MAAM;EACxB,MAAM,CAAC,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC,GAAG,KAAK,IAAI,OAAO,CAAC,CAAC;AAC7D,KAAG,gBAAgB,CAAC,OAAO,EAAE,QAAQ;EAErC,MAAM,QAAQ,OAAO,uCACpB,IACA,KAAK,OACL,WACA,KACA,CAAC,KAAK,OAAO,SAAS,OAAO,CAAC;EAE/B,MAAM,YAAY,OAAO,KAAK,KAC5B,YAAY,KAAK,OAAO,MAAM,CAC9B,KAAK,OAAO,SAAS,OAAO,CAAC;AAC/B,MAAI,CAAC,UAAU,QACd,QAAO,OAAO,OAAO,KACpB,UACC,KAAK,OACL,SACA,QACA,qCAAqC,UAAU,OAAO,mBACtD,CACD;AAGF,SAAO,OAAO,WAAW;GACxB,WAAW,KAAK,IAAI,KAAK,mBAAmB,EAAE,QAAQ,UAAU,QAAQ,CAAC;GACzE,QAAQ,UACP,UACC,KAAK,OACL,SACA,QACA,uCAAuC,UAAU,OAAO,YAAY,mBAAmB,MAAM,GAC7F;GACF,CAAC;GACD;AAEF,QAAO,kBAAkB,KAAK,eAAe,SAAS,CAAC,KACtD,OAAO,SAAS,0CAA0C,EACzD,YAAY,GAAG,SAAS,kBAAkB,KAAK,OAAO,EACtD,CAAC,CACF;GAEF"}

package/dist/plugins/sui/fork-orchestration.d.mts

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

package/dist/plugins/sui/fork-orchestration.mjs

@@ -1,5 +1,170 @@
-import { forkUnsupportedError } from "./errors.mjs";
+import { SpanAttr } from "../../substrate/runtime/observability/spans.mjs";
+import { selfPid } from "../../substrate/runtime/cross-process/self-pid.mjs";
+import { atomicWriteJsonSync } from "../../substrate/runtime/atomic-write.mjs";
+import { parseVersionedDocumentBodyOrNull } from "../../substrate/versioned-doc-sync.mjs";
+import { isPidAlive, processStartTime } from "../../substrate/runtime/cross-process/liveness.mjs";
+import { acquireStackLock } from "../../substrate/runtime/cross-process/stack-lock.mjs";
+import { mintRandomSuffix } from "../../substrate/runtime/random-suffix.mjs";
+import { forkUnsupportedError, suiPluginError } from "./errors.mjs";
+import "../../substrate/runtime/cross-process/index.mjs";
+import { Effect, Schedule, Schema } from "effect";
+import { readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { hostname } from "node:os";
 //#region src/plugins/sui/fork-orchestration.ts
+/** Heartbeat cadence — refresh `startedAt` every 10s. Matches the
+*  roster's `heartbeatIntervalMillis`. The heartbeat keeps the holder's
+*  `startedAt`/`startTime` fresh for diagnostics and so a peer that DOES
+*  later add a foreign-host liveness signal has recent data; with the
+*  current conservative foreign-host policy (always-alive) it is not a
+*  reclaim gate, mirroring the roster heartbeat fiber. */
+const FORK_HOLDER_HEARTBEAT_INTERVAL_MILLIS = 1e4;
+/** Brief acquire timeout for the holder critical section. The OS lock
+*  is held only across a read → liveness-check → write, never across
+*  I/O — a tight budget keeps peers reacting quickly to a release. */
+const FORK_HOLDER_LOCK_TIMEOUT_MILLIS = 5e3;
+const ForkLockHolderSchema = Schema.Struct({
+	pid: Schema.Number,
+	host: Schema.String,
+	instanceId: Schema.String,
+	startedAt: Schema.Number,
+	startTime: Schema.NullOr(Schema.Number)
+});
+/** Holder file lives inside the data dir so it travels with the dir's
+*  lifecycle (wipe removes it). */
+const forkHolderPath = (dataDir) => join(dataDir, "holder.json");
+/** Is an existing holder alive? Mirrors `liveness.checkHolderLiveness`
+*  exactly (the `RosterHolder` shape doesn't fit — that carries
+*  `hostname`/`heartbeatAt`, not our `host`/`startedAt` — so we
+*  replicate its logic against the `ForkLockHolder` fields):
+*
+*   - Foreign-host → ALWAYS ALIVE. Cross-host pid comparison is
+*     meaningless, and comparing our `Date.now()` to the holder's
+*     `startedAt` (a different host's clock) is clock-skew-unsafe — a
+*     >~20s skew on an NFS root could reclaim a LIVE foreign holder and
+*     produce dual-writer RocksDB corruption. The NFS-safe trade is to
+*     never auto-reclaim a foreign holder; a truly-abandoned one needs
+*     manual cleanup (`rm <dataDir>/holder.json`).
+*   - Same-host → pid must be live AND its start-time must match, so a
+*     crashed-then-recycled pid (an abandoned dir whose pid the kernel
+*     handed to an unrelated process) no longer reads as "in use".
+*
+*  A `null` start-time on either side is handled conservatively the
+*  same way roster does — ALIVE — because we have nothing to dispute
+*  the recorded identity with (mismatching a probed stamp against a
+*  recorded `null`, or vice versa, would falsely harvest a live
+*  holder). */
+const isForkHolderAlive = (holder) => {
+	if (holder.host !== hostname()) return true;
+	if (!isPidAlive(holder.pid)) return false;
+	const probedStart = processStartTime(holder.pid);
+	if (probedStart === null) return true;
+	if (holder.startTime === null) return true;
+	return probedStart === holder.startTime;
+};
+const readForkHolder = (path) => parseVersionedDocumentBodyOrNull(safeReadHolderRaw(path), ForkLockHolderSchema, "sui-fork.holder");
+/** Read the holder file's bytes, returning `''` (→ parses to null) on
+*  any I/O error. A missing/unreadable holder means "no live claim";
+*  the caller writes its own. Sync read is correct here — we are
+*  inside the brief OS-lock critical section, same non-yielding
+*  discipline as the cross-process roster reader. */
+const safeReadHolderRaw = (path) => {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+};
+const ownForkHolder = () => {
+	const pid = selfPid();
+	return {
+		pid,
+		host: hostname(),
+		instanceId: mintRandomSuffix(8),
+		startedAt: Date.now(),
+		startTime: processStartTime(pid)
+	};
+};
+/** Run `body` under a BRIEFLY-held `stack.lock`. The lock serializes
+*  the holder file's read → liveness-check → write critical section so
+*  two claimers never both decide the dir is free. Released the moment
+*  `body` completes — never held across the fork's lifetime. */
+const underStackLock = (stackLockFile, holderPath, body) => Effect.scoped(Effect.gen(function* () {
+	yield* acquireStackLock(stackLockFile, FORK_HOLDER_LOCK_TIMEOUT_MILLIS).pipe(Effect.mapError((cause) => suiPluginError("fork-lock", `sui fork mode: failed to acquire stack lock for data dir ${holderPath}: ${cause._tag}`, cause)));
+	return yield* body;
+}));
+/** The brief critical section: under `stack.lock`, read any existing
+*  holder; if a LIVE one is present, fail with an actionable error;
+*  otherwise claim by writing our own holder atomically. Returns the
+*  holder we wrote so the heartbeat fiber can refresh it. */
+const claimForkHolder = (stackLockFile, holderPath) => underStackLock(stackLockFile, holderPath, Effect.gen(function* () {
+	const existing = readForkHolder(holderPath);
+	if (existing !== null && isForkHolderAlive(existing)) return yield* Effect.fail(suiPluginError("fork-lock", `sui fork mode: fork data dir ${holderPath} is in use by pid ${existing.pid} on ${existing.host}; stop that stack or use a different fork key.`));
+	const self = ownForkHolder();
+	yield* writeForkHolder(holderPath, self);
+	return self;
+}));
+/** Heartbeat: under the brief lock, re-stamp `startedAt` IF the holder
+*  on disk is still ours. A peer that reclaimed us (same-host recycled-
+*  pid takeover) owns the file now; we must not clobber its claim, so a
+*  mismatched `instanceId` makes this a no-op. */
+const refreshForkHolder = (stackLockFile, holderPath, self) => underStackLock(stackLockFile, holderPath, Effect.gen(function* () {
+	const current = readForkHolder(holderPath);
+	if (current !== null && current.instanceId !== self.instanceId) return;
+	yield* writeForkHolder(holderPath, {
+		...self,
+		startedAt: Date.now()
+	});
+}));
+/** Scope-finalizer release: unlink the holder file ONLY if it is still
+*  ours. A finalizer that unconditionally `unlinkSync`d by path would,
+*  after a legitimate same-host reclaim (our pid crashed-and-recycled,
+*  a peer took over), delete the PEER's holder and unprotect a dir the
+*  peer is actively writing. Re-reading and matching `instanceId` makes
+*  the release a no-op once we no longer own the file. A missing/
+*  unreadable holder is already-gone — also a no-op. Best-effort: a
+*  crash that skips this is recovered by the next peer's same-host
+*  liveness check. */
+const releaseOwnForkHolder = (holderPath, self) => {
+	const current = readForkHolder(holderPath);
+	if (current !== null && current.instanceId !== self.instanceId) return;
+	try {
+		unlinkSync(holderPath);
+	} catch {}
+};
+const writeForkHolder = (path, holder) => Effect.try({
+	try: () => atomicWriteJsonSync(path, holder),
+	catch: (cause) => suiPluginError("fork-lock", `sui fork mode: failed to write fork data-dir holder ${path}.`, cause)
+});
+/**
+* Acquire the data-dir holder for the lifetime of the surrounding
+* scope.
+*
+*   1. Briefly take `stack.lock`, read any existing holder, fail if a
+*      live peer holds it, else write our own holder. Release the OS
+*      lock immediately (the claim outlives the lock).
+*   2. Fork a scope-bound heartbeat fiber that re-takes the brief lock
+*      every `FORK_HOLDER_HEARTBEAT_INTERVAL_MILLIS` and refreshes
+*      `startedAt` (only while the file is still ours). A heartbeat
+*      failure is non-fatal — log and retry next tick (same policy as
+*      the roster heartbeat fiber).
+*   3. Register a finalizer that removes our holder file on scope
+*      close (wipe / restart / Ctrl-C) — but ONLY if the on-disk holder
+*      is still ours, so a legitimate peer reclaim is never clobbered.
+*      A crash that skips the finalizer is recovered same-host by the
+*      next peer's liveness check (foreign-host needs manual cleanup —
+*      the NFS-safe trade in `isForkHolderAlive`).
+*/
+const acquireForkDataDirHolder = (stackLockFile, dataDir) => Effect.gen(function* () {
+	const holderPath = forkHolderPath(dataDir);
+	const self = yield* claimForkHolder(stackLockFile, holderPath);
+	yield* Effect.addFinalizer(() => Effect.sync(() => releaseOwnForkHolder(holderPath, self)));
+	yield* refreshForkHolder(stackLockFile, holderPath, self).pipe(Effect.catch((err) => Effect.logWarning("sui fork data-dir holder heartbeat failed; next tick will retry").pipe(Effect.annotateLogs({
+		[SpanAttr.phase]: err.phase,
+		[SpanAttr.errorMessage]: err.message
+	})))).pipe(Effect.repeat(Schedule.spaced(`${FORK_HOLDER_HEARTBEAT_INTERVAL_MILLIS} millis`)), Effect.forkScoped);
+	return self;
+}).pipe(Effect.withSpan("devstack.plugin.sui.fork.acquireDataDirHolder"));
 /** Surfaces that the sui-fork binary explicitly panics on. New
 *  upstream additions fail OPEN by default — architecture
 *  invariant. */
@@ -8,6 +173,9 @@ const FORK_UNSUPPORTED_SURFACES = [
 	"listBalances",
 	"getCoinInfo"
 ];
+/** Wrap a Sui SDK shim with the fork guard. Property access for a
+*  blocklisted surface SYNCHRONOUSLY throws — the wire call never
+*  happens, so the fork binary stays up. */
 const wrapWithForkGuard = (sdk) => {
 	const guardedCore = new Proxy(sdk.core, { get(target, prop, receiver) {
 		if (typeof prop === "string" && FORK_UNSUPPORTED_SURFACES.includes(prop)) throw forkUnsupportedError(`client.core.${prop}`, "fork mode does not implement this SDK surface — use the impersonation helper or read state via ChainProbe.");
@@ -19,6 +187,6 @@ const wrapWithForkGuard = (sdk) => {
 	};
 };
 //#endregion
-export { FORK_UNSUPPORTED_SURFACES, wrapWithForkGuard };
+export { FORK_UNSUPPORTED_SURFACES, acquireForkDataDirHolder, wrapWithForkGuard };
 
 //# sourceMappingURL=fork-orchestration.mjs.map