@mysten-incubation/devstack 0.0.0

package/dist/plugins/action/index.d.mts

@@ -0,0 +1,56 @@
+import { AnyResourceRef, DependencyInput, DependencyList, Plugin, ResolvedDependencies, ResourceRef } from "../../substrate/plugin.mjs";
+import { SeedObjectsAccumulator } from "../sui/seed-objects.mjs";
+import { SuiClient } from "../sui/mode/shared.mjs";
+import { SuiOptions } from "../sui/mode/spec.mjs";
+import { ActionError, ActionPhase } from "./errors.mjs";
+import { DynamicDiscriminator } from "./discriminator.mjs";
+import { ActionReceipt } from "./service.mjs";
+import { ActionBuildContext } from "./build-context.mjs";
+import { Effect, Scope } from "effect";
+
+//#region src/plugins/action/index.d.ts
+/** A user-supplied upstream resource ref. The user passes plugin values
+ *  such as `account('alice')` or `localPackage('demo', ...)`; object,
+ *  tuple, and single-ref shapes are preserved for the action body. */
+type ActionUpstreamRef = AnyResourceRef;
+/** Options for `action(name, opts)`. */
+type ActionDependencySpec = DependencyInput;
+type ResolvedActionDependencies<Input extends ActionDependencySpec> = ResolvedDependencies<Input>;
+interface ActionOptions<DependsOn extends ActionDependencySpec> {
+  /** Upstream refs the action depends on. The shape determines the
+   *  second argument passed to `body`. */
+  readonly dependsOn: DependsOn;
+  /** Optional caller-supplied discriminator material. Two shapes:
+   *  a literal `string`, or a callback `(ctx, deps) => Effect<string>`
+   *  that receives action helpers plus resolved deps shaped like
+   *  `dependsOn`, so the discriminator can derive its value from
+   *  upstream resolved values. See
+   *  `discriminator.ts`. */
+  readonly discriminator?: DynamicDiscriminator<ResolvedActionDependencies<DependsOn>>;
+  /** The user's body. Receives action helpers plus resolved deps
+   *  shaped like `dependsOn`, then returns the on-chain effect.
+   *
+   *  Errors raised here surface as `ActionError({phase:'sign'})`
+   *  unless the body raises an `ActionError` itself (in which case
+   *  it propagates verbatim). */
+  readonly body: (ctx: ActionBuildContext, deps: ResolvedActionDependencies<DependsOn>) => Effect.Effect<ActionReceipt, ActionError, Scope.Scope>;
+}
+/** Construct the action plugin instance.
+ *
+ *  The result is a plugin/resource ref that:
+ *
+ *   - publishes an `ActionReceipt`-typed resource identified by
+ *     `action:<name>`,
+ *   - `dependsOn:` `[suiResource, ...userDependencies]` (Sui hard upstream for
+ *     ChainProbe lookup + chainId folding),
+ *   - `role: 'task'` — Action has no long-lived resources;
+ *     the substrate's lifecycle wrap surfaces it as "done" after
+ *     `start` resolves.
+ */
+declare const action: <const Name extends string, const DependsOn extends ActionDependencySpec>(name: Name, opts: ActionOptions<DependsOn>) => Plugin<`action:${Name}`, ActionReceipt, readonly [ResourceRef<"sui", SuiClient & {
+  readonly mode: SuiOptions["mode"];
+  readonly seedObjects: SeedObjectsAccumulator;
+}>, ...DependencyList<DependsOn>], readonly []>;
+//#endregion
+export { ActionOptions, ActionUpstreamRef, action };
+//# sourceMappingURL=index.d.mts.map

package/dist/plugins/action/index.mjs

@@ -0,0 +1,82 @@
+import { definePlugin, dependencyList, resolveDependencyValues, resource } from "../../substrate/plugin.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import { suiResource } from "../sui/index.mjs";
+import { ArtifactPublisherService } from "../../substrate/runtime/artifact-publisher/index.mjs";
+import { chainProbeFor } from "../../substrate/runtime/strategy-registry/chain-probe-for.mjs";
+import { ACTION_ERROR_TAGS, actionError } from "./errors.mjs";
+import { signAndExecute } from "./execute.mjs";
+import { bootActionService, resolveDiscriminator } from "./service.mjs";
+import { Effect } from "effect";
+//#region src/plugins/action/index.ts
+const actionErrorContributions = pluginErrorContributions(ACTION_ERROR_TAGS);
+/** Resource id constructor. The symbolic action name is part of the tag
+*  identity so two `action('foo', ...)` calls in one stack collide
+*  cleanly at compose time. */
+const actionResourceId = (name) => `action:${name}`;
+/** Construct the action plugin instance.
+*
+*  The result is a plugin/resource ref that:
+*
+*   - publishes an `ActionReceipt`-typed resource identified by
+*     `action:<name>`,
+*   - `dependsOn:` `[suiResource, ...userDependencies]` (Sui hard upstream for
+*     ChainProbe lookup + chainId folding),
+*   - `role: 'task'` — Action has no long-lived resources;
+*     the substrate's lifecycle wrap surfaces it as "done" after
+*     `start` resolves.
+*/
+const action = (name, opts) => {
+	const actionRef = resource(actionResourceId(name));
+	const upstreamRefs = dependencyList(opts.dependsOn);
+	const dependencies = [suiResource, ...upstreamRefs];
+	const dependencyResourceIds = upstreamRefs.map(({ id }) => id);
+	return definePlugin({
+		id: actionRef.id,
+		dependsOn: dependencies,
+		role: "task",
+		start: (deps) => Effect.gen(function* () {
+			const [sui, ...resolvedUpstream] = deps;
+			const resolvedByResourceId = new Map(upstreamRefs.map((ref, index) => [ref.id, resolvedUpstream[index]]));
+			const readDeclaredDependency = (id) => {
+				if (!resolvedByResourceId.has(id)) throw new Error(`Action '${name}': dependency '${id}' was not resolved.`);
+				return resolvedByResourceId.get(id);
+			};
+			const publisher = yield* ArtifactPublisherService;
+			const probe = yield* chainProbeFor(sui.chain);
+			const bodyCtx = {
+				sui,
+				signAndExecute: (account, build) => signAndExecute({
+					actionName: name,
+					sui,
+					account,
+					build
+				})
+			};
+			const bodyDeps = resolveDependencyValues(opts.dependsOn, (member) => readDeclaredDependency(member.id));
+			return yield* bootActionService(publisher, probe, {
+				actionName: name,
+				chainId: sui.chain,
+				staticDiscriminator: {
+					actionName: name,
+					dependencyResourceIds
+				},
+				dynamicMaterial: resolveDiscriminator(name, opts.discriminator, bodyCtx, bodyDeps),
+				body: opts.body(bodyCtx, bodyDeps)
+			}).pipe(Effect.catch((err) => {
+				if (err._tag === "ActionError") return Effect.fail(err);
+				const detail = err.detail ?? `Action '${name}': substrate failure.`;
+				return Effect.fail(actionError("sign", {
+					actionName: name,
+					message: detail,
+					cause: err
+				}));
+			}));
+		}),
+		capabilities: [],
+		errorContributions: actionErrorContributions
+	});
+};
+//#endregion
+export { action };
+
+//# sourceMappingURL=index.mjs.map

