@mysten-incubation/devstack 0.0.0

package/dist/plugins/package/codegen.mjs

@@ -0,0 +1,41 @@
+import { Effect } from "effect";
+//#region src/plugins/package/codegen.ts
+/** Build the Codegenable contribution for a local package. */
+const makeLocalCodegenable = (resolved, options) => ({
+	kind: "codegenable",
+	emitterName: "package",
+	outputPath: `package/${resolved.mvrPlaceholder}.ts`,
+	emit: (ctx) => Effect.sync(() => {
+		ctx.exportConst("packageBindings", {
+			name: resolved.name,
+			packageId: resolved.packageId,
+			mvrPlaceholder: resolved.mvrPlaceholder,
+			sourcePath: resolved.sourcePath,
+			excluded: options.excluded
+		});
+		return ctx.done();
+	})
+});
+/** Build the Codegenable contribution for a known package. The
+*  shape is identical except `sourcePath: null`. The codegen
+*  orchestrator filters these out before invoking the bindings
+*  emitter. */
+const makeKnownCodegenable = (resolved) => ({
+	kind: "codegenable",
+	emitterName: "package",
+	outputPath: `package/${resolved.mvrPlaceholder}.ts`,
+	emit: (ctx) => Effect.sync(() => {
+		ctx.exportConst("packageBindings", {
+			name: resolved.name,
+			packageId: resolved.packageId,
+			mvrPlaceholder: resolved.mvrPlaceholder,
+			sourcePath: null,
+			excluded: true
+		});
+		return ctx.done();
+	})
+});
+//#endregion
+export { makeKnownCodegenable, makeLocalCodegenable };
+
+//# sourceMappingURL=codegen.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/package/codegen.ts"],"sourcesContent":["// Package plugin — Codegenable contribution.\n//\n// Distilled doc §Outputs: \"Bindings input — the source path of every\n// local Package is read by the bindings emitter (KnownPackages\n// filtered out).\"\n//\n// The contribution emitted here is the LIGHTWEIGHT one: package id +\n// MVR placeholder + (for local packages) the source path the\n// bindings emitter consumes. The HEAVY codegen — `@mysten/codegen`\n// emitting typed function shims — happens in the codegen\n// ORCHESTRATOR (plugin/codegen layer, NOT this plugin). The\n// orchestrator walks every member's caps tuple, finds the\n// Package-emitted contributions, and dispatches `@mysten/codegen`\n// once across all of them so a single TS program references every\n// emitted package binding.\n//\n// This file therefore declares the SEAM, not the binding bytes.\n// Distilled doc §Cross-component references §codegen: package\n// \"consumes local Package source paths to emit bindings; respects\n// the per-package codegen-exclude flag; uses MVR placeholders so\n// emitted code stays portable.\"\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\nimport type { ResolvedLocalPackage, ResolvedKnownPackage } from './registry.ts';\n\n/** Codegenable shape — what each Package contributes to the codegen\n *  orchestrator. Two variants mirror the local/known split. */\nexport interface PackageBindings {\n\treadonly name: string;\n\treadonly packageId: string;\n\treadonly mvrPlaceholder: string;\n\t/** Present for local packages only — the bindings emitter reads\n\t *  this; KnownPackages omit it and the orchestrator skips them\n\t *  for bindings emission (compile-time enforcement at the\n\t *  factory layer per distilled doc Invariant 9). */\n\treadonly sourcePath: string | null;\n\t/** Per-package opt-out (distilled doc §Inputs — \"Codegen\n\t *  exclusion flag\"). */\n\treadonly excluded: boolean;\n}\n\n/** Build the Codegenable contribution for a local package. */\nexport const makeLocalCodegenable = (\n\tresolved: ResolvedLocalPackage,\n\toptions: { readonly excluded: boolean },\n): CodegenableDecl<'package'> => ({\n\tkind: 'codegenable',\n\temitterName: 'package',\n\toutputPath: `package/${resolved.mvrPlaceholder}.ts`,\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\t// The orchestrator picks up these fields and threads them\n\t\t\t// into `@mysten/codegen` along with the source-path read.\n\t\t\t// The literal binding-file bytes are written by the\n\t\t\t// orchestrator, NOT this plugin.\n\t\t\tctx.exportConst('packageBindings', {\n\t\t\t\tname: resolved.name,\n\t\t\t\tpackageId: resolved.packageId,\n\t\t\t\tmvrPlaceholder: resolved.mvrPlaceholder,\n\t\t\t\tsourcePath: resolved.sourcePath,\n\t\t\t\texcluded: options.excluded,\n\t\t\t} satisfies PackageBindings);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n\n/** Build the Codegenable contribution for a known package. The\n *  shape is identical except `sourcePath: null`. The codegen\n *  orchestrator filters these out before invoking the bindings\n *  emitter. */\nexport const makeKnownCodegenable = (\n\tresolved: ResolvedKnownPackage,\n): CodegenableDecl<'package'> => ({\n\tkind: 'codegenable',\n\temitterName: 'package',\n\toutputPath: `package/${resolved.mvrPlaceholder}.ts`,\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tctx.exportConst('packageBindings', {\n\t\t\t\tname: resolved.name,\n\t\t\t\tpackageId: resolved.packageId,\n\t\t\t\tmvrPlaceholder: resolved.mvrPlaceholder,\n\t\t\t\tsourcePath: null,\n\t\t\t\texcluded: true, // implicit — KnownPackages never emit bindings.\n\t\t\t} satisfies PackageBindings);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;AA4CA,MAAa,wBACZ,UACA,aACiC;CACjC,MAAM;CACN,aAAa;CACb,YAAY,WAAW,SAAS,eAAe;CAC/C,OAAO,QACN,OAAO,WAAW;AAKjB,MAAI,YAAY,mBAAmB;GAClC,MAAM,SAAS;GACf,WAAW,SAAS;GACpB,gBAAgB,SAAS;GACzB,YAAY,SAAS;GACrB,UAAU,QAAQ;GAClB,CAA2B;AAC5B,SAAO,IAAI,MAAM;GAChB;CACH;;;;;AAMD,MAAa,wBACZ,cACiC;CACjC,MAAM;CACN,aAAa;CACb,YAAY,WAAW,SAAS,eAAe;CAC/C,OAAO,QACN,OAAO,WAAW;AACjB,MAAI,YAAY,mBAAmB;GAClC,MAAM,SAAS;GACf,WAAW,SAAS;GACpB,gBAAgB,SAAS;GACzB,YAAY;GACZ,UAAU;GACV,CAA2B;AAC5B,SAAO,IAAI,MAAM;GAChB;CACH"}

package/dist/plugins/package/dep-resolution.mjs

@@ -0,0 +1,10 @@
+//#region src/plugins/package/dep-resolution.ts
+/**
+* Slugify a package name into the MVR placeholder shape required by
+* codegen emitters.
+*/
+const mvrSlugify = (name) => name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+//#endregion
+export { mvrSlugify };
+
+//# sourceMappingURL=dep-resolution.mjs.map