package/dist/plugins/action/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["signAndExecuteImpl"],"sources":["../../../src/plugins/action/index.ts"],"sourcesContent":["// Action plugin — barrel + `action(name, opts)` factory.\n//\n// Architecture (16-action.md): an action is a ONE-SHOT on-chain effect\n// (mint, create-singleton-object, seed-config, etc.) that runs after\n// its declared upstream refs (typically a signer account + one or more\n// published packages) are ready. The result (digest + change arrays)\n// is yieldable through the action resource.\n//\n// User-facing factory shape (recommended high-level form):\n//\n//   const openLobby = action('connect-four.openLobby', {\n//     dependsOn: { signer: alice, pkg: connectFour },\n//     body: (ctx, { signer, pkg }) =>\n//       ctx.signAndExecute(signer, (tx) => {\n//         tx.moveCall({ target: `${pkg.packageId}::game::create_lobby` });\n//       }),\n//   });\n//\n// The `ctx.signAndExecute(account, build)` helper folds the full\n// build → sign → execute (with `include: {effects, objectTypes}`) →\n// wait-for-finality → envelope-projection pipeline into a single call\n// (see `execute.ts`). The returned `ActionReceipt` carries the real\n// transaction digest and an `objectChanges` array that surfaces the\n// SDK's `changedObjects` (with `kind: 'created' | 'mutated'` + the\n// fully-qualified `objectType` string when available).\n//\n// Resource id: `'action:<name>'` — one tag per user-declared action (the\n// symbolic name is part of the identity so two `action('foo', ...)`\n// calls in one stack collide cleanly at compose time).\n//\n// Caching: delegated to the substrate's `ArtifactPublisher`.\n// Namespace is `action`; the cache key folds chainId + content-hash\n// derived from (name, dependencyResourceIds, dynamic discriminator).\n\nimport { Effect, type Scope } from 'effect';\n\nimport {\n\tdefinePlugin,\n\tdependencyList,\n\tresource,\n\tresolveDependencyValues,\n\ttype AnyResourceRef,\n\ttype DependencyInput,\n\ttype ResolvedDependencies,\n} from '../../api/define-plugin.ts';\nimport { pluginErrorContributions } from '../../api/plugin-errors.ts';\nimport { ArtifactPublisherService } from '../../substrate/runtime/artifact-publisher/index.ts';\nimport { chainProbeFor } from '../../substrate/runtime/strategy-registry/index.ts';\nimport { suiResource } from '../sui/index.ts';\nimport type { SuiProbeKey } from '../sui/chain-probe.ts';\n\nimport type { ActionBuildContext } from './build-context.ts';\nimport { actionError, ACTION_ERROR_TAGS, type ActionError } from './errors.ts';\nimport type { DynamicDiscriminator } from './discriminator.ts';\nimport { signAndExecute as signAndExecuteImpl } from './execute.ts';\nimport {\n\tbootActionService,\n\tresolveDiscriminator,\n\ttype ActionAcquireInputs,\n\ttype ActionReceipt,\n} from './service.ts';\n\nconst actionErrorContributions = pluginErrorContributions(ACTION_ERROR_TAGS);\n\n// ---------------------------------------------------------------------------\n// Resource — one per declared action, keyed by symbolic name\n// ---------------------------------------------------------------------------\n\n/** Resource id constructor. The symbolic action name is part of the tag\n *  identity so two `action('foo', ...)` calls in one stack collide\n *  cleanly at compose time. */\nexport const actionResourceId = <Name extends string>(name: Name): `action:${Name}` =>\n\t`action:${name}`;\n\nexport type ActionResourceId<Name extends string> = `action:${Name}`;\n\n// ---------------------------------------------------------------------------\n// User-facing factory shape\n// ---------------------------------------------------------------------------\n\n/** A user-supplied upstream resource ref. The user passes plugin values\n *  such as `account('alice')` or `localPackage('demo', ...)`; object,\n *  tuple, and single-ref shapes are preserved for the action body. */\nexport type ActionUpstreamRef = AnyResourceRef;\n\n/** Options for `action(name, opts)`. */\ntype ActionDependencySpec = DependencyInput;\n\ntype ResolvedActionDependencies<Input extends ActionDependencySpec> = ResolvedDependencies<Input>;\n\nexport interface ActionOptions<DependsOn extends ActionDependencySpec> {\n\t/** Upstream refs the action depends on. The shape determines the\n\t *  second argument passed to `body`. */\n\treadonly dependsOn: DependsOn;\n\t/** Optional caller-supplied discriminator material. Two shapes:\n\t *  a literal `string`, or a callback `(ctx, deps) => Effect<string>`\n\t *  that receives action helpers plus resolved deps shaped like\n\t *  `dependsOn`, so the discriminator can derive its value from\n\t *  upstream resolved values. See\n\t *  `discriminator.ts`. */\n\treadonly discriminator?: DynamicDiscriminator<ResolvedActionDependencies<DependsOn>>;\n\t/** The user's body. Receives action helpers plus resolved deps\n\t *  shaped like `dependsOn`, then returns the on-chain effect.\n\t *\n\t *  Errors raised here surface as `ActionError({phase:'sign'})`\n\t *  unless the body raises an `ActionError` itself (in which case\n\t *  it propagates verbatim). */\n\treadonly body: (\n\t\tctx: ActionBuildContext,\n\t\tdeps: ResolvedActionDependencies<DependsOn>,\n\t) => Effect.Effect<ActionReceipt, ActionError, Scope.Scope>;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/** Construct the action plugin instance.\n *\n *  The result is a plugin/resource ref that:\n *\n *   - publishes an `ActionReceipt`-typed resource identified by\n *     `action:<name>`,\n *   - `dependsOn:` `[suiResource, ...userDependencies]` (Sui hard upstream for\n *     ChainProbe lookup + chainId folding),\n *   - `role: 'task'` — Action has no long-lived resources;\n *     the substrate's lifecycle wrap surfaces it as \"done\" after\n *     `start` resolves.\n */\nexport const action = <const Name extends string, const DependsOn extends ActionDependencySpec>(\n\tname: Name,\n\topts: ActionOptions<DependsOn>,\n) => {\n\tconst actionRef = resource<ActionResourceId<Name>, ActionReceipt>(actionResourceId(name));\n\n\t// Flatten the user-supplied upstream refs for ordering. The start\n\t// body below keeps the original `dependsOn` shape so it can\n\t// reconstruct the user's dependency argument.\n\tconst upstreamRefs = dependencyList(opts.dependsOn);\n\tconst dependencies = [suiResource, ...upstreamRefs] as const;\n\n\t// Static discriminator pieces — known at factory construction\n\t// time. The tag-ids preserve the literal `id` so two actions with\n\t// identical bodies but different upstream packages get different\n\t// cache keys.\n\tconst dependencyResourceIds = upstreamRefs.map(({ id }) => id) as ReadonlyArray<string>;\n\n\treturn definePlugin({\n\t\tid: actionRef.id,\n\t\tdependsOn: dependencies,\n\t\t// Action has no long-lived resources — the body runs once at\n\t\t// acquire and returns; supervisor's lifecycle wrap surfaces\n\t\t// \"done\" after that.\n\t\trole: 'task',\n\t\tstart: (deps) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst [sui, ...resolvedUpstream] = deps;\n\t\t\t\tconst resolvedByResourceId = new Map<string, unknown>(\n\t\t\t\t\tupstreamRefs.map((ref, index) => [ref.id, resolvedUpstream[index]]),\n\t\t\t\t);\n\t\t\t\tconst readDeclaredDependency = (id: string): unknown => {\n\t\t\t\t\tif (!resolvedByResourceId.has(id)) {\n\t\t\t\t\t\tthrow new Error(`Action '${name}': dependency '${id}' was not resolved.`);\n\t\t\t\t\t}\n\t\t\t\t\treturn resolvedByResourceId.get(id);\n\t\t\t\t};\n\n\t\t\t\t// Substrate-context primitives. artifact publisher + strategy registry\n\t\t\t\t// are both provided by the supervisor's pluginContext.\n\t\t\t\tconst publisher = yield* ArtifactPublisherService;\n\t\t\t\tconst probe = yield* chainProbeFor<SuiProbeKey>(sui.chain);\n\n\t\t\t\t// Compose the user's body Effect, closing over the\n\t\t\t\t// action helper context. Resolved upstream values are\n\t\t\t\t// passed separately in the same shape as `dependsOn`.\n\t\t\t\t//   - `ctx.sui` — the resolved SuiClient (always set;\n\t\t\t\t//     suiResource is the hard upstream).\n\t\t\t\t//   - `ctx.signAndExecute(account, build)` — high-level\n\t\t\t\t//     helper that drives the full build → sign → execute\n\t\t\t\t//     → wait → project pipeline against the supplied\n\t\t\t\t//     account, returning a parsed `ActionReceipt`. This\n\t\t\t\t//     is what most action bodies want — it folds the\n\t\t\t\t//     SDK-boundary cast + `include: {effects, objectTypes}`\n\t\t\t\t//     execute + finality wait + envelope projection.\n\t\t\t\tconst bodyCtx: ActionBuildContext = {\n\t\t\t\t\tsui,\n\t\t\t\t\tsignAndExecute: (account, build) =>\n\t\t\t\t\t\tsignAndExecuteImpl({\n\t\t\t\t\t\t\tactionName: name,\n\t\t\t\t\t\t\tsui,\n\t\t\t\t\t\t\taccount,\n\t\t\t\t\t\t\tbuild,\n\t\t\t\t\t\t}),\n\t\t\t\t};\n\n\t\t\t\tconst bodyDeps = resolveDependencyValues(opts.dependsOn, (member) =>\n\t\t\t\t\treadDeclaredDependency(member.id),\n\t\t\t\t) as ResolvedActionDependencies<DependsOn>;\n\t\t\t\tconst acquireInputs: ActionAcquireInputs = {\n\t\t\t\t\tactionName: name,\n\t\t\t\t\tchainId: sui.chain,\n\t\t\t\t\tstaticDiscriminator: {\n\t\t\t\t\t\tactionName: name,\n\t\t\t\t\t\tdependencyResourceIds,\n\t\t\t\t\t},\n\t\t\t\t\tdynamicMaterial: resolveDiscriminator(name, opts.discriminator, bodyCtx, bodyDeps),\n\t\t\t\t\tbody: opts.body(bodyCtx, bodyDeps),\n\t\t\t\t};\n\n\t\t\t\tconst receipt = yield* bootActionService(publisher, probe, acquireInputs).pipe(\n\t\t\t\t\tEffect.catch((err): Effect.Effect<ActionReceipt, ActionError> => {\n\t\t\t\t\t\t// Re-wrap the ArtifactPublishError into an\n\t\t\t\t\t\t// ActionError so downstream consumers always see\n\t\t\t\t\t\t// the typed `ActionError` shape. The detail\n\t\t\t\t\t\t// already includes the phase + message from the\n\t\t\t\t\t\t// produce-side mapper.\n\t\t\t\t\t\tif ((err as { _tag?: string })._tag === 'ActionError') {\n\t\t\t\t\t\t\treturn Effect.fail(err as ActionError);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst detail =\n\t\t\t\t\t\t\t(err as { detail?: string }).detail ?? `Action '${name}': substrate failure.`;\n\t\t\t\t\t\treturn Effect.fail(\n\t\t\t\t\t\t\tactionError('sign', {\n\t\t\t\t\t\t\t\tactionName: name,\n\t\t\t\t\t\t\t\tmessage: detail,\n\t\t\t\t\t\t\t\tcause: err,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t);\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\treturn receipt;\n\t\t\t}),\n\t\t// No capability decls today. Future surfaces (codegen of\n\t\t// action receipts, manifest extras) land here.\n\t\tcapabilities: [] as const,\n\t\t// Plugin-side error vocabulary. The supervisor's harvest loop\n\t\t// folds this into the substrate's FormatterRegistry; the\n\t\t// cascade formatter then renders `ActionError`-tagged failures\n\t\t// with the action's phase/message header.\n\t\terrorContributions: actionErrorContributions,\n\t});\n};\n\n// ---------------------------------------------------------------------------\n// Re-exports\n// ---------------------------------------------------------------------------\n\nexport type { ActionBuildContext } from './build-context.ts';\nexport type { ActionError, ActionPhase } from './errors.ts';\nexport { ACTION_ERROR_TAGS } from './errors.ts';\nexport type { ActionLifecyclePhase } from './lifecycle.ts';\nexport type { DynamicDiscriminator, StaticDiscriminator } from './discriminator.ts';\nexport type { ActionReceipt } from './service.ts';\nexport { ActionReceiptSchema } from './service.ts';\nexport type { ActionObjectChange } from './execute.ts';\nexport { signAndExecute } from './execute.ts';\n"],"mappings":";;;;;;;;;;AA8DA,MAAM,2BAA2B,yBAAyB,kBAAkB;;;;AAS5E,MAAa,oBAAyC,SACrD,UAAU;;;;;;;;;;;;;AAyDX,MAAa,UACZ,MACA,SACI;CACJ,MAAM,YAAY,SAAgD,iBAAiB,KAAK,CAAC;CAKzF,MAAM,eAAe,eAAe,KAAK,UAAU;CACnD,MAAM,eAAe,CAAC,aAAa,GAAG,aAAa;CAMnD,MAAM,wBAAwB,aAAa,KAAK,EAAE,SAAS,GAAG;AAE9D,QAAO,aAAa;EACnB,IAAI,UAAU;EACd,WAAW;EAIX,MAAM;EACN,QAAQ,SACP,OAAO,IAAI,aAAa;GACvB,MAAM,CAAC,KAAK,GAAG,oBAAoB;GACnC,MAAM,uBAAuB,IAAI,IAChC,aAAa,KAAK,KAAK,UAAU,CAAC,IAAI,IAAI,iBAAiB,OAAO,CAAC,CACnE;GACD,MAAM,0BAA0B,OAAwB;AACvD,QAAI,CAAC,qBAAqB,IAAI,GAAG,CAChC,OAAM,IAAI,MAAM,WAAW,KAAK,iBAAiB,GAAG,qBAAqB;AAE1E,WAAO,qBAAqB,IAAI,GAAG;;GAKpC,MAAM,YAAY,OAAO;GACzB,MAAM,QAAQ,OAAO,cAA2B,IAAI,MAAM;GAc1D,MAAM,UAA8B;IACnC;IACA,iBAAiB,SAAS,UACzBA,eAAmB;KAClB,YAAY;KACZ;KACA;KACA;KACA,CAAC;IACH;GAED,MAAM,WAAW,wBAAwB,KAAK,YAAY,WACzD,uBAAuB,OAAO,GAAG,CACjC;AAiCD,UAAO,OArBgB,kBAAkB,WAAW,OAAO;IAV1D,YAAY;IACZ,SAAS,IAAI;IACb,qBAAqB;KACpB,YAAY;KACZ;KACA;IACD,iBAAiB,qBAAqB,MAAM,KAAK,eAAe,SAAS,SAAS;IAClF,MAAM,KAAK,KAAK,SAAS,SAAS;IAGqC,CAAC,CAAC,KACzE,OAAO,OAAO,QAAmD;AAMhE,QAAK,IAA0B,SAAS,cACvC,QAAO,OAAO,KAAK,IAAmB;IAEvC,MAAM,SACJ,IAA4B,UAAU,WAAW,KAAK;AACxD,WAAO,OAAO,KACb,YAAY,QAAQ;KACnB,YAAY;KACZ,SAAS;KACT,OAAO;KACP,CAAC,CACF;KACA,CACF;IAEA;EAGH,cAAc,EAAE;EAKhB,oBAAoB;EACpB,CAAC"}

package/dist/plugins/action/service.d.mts

@@ -0,0 +1,26 @@
+import { Effect, Schema, Scope } from "effect";
+
+//#region src/plugins/action/service.d.ts
+/** Action receipt — the cached value. Minimal shape: digest is the
+ *  load-bearing identifier (drives verify probe + downstream
+ *  consumers); the change arrays are surfaced opaquely (typed
+ *  `unknown` here so the cache schema stays narrow) but the in-memory
+ *  shape produced by the `ctx.signAndExecute` helper is
+ *  `ActionObjectChange` (`{ kind: 'created' | 'mutated', objectId,
+ *  objectType?, outputState?, idOperation? }`). Consumers can cast or
+ *  use `findCreatedByType`-style helpers — mirrors v3's
+ *  `pickCreatedByType(r.objectChanges, ...)` pattern from
+ *  `examples/connect-four/devstack.config.ts`.
+ *
+ *  Distilled doc §"Capabilities PRODUCED" — the v3 Action's `TxResult`
+ *  carries `digest`, `effects`, `objectChanges`, `balanceChanges`. We
+ *  narrow to the columns that fit the cache + are actually used by
+ *  downstream consumers. */
+interface ActionReceipt {
+  readonly digest: string;
+  readonly objectChanges?: ReadonlyArray<unknown>;
+  readonly balanceChanges?: ReadonlyArray<unknown>;
+}
+//#endregion
+export { ActionReceipt };
+//# sourceMappingURL=service.d.mts.map

package/dist/plugins/action/service.mjs

@@ -0,0 +1,84 @@
+import { contentHash } from "../../substrate/brand.mjs";
+import { actionError } from "./errors.mjs";
+import { composeDiscriminatorMaterial } from "./discriminator.mjs";
+import { Effect, Schema } from "effect";
+import { createHash } from "node:crypto";
+Schema.Struct({
+	digest: Schema.String,
+	objectChanges: Schema.optional(Schema.Array(Schema.Unknown)),
+	balanceChanges: Schema.optional(Schema.Array(Schema.Unknown))
+});
+/** Verify-probe shape — what `getTransaction(digest)` returns on
+*  success. We don't decode the full transaction envelope; presence
+*  of the digest field is the "exists" signal. The lenient probe
+*  already coerces transient + not-found to null. */
+const VerifyTxShape = Schema.Struct({ digest: Schema.String });
+/** Resolve a `DynamicDiscriminator` against the action's
+*  action context and resolved dependency values. Two input shapes
+*  (per `DynamicDiscriminator`) collapse onto
+*  `Effect<string | undefined, ActionError>`. */
+const resolveDiscriminator = (actionName, dynamic, ctx, deps) => {
+	if (dynamic === void 0) return Effect.succeed(void 0);
+	if (typeof dynamic === "string") return Effect.succeed(dynamic);
+	return dynamic(ctx, deps).pipe(Effect.catch((cause) => Effect.fail(cause._tag === "ActionError" ? cause : actionError("discriminator", {
+		actionName,
+		message: `Action '${actionName}': discriminator Effect failed.`,
+		cause
+	}))));
+};
+/** Build the verify-probe Effect for a given cached digest. Lenient
+*  mode coerces transient + not-found to null; the substrate then
+*  re-produces on null. */
+const buildVerifyProbe = (probe, cachedDigest) => probe.get({
+	kind: "transaction",
+	digest: cachedDigest
+}, VerifyTxShape, "lenient").pipe(Effect.catch(() => Effect.succeed(null)));
+/** Main acquire body. Composes the ArtifactSpec for the action
+*  and yields it to the publisher.
+*
+*  Returns the cached/produced `ActionReceipt`. Errors flow as
+*  `ActionError | ArtifactPublishError` — the latter when the substrate
+*  itself surfaces a produce-failure wrap. */
+const bootActionService = (publisher, probe, inputs) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({
+		"action.name": inputs.actionName,
+		"action.chain": inputs.chainId
+	});
+	const resolvedDynamic = yield* inputs.dynamicMaterial;
+	const material = composeDiscriminatorMaterial(inputs.staticDiscriminator, resolvedDynamic);
+	const inputsHash = contentHash(createHash("sha256").update(material).digest("hex"));
+	const produced = yield* publisher.publish({
+		namespace: "action",
+		chain: inputs.chainId,
+		contentHash: inputsHash,
+		verifySchema: VerifyTxShape,
+		verify: (cached) => buildVerifyProbe(probe, cached.digest),
+		produce: Effect.gen(function* () {
+			yield* Effect.annotateCurrentSpan({ "action.phase": "building" });
+			const receipt = yield* inputs.body.pipe(Effect.catch((cause) => Effect.fail(cause?._tag === "ActionError" ? cause : actionError("sign", {
+				actionName: inputs.actionName,
+				message: `Action '${inputs.actionName}': body Effect failed.`,
+				cause
+			}))));
+			yield* Effect.annotateCurrentSpan({
+				"action.phase": "parsing",
+				"action.digest": receipt.digest
+			});
+			return receipt;
+		}).pipe(Effect.mapError((err) => ({
+			_tag: "ArtifactPublishError",
+			reason: "produce-failed",
+			detail: `action.${inputs.actionName} ${err.phase}: ${err.message}`
+		}))),
+		register: (_artifact) => Effect.void
+	});
+	if ("digest" in produced && typeof produced.digest === "string") return produced;
+	return yield* Effect.fail(actionError("parse", {
+		actionName: inputs.actionName,
+		message: `Action '${inputs.actionName}': cached payload missing digest.`
+	}));
+});
+//#endregion
+export { bootActionService, resolveDiscriminator };
+
+//# sourceMappingURL=service.mjs.map