package/dist/plugins/package/dep-resolution.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep-resolution.mjs","names":[],"sources":["../../../src/plugins/package/dep-resolution.ts"],"sourcesContent":["// Move-dep helpers.\n//\n// `mvrSlugify` normalises a package name into the slug shape that\n// codegen emitters write into Move source as MVR placeholders.\n// Distilled doc Invariant 13: the result MUST satisfy `[a-z0-9-]+`\n// (downstream validators reject underscores).\n\n/**\n * Slugify a package name into the MVR placeholder shape required by\n * codegen emitters.\n */\nexport const mvrSlugify = (name: string): string =>\n\tname\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9-]+/g, '-')\n\t\t.replace(/^-+|-+$/g, '')\n\t\t.replace(/-{2,}/g, '-');\n"],"mappings":";;;;;AAWA,MAAa,cAAc,SAC1B,KACE,aAAa,CACb,QAAQ,gBAAgB,IAAI,CAC5B,QAAQ,YAAY,GAAG,CACvB,QAAQ,UAAU,IAAI"}

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

@@ -0,0 +1,34 @@
+//#region src/plugins/package/errors.d.ts
+/** Closed step set for `PublishError`.
+ *
+ *   - `hash`        — source-tree walk / digest failed (FS read perms,
+ *                     symlink loop, disk error).
+ *   - `scrub`       — vendored Move.lock scrub failed.
+ *   - `build`       — `sui move build` exit / parse failure / container
+ *                     unreachable. Cause-chain carries verbatim
+ *                     stdout/stderr.
+ *   - `publish-tx`  — sign-and-execute failed (gas, bytecode
+ *                     verification, RPC).
+ *   - `parse`       — no `published` change in receipt OR the
+ *                     post-publish ready-probe timed out.
+ *   - `verify`      — KnownPackage verify probe authoritatively says
+ *                     "object not present" (transient is masked by
+ *                     lenient probe — does NOT raise this).
+ */
+type PublishPhase = 'hash' | 'scrub' | 'build' | 'publish-tx' | 'parse' | 'verify';
+/** Single tagged publish error. */
+interface PublishError {
+  readonly _tag: 'PublishError';
+  readonly phase: PublishPhase;
+  /** Source path of the package being published. ALWAYS populated
+   *  — `KnownPackage` paths set this to the symbolic id (distilled
+   *  doc §Opportunities — "every throw site passes sourcePath"). */
+  readonly sourcePath: string;
+  /** Symbolic package name (the user-declared `pkg.name`). */
+  readonly packageName: string;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+//#endregion
+export { PublishError };
+//# sourceMappingURL=errors.d.mts.map

package/dist/plugins/package/errors.mjs

@@ -0,0 +1,13 @@
+//#region src/plugins/package/errors.ts
+const publishError = (phase, parts) => ({
+	_tag: "PublishError",
+	phase,
+	...parts
+});
+/** Error tags this plugin contributes — surfaced to the cause walker
+*  via `PluginErrorContribution`. */
+const PACKAGE_ERROR_TAGS = ["PublishError"];
+//#endregion
+export { PACKAGE_ERROR_TAGS, publishError };
+
+//# sourceMappingURL=errors.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/package/errors.ts"],"sourcesContent":["// Package plugin — typed errors.\n//\n// Distilled doc §\"Edge cases and known failure modes\": the publish\n// error is a SINGLE tagged error with a CLOSED step set. Per\n// architecture §Effect, errors are plain interfaces with a `_tag`\n// discriminator; `Effect.catchTag` / `catchTags` match on the literal.\n\n/** Closed step set for `PublishError`.\n *\n *   - `hash`        — source-tree walk / digest failed (FS read perms,\n *                     symlink loop, disk error).\n *   - `scrub`       — vendored Move.lock scrub failed.\n *   - `build`       — `sui move build` exit / parse failure / container\n *                     unreachable. Cause-chain carries verbatim\n *                     stdout/stderr.\n *   - `publish-tx`  — sign-and-execute failed (gas, bytecode\n *                     verification, RPC).\n *   - `parse`       — no `published` change in receipt OR the\n *                     post-publish ready-probe timed out.\n *   - `verify`      — KnownPackage verify probe authoritatively says\n *                     \"object not present\" (transient is masked by\n *                     lenient probe — does NOT raise this).\n */\nexport type PublishPhase = 'hash' | 'scrub' | 'build' | 'publish-tx' | 'parse' | 'verify';\n\n/** Single tagged publish error. */\nexport interface PublishError {\n\treadonly _tag: 'PublishError';\n\treadonly phase: PublishPhase;\n\t/** Source path of the package being published. ALWAYS populated\n\t *  — `KnownPackage` paths set this to the symbolic id (distilled\n\t *  doc §Opportunities — \"every throw site passes sourcePath\"). */\n\treadonly sourcePath: string;\n\t/** Symbolic package name (the user-declared `pkg.name`). */\n\treadonly packageName: string;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const publishError = (\n\tphase: PublishPhase,\n\tparts: Omit<PublishError, '_tag' | 'phase'>,\n): PublishError => ({ _tag: 'PublishError', phase, ...parts });\n\n/** Error tags this plugin contributes — surfaced to the cause walker\n *  via `PluginErrorContribution`. */\nexport const PACKAGE_ERROR_TAGS = ['PublishError'] as const;\n\nexport type PackageError = PublishError;\n"],"mappings":";AAuCA,MAAa,gBACZ,OACA,WACmB;CAAE,MAAM;CAAgB;CAAO,GAAG;CAAO;;;AAI7D,MAAa,qBAAqB,CAAC,eAAe"}

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

@@ -0,0 +1,109 @@
+import { CodegenableDecl } from "../../contracts/codegenable.mjs";
+import { ProjectionDecl } from "../../contracts/projection.mjs";
+import { SnapshotableDecl } from "../../contracts/snapshotable.mjs";
+import { StrategyContributorDecl } from "../../contracts/strategy-contributor.mjs";
+import { AnyResourceRef, Plugin, 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 { AccountValue } from "../account/service.mjs";
+import { AccountResourceId } from "../account/index.mjs";
+import { LocalPackagePublishOutput, LocalPackagePublishedDecl, PackagePublishObjectChange } from "./publish-output.mjs";
+import { ResolvedKnownPackage, ResolvedLocalPackage } from "./registry.mjs";
+import { PublishError } from "./errors.mjs";
+import { PackageBindings } from "./codegen.mjs";
+//#region src/plugins/package/index.d.ts
+/** A user-supplied publisher account ref. The user passes the result
+ *  of `account('alice')` — NOT a bare string. Generic over the
+ *  literal account name so the package dependency preserves the
+ *  per-account resource id. */
+type PublisherAccountMember<Name extends string = string> = ResourceRef<AccountResourceId<Name>, AccountValue>;
+/** Resolved value carried by the package resource. Local packages also
+ *  expose the publish output so manifest emitters and capture-spec
+ *  callers can read it. Sibling plugin folds consume the package-owned
+ *  extension contribution instead of importing package internals. */
+type PackageCaptureMap = Readonly<Record<string, string>>;
+type PackageCaptureCallback = (output: LocalPackagePublishOutput) => Readonly<Record<string, string>>;
+type PackageCapture = PackageCaptureMap;
+type CapturedPackageValues<Capture> = Capture extends PackageCaptureCallback ? Readonly<Record<string, string>> : Capture extends PackageCaptureMap ? { readonly [K in keyof Capture]: string } : Readonly<Record<string, string>>;
+interface LocalPackageResolved<Capture = undefined> extends Omit<ResolvedLocalPackage, 'captured'> {
+  /** Captured object ids keyed by the user's `capture` option. */
+  readonly captured: CapturedPackageValues<Capture>;
+  /** Publisher account that signed this package. Kept on the live
+   *  resource value so downstream local coin plugins can mint from
+   *  publisher-owned TreasuryCaps through the centralized funding
+   *  strategy path. It is intentionally not written to generated
+   *  bindings or the package registry. */
+  readonly publisher: AccountValue;
+  /** Publish output — present after a fresh publish, null on
+   *  cache hit (verify-only path). Consumers that need the
+   *  output MUST tolerate null and fall back to chain reads via
+   *  the ChainProbe. */
+  readonly publishResult: LocalPackagePublishOutput | null;
+}
+type KnownPackageResolved = ResolvedKnownPackage;
+type PackageResolved = LocalPackageResolved | KnownPackageResolved;
+interface LocalPackageOptions<Publisher extends PublisherAccountMember = PublisherAccountMember, Capture extends PackageCapture | undefined = undefined> {
+  readonly sourcePath: string;
+  readonly mvrPlaceholder?: string;
+  readonly excludeFromCodegen?: boolean;
+  /** Capture created objects from the publish output. The record
+   *  form maps output keys to object-type suffixes, e.g.
+   *  `{ boardId: '::board::Board' }`. */
+  readonly capture?: Capture;
+  /** Publisher account — the signer for the publish tx. Pass the
+   *  result of `account('alice')` (the same plugin/resource ref used
+   *  in the rest of the stack — NOT a duplicate factory call).
+   *
+   *  Required for local packages: a publish tx must be signed by
+   *  SOMEONE; we make the choice explicit so two packages in the
+   *  same stack can publish under different accounts (no implicit
+   *  "first account" convention to memorise). Distilled doc Invariant
+   *  4 — "Signer MUST be an explicit upstream". */
+  readonly publisher: Publisher;
+}
+interface KnownPackageOptions {
+  readonly packageId: string;
+  readonly upgradeCapId?: string;
+  readonly mvrPlaceholder?: string;
+}
+interface PackageRegistryProjectionContribution {
+  readonly kind: 'local' | 'known';
+  readonly name: string;
+  readonly packageId: string;
+  readonly upgradeCapId: string | null;
+  readonly mvrPlaceholder: string;
+  readonly sourcePath: string | null;
+}
+/** Build + publish a local Move package. The resolved value is
+ *  `LocalPackageResolved` so consumers that need bindings / source
+ *  path are typed correctly.
+ *
+ *  Required `opts.publisher`: the account that signs the publish tx.
+ *  Pass the same `account('alice')` reference used elsewhere in the
+ *  stack — the package.s `dependsOn` includes `account/<publisher>`
+ *  so the substrate orders the publisher's keypair + funding strictly
+ *  before publish. */
+declare const localPackage: <Name extends string, const Publisher extends PublisherAccountMember, const Capture extends PackageCapture | undefined = undefined>(name: Name, opts: LocalPackageOptions<Publisher, Capture>) => Plugin<`package:${Name}`, LocalPackageResolved<Capture>, {
+  readonly sui: ResourceRef<"sui", SuiClient & {
+    readonly mode: SuiOptions["mode"];
+    readonly seedObjects: SeedObjectsAccumulator;
+  }>;
+  readonly publisher: Publisher;
+} extends infer T ? T extends {
+  readonly sui: ResourceRef<"sui", SuiClient & {
+    readonly mode: SuiOptions["mode"];
+    readonly seedObjects: SeedObjectsAccumulator;
+  }>;
+  readonly publisher: Publisher;
+} ? T extends Readonly<Record<string, AnyResourceRef>> ? readonly T[keyof T][] : readonly [] : never : never, readonly [SnapshotableDecl, CodegenableDecl<"package">, StrategyContributorDecl<"package-registry", PackageRegistryProjectionContribution>, ProjectionDecl, ...LocalPackagePublishedDecl[]]>;
+/** Verify-only against a fixed on-chain package id. The resolved
+ *  value is `KnownPackageResolved` — narrower than local, so the
+ *  bindings emitter rejects this at compose time. */
+declare const knownPackage: <Name extends string>(name: Name, opts: KnownPackageOptions) => Plugin<`package:${Name}`, ResolvedKnownPackage, readonly ResourceRef<"sui", SuiClient & {
+  readonly mode: SuiOptions["mode"];
+  readonly seedObjects: SeedObjectsAccumulator;
+}>[], readonly [SnapshotableDecl, CodegenableDecl<"package">, StrategyContributorDecl<"package-registry", PackageRegistryProjectionContribution>, ProjectionDecl]>;
+//#endregion
+export { KnownPackageOptions, KnownPackageResolved, LocalPackageOptions, LocalPackageResolved, PackageCapture, PackageResolved, PublisherAccountMember, knownPackage, localPackage };
+//# sourceMappingURL=index.d.mts.map

package/dist/plugins/package/index.mjs

@@ -0,0 +1,207 @@
+import { definePlugin, resource } from "../../substrate/plugin.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import { ContainerRuntimeService } from "../../runtime/docker/service.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 { makeLocalPackagePublishedDecl, pickCreatedByType } from "./publish-output.mjs";
+import { PACKAGE_REGISTRY_CAPABILITY_KEY, PackageRegistryService } from "./registry.mjs";
+import { makeKnownCodegenable, makeLocalCodegenable } from "./codegen.mjs";
+import { PACKAGE_ERROR_TAGS } from "./errors.mjs";
+import { makePublishExecutor } from "./publish-executor.mjs";
+import { bootPackageService } from "./service.mjs";
+import { makeSnapshotable } from "./snapshot.mjs";
+import { Effect } from "effect";
+//#region src/plugins/package/index.ts
+const packageErrorContributions = pluginErrorContributions(PACKAGE_ERROR_TAGS);
+/** Resource id constructor. The symbolic package name is part of the tag
+*  identity so the substrate's compose-time dedup detects collisions
+*  cleanly (two `localPackage('foo', ...)` calls in one stack → typed
+*  error at compose time). */
+const packageResourceId = (name) => `package:${name}`;
+const makePackageProjectionContribution = (projection) => {
+	const updatedAt = Date.now();
+	return {
+		kind: "projection",
+		event: {
+			tag: "package.updated",
+			package: {
+				key: `package/${projection.name}`,
+				rowKey: null,
+				name: projection.name,
+				kind: projection.kind,
+				packageId: projection.packageId,
+				upgradeCapId: projection.upgradeCapId,
+				mvrPlaceholder: projection.mvrPlaceholder,
+				sourcePath: projection.sourcePath,
+				updatedAt
+			},
+			at: updatedAt
+		}
+	};
+};
+const normalizeCapture = (packageName, capture) => {
+	if (capture === void 0) return void 0;
+	return (output) => {
+		const captured = {};
+		for (const [key, suffix] of Object.entries(capture)) {
+			const objectId = pickCreatedByType(output.objectChanges, { suffix });
+			if (objectId === void 0) throw new Error(`localPackage('${packageName}') capture '${key}' matched no created object with suffix '${suffix}'.`);
+			captured[key] = objectId;
+		}
+		return captured;
+	};
+};
+const buildLocalPlugin = (name, opts) => {
+	const packageRef = resource(packageResourceId(name));
+	const capture = normalizeCapture(name, opts.capture);
+	return definePlugin({
+		id: packageRef.id,
+		dependsOn: {
+			sui: suiResource,
+			publisher: opts.publisher
+		},
+		role: "task",
+		watch: {
+			paths: [
+				`${opts.sourcePath}/**/*.move`,
+				`${opts.sourcePath}/Move.toml`,
+				`${opts.sourcePath}/Move.lock`
+			],
+			cascade: true
+		},
+		start: ({ sui, publisher: publisherAccount }) => Effect.gen(function* () {
+			const publisher = yield* ArtifactPublisherService;
+			const probe = yield* chainProbeFor(sui.chain);
+			const registry = yield* PackageRegistryService;
+			const containerRuntime = yield* ContainerRuntimeService;
+			const executor = makePublishExecutor({
+				sdk: sui.sdk,
+				account: publisherAccount,
+				runtime: containerRuntime,
+				...sui.buildImage !== null ? { buildImage: sui.buildImage } : {}
+			});
+			const { resolved, output } = yield* bootPackageService(publisher, probe, registry, {
+				mode: "local",
+				packageName: name,
+				sourcePath: opts.sourcePath,
+				chainId: sui.chain,
+				publisherAddress: publisherAccount.address,
+				mvrOverride: opts.mvrPlaceholder,
+				...capture !== void 0 ? { capture } : {},
+				executor
+			});
+			return {
+				...resolved,
+				captured: resolved.captured,
+				publisher: publisherAccount,
+				publishResult: output
+			};
+		}),
+		errorContributions: packageErrorContributions,
+		capabilities: ({ value, runtime }) => makeLocalCapabilities(name, opts, value, runtime.chain)
+	});
+};
+const buildKnownPlugin = (name, opts) => {
+	return definePlugin({
+		id: resource(packageResourceId(name)).id,
+		dependsOn: { sui: suiResource },
+		role: "task",
+		start: ({ sui }) => Effect.gen(function* () {
+			const { resolved } = yield* bootPackageService(yield* ArtifactPublisherService, yield* chainProbeFor(sui.chain), yield* PackageRegistryService, {
+				mode: "known",
+				packageName: name,
+				packageId: opts.packageId,
+				upgradeCapId: opts.upgradeCapId,
+				mvrOverride: opts.mvrPlaceholder
+			});
+			return resolved;
+		}),
+		errorContributions: packageErrorContributions,
+		capabilities: ({ value }) => makeKnownCapabilities(name, opts, value)
+	});
+};
+const makeLocalCapabilities = (name, opts, resolved, chain) => {
+	const snap = makeSnapshotable(name, resolved.publishResult?.packageId ?? resolved.packageId);
+	const codegen = makeLocalCodegenable({
+		kind: "local",
+		name,
+		packageId: resolved.packageId,
+		upgradeCapId: resolved.upgradeCapId,
+		sourcePath: resolved.sourcePath,
+		mvrPlaceholder: resolved.mvrPlaceholder,
+		captured: resolved.captured
+	}, { excluded: opts.excludeFromCodegen ?? false });
+	const projection = {
+		kind: "local",
+		name,
+		packageId: resolved.packageId,
+		upgradeCapId: resolved.upgradeCapId ?? null,
+		mvrPlaceholder: resolved.mvrPlaceholder,
+		sourcePath: resolved.sourcePath
+	};
+	return [
+		snap,
+		codegen,
+		{
+			kind: "strategy-contributor",
+			capabilityKey: PACKAGE_REGISTRY_CAPABILITY_KEY,
+			strategy: projection,
+			autoMounted: true
+		},
+		makePackageProjectionContribution(projection),
+		...resolved.publishResult === null ? [] : [makeLocalPackagePublishedDecl({
+			packageName: name,
+			packageId: resolved.packageId,
+			chain,
+			output: resolved.publishResult
+		})]
+	];
+};
+const makeKnownCapabilities = (name, opts, resolved) => {
+	const snap = makeSnapshotable(name, `known:${resolved.packageId}`);
+	const codegen = makeKnownCodegenable({
+		kind: "known",
+		name,
+		packageId: resolved.packageId,
+		upgradeCapId: resolved.upgradeCapId ?? opts.upgradeCapId,
+		mvrPlaceholder: resolved.mvrPlaceholder
+	});
+	const projection = {
+		kind: "known",
+		name,
+		packageId: resolved.packageId,
+		upgradeCapId: resolved.upgradeCapId ?? opts.upgradeCapId ?? null,
+		mvrPlaceholder: resolved.mvrPlaceholder,
+		sourcePath: null
+	};
+	return [
+		snap,
+		codegen,
+		{
+			kind: "strategy-contributor",
+			capabilityKey: PACKAGE_REGISTRY_CAPABILITY_KEY,
+			strategy: projection,
+			autoMounted: true
+		},
+		makePackageProjectionContribution(projection)
+	];
+};
+/** Build + publish a local Move package. The resolved value is
+*  `LocalPackageResolved` so consumers that need bindings / source
+*  path are typed correctly.
+*
+*  Required `opts.publisher`: the account that signs the publish tx.
+*  Pass the same `account('alice')` reference used elsewhere in the
+*  stack — the package.s `dependsOn` includes `account/<publisher>`
+*  so the substrate orders the publisher's keypair + funding strictly
+*  before publish. */
+const localPackage = (name, opts) => buildLocalPlugin(name, opts);
+/** Verify-only against a fixed on-chain package id. The resolved
+*  value is `KnownPackageResolved` — narrower than local, so the
+*  bindings emitter rejects this at compose time. */
+const knownPackage = (name, opts) => buildKnownPlugin(name, opts);
+//#endregion
+export { knownPackage, localPackage };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/plugins/package/index.ts"],"sourcesContent":["// Package plugin — barrel + factories.\n//\n// Architecture: Package is the canonical implementation of the\n// `ArtifactPublisher` substrate primitive. Many service\n// plugins depend on its publish output (Coin types, Walrus/Seal/\n// Deepbook contracts, Action outputs).\n//\n// Public surface:\n//\n//   - `localPackage(name, opts)`  — build + publish a Move source tree.\n//   - `knownPackage(name, opts)`  — verify-only against a fixed id.\n//\n// Type split (distilled doc Invariant 9): `localPackage` resolves to\n// `LocalPackage`; `knownPackage` resolves to `KnownPackage`. The\n// bindings emitter (in the codegen orchestrator) types-out KnownPackage\n// at compose time, so misuse fails at compile time rather than at\n// emit time.\n//\n// Resource id: `'package:<name>'` — one tag per user-declared package\n// (the symbolic name is part of the identity so two `localPackage`\n// calls in the same stack don't collide on the substrate's tag\n// registry). Substrate-side plugin key is the same string.\n\nimport { Effect } from 'effect';\n\nimport { definePlugin, resource, type ResourceRef } from '../../api/define-plugin.ts';\nimport { pluginErrorContributions } from '../../api/plugin-errors.ts';\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\nimport type { ProjectionDecl } from '../../contracts/projection.ts';\nimport {\n\tmakeLocalPackagePublishedDecl,\n\tpickCreatedByType,\n\ttype LocalPackagePublishOutput,\n} from './publish-output.ts';\nimport type { SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport type { StrategyContributorDecl } from '../../contracts/strategy-contributor.ts';\nimport { ContainerRuntimeService } from '../../runtime/docker/service.ts';\nimport type { ChainId } from '../../substrate/brand.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';\nimport type { AccountResourceId } from '../account/index.ts';\nimport type { AccountValue } from '../account/service.ts';\nimport { makeKnownCodegenable, makeLocalCodegenable } from './codegen.ts';\nimport { makePublishExecutor } from './publish-executor.ts';\nimport { bootPackageService, type PackageMode } from './service.ts';\nimport {\n\tPACKAGE_REGISTRY_CAPABILITY_KEY,\n\tPackageRegistryService,\n\ttype ResolvedKnownPackage,\n\ttype ResolvedLocalPackage,\n} from './registry.ts';\nimport { makeSnapshotable } from './snapshot.ts';\nimport { PACKAGE_ERROR_TAGS } from './errors.ts';\n\nconst packageErrorContributions = pluginErrorContributions(PACKAGE_ERROR_TAGS);\n\n// ---------------------------------------------------------------------------\n// Publisher account ref — explicit upstream\n// ---------------------------------------------------------------------------\n\n/** A user-supplied publisher account ref. The user passes the result\n *  of `account('alice')` — NOT a bare string. Generic over the\n *  literal account name so the package dependency preserves the\n *  per-account resource id. */\nexport type PublisherAccountMember<Name extends string = string> = ResourceRef<\n\tAccountResourceId<Name>,\n\tAccountValue\n>;\n\n// ---------------------------------------------------------------------------\n// Resource — one per declared package, keyed by symbolic name\n// ---------------------------------------------------------------------------\n\n/** Resource id constructor. The symbolic package name is part of the tag\n *  identity so the substrate's compose-time dedup detects collisions\n *  cleanly (two `localPackage('foo', ...)` calls in one stack → typed\n *  error at compose time). */\nexport const packageResourceId = <Name extends string>(name: Name): `package:${Name}` =>\n\t`package:${name}`;\n\n/** The literal-template resource id for a package by symbolic name. */\nexport type PackageResourceId<Name extends string> = `package:${Name}`;\n\n/** Public resolved value shapes — re-exported from `registry.ts` to\n *  give consumers one stable import path. */\nexport type { ResolvedLocalPackage, ResolvedKnownPackage, ResolvedPackage } from './registry.ts';\nexport type {\n\tPickCreatedByTypeOptions,\n\tLocalPackagePublishOutput,\n\tPackagePublishObjectChange,\n} from './publish-output.ts';\nexport { pickCreatedByType } from './publish-output.ts';\nexport type { PublishError } from './errors.ts';\nexport { PACKAGE_ERROR_TAGS } from './errors.ts';\nexport type { PackageBindings } from './codegen.ts';\nexport type { PublishExecutor } from './mode-local.ts';\n\n/** Resolved value carried by the package resource. Local packages also\n *  expose the publish output so manifest emitters and capture-spec\n *  callers can read it. Sibling plugin folds consume the package-owned\n *  extension contribution instead of importing package internals. */\nexport type PackageCaptureMap = Readonly<Record<string, string>>;\n\ntype PackageCaptureCallback = (\n\toutput: LocalPackagePublishOutput,\n) => Readonly<Record<string, string>>;\n\nexport type PackageCapture = PackageCaptureMap;\n\nexport type CapturedPackageValues<Capture> = Capture extends PackageCaptureCallback\n\t? Readonly<Record<string, string>>\n\t: Capture extends PackageCaptureMap\n\t\t? { readonly [K in keyof Capture]: string }\n\t\t: Readonly<Record<string, string>>;\n\nexport interface LocalPackageResolved<Capture = undefined> extends Omit<\n\tResolvedLocalPackage,\n\t'captured'\n> {\n\t/** Captured object ids keyed by the user's `capture` option. */\n\treadonly captured: CapturedPackageValues<Capture>;\n\t/** Publisher account that signed this package. Kept on the live\n\t *  resource value so downstream local coin plugins can mint from\n\t *  publisher-owned TreasuryCaps through the centralized funding\n\t *  strategy path. It is intentionally not written to generated\n\t *  bindings or the package registry. */\n\treadonly publisher: AccountValue;\n\t/** Publish output — present after a fresh publish, null on\n\t *  cache hit (verify-only path). Consumers that need the\n\t *  output MUST tolerate null and fall back to chain reads via\n\t *  the ChainProbe. */\n\treadonly publishResult: LocalPackagePublishOutput | null;\n}\n\nexport type KnownPackageResolved = ResolvedKnownPackage;\n\nexport type PackageResolved = LocalPackageResolved | KnownPackageResolved;\n\n// ---------------------------------------------------------------------------\n// Factory options\n// ---------------------------------------------------------------------------\n\nexport interface LocalPackageOptions<\n\tPublisher extends PublisherAccountMember = PublisherAccountMember,\n\tCapture extends PackageCapture | undefined = undefined,\n> {\n\treadonly sourcePath: string;\n\treadonly mvrPlaceholder?: string;\n\treadonly excludeFromCodegen?: boolean;\n\t/** Capture created objects from the publish output. The record\n\t *  form maps output keys to object-type suffixes, e.g.\n\t *  `{ boardId: '::board::Board' }`. */\n\treadonly capture?: Capture;\n\t/** Publisher account — the signer for the publish tx. Pass the\n\t *  result of `account('alice')` (the same plugin/resource ref used\n\t *  in the rest of the stack — NOT a duplicate factory call).\n\t *\n\t *  Required for local packages: a publish tx must be signed by\n\t *  SOMEONE; we make the choice explicit so two packages in the\n\t *  same stack can publish under different accounts (no implicit\n\t *  \"first account\" convention to memorise). Distilled doc Invariant\n\t *  4 — \"Signer MUST be an explicit upstream\". */\n\treadonly publisher: Publisher;\n}\n\nexport interface KnownPackageOptions {\n\treadonly packageId: string;\n\treadonly upgradeCapId?: string;\n\treadonly mvrPlaceholder?: string;\n}\n\ninterface PackageRegistryProjectionContribution {\n\treadonly kind: 'local' | 'known';\n\treadonly name: string;\n\treadonly packageId: string;\n\treadonly upgradeCapId: string | null;\n\treadonly mvrPlaceholder: string;\n\treadonly sourcePath: string | null;\n}\n\nconst makePackageProjectionContribution = (\n\tprojection: PackageRegistryProjectionContribution,\n): ProjectionDecl => {\n\tconst updatedAt = Date.now();\n\treturn {\n\t\tkind: 'projection',\n\t\tevent: {\n\t\t\ttag: 'package.updated',\n\t\t\tpackage: {\n\t\t\t\tkey: `package/${projection.name}` as `package/${string}`,\n\t\t\t\trowKey: null,\n\t\t\t\tname: projection.name,\n\t\t\t\tkind: projection.kind,\n\t\t\t\tpackageId: projection.packageId,\n\t\t\t\tupgradeCapId: projection.upgradeCapId,\n\t\t\t\tmvrPlaceholder: projection.mvrPlaceholder,\n\t\t\t\tsourcePath: projection.sourcePath,\n\t\t\t\tupdatedAt,\n\t\t\t},\n\t\t\tat: updatedAt,\n\t\t},\n\t};\n};\n\n// ---------------------------------------------------------------------------\n// Internal builders\n// ---------------------------------------------------------------------------\n\nconst normalizeCapture = <Capture extends PackageCapture | undefined>(\n\tpackageName: string,\n\tcapture: Capture,\n): PackageCaptureCallback | undefined => {\n\tif (capture === undefined) return undefined;\n\treturn (output) => {\n\t\tconst captured: Record<string, string> = {};\n\t\tfor (const [key, suffix] of Object.entries(capture)) {\n\t\t\tconst objectId = pickCreatedByType(output.objectChanges, { suffix });\n\t\t\tif (objectId === undefined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`localPackage('${packageName}') capture '${key}' matched no created object with suffix '${suffix}'.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tcaptured[key] = objectId;\n\t\t}\n\t\treturn captured;\n\t};\n};\n\nconst buildLocalPlugin = <\n\tName extends string,\n\tconst Publisher extends PublisherAccountMember,\n\tCapture extends PackageCapture | undefined,\n>(\n\tname: Name,\n\topts: LocalPackageOptions<Publisher, Capture>,\n) => {\n\tconst packageRef = resource<PackageResourceId<Name>, LocalPackageResolved<Capture>>(\n\t\tpackageResourceId(name),\n\t);\n\tconst capture = normalizeCapture(name, opts.capture);\n\n\treturn definePlugin({\n\t\tid: packageRef.id,\n\t\tdependsOn: { sui: suiResource, publisher: opts.publisher },\n\t\trole: 'task',\n\t\twatch: {\n\t\t\t// File-watcher contribution — restart on Move source edits.\n\t\t\t// Distilled doc §Outputs: literal-path Packages contribute\n\t\t\t// watch roots. Effect-resolved paths do NOT auto-attach.\n\t\t\tpaths: [\n\t\t\t\t`${opts.sourcePath}/**/*.move`,\n\t\t\t\t`${opts.sourcePath}/Move.toml`,\n\t\t\t\t`${opts.sourcePath}/Move.lock`,\n\t\t\t],\n\t\t\tcascade: true,\n\t\t},\n\t\tstart: ({ sui, publisher: publisherAccount }) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\t// Substrate-context primitives: ArtifactPublisher\n\t\t\t\t// is provided by the supervisor's pluginContext;\n\t\t\t\t// ChainProbe is looked up via the StrategyRegistry\n\t\t\t\t// (Sui registered itself there at acquire). The\n\t\t\t\t// PackageRegistry is a per-stack plugin-owned service\n\t\t\t\t// (instantiated from the substrate's generic\n\t\t\t\t// ScopedRefMap primitive — see `registry.ts`) — every\n\t\t\t\t// package plugin in the stack yields the SAME instance\n\t\t\t\t// via `PackageRegistryService`, so cross-plugin lookups\n\t\t\t\t// stay consistent and warm-restart verify can use the\n\t\t\t\t// previous packageId as a hint.\n\t\t\t\tconst publisher = yield* ArtifactPublisherService;\n\t\t\t\tconst probe = yield* chainProbeFor<SuiProbeKey>(sui.chain);\n\t\t\t\tconst registry = yield* PackageRegistryService;\n\t\t\t\t// ContainerRuntime + the Sui plugin's resolved image feed\n\t\t\t\t// `runMoveBuild`'s path-(b) (`docker run --rm`) build path.\n\t\t\t\t// Sui surfaces `buildImage` on its resolved client; modes\n\t\t\t\t// without an in-stack image (external, live) surface null\n\t\t\t\t// — runMoveBuild then surfaces a typed error from path (c)\n\t\t\t\t// (host CLI not routed).\n\t\t\t\tconst containerRuntime = yield* ContainerRuntimeService;\n\n\t\t\t\t// Build the concrete `PublishExecutor` once per acquire.\n\t\t\t\t// Hands the resolved SuiSdkShim (for `Transaction.build`,\n\t\t\t\t// `executeTransaction`, `waitForTransaction`) and the\n\t\t\t\t// publisher account (for `signAndExecute`) to the executor\n\t\t\t\t// methods; mode-local's produce body drives them.\n\t\t\t\tconst executor = makePublishExecutor({\n\t\t\t\t\tsdk: sui.sdk,\n\t\t\t\t\taccount: publisherAccount,\n\t\t\t\t\truntime: containerRuntime,\n\t\t\t\t\t...(sui.buildImage !== null ? { buildImage: sui.buildImage } : {}),\n\t\t\t\t});\n\n\t\t\t\tconst mode = {\n\t\t\t\t\tmode: 'local',\n\t\t\t\t\tpackageName: name,\n\t\t\t\t\tsourcePath: opts.sourcePath,\n\t\t\t\t\tchainId: sui.chain,\n\t\t\t\t\tpublisherAddress: publisherAccount.address,\n\t\t\t\t\tmvrOverride: opts.mvrPlaceholder,\n\t\t\t\t\t...(capture !== undefined ? { capture } : {}),\n\t\t\t\t\texecutor,\n\t\t\t\t} satisfies PackageMode;\n\n\t\t\t\tconst { resolved, output } = yield* bootPackageService(publisher, probe, registry, mode);\n\n\t\t\t\tconst projected: LocalPackageResolved<Capture> = {\n\t\t\t\t\t...resolved,\n\t\t\t\t\tcaptured: resolved.captured as CapturedPackageValues<Capture>,\n\t\t\t\t\tpublisher: publisherAccount,\n\t\t\t\t\tpublishResult: output,\n\t\t\t\t};\n\t\t\t\treturn projected;\n\t\t\t}),\n\t\terrorContributions: packageErrorContributions,\n\t\tcapabilities: ({ value, runtime }) => makeLocalCapabilities(name, opts, value, runtime.chain),\n\t});\n};\n\nconst buildKnownPlugin = <Name extends string>(name: Name, opts: KnownPackageOptions) => {\n\tconst packageRef = resource<PackageResourceId<Name>, KnownPackageResolved>(\n\t\tpackageResourceId(name),\n\t);\n\treturn definePlugin({\n\t\tid: packageRef.id,\n\t\tdependsOn: { sui: suiResource },\n\t\trole: 'task',\n\t\tstart: ({ sui }) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst publisher = yield* ArtifactPublisherService;\n\t\t\t\tconst probe = yield* chainProbeFor<SuiProbeKey>(sui.chain);\n\t\t\t\tconst registry = yield* PackageRegistryService;\n\t\t\t\tconst mode = {\n\t\t\t\t\tmode: 'known',\n\t\t\t\t\tpackageName: name,\n\t\t\t\t\tpackageId: opts.packageId,\n\t\t\t\t\tupgradeCapId: opts.upgradeCapId,\n\t\t\t\t\tmvrOverride: opts.mvrPlaceholder,\n\t\t\t\t} satisfies PackageMode;\n\t\t\t\tconst { resolved } = yield* bootPackageService(publisher, probe, registry, mode);\n\t\t\t\t// Known mode never publishes — no output to walk, so\n\t\t\t\t// the coin-discovery hook is skipped here. Users who\n\t\t\t\t// want coin records for a knownPackage point a\n\t\t\t\t// `coin.known('0xPKG::module::Witness')` at the\n\t\t\t\t// fully-qualified type directly; the bare-type path\n\t\t\t\t// hits the live RPC for metadata rather than the\n\t\t\t\t// output-walker.\n\t\t\t\treturn resolved;\n\t\t\t}),\n\t\terrorContributions: packageErrorContributions,\n\t\tcapabilities: ({ value }) => makeKnownCapabilities(name, opts, value),\n\t});\n};\n\nconst makeLocalCapabilities = (\n\tname: string,\n\topts: { readonly excludeFromCodegen?: boolean },\n\tresolved: LocalPackageResolved,\n\tchain: ChainId,\n) => {\n\t// Snapshot + codegen lift their typed fields off the resolved\n\t// publish (real packageId + captured object ids). The static-form\n\t// placeholders are gone.\n\tconst snap: SnapshotableDecl = makeSnapshotable(\n\t\tname,\n\t\tresolved.publishResult?.packageId ?? resolved.packageId,\n\t);\n\tconst codegen: CodegenableDecl<'package'> = makeLocalCodegenable(\n\t\t{\n\t\t\tkind: 'local',\n\t\t\tname,\n\t\t\tpackageId: resolved.packageId,\n\t\t\tupgradeCapId: resolved.upgradeCapId,\n\t\t\tsourcePath: resolved.sourcePath,\n\t\t\tmvrPlaceholder: resolved.mvrPlaceholder,\n\t\t\tcaptured: resolved.captured,\n\t\t},\n\t\t{ excluded: opts.excludeFromCodegen ?? false },\n\t);\n\t// The plugin contributes to the package-registry strategy under a\n\t// fixed key — the substrate orchestrator wires all packages'\n\t// contributions into the same per-stack registry.\n\tconst projection: PackageRegistryProjectionContribution = {\n\t\tkind: 'local',\n\t\tname,\n\t\tpackageId: resolved.packageId,\n\t\tupgradeCapId: resolved.upgradeCapId ?? null,\n\t\tmvrPlaceholder: resolved.mvrPlaceholder,\n\t\tsourcePath: resolved.sourcePath,\n\t};\n\tconst registryContribution: StrategyContributorDecl<\n\t\ttypeof PACKAGE_REGISTRY_CAPABILITY_KEY,\n\t\tPackageRegistryProjectionContribution\n\t> = {\n\t\tkind: 'strategy-contributor',\n\t\tcapabilityKey: PACKAGE_REGISTRY_CAPABILITY_KEY,\n\t\tstrategy: projection,\n\t\tautoMounted: true,\n\t};\n\treturn [\n\t\tsnap,\n\t\tcodegen,\n\t\tregistryContribution,\n\t\tmakePackageProjectionContribution(projection),\n\t\t...(resolved.publishResult === null\n\t\t\t? []\n\t\t\t: [\n\t\t\t\t\tmakeLocalPackagePublishedDecl({\n\t\t\t\t\t\tpackageName: name,\n\t\t\t\t\t\tpackageId: resolved.packageId,\n\t\t\t\t\t\tchain,\n\t\t\t\t\t\toutput: resolved.publishResult,\n\t\t\t\t\t}),\n\t\t\t\t]),\n\t] as const;\n};\n\nconst makeKnownCapabilities = (\n\tname: string,\n\topts: KnownPackageOptions,\n\tresolved: KnownPackageResolved,\n) => {\n\tconst snap: SnapshotableDecl = makeSnapshotable(name, `known:${resolved.packageId}`);\n\tconst codegen: CodegenableDecl<'package'> = makeKnownCodegenable({\n\t\tkind: 'known',\n\t\tname,\n\t\tpackageId: resolved.packageId,\n\t\tupgradeCapId: resolved.upgradeCapId ?? opts.upgradeCapId,\n\t\tmvrPlaceholder: resolved.mvrPlaceholder,\n\t});\n\tconst projection: PackageRegistryProjectionContribution = {\n\t\tkind: 'known',\n\t\tname,\n\t\tpackageId: resolved.packageId,\n\t\tupgradeCapId: resolved.upgradeCapId ?? opts.upgradeCapId ?? null,\n\t\tmvrPlaceholder: resolved.mvrPlaceholder,\n\t\tsourcePath: null,\n\t};\n\tconst registryContribution: StrategyContributorDecl<\n\t\ttypeof PACKAGE_REGISTRY_CAPABILITY_KEY,\n\t\tPackageRegistryProjectionContribution\n\t> = {\n\t\tkind: 'strategy-contributor',\n\t\tcapabilityKey: PACKAGE_REGISTRY_CAPABILITY_KEY,\n\t\tstrategy: projection,\n\t\tautoMounted: true,\n\t};\n\treturn [\n\t\tsnap,\n\t\tcodegen,\n\t\tregistryContribution,\n\t\tmakePackageProjectionContribution(projection),\n\t] as const;\n};\n\n// ---------------------------------------------------------------------------\n// Public factories\n// ---------------------------------------------------------------------------\n\n/** Build + publish a local Move package. The resolved value is\n *  `LocalPackageResolved` so consumers that need bindings / source\n *  path are typed correctly.\n *\n *  Required `opts.publisher`: the account that signs the publish tx.\n *  Pass the same `account('alice')` reference used elsewhere in the\n *  stack — the package.s `dependsOn` includes `account/<publisher>`\n *  so the substrate orders the publisher's keypair + funding strictly\n *  before publish. */\nexport const localPackage = <\n\tName extends string,\n\tconst Publisher extends PublisherAccountMember,\n\tconst Capture extends PackageCapture | undefined = undefined,\n>(\n\tname: Name,\n\topts: LocalPackageOptions<Publisher, Capture>,\n) => buildLocalPlugin(name, opts);\n\n/** Verify-only against a fixed on-chain package id. The resolved\n *  value is `KnownPackageResolved` — narrower than local, so the\n *  bindings emitter rejects this at compose time. */\nexport const knownPackage = <Name extends string>(name: Name, opts: KnownPackageOptions) =>\n\tbuildKnownPlugin(name, opts);\n"],"mappings":"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"}

package/dist/plugins/package/mode-known.mjs

@@ -0,0 +1,41 @@
+import { publishError } from "./errors.mjs";
+import { mvrSlugify } from "./dep-resolution.mjs";
+import { Effect, Schema } from "effect";
+//#region src/plugins/package/mode-known.ts
+/** Verify-schema for known mode — minimum signal: object exists at
+*  the given id. */
+const KnownObjectShape = Schema.Struct({ objectId: Schema.String });
+/**
+* Acquire body for known mode.
+*
+* Runs the lenient ChainProbe verify and registers the resolved value.
+* Lenient mode masks transient RPC failure — the user-visible failure
+* here is "object truly missing on this chain". A `null` probe result
+* does not surface yet: distinguishing transient-vs-missing requires a
+* second strict probe layer that the ChainProbe primitive does not
+* expose.
+*/
+const acquireKnown = (probe, registry, inputs) => Effect.gen(function* () {
+	const mvrPlaceholder = mvrSlugify(inputs.mvrOverride ?? inputs.packageName);
+	yield* probe.get({
+		kind: "object",
+		objectId: inputs.packageId
+	}, KnownObjectShape, "lenient").pipe(Effect.mapError(() => publishError("verify", {
+		sourcePath: `known:${inputs.packageId}`,
+		packageName: inputs.packageName,
+		message: "verify probe failed"
+	})));
+	const resolved = {
+		kind: "known",
+		name: inputs.packageName,
+		packageId: inputs.packageId,
+		upgradeCapId: inputs.upgradeCapId,
+		mvrPlaceholder
+	};
+	yield* registry.set(resolved.name, resolved);
+	return { resolved };
+});
+//#endregion
+export { acquireKnown };
+
+//# sourceMappingURL=mode-known.mjs.map

package/dist/plugins/package/mode-known.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-known.mjs","names":[],"sources":["../../../src/plugins/package/mode-known.ts"],"sourcesContent":["// Known mode — skip publish; load existing package id from on-chain.\n//\n// Distilled doc §Responsibilities + §Inputs/dependencies §KnownPackage-\n// only: a `KnownPackage` declares a fixed `packageId` (optionally\n// `upgradeCapId`, `mvrPlaceholder`) and threads through the same\n// registries as a freshly published one. No build, no publish-tx, no\n// cache key folding by content-hash — the id IS the identity.\n//\n// What we still do:\n//\n//   1. Lenient verify probe (chain reachable + object exists). On\n//      transient RPC failure, lenient mode masks → no abort. On\n//      authoritative not-found we surface a PublishError(phase='verify')\n//      so the user catches the typo / wrong-network mistake at boot.\n//   2. Register the resolved value on EVERY cycle.\n//\n// Bindings: KnownPackage cannot be bound by `@mysten/codegen` (no\n// source tree). The codegen contribution emitted for known packages\n// has `sourcePath: null`; the codegen orchestrator filters those\n// out before invoking the bindings emitter. The user-facing type\n// split (`localPackage` vs `knownPackage` factories) enforces this\n// at compose time per distilled doc Invariant 9.\n\nimport { Effect, Schema, type Scope } from 'effect';\n\nimport type { ChainProbe } from '../../contracts/chain-probe.ts';\nimport type { SuiProbeKey } from '../sui/chain-probe.ts';\nimport { mvrSlugify } from './dep-resolution.ts';\nimport { type PackageRegistry, type ResolvedKnownPackage } from './registry.ts';\nimport { publishError, type PublishError } from './errors.ts';\n\n/** Verify-schema for known mode — minimum signal: object exists at\n *  the given id. */\nconst KnownObjectShape = Schema.Struct({\n\tobjectId: Schema.String,\n});\n\nexport interface KnownModeInputs {\n\treadonly packageName: string;\n\treadonly packageId: string;\n\treadonly upgradeCapId?: string;\n\treadonly mvrOverride?: string;\n}\n\nexport interface KnownModeOutputs {\n\treadonly resolved: ResolvedKnownPackage;\n}\n\n/**\n * Acquire body for known mode.\n *\n * Runs the lenient ChainProbe verify and registers the resolved value.\n * Lenient mode masks transient RPC failure — the user-visible failure\n * here is \"object truly missing on this chain\". A `null` probe result\n * does not surface yet: distinguishing transient-vs-missing requires a\n * second strict probe layer that the ChainProbe primitive does not\n * expose.\n */\nexport const acquireKnown = (\n\tprobe: ChainProbe<SuiProbeKey>,\n\tregistry: PackageRegistry,\n\tinputs: KnownModeInputs,\n): Effect.Effect<KnownModeOutputs, PublishError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst mvrPlaceholder = mvrSlugify(inputs.mvrOverride ?? inputs.packageName);\n\n\t\tyield* probe\n\t\t\t.get({ kind: 'object', objectId: inputs.packageId }, KnownObjectShape, 'lenient')\n\t\t\t.pipe(\n\t\t\t\tEffect.mapError(\n\t\t\t\t\t(): PublishError =>\n\t\t\t\t\t\tpublishError('verify', {\n\t\t\t\t\t\t\tsourcePath: `known:${inputs.packageId}`,\n\t\t\t\t\t\t\tpackageName: inputs.packageName,\n\t\t\t\t\t\t\tmessage: 'verify probe failed',\n\t\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t);\n\n\t\tconst resolved: ResolvedKnownPackage = {\n\t\t\tkind: 'known',\n\t\t\tname: inputs.packageName,\n\t\t\tpackageId: inputs.packageId,\n\t\t\tupgradeCapId: inputs.upgradeCapId,\n\t\t\tmvrPlaceholder,\n\t\t};\n\n\t\t// Distilled doc Invariant 6: register on EVERY cycle (here\n\t\t// always — known mode has no \"miss\" branch).\n\t\tyield* registry.set(resolved.name, resolved);\n\n\t\treturn { resolved };\n\t});\n"],"mappings":";;;;;;AAiCA,MAAM,mBAAmB,OAAO,OAAO,EACtC,UAAU,OAAO,QACjB,CAAC;;;;;;;;;;;AAuBF,MAAa,gBACZ,OACA,UACA,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,iBAAiB,WAAW,OAAO,eAAe,OAAO,YAAY;AAE3E,QAAO,MACL,IAAI;EAAE,MAAM;EAAU,UAAU,OAAO;EAAW,EAAE,kBAAkB,UAAU,CAChF,KACA,OAAO,eAEL,aAAa,UAAU;EACtB,YAAY,SAAS,OAAO;EAC5B,aAAa,OAAO;EACpB,SAAS;EACT,CAAC,CACH,CACD;CAEF,MAAM,WAAiC;EACtC,MAAM;EACN,MAAM,OAAO;EACb,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB;EACA;AAID,QAAO,SAAS,IAAI,SAAS,MAAM,SAAS;AAE5C,QAAO,EAAE,UAAU;EAClB"}

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

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