package/dist/plugins/action/service.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.mjs","names":["brandContentHash"],"sources":["../../../src/plugins/action/service.ts"],"sourcesContent":["// Action plugin — main acquire body.\n//\n// Architecture (16-action.md): an action is a ONE-SHOT on-chain effect\n// that runs once per (chain × content-hash), caches its receipt, and\n// re-fires when its discriminator changes (or the chain regenesises).\n//\n// Implementation: thin wrapper over `ArtifactPublisher`. The\n// substrate handles the cache → verify → produce → register cycle; this\n// file composes the spec:\n//\n//   - namespace      = `action`\n//   - chain          = Sui dependency's resolved `chain`\n//   - contentHash    = hash of (actionName, upstreamResourceIds[], dynamic\n//                      discriminator if any)\n//   - verifySchema   = `ActionReceiptSchema` — Schema-validated cached\n//                      shape so a corrupt entry surfaces as a miss\n//   - verify         = `chainProbe.get({kind:'transaction', digest},\n//                      VerifyTxShape, 'lenient')` — null on transient\n//                      or not-found, NOT raise.\n//   - produce        = user's `body(ctx)` Effect. Wraps any non-tagged\n//                      throw in `ActionError({phase:'sign'})`.\n//   - register       = no-op (Action declares no in-process registry —\n//                      mirrors v3 `services/action.ts:189-191` \"Action\n//                      does NOT populate any in-process registries\").\n//\n// Constraints honored:\n//\n//   - Cache key folds (name, chainId, dependency resource ids, discriminator?) —\n//     16-action.md invariant #1.\n//   - Dynamic discriminator re-runs on EVERY acquire — invariant #6.\n//   - Lenient verify probe — invariant #4.\n//   - signAndExecute failure routes via ActionError(phase: 'sign') —\n//     invariant #8 (mirroring v3's `PublishError({phase:'publish-tx'})`,\n//     but tagged separately so action consumers `catchTag('ActionError')`\n//     without clashing with package's tagged error).\n\nimport { createHash } from 'node:crypto';\n\nimport { Effect, Schema, type Scope } from 'effect';\n\nimport { contentHash as brandContentHash, type ChainId } from '../../substrate/brand.ts';\nimport type {\n\tArtifactPublishError,\n\tArtifactPublisher,\n} from '../../primitives/artifact-publisher.ts';\nimport type { ChainProbe } from '../../contracts/chain-probe.ts';\nimport type { SuiProbeKey } from '../sui/chain-probe.ts';\nimport type { ActionBuildContext } from './build-context.ts';\nimport { actionError, type ActionError } from './errors.ts';\nimport {\n\tcomposeDiscriminatorMaterial,\n\ttype DynamicDiscriminator,\n\ttype StaticDiscriminator,\n} from './discriminator.ts';\n\n/** Action receipt — the cached value. Minimal shape: digest is the\n *  load-bearing identifier (drives verify probe + downstream\n *  consumers); the change arrays are surfaced opaquely (typed\n *  `unknown` here so the cache schema stays narrow) but the in-memory\n *  shape produced by the `ctx.signAndExecute` helper is\n *  `ActionObjectChange` (`{ kind: 'created' | 'mutated', objectId,\n *  objectType?, outputState?, idOperation? }`). Consumers can cast or\n *  use `findCreatedByType`-style helpers — mirrors v3's\n *  `pickCreatedByType(r.objectChanges, ...)` pattern from\n *  `examples/connect-four/devstack.config.ts`.\n *\n *  Distilled doc §\"Capabilities PRODUCED\" — the v3 Action's `TxResult`\n *  carries `digest`, `effects`, `objectChanges`, `balanceChanges`. We\n *  narrow to the columns that fit the cache + are actually used by\n *  downstream consumers. */\nexport interface ActionReceipt {\n\treadonly digest: string;\n\treadonly objectChanges?: ReadonlyArray<unknown>;\n\treadonly balanceChanges?: ReadonlyArray<unknown>;\n}\n\n/** Schema for the cached `ActionReceipt`. `objectChanges` /\n *  `balanceChanges` are `Unknown`-typed arrays — we don't enforce the\n *  SDK's wide change-shape here because callers project these\n *  manually (mirrors v3's `pickCreatedByType(r.objectChanges, ...)`\n *  pattern from `examples/connect-four/devstack.config.ts`). */\nexport const ActionReceiptSchema = Schema.Struct({\n\tdigest: Schema.String,\n\tobjectChanges: Schema.optional(Schema.Array(Schema.Unknown)),\n\tbalanceChanges: Schema.optional(Schema.Array(Schema.Unknown)),\n});\n\n/** Verify-probe shape — what `getTransaction(digest)` returns on\n *  success. We don't decode the full transaction envelope; presence\n *  of the digest field is the \"exists\" signal. The lenient probe\n *  already coerces transient + not-found to null. */\nconst VerifyTxShape = Schema.Struct({\n\tdigest: Schema.String,\n});\n\n/** Per-acquire inputs handed to `bootActionService`. The dynamic\n *  discriminator is pre-resolved by `index.ts` — at this layer the\n *  `staticDiscriminator` + optional `dynamicMaterial` string suffice. */\nexport interface ActionAcquireInputs {\n\treadonly actionName: string;\n\treadonly chainId: ChainId;\n\treadonly staticDiscriminator: StaticDiscriminator;\n\t/** Resolved dynamic-discriminator material — already projected to\n\t *  a string at acquire-time by `index.ts` (the callback form\n\t *  receives the `ActionBuildContext` there). */\n\treadonly dynamicMaterial: Effect.Effect<string | undefined, ActionError>;\n\t/** The user's body Effect. Receives no parameter — it closes over\n\t *  upstream-tag values via the outer `acquire` scope. Returns the\n\t *  receipt of the on-chain effect; the plugin caches this. */\n\treadonly body: Effect.Effect<ActionReceipt, ActionError, Scope.Scope>;\n}\n\n/** Resolve a `DynamicDiscriminator` against the action's\n *  action context and resolved dependency values. Two input shapes\n *  (per `DynamicDiscriminator`) collapse onto\n *  `Effect<string | undefined, ActionError>`. */\nexport const resolveDiscriminator = <Deps>(\n\tactionName: string,\n\tdynamic: DynamicDiscriminator<Deps> | undefined,\n\tctx: ActionBuildContext,\n\tdeps: Deps,\n): Effect.Effect<string | undefined, ActionError> => {\n\tif (dynamic === undefined) return Effect.succeed(undefined);\n\tif (typeof dynamic === 'string') return Effect.succeed(dynamic);\n\treturn dynamic(ctx, deps).pipe(\n\t\tEffect.catch(\n\t\t\t(cause): Effect.Effect<string, ActionError> =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\t// If the user's discriminator Effect itself raises an\n\t\t\t\t\t// ActionError, surface it verbatim. Otherwise wrap.\n\t\t\t\t\t(cause as ActionError)._tag === 'ActionError'\n\t\t\t\t\t\t? (cause as ActionError)\n\t\t\t\t\t\t: actionError('discriminator', {\n\t\t\t\t\t\t\t\tactionName,\n\t\t\t\t\t\t\t\tmessage: `Action '${actionName}': discriminator Effect failed.`,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t),\n\t\t),\n\t);\n};\n\n/** Build the verify-probe Effect for a given cached digest. Lenient\n *  mode coerces transient + not-found to null; the substrate then\n *  re-produces on null. */\nconst buildVerifyProbe = (\n\tprobe: ChainProbe<SuiProbeKey>,\n\tcachedDigest: string,\n): Effect.Effect<typeof VerifyTxShape.Type | null, never> =>\n\tprobe.get({ kind: 'transaction', digest: cachedDigest }, VerifyTxShape, 'lenient').pipe(\n\t\t// `decode-failed` on verify is stale shape — null so the\n\t\t// substrate re-fires rather than carry forward a mismatch.\n\t\tEffect.catch(() => Effect.succeed(null as typeof VerifyTxShape.Type | null)),\n\t);\n\n/** Main acquire body. Composes the ArtifactSpec for the action\n *  and yields it to the publisher.\n *\n *  Returns the cached/produced `ActionReceipt`. Errors flow as\n *  `ActionError | ArtifactPublishError` — the latter when the substrate\n *  itself surfaces a produce-failure wrap. */\nexport const bootActionService = (\n\tpublisher: ArtifactPublisher,\n\tprobe: ChainProbe<SuiProbeKey>,\n\tinputs: ActionAcquireInputs,\n): Effect.Effect<ActionReceipt, ActionError | ArtifactPublishError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'action.name': inputs.actionName,\n\t\t\t'action.chain': inputs.chainId,\n\t\t});\n\n\t\t// --- Pull the pre-projected dynamic-discriminator material\n\t\t// (every acquire — hit OR miss). The callback form's\n\t\t// `(ctx) => Effect<string>` is invoked by `index.ts` before\n\t\t// reaching here, so this layer sees only the resolved Effect.\n\t\tconst resolvedDynamic = yield* inputs.dynamicMaterial;\n\n\t\t// --- Compose content-hash inputs\n\t\tconst material = composeDiscriminatorMaterial(inputs.staticDiscriminator, resolvedDynamic);\n\t\tconst inputsHash = brandContentHash(createHash('sha256').update(material).digest('hex'));\n\n\t\t// --- Submit the spec to the publisher.\n\t\t//\n\t\t// The artifact publisher substrate decodes the cached `ActionReceipt` and\n\t\t// passes it into `verify(cached)` — so the verify Effect can\n\t\t// pull the digest off the cached payload directly. No\n\t\t// in-process registry-hop required (mirrors the seam pattern\n\t\t// the package plugin's mode-local TODO calls out).\n\t\tconst produced = yield* publisher.publish<ActionReceipt, typeof VerifyTxShape.Type>({\n\t\t\tnamespace: 'action',\n\t\t\tchain: inputs.chainId,\n\t\t\tcontentHash: inputsHash,\n\t\t\tverifySchema: VerifyTxShape,\n\t\t\tverify: (cached) => buildVerifyProbe(probe, cached.digest),\n\t\t\tproduce: Effect.gen(function* () {\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t'action.phase': 'building',\n\t\t\t\t});\n\t\t\t\tconst receipt: ActionReceipt = yield* inputs.body.pipe(\n\t\t\t\t\tEffect.catch(\n\t\t\t\t\t\t(cause): Effect.Effect<ActionReceipt, ActionError> =>\n\t\t\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\t\t\t(cause as ActionError)?._tag === 'ActionError'\n\t\t\t\t\t\t\t\t\t? (cause as ActionError)\n\t\t\t\t\t\t\t\t\t: actionError('sign', {\n\t\t\t\t\t\t\t\t\t\t\tactionName: inputs.actionName,\n\t\t\t\t\t\t\t\t\t\t\tmessage: `Action '${inputs.actionName}': body Effect failed.`,\n\t\t\t\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t'action.phase': 'parsing',\n\t\t\t\t\t'action.digest': receipt.digest,\n\t\t\t\t});\n\t\t\t\treturn receipt;\n\t\t\t}).pipe(\n\t\t\t\tEffect.mapError(\n\t\t\t\t\t(err): ArtifactPublishError => ({\n\t\t\t\t\t\t_tag: 'ArtifactPublishError',\n\t\t\t\t\t\treason: 'produce-failed',\n\t\t\t\t\t\tdetail: `action.${inputs.actionName} ${err.phase}: ${err.message}`,\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\t\tregister: (_artifact) =>\n\t\t\t\t// Action declares no in-process registry (mirrors v3's\n\t\t\t\t// `services/action.ts:189-191` \"Action does NOT populate\n\t\t\t\t// any in-process registries\"). The cached digest is now\n\t\t\t\t// threaded directly via the artifact publisher's `verify(cached)`\n\t\t\t\t// parameter — no register-hop hint required.\n\t\t\t\tEffect.void,\n\t\t});\n\n\t\t// The publisher returns `Produced | Verified`. Both shapes\n\t\t// carry `digest`; the action's resolved value is the cached\n\t\t// receipt (full `ActionReceipt` on produce/decoded-hit, or a\n\t\t// projected `{digest}` on bare-verify-hit). Callers expect the\n\t\t// wider shape — surface defensively.\n\t\tif ('digest' in produced && typeof produced.digest === 'string') {\n\t\t\t// Already-`ActionReceipt`-shaped. Cast through to recover\n\t\t\t// the optional change arrays if present.\n\t\t\treturn produced as ActionReceipt;\n\t\t}\n\t\t// Defensive: unreachable under the current substrate (verify\n\t\t// returns the bare `{digest}` shape; the substrate falls back\n\t\t// to it ONLY when the cached payload failed to decode, which\n\t\t// we treat as miss elsewhere). Surface a parse-phase error.\n\t\treturn yield* Effect.fail(\n\t\t\tactionError('parse', {\n\t\t\t\tactionName: inputs.actionName,\n\t\t\t\tmessage: `Action '${inputs.actionName}': cached payload missing digest.`,\n\t\t\t}),\n\t\t);\n\t});\n"],"mappings":";;;;;AAiFmC,OAAO,OAAO;CAChD,QAAQ,OAAO;CACf,eAAe,OAAO,SAAS,OAAO,MAAM,OAAO,QAAQ,CAAC;CAC5D,gBAAgB,OAAO,SAAS,OAAO,MAAM,OAAO,QAAQ,CAAC;CAC7D,CAAC;;;;;AAMF,MAAM,gBAAgB,OAAO,OAAO,EACnC,QAAQ,OAAO,QACf,CAAC;;;;;AAuBF,MAAa,wBACZ,YACA,SACA,KACA,SACoD;AACpD,KAAI,YAAY,KAAA,EAAW,QAAO,OAAO,QAAQ,KAAA,EAAU;AAC3D,KAAI,OAAO,YAAY,SAAU,QAAO,OAAO,QAAQ,QAAQ;AAC/D,QAAO,QAAQ,KAAK,KAAK,CAAC,KACzB,OAAO,OACL,UACA,OAAO,KAGL,MAAsB,SAAS,gBAC5B,QACD,YAAY,iBAAiB;EAC7B;EACA,SAAS,WAAW,WAAW;EAC/B;EACA,CAAC,CACJ,CACF,CACD;;;;;AAMF,MAAM,oBACL,OACA,iBAEA,MAAM,IAAI;CAAE,MAAM;CAAe,QAAQ;CAAc,EAAE,eAAe,UAAU,CAAC,KAGlF,OAAO,YAAY,OAAO,QAAQ,KAAyC,CAAC,CAC5E;;;;;;;AAQF,MAAa,qBACZ,WACA,OACA,WAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;EACjC,eAAe,OAAO;EACtB,gBAAgB,OAAO;EACvB,CAAC;CAMF,MAAM,kBAAkB,OAAO,OAAO;CAGtC,MAAM,WAAW,6BAA6B,OAAO,qBAAqB,gBAAgB;CAC1F,MAAM,aAAaA,YAAiB,WAAW,SAAS,CAAC,OAAO,SAAS,CAAC,OAAO,MAAM,CAAC;CASxF,MAAM,WAAW,OAAO,UAAU,QAAkD;EACnF,WAAW;EACX,OAAO,OAAO;EACd,aAAa;EACb,cAAc;EACd,SAAS,WAAW,iBAAiB,OAAO,OAAO,OAAO;EAC1D,SAAS,OAAO,IAAI,aAAa;AAChC,UAAO,OAAO,oBAAoB,EACjC,gBAAgB,YAChB,CAAC;GACF,MAAM,UAAyB,OAAO,OAAO,KAAK,KACjD,OAAO,OACL,UACA,OAAO,KACL,OAAuB,SAAS,gBAC7B,QACD,YAAY,QAAQ;IACpB,YAAY,OAAO;IACnB,SAAS,WAAW,OAAO,WAAW;IACtC;IACA,CAAC,CACJ,CACF,CACD;AACD,UAAO,OAAO,oBAAoB;IACjC,gBAAgB;IAChB,iBAAiB,QAAQ;IACzB,CAAC;AACF,UAAO;IACN,CAAC,KACF,OAAO,UACL,SAA+B;GAC/B,MAAM;GACN,QAAQ;GACR,QAAQ,UAAU,OAAO,WAAW,GAAG,IAAI,MAAM,IAAI,IAAI;GACzD,EACD,CACD;EACD,WAAW,cAMV,OAAO;EACR,CAAC;AAOF,KAAI,YAAY,YAAY,OAAO,SAAS,WAAW,SAGtD,QAAO;AAMR,QAAO,OAAO,OAAO,KACpB,YAAY,SAAS;EACpB,YAAY,OAAO;EACnB,SAAS,WAAW,OAAO,WAAW;EACtC,CAAC,CACF;EACA"}

package/dist/plugins/coin/address-resolution.d.mts

@@ -0,0 +1,34 @@
+import { Effect } from "effect";
+
+//#region src/plugins/coin/address-resolution.d.ts
+/** The Tag's resolved value. One uniform shape across all three
+ *  address forms — downstream consumers branch on `source` only if
+ *  they care about provenance. */
+interface ResolvedCoin {
+  readonly fullCoinType: string;
+  readonly decimals: number;
+  readonly source: 'registry' | 'on-chain' | 'builtin';
+  readonly symbol?: string;
+  readonly displayName?: string;
+  readonly iconUrl?: string;
+  readonly treasuryCapId?: string;
+  readonly metadataId?: string;
+  readonly packageId?: string;
+}
+/** Distilled-doc 13-coin.md Invariant 4: `BUILTIN_COINS.sui` MUST
+ *  always be `0x2::sui::SUI` with `decimals: 9`. Protocol-defined; any
+ *  divergence breaks downstream guards (Deepbook's SUI guard, the
+ *  balance UI's canonical-type compare). */
+declare const BUILTIN_COINS: {
+  readonly sui: {
+    fullCoinType: string;
+    decimals: number;
+    source: "builtin";
+    symbol: string;
+    displayName: string;
+  };
+};
+type BuiltinCoinName = keyof typeof BUILTIN_COINS;
+//#endregion
+export { BUILTIN_COINS, BuiltinCoinName, ResolvedCoin };
+//# sourceMappingURL=address-resolution.d.mts.map

package/dist/plugins/coin/address-resolution.mjs

@@ -0,0 +1,80 @@
+import { coinError } from "./errors.mjs";
+import { fetchCoinMetadataOnce, isBareCoinType, validateBareCoinType } from "./metadata.mjs";
+import { Effect } from "effect";
+//#region src/plugins/coin/address-resolution.ts
+/** Distilled-doc 13-coin.md Invariant 4: `BUILTIN_COINS.sui` MUST
+*  always be `0x2::sui::SUI` with `decimals: 9`. Protocol-defined; any
+*  divergence breaks downstream guards (Deepbook's SUI guard, the
+*  balance UI's canonical-type compare). */
+const BUILTIN_COINS = { sui: {
+	fullCoinType: "0x2::sui::SUI",
+	decimals: 9,
+	source: "builtin",
+	symbol: "SUI",
+	displayName: "Sui"
+} };
+/** Resolve a builtin coin. Pure constant — no Effect, no upstream. */
+const resolveBuiltin = (name) => BUILTIN_COINS[name];
+/** Project a `CoinRecord` to the resolved-value shape. Shared across
+*  registry-backed forms. */
+const projectRecord = (record, source) => ({
+	fullCoinType: record.type,
+	decimals: record.decimals,
+	source,
+	...record.symbol !== void 0 ? { symbol: record.symbol } : {},
+	...record.displayName !== void 0 ? { displayName: record.displayName } : {},
+	...record.iconUrl !== void 0 ? { iconUrl: record.iconUrl } : {},
+	...record.treasuryCapId !== void 0 ? { treasuryCapId: record.treasuryCapId } : {},
+	...record.metadataId !== void 0 ? { metadataId: record.metadataId } : {},
+	packageId: record.packageId
+});
+/** Resolve a coin by `(publishing package's symbolic name, witness)`.
+*  Distilled-doc 13-coin.md §"Lifecycle" path 3: the caller yields
+*  the package tag first to force the dep edge; this helper assumes
+*  the registry is already populated by the time it runs. */
+const resolveByWitness = (registry, packageName, witness) => Effect.gen(function* () {
+	const record = yield* registry.byWitness(packageName, witness);
+	if (record === null) {
+		const candidates = (yield* registry.list()).filter((r) => r.publishingPackageName === packageName).map((r) => r.symbol ?? r.witness);
+		return yield* Effect.fail(coinError("not-found", {
+			identifier: `${packageName}::${witness}`,
+			message: `coin.fromPackage('${packageName}', '${witness}'): witness not present in the package's discovered coins.`,
+			candidates
+		}));
+	}
+	return projectRecord(record, "registry");
+});
+/** Resolve a coin by bare on-chain type. Calls `getCoinMetadata`
+*  against the resolved Sui client; soft-degrades to `decimals: 0` on
+*  RPC failure (distilled-doc 13-coin.md Failure modes table).
+*
+*  Bare type is validated first (distilled-doc invariant 7: refuses
+*  nested generics). The validator surfaces `CoinError('nested-
+*  generic')`; everything else falls through to the lenient fetch. */
+const resolveByBareType = (sdk, fullCoinType) => Effect.gen(function* () {
+	const validation = validateBareCoinType(fullCoinType);
+	if (validation !== null) return yield* Effect.fail(validation);
+	if (!isBareCoinType(fullCoinType)) return yield* Effect.fail(coinError("not-found", {
+		identifier: fullCoinType,
+		message: `coin.known('${fullCoinType}'): not a bare on-chain coin type — expected '0xHEX::module::Witness'.`
+	}));
+	const metadata = yield* fetchCoinMetadataOnce(sdk, fullCoinType);
+	if (metadata === null) return {
+		fullCoinType,
+		decimals: 0,
+		source: "on-chain"
+	};
+	return {
+		fullCoinType,
+		decimals: metadata.decimals,
+		source: "on-chain",
+		symbol: metadata.symbol,
+		displayName: metadata.name,
+		...metadata.iconUrl !== void 0 ? { iconUrl: metadata.iconUrl } : {},
+		metadataId: metadata.id
+	};
+});
+//#endregion
+export { BUILTIN_COINS, resolveBuiltin, resolveByBareType, resolveByWitness };
+
+//# sourceMappingURL=address-resolution.mjs.map

package/dist/plugins/coin/address-resolution.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-resolution.mjs","names":[],"sources":["../../../src/plugins/coin/address-resolution.ts"],"sourcesContent":["// Coin address-resolution — the three user-facing forms unified.\n//\n// Distilled-doc 13-coin.md §Configuration: the user-facing\n// `coin(...)` factory takes one of three address forms. Each form\n// resolves to a `ResolvedCoin`:\n//\n//   1. **Package-scoped witness** — `coin.fromPackage(pkg, 'MOCK_USDC')`.\n//      Forces a dependency edge on the publishing package resource, then\n//      reads its publish output's discovered coins. Statically typed\n//      against local packages only (KnownPackages have no output).\n//\n//   2. **Bare on-chain type** — `coin.known('0x...::DEEP::DEEP')`.\n//      Bypasses the registry; calls `getCoinMetadata` against the\n//      resolved Sui client. Use for live-net coins (mainnet DEEP).\n//\n//   3. **Builtin SUI** — `coin.builtin('sui')`. Pure constant.\n//      Resolves to `0x2::sui::SUI` with `decimals: 9` synchronously.\n//\n// Each form returns a `ResolvedCoin` carrying the same shape so\n// downstream consumers (Wallet balance UI, Faucet treasury-cap mint,\n// Deepbook market maker) see one consistent value.\n\nimport { Effect } from 'effect';\n\nimport { coinError, type CoinError } from './errors.ts';\nimport {\n\tfetchCoinMetadataOnce,\n\tisBareCoinType,\n\tvalidateBareCoinType,\n\ttype MetadataSdkShim,\n} from './metadata.ts';\nimport type { CoinRecord, CoinRegistry } from './registry.ts';\n\n/** The Tag's resolved value. One uniform shape across all three\n *  address forms — downstream consumers branch on `source` only if\n *  they care about provenance. */\nexport interface ResolvedCoin {\n\treadonly fullCoinType: string;\n\treadonly decimals: number;\n\treadonly source: 'registry' | 'on-chain' | 'builtin';\n\treadonly symbol?: string;\n\treadonly displayName?: string;\n\treadonly iconUrl?: string;\n\treadonly treasuryCapId?: string;\n\treadonly metadataId?: string;\n\treadonly packageId?: string;\n}\n\n// -----------------------------------------------------------------------------\n// Builtin SUI\n// -----------------------------------------------------------------------------\n\n/** Distilled-doc 13-coin.md Invariant 4: `BUILTIN_COINS.sui` MUST\n *  always be `0x2::sui::SUI` with `decimals: 9`. Protocol-defined; any\n *  divergence breaks downstream guards (Deepbook's SUI guard, the\n *  balance UI's canonical-type compare). */\nexport const BUILTIN_COINS = {\n\tsui: {\n\t\tfullCoinType: '0x2::sui::SUI',\n\t\tdecimals: 9,\n\t\tsource: 'builtin' as const,\n\t\tsymbol: 'SUI',\n\t\tdisplayName: 'Sui',\n\t} satisfies ResolvedCoin,\n} as const;\n\nexport type BuiltinCoinName = keyof typeof BUILTIN_COINS;\n\n/** Resolve a builtin coin. Pure constant — no Effect, no upstream. */\nexport const resolveBuiltin = (name: BuiltinCoinName): ResolvedCoin => BUILTIN_COINS[name];\n\n// -----------------------------------------------------------------------------\n// Registry record projection\n// -----------------------------------------------------------------------------\n\n/** Project a `CoinRecord` to the resolved-value shape. Shared across\n *  registry-backed forms. */\nconst projectRecord = (record: CoinRecord, source: 'registry'): ResolvedCoin => ({\n\tfullCoinType: record.type,\n\tdecimals: record.decimals,\n\tsource,\n\t...(record.symbol !== undefined ? { symbol: record.symbol } : {}),\n\t...(record.displayName !== undefined ? { displayName: record.displayName } : {}),\n\t...(record.iconUrl !== undefined ? { iconUrl: record.iconUrl } : {}),\n\t...(record.treasuryCapId !== undefined ? { treasuryCapId: record.treasuryCapId } : {}),\n\t...(record.metadataId !== undefined ? { metadataId: record.metadataId } : {}),\n\tpackageId: record.packageId,\n});\n\n// -----------------------------------------------------------------------------\n// Form 1: package-scoped witness → registry\n// -----------------------------------------------------------------------------\n\n/** Resolve a coin by `(publishing package's symbolic name, witness)`.\n *  Distilled-doc 13-coin.md §\"Lifecycle\" path 3: the caller yields\n *  the package tag first to force the dep edge; this helper assumes\n *  the registry is already populated by the time it runs. */\nexport const resolveByWitness = (\n\tregistry: CoinRegistry,\n\tpackageName: string,\n\twitness: string,\n): Effect.Effect<ResolvedCoin, CoinError> =>\n\tEffect.gen(function* () {\n\t\tconst record = yield* registry.byWitness(packageName, witness);\n\t\tif (record === null) {\n\t\t\tconst candidates = (yield* registry.list())\n\t\t\t\t.filter((r) => r.publishingPackageName === packageName)\n\t\t\t\t.map((r) => r.symbol ?? r.witness);\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tcoinError('not-found', {\n\t\t\t\t\tidentifier: `${packageName}::${witness}`,\n\t\t\t\t\tmessage: `coin.fromPackage('${packageName}', '${witness}'): witness not present in the package's discovered coins.`,\n\t\t\t\t\tcandidates,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\treturn projectRecord(record, 'registry');\n\t});\n\n// -----------------------------------------------------------------------------\n// Form 2: bare on-chain type → live RPC\n// -----------------------------------------------------------------------------\n\n/** Resolve a coin by bare on-chain type. Calls `getCoinMetadata`\n *  against the resolved Sui client; soft-degrades to `decimals: 0` on\n *  RPC failure (distilled-doc 13-coin.md Failure modes table).\n *\n *  Bare type is validated first (distilled-doc invariant 7: refuses\n *  nested generics). The validator surfaces `CoinError('nested-\n *  generic')`; everything else falls through to the lenient fetch. */\nexport const resolveByBareType = (\n\tsdk: MetadataSdkShim,\n\tfullCoinType: string,\n): Effect.Effect<ResolvedCoin, CoinError> =>\n\tEffect.gen(function* () {\n\t\tconst validation = validateBareCoinType(fullCoinType);\n\t\tif (validation !== null) {\n\t\t\treturn yield* Effect.fail(validation);\n\t\t}\n\t\tif (!isBareCoinType(fullCoinType)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tcoinError('not-found', {\n\t\t\t\t\tidentifier: fullCoinType,\n\t\t\t\t\tmessage: `coin.known('${fullCoinType}'): not a bare on-chain coin type — expected '0xHEX::module::Witness'.`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst metadata = yield* fetchCoinMetadataOnce(sdk, fullCoinType);\n\t\tif (metadata === null) {\n\t\t\t// Soft-degradation: surface a record with decimals=0 and no\n\t\t\t// metadata. Downstream consumers that NEED metadata see\n\t\t\t// degraded fields — but we don't fail boot.\n\t\t\treturn {\n\t\t\t\tfullCoinType,\n\t\t\t\tdecimals: 0,\n\t\t\t\tsource: 'on-chain',\n\t\t\t};\n\t\t}\n\t\treturn {\n\t\t\tfullCoinType,\n\t\t\tdecimals: metadata.decimals,\n\t\t\tsource: 'on-chain',\n\t\t\tsymbol: metadata.symbol,\n\t\t\tdisplayName: metadata.name,\n\t\t\t...(metadata.iconUrl !== undefined ? { iconUrl: metadata.iconUrl } : {}),\n\t\t\tmetadataId: metadata.id,\n\t\t};\n\t});\n"],"mappings":";;;;;;;;AAwDA,MAAa,gBAAgB,EAC5B,KAAK;CACJ,cAAc;CACd,UAAU;CACV,QAAQ;CACR,QAAQ;CACR,aAAa;CACb,EACD;;AAKD,MAAa,kBAAkB,SAAwC,cAAc;;;AAQrF,MAAM,iBAAiB,QAAoB,YAAsC;CAChF,cAAc,OAAO;CACrB,UAAU,OAAO;CACjB;CACA,GAAI,OAAO,WAAW,KAAA,IAAY,EAAE,QAAQ,OAAO,QAAQ,GAAG,EAAE;CAChE,GAAI,OAAO,gBAAgB,KAAA,IAAY,EAAE,aAAa,OAAO,aAAa,GAAG,EAAE;CAC/E,GAAI,OAAO,YAAY,KAAA,IAAY,EAAE,SAAS,OAAO,SAAS,GAAG,EAAE;CACnE,GAAI,OAAO,kBAAkB,KAAA,IAAY,EAAE,eAAe,OAAO,eAAe,GAAG,EAAE;CACrF,GAAI,OAAO,eAAe,KAAA,IAAY,EAAE,YAAY,OAAO,YAAY,GAAG,EAAE;CAC5E,WAAW,OAAO;CAClB;;;;;AAUD,MAAa,oBACZ,UACA,aACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,SAAS,OAAO,SAAS,UAAU,aAAa,QAAQ;AAC9D,KAAI,WAAW,MAAM;EACpB,MAAM,cAAc,OAAO,SAAS,MAAM,EACxC,QAAQ,MAAM,EAAE,0BAA0B,YAAY,CACtD,KAAK,MAAM,EAAE,UAAU,EAAE,QAAQ;AACnC,SAAO,OAAO,OAAO,KACpB,UAAU,aAAa;GACtB,YAAY,GAAG,YAAY,IAAI;GAC/B,SAAS,qBAAqB,YAAY,MAAM,QAAQ;GACxD;GACA,CAAC,CACF;;AAEF,QAAO,cAAc,QAAQ,WAAW;EACvC;;;;;;;;AAaH,MAAa,qBACZ,KACA,iBAEA,OAAO,IAAI,aAAa;CACvB,MAAM,aAAa,qBAAqB,aAAa;AACrD,KAAI,eAAe,KAClB,QAAO,OAAO,OAAO,KAAK,WAAW;AAEtC,KAAI,CAAC,eAAe,aAAa,CAChC,QAAO,OAAO,OAAO,KACpB,UAAU,aAAa;EACtB,YAAY;EACZ,SAAS,eAAe,aAAa;EACrC,CAAC,CACF;CAEF,MAAM,WAAW,OAAO,sBAAsB,KAAK,aAAa;AAChE,KAAI,aAAa,KAIhB,QAAO;EACN;EACA,UAAU;EACV,QAAQ;EACR;AAEF,QAAO;EACN;EACA,UAAU,SAAS;EACnB,QAAQ;EACR,QAAQ,SAAS;EACjB,aAAa,SAAS;EACtB,GAAI,SAAS,YAAY,KAAA,IAAY,EAAE,SAAS,SAAS,SAAS,GAAG,EAAE;EACvE,YAAY,SAAS;EACrB;EACA"}

package/dist/plugins/coin/codegen.d.mts

@@ -0,0 +1,16 @@
+//#region src/plugins/coin/codegen.d.ts
+/** The typed shape per emitted coin record. */
+interface CoinBindings {
+  readonly symbol: string;
+  readonly fullCoinType: string;
+  readonly decimals: number;
+  readonly displayName?: string;
+  readonly iconUrl?: string;
+  readonly treasuryCapId?: string;
+  readonly metadataId?: string;
+  readonly packageId?: string;
+  readonly source: 'registry' | 'on-chain' | 'builtin';
+}
+//#endregion
+export { CoinBindings };
+//# sourceMappingURL=codegen.d.mts.map

package/dist/plugins/coin/codegen.mjs

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+//#region src/plugins/coin/codegen.ts
+/** Construct the Codegenable contribution for one coin instance.
+*
+*  Emitter name is literal `coin/${symbol}` so the orchestrator can
+*  group them and folds them into a single `coins.ts` at staging
+*  time. Mirrors `account/${name}` naming in the Account plugin. */
+const makeCoinCodegen = (parts) => ({
+	kind: "codegenable",
+	emitterName: `coin/${parts.symbol}`,
+	outputPath: `coins/${parts.symbol}.ts`,
+	sensitive: false,
+	emit: (ctx) => Effect.sync(() => {
+		ctx.exportConst(parts.symbol, parts.resolved);
+		return ctx.done();
+	})
+});
+//#endregion
+export { makeCoinCodegen };
+
+//# sourceMappingURL=codegen.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/coin/codegen.ts"],"sourcesContent":["// Coin plugin — Codegenable contribution.\n//\n// Distilled-doc 13-coin.md §\"Files written\": the codegen orchestrator\n// projects the per-stack CoinRegistry into a generated `coins.ts`\n// table:\n//\n//   export const coins = {\n//     mUSDC: { type, decimals, sdkCoin, symbol, ... },\n//     mWETH: { type, decimals, sdkCoin, symbol, ... },\n//   } as const;\n//   export type CoinName = keyof typeof coins;\n//\n// This file declares the SEAM — the typed binding shape and the\n// per-coin contribution. The heavy lift (writing the bytes, merging\n// all coins into one file) happens in the codegen orchestrator\n// (plugin/codegen layer, NOT this plugin); it walks every member's\n// caps tuple, finds the Coin-emitted contributions, and emits ONE\n// `coins.ts` referencing every entry.\n//\n// Per-coin shape mirrors the v3 `CoinEntry` (manifest schema) sans\n// the `sdkCoin` runtime projection — that lives in the SDK adapter\n// at codegen time, not in the binding shape.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\n/** The typed shape per emitted coin record. */\nexport interface CoinBindings {\n\treadonly symbol: string;\n\treadonly fullCoinType: string;\n\treadonly decimals: number;\n\treadonly displayName?: string;\n\treadonly iconUrl?: string;\n\treadonly treasuryCapId?: string;\n\treadonly metadataId?: string;\n\treadonly packageId?: string;\n\treadonly source: 'registry' | 'on-chain' | 'builtin';\n}\n\n/** Construct the Codegenable contribution for one coin instance.\n *\n *  Emitter name is literal `coin/${symbol}` so the orchestrator can\n *  group them and folds them into a single `coins.ts` at staging\n *  time. Mirrors `account/${name}` naming in the Account plugin. */\nexport const makeCoinCodegen = <Symbol extends string>(parts: {\n\treadonly symbol: Symbol;\n\treadonly resolved: CoinBindings;\n}): CodegenableDecl<`coin/${Symbol}`> => ({\n\tkind: 'codegenable',\n\temitterName: `coin/${parts.symbol}` as `coin/${Symbol}`,\n\toutputPath: `coins/${parts.symbol}.ts`,\n\tsensitive: false,\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tctx.exportConst(parts.symbol, parts.resolved);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;;;AA6CA,MAAa,mBAA0C,WAGb;CACzC,MAAM;CACN,aAAa,QAAQ,MAAM;CAC3B,YAAY,SAAS,MAAM,OAAO;CAClC,WAAW;CACX,OAAO,QACN,OAAO,WAAW;AACjB,MAAI,YAAY,MAAM,QAAQ,MAAM,SAAS;AAC7C,SAAO,IAAI,MAAM;GAChB;CACH"}

package/dist/plugins/coin/discovery.d.mts

@@ -0,0 +1,26 @@
+//#region src/plugins/coin/discovery.d.ts
+/** A discovered coin pulled out of a publish output. The downstream
+ *  metadata enricher in `metadata.ts` turns this into a full
+ *  `CoinRecord`. */
+interface DiscoveredCoin {
+  /** `0xPKG::module::Witness`. */
+  readonly fullCoinType: string;
+  /** Lower-cased witness name. */
+  readonly witness: string;
+  /** Lower-cased module name. */
+  readonly moduleName: string;
+  readonly treasuryCapId?: string;
+  readonly treasuryCapOwner?: string;
+  readonly metadataId?: string;
+  readonly decimals?: number;
+  readonly symbol?: string;
+  readonly displayName?: string;
+  readonly iconUrl?: string;
+  /** True when the cap is address-owned by the publisher at the
+   *  end of the publish tx. Distilled-doc invariant: the faucet's
+   *  treasury-cap-mint auto-registration is gated off this flag. */
+  readonly publisherOwnsCap: boolean;
+}
+//#endregion
+export { DiscoveredCoin };
+//# sourceMappingURL=discovery.d.mts.map

package/dist/plugins/coin/discovery.mjs

@@ -0,0 +1,112 @@
+import { pickSuiFrameworkInnerGeneric, pickSuiFrameworkInnerGenericFromModule } from "./type-strings.mjs";
+//#region src/plugins/coin/discovery.ts
+/** Extract module + witness from `0xPKG::module::Witness`. */
+const splitCoinType = (fullCoinType) => {
+	const parts = fullCoinType.split("::");
+	if (parts.length !== 3) return null;
+	const [, moduleName, witness] = parts;
+	if (moduleName === void 0 || witness === void 0) return null;
+	return {
+		moduleName,
+		witness
+	};
+};
+/** Read the address owner from a package-publish-output change. Handles
+*  the SDK's discriminated owner-shape; non-address owners surface as
+*  `undefined`. The owner shape varies across SDK versions; this
+*  helper covers the common surface and degrades gracefully. */
+const pickAddressOwner = (change) => {
+	const owner = change.owner;
+	if (owner === void 0 || owner === null) return void 0;
+	if (typeof owner === "string") return owner;
+	if (typeof owner === "object" && "AddressOwner" in owner) return owner.AddressOwner;
+};
+const pickString = (json, key) => {
+	const value = json[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+const pickNumber = (json, key) => {
+	const value = json[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+};
+const pickMetadata = (change) => {
+	const json = change.json;
+	if (json === null || typeof json !== "object" || Array.isArray(json)) return null;
+	const record = json;
+	const decimals = pickNumber(record, "decimals");
+	const symbol = pickString(record, "symbol");
+	const displayName = pickString(record, "name");
+	const iconUrl = pickString(record, "iconUrl") ?? pickString(record, "icon_url");
+	if (decimals === void 0 && symbol === void 0 && displayName === void 0 && iconUrl === void 0) return null;
+	return {
+		...decimals === void 0 ? {} : { decimals },
+		...symbol === void 0 ? {} : { symbol },
+		...displayName === void 0 ? {} : { displayName },
+		...iconUrl === void 0 ? {} : { iconUrl }
+	};
+};
+/** Walk a publish output for coin pairs.
+*
+*  Sort ascending by fullCoinType — distilled-doc invariant 6 — so
+*  the registry sees a stable order across re-runs of the same
+*  publish.
+*
+*  Pure. No Effect / RPC. */
+const discoverCoinsFromPublish = (output) => {
+	const publisher = output.publisher;
+	const caps = /* @__PURE__ */ new Map();
+	const metadata = /* @__PURE__ */ new Map();
+	for (const change of output.objectChanges) {
+		if (change.type !== "created") continue;
+		if (!change.objectType) continue;
+		const capInner = pickSuiFrameworkInnerGeneric(change.objectType, "TreasuryCap");
+		if (capInner !== null && change.objectId !== void 0) {
+			caps.set(capInner, {
+				id: change.objectId,
+				owner: pickAddressOwner(change)
+			});
+			continue;
+		}
+		const metaInner = pickSuiFrameworkInnerGeneric(change.objectType, "CoinMetadata");
+		if (metaInner !== null && change.objectId !== void 0) {
+			metadata.set(metaInner, {
+				id: change.objectId,
+				...pickMetadata(change) ?? {}
+			});
+			continue;
+		}
+		const currencyInner = pickSuiFrameworkInnerGenericFromModule(change.objectType, "coin_registry", "Currency");
+		if (currencyInner !== null && change.objectId !== void 0) metadata.set(currencyInner, {
+			id: change.objectId,
+			...pickMetadata(change) ?? {}
+		});
+	}
+	const allTypes = new Set([...caps.keys(), ...metadata.keys()]);
+	const records = [];
+	for (const fullCoinType of allTypes) {
+		const parts = splitCoinType(fullCoinType);
+		if (!parts) continue;
+		const cap = caps.get(fullCoinType);
+		const meta = metadata.get(fullCoinType);
+		const publisherOwnsCap = cap !== void 0 && cap.owner === publisher;
+		records.push({
+			fullCoinType,
+			witness: parts.witness.toLowerCase(),
+			moduleName: parts.moduleName.toLowerCase(),
+			treasuryCapId: cap?.id,
+			treasuryCapOwner: cap?.owner,
+			metadataId: meta?.id,
+			...meta?.decimals === void 0 ? {} : { decimals: meta.decimals },
+			...meta?.symbol === void 0 ? {} : { symbol: meta.symbol },
+			...meta?.displayName === void 0 ? {} : { displayName: meta.displayName },
+			...meta?.iconUrl === void 0 ? {} : { iconUrl: meta.iconUrl },
+			publisherOwnsCap
+		});
+	}
+	records.sort((a, b) => a.fullCoinType < b.fullCoinType ? -1 : a.fullCoinType > b.fullCoinType ? 1 : 0);
+	return records;
+};
+//#endregion
+export { discoverCoinsFromPublish };
+
+//# sourceMappingURL=discovery.mjs.map