@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/substrate/manifest.d.mts

@@ -1,10 +1,9 @@
 import { Effect, Schema } from "effect";
-import * as _$effect_Cause0 from "effect/Cause";
 
 //#region src/substrate/manifest.d.ts
 declare const ManifestExtrasInvalid_base: Schema.Class<ManifestExtrasInvalid, Schema.TaggedStruct<"ManifestExtrasInvalid", {
   readonly detail: Schema.String;
-}>, _$effect_Cause0.YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /** Tagged failure when a plugin's manifest-extras contribution does
  *  not resolve to a plain record. STYLE_GUIDE §2.2 — substrate (L0)
  *  errors use `Schema.TaggedErrorClass`; downstream classifiers
@@ -14,7 +13,7 @@ declare class ManifestExtrasInvalid extends ManifestExtrasInvalid_base {}
 declare const ManifestExtrasLookupError_base: Schema.Class<ManifestExtrasLookupError, Schema.TaggedStruct<"ManifestExtrasLookupError", {
   readonly kind: Schema.Literals<readonly ["unknown-resource", "unresolved-resource"]>;
   readonly resourceId: Schema.String;
-}>, _$effect_Cause0.YieldableError>;
+}>, import("effect/Cause").YieldableError>;
 /** Tagged failure when a plugin's `extras` factory references a
  *  resource the host cannot resolve — either the resource id is not
  *  registered with the supervisor, or it has not produced a value
@@ -25,36 +24,41 @@ declare const ManifestExtrasLookupError_base: Schema.Class<ManifestExtrasLookupE
  *  than die-cause inspection. */
 declare class ManifestExtrasLookupError extends ManifestExtrasLookupError_base {}
 /** Codegen metadata recorded per stack. The supervisor writes the
- *  resolved absolute output dir here at manifest-flush time so the
- *  read-side build integrations (the Vite plugin) point an `@generated`
- *  alias at the EXACT dir codegen emitted into for THIS stack — read
- *  and write share one decision (see
- *  `orchestrators/codegen/output-location.ts`). Optional + additive:
- *  manifests written before this field existed (and stacks that somehow
- *  flush without it) still decode; consumers fall back to
- *  `src/generated/`. */
+ *  dev-only `extrasDir` (the `@devstack-dev` overlay) and the live
+ *  `idsFile` (the gitignored `devstack-ids.json` injected as
+ *  `__DEVSTACK_IDS__`) here at manifest-flush time so the read-side
+ *  build integrations (the Vite plugin) consult the exact locations the
+ *  boot wrote — read and write share one decision. Bindings themselves
+ *  are NOT recorded here: the `@generated` alias always resolves to the
+ *  committed `src/generated` tree written by the stack-free `codegen`
+ *  verb. Optional + additive: manifests written before these fields
+ *  existed still decode; consumers fall back to their cold-start paths. */
 interface ManifestCodegen {
-  /** Absolute path to the directory codegen emitted into for this
-   *  stack (primary → `<appRoot>/src/generated`; secondary →
-   *  `<appRoot>/.devstack/stacks/<stack>/generated`). */
-  readonly generatedDir: string;
+  /** Absolute path to the dev-only + secret `generated-extras` tree
+   *  for this stack (`<appRoot>/.devstack/stacks/<stack>/generated-extras`).
+   *  The `@devstack-dev` Vite alias resolves here. Optional +
+   *  additive — older manifests omit it; the reader falls back to
+   *  `.devstack/stacks/<stack>/generated-extras`. */
+  readonly extrasDir?: string;
+  /** Absolute path to the gitignored `devstack-ids.json` the boot wrote
+   *  for this stack (the live on-chain ids). The Vite plugin reads it to
+   *  inject `__DEVSTACK_IDS__` in dev. Optional + additive. */
+  readonly idsFile?: string;
 }
-/** Manifest envelope. The `services` slot is open (`unknown`) at
- *  the envelope level; each plugin's Codegenable contribution
- *  emits a typed file the consumer imports for the typed shape.
- */
+/** Manifest envelope. */
 interface ManifestEnvelope {
   readonly identity: {
     readonly app: string;
     readonly stack: string;
-    readonly chain: string;
+    readonly network: string;
   };
   readonly manifestVersion: number;
-  readonly services: Readonly<Record<string, unknown>>;
+  /** Optional per-plugin service slot. The read-side build-integration API
+   *  surfaces `{}` when absent. */
+  readonly services?: Readonly<Record<string, unknown>>;
   readonly endpoints: Readonly<Record<string, EndpointEntry>>;
   readonly extras: Readonly<Record<string, unknown>>;
-  /** Per-stack codegen metadata. Optional — absent in older
-   *  manifests; the reader falls back to `src/generated/`. */
+  /** Per-stack codegen metadata. When absent, readers use `src/generated/`. */
   readonly codegen?: ManifestCodegen;
 }
 type ManifestExtras = Readonly<Record<string, unknown>>;
@@ -80,10 +84,10 @@ declare const ManifestEnvelopeSchema: Schema.Struct<{
   readonly identity: Schema.Struct<{
     readonly app: Schema.String;
     readonly stack: Schema.String;
-    readonly chain: Schema.String;
+    readonly network: Schema.String;
   }>;
   readonly manifestVersion: Schema.Number;
-  readonly services: Schema.$Record<Schema.String, Schema.Unknown>;
+  readonly services: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
   readonly endpoints: Schema.$Record<Schema.String, Schema.Struct<{
     readonly name: Schema.String;
     readonly url: Schema.String;
@@ -94,7 +98,10 @@ declare const ManifestEnvelopeSchema: Schema.Struct<{
   }>>;
   readonly extras: Schema.$Record<Schema.String, Schema.Unknown>;
   readonly codegen: Schema.optional<Schema.Struct<{
-    readonly generatedDir: Schema.String;
+    readonly extrasDir: Schema.optional<Schema.String>;
+    /** Absolute path to the gitignored `devstack-ids.json` the boot
+     *  wrote for this stack. The Vite plugin reads it in dev. */
+    readonly idsFile: Schema.optional<Schema.String>;
   }>>;
 }>;
 //#endregion

package/dist/substrate/manifest.mjs

@@ -37,10 +37,10 @@ const ManifestEnvelopeSchema = Schema.Struct({
 	identity: Schema.Struct({
 		app: Schema.String,
 		stack: Schema.String,
-		chain: Schema.String
+		network: Schema.String
 	}),
 	manifestVersion: Schema.Number,
-	services: Schema.Record(Schema.String, Schema.Unknown),
+	services: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
 	endpoints: Schema.Record(Schema.String, Schema.Struct({
 		name: Schema.String,
 		url: Schema.String,
@@ -54,7 +54,12 @@ const ManifestEnvelopeSchema = Schema.Struct({
 		endpointKey: Schema.String
 	})),
 	extras: Schema.Record(Schema.String, Schema.Unknown),
-	codegen: Schema.optional(Schema.Struct({ generatedDir: Schema.String }))
+	codegen: Schema.optional(Schema.Struct({
+		extrasDir: Schema.optional(Schema.String),
+		/** Absolute path to the gitignored `devstack-ids.json` the boot
+		*  wrote for this stack. The Vite plugin reads it in dev. */
+		idsFile: Schema.optional(Schema.String)
+	}))
 });
 //#endregion
 export { ManifestEnvelopeSchema, ManifestExtrasInvalid, ManifestExtrasLookupError, resolveManifestExtras };

package/dist/substrate/manifest.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.mjs","names":[],"sources":["../../src/substrate/manifest.ts"],"sourcesContent":["// Manifest envelope schema.\n//\n// Architecture § Manifest data model: envelope shape is fixed at L0,\n// per-service projection is each plugin's responsibility (lives in\n// the Codegenable contribution). Build integrations read the\n// envelope; codegen output carries the typed per-service slice.\n//\n// L0 owns:\n//   - the envelope (identity tuple, manifestVersion, services slot,\n//     endpoints lookup, opaque extras),\n//   - the endpoint-declaration shape (decl emitted by Routable; the\n//     manifest writer at L3 walks them).\n\nimport { Effect, Schema } from 'effect';\n\n/** Tagged failure when a plugin's manifest-extras contribution does\n *  not resolve to a plain record. STYLE_GUIDE §2.2 — substrate (L0)\n *  errors use `Schema.TaggedErrorClass`; downstream classifiers\n *  `catchTag('ManifestExtrasInvalid', ...)` instead of sniffing the\n *  message. */\nexport class ManifestExtrasInvalid extends Schema.TaggedErrorClass<ManifestExtrasInvalid>()(\n\t'ManifestExtrasInvalid',\n\t{\n\t\tdetail: Schema.String,\n\t},\n) {}\n\n/** Tagged failure when a plugin's `extras` factory references a\n *  resource the host cannot resolve — either the resource id is not\n *  registered with the supervisor, or it has not produced a value\n *  yet at the point the factory ran. Thrown synchronously from the\n *  user-supplied `ctx.value(...)` closure; `resolveManifestExtras`\n *  catches the throw and surfaces it as a typed failure so callers\n *  classify via `catchTag('ManifestExtrasLookupError', ...)` rather\n *  than die-cause inspection. */\nexport class ManifestExtrasLookupError extends Schema.TaggedErrorClass<ManifestExtrasLookupError>()(\n\t'ManifestExtrasLookupError',\n\t{\n\t\tkind: Schema.Literals(['unknown-resource', 'unresolved-resource']),\n\t\tresourceId: Schema.String,\n\t},\n) {}\n\n/** Codegen metadata recorded per stack. The supervisor writes the\n *  resolved absolute output dir here at manifest-flush time so the\n *  read-side build integrations (the Vite plugin) point an `@generated`\n *  alias at the EXACT dir codegen emitted into for THIS stack — read\n *  and write share one decision (see\n *  `orchestrators/codegen/output-location.ts`). Optional + additive:\n *  manifests written before this field existed (and stacks that somehow\n *  flush without it) still decode; consumers fall back to\n *  `src/generated/`. */\nexport interface ManifestCodegen {\n\t/** Absolute path to the directory codegen emitted into for this\n\t *  stack (primary → `<appRoot>/src/generated`; secondary →\n\t *  `<appRoot>/.devstack/stacks/<stack>/generated`). */\n\treadonly generatedDir: string;\n}\n\n/** Manifest envelope. The `services` slot is open (`unknown`) at\n *  the envelope level; each plugin's Codegenable contribution\n *  emits a typed file the consumer imports for the typed shape.\n */\nexport interface ManifestEnvelope {\n\treadonly identity: {\n\t\treadonly app: string;\n\t\treadonly stack: string;\n\t\treadonly chain: string;\n\t};\n\treadonly manifestVersion: number;\n\treadonly services: Readonly<Record<string, unknown>>;\n\treadonly endpoints: Readonly<Record<string, EndpointEntry>>;\n\treadonly extras: Readonly<Record<string, unknown>>;\n\t/** Per-stack codegen metadata. Optional — absent in older\n\t *  manifests; the reader falls back to `src/generated/`. */\n\treadonly codegen?: ManifestCodegen;\n}\n\nexport type ManifestExtras = Readonly<Record<string, unknown>>;\n\nexport interface ManifestExtrasContext {\n\treadonly value: (resource: { readonly id: string }) => unknown;\n}\n\nexport type ManifestExtrasInput =\n\t| ManifestExtras\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t| Effect.Effect<ManifestExtras, any, never>\n\t| ((\n\t\t\tctx: ManifestExtrasContext,\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t  ) => ManifestExtras | Effect.Effect<ManifestExtras, any, never>);\n\nconst isRecord = (value: unknown): value is ManifestExtras =>\n\ttypeof value === 'object' && value !== null && !Array.isArray(value);\n\nexport const resolveManifestExtras = (\n\tinput: ManifestExtrasInput | undefined,\n\tctx: ManifestExtrasContext,\n): Effect.Effect<ManifestExtras, ManifestExtrasInvalid | ManifestExtrasLookupError, never> =>\n\tEffect.gen(function* () {\n\t\tif (input === undefined) return {};\n\t\t// The user-supplied `extras` factory invokes `ctx.value(...)`\n\t\t// synchronously; a missing/unresolved resource throws a\n\t\t// `ManifestExtrasLookupError`. `Effect.try` with a typed\n\t\t// `catch` mapper promotes that throw into the typed failure\n\t\t// channel so callers `catchTag` it instead of having to inspect\n\t\t// the die-cause. Any non-tagged throw is rethrown to preserve\n\t\t// the existing defect semantics for genuine programmer errors\n\t\t// inside the factory body.\n\t\tconst resolvedEffect = Effect.isEffect(input)\n\t\t\t? input\n\t\t\t: typeof input === 'function'\n\t\t\t\t? Effect.try({\n\t\t\t\t\t\ttry: () => input(ctx),\n\t\t\t\t\t\tcatch: (cause) => {\n\t\t\t\t\t\t\tif (cause instanceof ManifestExtrasLookupError) return cause;\n\t\t\t\t\t\t\tthrow cause;\n\t\t\t\t\t\t},\n\t\t\t\t\t}).pipe(\n\t\t\t\t\t\tEffect.flatMap((value) => (Effect.isEffect(value) ? value : Effect.succeed(value))),\n\t\t\t\t\t)\n\t\t\t\t: Effect.succeed(input);\n\t\tconst resolved = yield* resolvedEffect;\n\t\tif (!isRecord(resolved)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew ManifestExtrasInvalid({\n\t\t\t\t\tdetail: 'manifest extras must resolve to a plain record',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\treturn resolved;\n\t});\n\n/** Flat endpoint entry — the manifest's load-bearing surface for\n *  build integrations. */\nexport interface EndpointEntry {\n\treadonly name: string;\n\treadonly url: string;\n\treadonly displayUrl: string | null;\n\treadonly wireProtocol: 'http' | 'h2c' | 'tcp';\n\treadonly pluginKey: string;\n\treadonly endpointKey: string;\n}\n\n/** Schema for runtime validation of an on-disk manifest. Build\n *  integrations decode through this on read. */\nexport const ManifestEnvelopeSchema = Schema.Struct({\n\tidentity: Schema.Struct({\n\t\tapp: Schema.String,\n\t\tstack: Schema.String,\n\t\tchain: Schema.String,\n\t}),\n\tmanifestVersion: Schema.Number,\n\tservices: Schema.Record(Schema.String, Schema.Unknown),\n\tendpoints: Schema.Record(\n\t\tSchema.String,\n\t\tSchema.Struct({\n\t\t\tname: Schema.String,\n\t\t\turl: Schema.String,\n\t\t\tdisplayUrl: Schema.NullOr(Schema.String),\n\t\t\twireProtocol: Schema.Literals(['http', 'h2c', 'tcp']),\n\t\t\tpluginKey: Schema.String,\n\t\t\tendpointKey: Schema.String,\n\t\t}),\n\t),\n\textras: Schema.Record(Schema.String, Schema.Unknown),\n\t// Optional + additive — a manifest written before this field\n\t// existed still decodes (the key is simply absent). The Vite plugin\n\t// reads `codegen.generatedDir` to point its `@generated` alias; on a\n\t// miss it falls back to `src/generated/`.\n\tcodegen: Schema.optional(\n\t\tSchema.Struct({\n\t\t\tgeneratedDir: Schema.String,\n\t\t}),\n\t),\n});\n"],"mappings":";;;;;;;AAoBA,IAAa,wBAAb,cAA2C,OAAO,kBAAyC,CAC1F,yBACA,EACC,QAAQ,OAAO,QACf,CACD,CAAC;;;;;;;;;AAUF,IAAa,4BAAb,cAA+C,OAAO,kBAA6C,CAClG,6BACA;CACC,MAAM,OAAO,SAAS,CAAC,oBAAoB,sBAAsB,CAAC;CAClE,YAAY,OAAO;CACnB,CACD,CAAC;AAoDF,MAAM,YAAY,UACjB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,MAAM;AAErE,MAAa,yBACZ,OACA,QAEA,OAAO,IAAI,aAAa;AACvB,KAAI,UAAU,KAAA,EAAW,QAAO,EAAE;CAsBlC,MAAM,WAAW,OAbM,OAAO,SAAS,MAAM,GAC1C,QACA,OAAO,UAAU,aAChB,OAAO,IAAI;EACX,WAAW,MAAM,IAAI;EACrB,QAAQ,UAAU;AACjB,OAAI,iBAAiB,0BAA2B,QAAO;AACvD,SAAM;;EAEP,CAAC,CAAC,KACF,OAAO,SAAS,UAAW,OAAO,SAAS,MAAM,GAAG,QAAQ,OAAO,QAAQ,MAAM,CAAE,CACnF,GACA,OAAO,QAAQ,MAAM;AAEzB,KAAI,CAAC,SAAS,SAAS,CACtB,QAAO,OAAO,OAAO,KACpB,IAAI,sBAAsB,EACzB,QAAQ,kDACR,CAAC,CACF;AAEF,QAAO;EACN;;;AAeH,MAAa,yBAAyB,OAAO,OAAO;CACnD,UAAU,OAAO,OAAO;EACvB,KAAK,OAAO;EACZ,OAAO,OAAO;EACd,OAAO,OAAO;EACd,CAAC;CACF,iBAAiB,OAAO;CACxB,UAAU,OAAO,OAAO,OAAO,QAAQ,OAAO,QAAQ;CACtD,WAAW,OAAO,OACjB,OAAO,QACP,OAAO,OAAO;EACb,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,YAAY,OAAO,OAAO,OAAO,OAAO;EACxC,cAAc,OAAO,SAAS;GAAC;GAAQ;GAAO;GAAM,CAAC;EACrD,WAAW,OAAO;EAClB,aAAa,OAAO;EACpB,CAAC,CACF;CACD,QAAQ,OAAO,OAAO,OAAO,QAAQ,OAAO,QAAQ;CAKpD,SAAS,OAAO,SACf,OAAO,OAAO,EACb,cAAc,OAAO,QACrB,CAAC,CACF;CACD,CAAC"}
+{"version":3,"file":"manifest.mjs","names":[],"sources":["../../src/substrate/manifest.ts"],"sourcesContent":["// Manifest envelope schema.\n//\n// Architecture § Manifest data model: envelope shape is fixed at L0,\n// per-service projection is each plugin's responsibility (lives in\n// the Codegenable contribution). Build integrations read the\n// envelope; codegen output carries the typed per-service slice.\n//\n// L0 owns:\n//   - the envelope (identity tuple, manifestVersion, endpoints lookup,\n//     opaque extras),\n//   - the endpoint-declaration shape (decl emitted by Routable; the\n//     manifest writer at L3 walks them).\n\nimport { Effect, Schema } from 'effect';\n\n/** Tagged failure when a plugin's manifest-extras contribution does\n *  not resolve to a plain record. STYLE_GUIDE §2.2 — substrate (L0)\n *  errors use `Schema.TaggedErrorClass`; downstream classifiers\n *  `catchTag('ManifestExtrasInvalid', ...)` instead of sniffing the\n *  message. */\nexport class ManifestExtrasInvalid extends Schema.TaggedErrorClass<ManifestExtrasInvalid>()(\n\t'ManifestExtrasInvalid',\n\t{\n\t\tdetail: Schema.String,\n\t},\n) {}\n\n/** Tagged failure when a plugin's `extras` factory references a\n *  resource the host cannot resolve — either the resource id is not\n *  registered with the supervisor, or it has not produced a value\n *  yet at the point the factory ran. Thrown synchronously from the\n *  user-supplied `ctx.value(...)` closure; `resolveManifestExtras`\n *  catches the throw and surfaces it as a typed failure so callers\n *  classify via `catchTag('ManifestExtrasLookupError', ...)` rather\n *  than die-cause inspection. */\nexport class ManifestExtrasLookupError extends Schema.TaggedErrorClass<ManifestExtrasLookupError>()(\n\t'ManifestExtrasLookupError',\n\t{\n\t\tkind: Schema.Literals(['unknown-resource', 'unresolved-resource']),\n\t\tresourceId: Schema.String,\n\t},\n) {}\n\n/** Codegen metadata recorded per stack. The supervisor writes the\n *  dev-only `extrasDir` (the `@devstack-dev` overlay) and the live\n *  `idsFile` (the gitignored `devstack-ids.json` injected as\n *  `__DEVSTACK_IDS__`) here at manifest-flush time so the read-side\n *  build integrations (the Vite plugin) consult the exact locations the\n *  boot wrote — read and write share one decision. Bindings themselves\n *  are NOT recorded here: the `@generated` alias always resolves to the\n *  committed `src/generated` tree written by the stack-free `codegen`\n *  verb. Optional + additive: manifests written before these fields\n *  existed still decode; consumers fall back to their cold-start paths. */\nexport interface ManifestCodegen {\n\t/** Absolute path to the dev-only + secret `generated-extras` tree\n\t *  for this stack (`<appRoot>/.devstack/stacks/<stack>/generated-extras`).\n\t *  The `@devstack-dev` Vite alias resolves here. Optional +\n\t *  additive — older manifests omit it; the reader falls back to\n\t *  `.devstack/stacks/<stack>/generated-extras`. */\n\treadonly extrasDir?: string;\n\t/** Absolute path to the gitignored `devstack-ids.json` the boot wrote\n\t *  for this stack (the live on-chain ids). The Vite plugin reads it to\n\t *  inject `__DEVSTACK_IDS__` in dev. Optional + additive. */\n\treadonly idsFile?: string;\n}\n\n/** Manifest envelope. */\nexport interface ManifestEnvelope {\n\treadonly identity: {\n\t\treadonly app: string;\n\t\treadonly stack: string;\n\t\treadonly network: string;\n\t};\n\treadonly manifestVersion: number;\n\t/** Optional per-plugin service slot. The read-side build-integration API\n\t *  surfaces `{}` when absent. */\n\treadonly services?: Readonly<Record<string, unknown>>;\n\treadonly endpoints: Readonly<Record<string, EndpointEntry>>;\n\treadonly extras: Readonly<Record<string, unknown>>;\n\t/** Per-stack codegen metadata. When absent, readers use `src/generated/`. */\n\treadonly codegen?: ManifestCodegen;\n}\n\nexport type ManifestExtras = Readonly<Record<string, unknown>>;\n\nexport interface ManifestExtrasContext {\n\treadonly value: (resource: { readonly id: string }) => unknown;\n}\n\nexport type ManifestExtrasInput =\n\t| ManifestExtras\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t| Effect.Effect<ManifestExtras, any, never>\n\t| ((\n\t\t\tctx: ManifestExtrasContext,\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t  ) => ManifestExtras | Effect.Effect<ManifestExtras, any, never>);\n\nconst isRecord = (value: unknown): value is ManifestExtras =>\n\ttypeof value === 'object' && value !== null && !Array.isArray(value);\n\nexport const resolveManifestExtras = (\n\tinput: ManifestExtrasInput | undefined,\n\tctx: ManifestExtrasContext,\n): Effect.Effect<ManifestExtras, ManifestExtrasInvalid | ManifestExtrasLookupError, never> =>\n\tEffect.gen(function* () {\n\t\tif (input === undefined) return {};\n\t\t// The user-supplied `extras` factory invokes `ctx.value(...)`\n\t\t// synchronously; a missing/unresolved resource throws a\n\t\t// `ManifestExtrasLookupError`. `Effect.try` with a typed\n\t\t// `catch` mapper promotes that throw into the typed failure\n\t\t// channel so callers `catchTag` it instead of having to inspect\n\t\t// the die-cause. Any non-tagged throw is rethrown to preserve\n\t\t// the existing defect semantics for genuine programmer errors\n\t\t// inside the factory body.\n\t\tconst resolvedEffect = Effect.isEffect(input)\n\t\t\t? input\n\t\t\t: typeof input === 'function'\n\t\t\t\t? Effect.try({\n\t\t\t\t\t\ttry: () => input(ctx),\n\t\t\t\t\t\tcatch: (cause) => {\n\t\t\t\t\t\t\tif (cause instanceof ManifestExtrasLookupError) return cause;\n\t\t\t\t\t\t\tthrow cause;\n\t\t\t\t\t\t},\n\t\t\t\t\t}).pipe(\n\t\t\t\t\t\tEffect.flatMap((value) => (Effect.isEffect(value) ? value : Effect.succeed(value))),\n\t\t\t\t\t)\n\t\t\t\t: Effect.succeed(input);\n\t\tconst resolved = yield* resolvedEffect;\n\t\tif (!isRecord(resolved)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew ManifestExtrasInvalid({\n\t\t\t\t\tdetail: 'manifest extras must resolve to a plain record',\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\treturn resolved;\n\t});\n\n/** Flat endpoint entry — the manifest's load-bearing surface for\n *  build integrations. */\nexport interface EndpointEntry {\n\treadonly name: string;\n\treadonly url: string;\n\treadonly displayUrl: string | null;\n\treadonly wireProtocol: 'http' | 'h2c' | 'tcp';\n\treadonly pluginKey: string;\n\treadonly endpointKey: string;\n}\n\n/** Schema for runtime validation of an on-disk manifest. Build\n *  integrations decode through this on read. */\nexport const ManifestEnvelopeSchema = Schema.Struct({\n\tidentity: Schema.Struct({\n\t\tapp: Schema.String,\n\t\tstack: Schema.String,\n\t\tnetwork: Schema.String,\n\t}),\n\tmanifestVersion: Schema.Number,\n\t// Optional service map for read-side integrations.\n\tservices: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),\n\tendpoints: Schema.Record(\n\t\tSchema.String,\n\t\tSchema.Struct({\n\t\t\tname: Schema.String,\n\t\t\turl: Schema.String,\n\t\t\tdisplayUrl: Schema.NullOr(Schema.String),\n\t\t\twireProtocol: Schema.Literals(['http', 'h2c', 'tcp']),\n\t\t\tpluginKey: Schema.String,\n\t\t\tendpointKey: Schema.String,\n\t\t}),\n\t),\n\textras: Schema.Record(Schema.String, Schema.Unknown),\n\t// Optional codegen metadata. The Vite plugin reads\n\t// `codegen.extrasDir` to point its `@devstack-dev` overlay alias and\n\t// `codegen.idsFile` to inject the live on-chain ids via\n\t// `__DEVSTACK_IDS__`; on a miss it falls back to the cold-start\n\t// `generated-extras` path and `__DEVSTACK_IDS__ = null`. Bindings are\n\t// not recorded here — `@generated` always resolves to the committed\n\t// `src/generated` tree.\n\tcodegen: Schema.optional(\n\t\tSchema.Struct({\n\t\t\textrasDir: Schema.optional(Schema.String),\n\t\t\t/** Absolute path to the gitignored `devstack-ids.json` the boot\n\t\t\t *  wrote for this stack. The Vite plugin reads it in dev. */\n\t\t\tidsFile: Schema.optional(Schema.String),\n\t\t}),\n\t),\n});\n"],"mappings":";;;;;;;AAoBA,IAAa,wBAAb,cAA2C,OAAO,iBAAwC,CAAC,CAC1F,yBACA,EACC,QAAQ,OAAO,OAChB,CACD,CAAC,CAAC,CAAC;;;;;;;;;AAUH,IAAa,4BAAb,cAA+C,OAAO,iBAA4C,CAAC,CAClG,6BACA;CACC,MAAM,OAAO,SAAS,CAAC,oBAAoB,qBAAqB,CAAC;CACjE,YAAY,OAAO;AACpB,CACD,CAAC,CAAC,CAAC;AAyDH,MAAM,YAAY,UACjB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAEpE,MAAa,yBACZ,OACA,QAEA,OAAO,IAAI,aAAa;CACvB,IAAI,UAAU,KAAA,GAAW,OAAO,CAAC;CAsBjC,MAAM,WAAW,OAbM,OAAO,SAAS,KAAK,IACzC,QACA,OAAO,UAAU,aAChB,OAAO,IAAI;EACX,WAAW,MAAM,GAAG;EACpB,QAAQ,UAAU;GACjB,IAAI,iBAAiB,2BAA2B,OAAO;GACvD,MAAM;EACP;CACD,CAAC,CAAC,CAAC,KACF,OAAO,SAAS,UAAW,OAAO,SAAS,KAAK,IAAI,QAAQ,OAAO,QAAQ,KAAK,CAAE,CACnF,IACC,OAAO,QAAQ,KAAK;CAExB,IAAI,CAAC,SAAS,QAAQ,GACrB,OAAO,OAAO,OAAO,KACpB,IAAI,sBAAsB,EACzB,QAAQ,iDACT,CAAC,CACF;CAED,OAAO;AACR,CAAC;;;AAeF,MAAa,yBAAyB,OAAO,OAAO;CACnD,UAAU,OAAO,OAAO;EACvB,KAAK,OAAO;EACZ,OAAO,OAAO;EACd,SAAS,OAAO;CACjB,CAAC;CACD,iBAAiB,OAAO;CAExB,UAAU,OAAO,SAAS,OAAO,OAAO,OAAO,QAAQ,OAAO,OAAO,CAAC;CACtE,WAAW,OAAO,OACjB,OAAO,QACP,OAAO,OAAO;EACb,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,YAAY,OAAO,OAAO,OAAO,MAAM;EACvC,cAAc,OAAO,SAAS;GAAC;GAAQ;GAAO;EAAK,CAAC;EACpD,WAAW,OAAO;EAClB,aAAa,OAAO;CACrB,CAAC,CACF;CACA,QAAQ,OAAO,OAAO,OAAO,QAAQ,OAAO,OAAO;CAQnD,SAAS,OAAO,SACf,OAAO,OAAO;EACb,WAAW,OAAO,SAAS,OAAO,MAAM;;;EAGxC,SAAS,OAAO,SAAS,OAAO,MAAM;CACvC,CAAC,CACF;AACD,CAAC"}

package/dist/substrate/options.d.mts

@@ -1,5 +1,4 @@
 import { ManifestExtrasInput } from "./manifest.mjs";
-import { NetworkConfig } from "./network.mjs";
 
 //#region src/substrate/options.d.ts
 /** Options shape — all fields optional. Renderer choice
@@ -7,14 +6,44 @@ import { NetworkConfig } from "./network.mjs";
  *  defaults. */
 interface DevstackOptions {
   readonly stackName?: string;
-  readonly network?: NetworkConfig;
+  /** Substrate-opaque network pass-through. The substrate is name-blind
+   *  and never reads `.mode`/`.chain` off this — it forwards the value to
+   *  `engine.options.network` verbatim. The sui-plugin authoring surface
+   *  (`DevstackOptionsWith<Mode>` in `api/define-devstack-with.ts`)
+   *  narrows this to the sui-plugin `NetworkConfig<Mode>` for typed
+   *  mode-narrowing; the flat form accepts any value. */
+  readonly network?: unknown;
   readonly stateDir?: string;
   readonly codegen?: {
-    readonly outputDir?: string;
-    readonly stackSubdir?: string | null;
+    /** Forwarded verbatim to `@mysten/codegen`'s
+     *  `generateFromPackageSummary({ includePhantomTypeParameters })`.
+     *  Default `false` — `@mysten/codegen`'s own default.
+     *
+     *  Off, a struct whose type parameters are ALL phantom renders as a
+     *  plain `const X = new MoveStruct({ name: '...::X<phantom T>' })` —
+     *  the phantom placeholder is baked into `.name`, so the instance is
+     *  unusable as a concrete type tag. On, such structs render as
+     *  factory functions
+     *  (`export function X<T extends BcsType<any>>(...typeParameters: [T])`)
+     *  whose returned MoveStruct's `.name` interpolates the arguments'
+     *  names — phantom parameters become REQUIRED, and the instance's
+     *  `.name` is a fully-qualified, composable type tag
+     *  (`Pool(DBTC, DUSDC).name`).
+     *
+     *  NOTE: flipping this reshapes the generated code for phantom-only
+     *  structs from consts to factories, so call sites consuming those
+     *  bindings change. */
+    readonly includePhantomTypeParameters?: boolean;
   };
   readonly renderer?: 'tui' | 'plain' | 'silent';
   readonly extras?: ManifestExtrasInput;
+  /** Per-network options, keyed by the resolved network name. The
+   *  name-blind substrate forwards this verbatim — it never reads the
+   *  shape. The authoring surface (`api/define-devstack-with.ts`) narrows
+   *  it to typed per-network toggles, and the plugin-aware orchestrator
+   *  interprets it (`orchestrators/network-options.ts`
+   *  `resolveNetworkOptions`). Mirrors the opaque `network` field. */
+  readonly networkOptions?: Readonly<Record<string, unknown>>;
 }
 //#endregion
 export { DevstackOptions };

package/dist/substrate/plugin-ctx.d.mts

@@ -0,0 +1,70 @@
+import { CodegenableDecl } from "../contracts/codegenable.mjs";
+import { SnapshotableDecl } from "../contracts/snapshotable.mjs";
+import { RoutableDecl } from "../contracts/routable.mjs";
+import { StrategyContributorDecl } from "../contracts/strategy-contributor.mjs";
+import { ProjectionDecl } from "../contracts/projection.mjs";
+import { Context } from "effect";
+
+//#region src/substrate/plugin-ctx.d.ts
+/**
+ * The minimal typed plugin-authoring context. A plugin reaches it from
+ * `start` with `const ctx = yield* PluginContext` (the service tag
+ * below); the supervisor provides a per-plugin instance into `start`'s
+ * requirement channel.
+ *
+ * EXACTLY 5 keys (INV-5 — see file header). Do not add a 6th.
+ */
+interface PluginCtx {
+  /** Buffered: contribute the plugin's LIVE codegen decl to the codegen
+   *  orchestrator. Replayed in the supervisor frame after a successful
+   *  `start` (it carries post-acquire runtime state — resolved ids, rpc —
+   *  so it cannot be a static spec field; that is exactly why it is a
+   *  buffered verb). Since codegen was decoupled from boot this is the
+   *  LIVE half ONLY: at boot the orchestrator projects the decl into the
+   *  loadable id-config (`assembleIdConfig`) and, for dev-only decls,
+   *  writes the `generated-extras` tree (`emitExtras`) — it does NOT write
+   *  the committed `src/generated` tree. That committed, stack-free tree is
+   *  emitted separately by the `devstack codegen` verb from the plugin
+   *  spec's `staticCodegen` hook, derived from the SAME `ConfigBindingSet`.
+   *  Returns void (the orchestrator owns rendering). */
+  readonly codegen: <E extends string>(decl: CodegenableDecl<E>) => void;
+  /** Buffered: declare a routable endpoint for the router orchestrator.
+   *  Replayed in the supervisor frame after a successful `start`.
+   *  Returns VOID — no URL is echoed back to the plugin (the router
+   *  mints and publishes the endpoint event itself). */
+  readonly endpoint: (decl: RoutableDecl) => void;
+  /** Buffered: declare extra snapshot subtrees / managed containers /
+   *  identity-guard hooks for the snapshot orchestrator. Replayed in
+   *  the supervisor frame after a successful `start`. */
+  readonly snapshotExtra: (decl: SnapshotableDecl) => void;
+  /** Buffered: publish a name-blind projection event through the
+   *  projection sink. Replayed in the supervisor frame after a
+   *  successful `start`. */
+  readonly publish: (decl: ProjectionDecl) => void;
+  /** Strategy bus (write): contribute a strategy under a capability
+   *  key for a sibling to read via `StrategyRegistryService`. Registers
+   *  on the scope-local StrategyRegistry, publishes `strategy.registered`,
+   *  and arms a finalizer publishing `strategy.unregistered`. */
+  readonly provides: <K extends string, S>(decl: StrategyContributorDecl<K, S>) => void;
+}
+declare const PluginContext_base: Context.ServiceClass<PluginContext, "@devstack/substrate/PluginContext", PluginCtx>;
+/**
+ * Effect service tag carrying the per-plugin {@link PluginCtx}.
+ *
+ * A plugin's `start` body reaches its ctx with `const ctx = yield*
+ * PluginContext`. The supervisor builds a fresh per-plugin ctx (+ its
+ * replay buffer) in `runtime/supervisor/acquire-node.ts` and PROVIDES it
+ * into `start`'s requirement channel
+ * (`Effect.provideService(start(deps), PluginContext, ctx)`), so the tag
+ * is always satisfied for code the supervisor runs.
+ *
+ * This ambient requirement lives only in `start`'s R-channel; it does NOT
+ * surface in the public `Plugin<Id, Value, Needs>` contract (`Needs` is
+ * `dependsOn` only — see `plugin.ts`). Declaring it as a service rather
+ * than a `start` argument is what keeps `start` single-arg, restoring
+ * automatic `deps` inference.
+ */
+declare class PluginContext extends PluginContext_base {}
+//#endregion
+export { PluginContext, PluginCtx };
+//# sourceMappingURL=plugin-ctx.d.mts.map

package/dist/substrate/plugin-ctx.mjs

@@ -0,0 +1,66 @@
+import { Context } from "effect";
+//#region src/substrate/plugin-ctx.ts
+/**
+* The ONE shared contribution router. A plugin's `start` builds an ordered
+* (possibly conditional/variadic) list of {@link Contribution} decls and
+* feeds it here; this routes each decl to its matching `ctx` verb by its
+* `kind` discriminant, IN LIST ORDER:
+*
+*   snapshotable          → `ctx.snapshotExtra`
+*   codegenable           → `ctx.codegen`
+*   routable              → `ctx.endpoint`
+*   projection            → `ctx.publish`
+*   strategy-contributor  → `ctx.provides`
+*
+* This is the single exhaustive `switch` over the closed `Contribution`
+* union — replacing the per-plugin `build*`/`emit*` wrapper pairs that each
+* re-implemented this same routing. The supervisor mirrors this dispatch
+* when it REPLAYS the buffered decls (`acquire-node.ts`); the verbs simply
+* buffer here. For a fixed, unconditional set of decls a plugin may prefer
+* direct `ctx.*` calls — but any conditional or variadic emission should
+* route through this helper so the routing lives in exactly one place.
+*
+* Exhaustive: the `default` arm narrows `decl` to `never`, so adding a
+* sixth `Contribution` kind is a compile error here until handled.
+*/
+const emitContributions = (ctx, decls) => {
+	for (const decl of decls) switch (decl.kind) {
+		case "snapshotable":
+			ctx.snapshotExtra(decl);
+			break;
+		case "codegenable":
+			ctx.codegen(decl);
+			break;
+		case "routable":
+			ctx.endpoint(decl);
+			break;
+		case "projection":
+			ctx.publish(decl);
+			break;
+		case "strategy-contributor":
+			ctx.provides(decl);
+			break;
+		default:
+	}
+};
+/**
+* Effect service tag carrying the per-plugin {@link PluginCtx}.
+*
+* A plugin's `start` body reaches its ctx with `const ctx = yield*
+* PluginContext`. The supervisor builds a fresh per-plugin ctx (+ its
+* replay buffer) in `runtime/supervisor/acquire-node.ts` and PROVIDES it
+* into `start`'s requirement channel
+* (`Effect.provideService(start(deps), PluginContext, ctx)`), so the tag
+* is always satisfied for code the supervisor runs.
+*
+* This ambient requirement lives only in `start`'s R-channel; it does NOT
+* surface in the public `Plugin<Id, Value, Needs>` contract (`Needs` is
+* `dependsOn` only — see `plugin.ts`). Declaring it as a service rather
+* than a `start` argument is what keeps `start` single-arg, restoring
+* automatic `deps` inference.
+*/
+var PluginContext = class extends Context.Service()("@devstack/substrate/PluginContext") {};
+//#endregion
+export { PluginContext, emitContributions };
+
+//# sourceMappingURL=plugin-ctx.mjs.map

package/dist/substrate/plugin-ctx.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-ctx.mjs","names":[],"sources":["../../src/substrate/plugin-ctx.ts"],"sourcesContent":["// PluginCtx — the minimal, closed, typed plugin-authoring surface.\n//\n// A plugin contributes to the stack through inline typed verbs it calls\n// from `start`. The plugin reaches this `ctx` by `yield* PluginContext` (an Effect\n// service tag, declared at the bottom of this file) — exactly like any\n// other substrate service it `yield*`s (`ContainerRuntimeService`,\n// `IdentityContext`, …). The supervisor PROVIDES a freshly-built\n// per-plugin ctx into `start`'s requirement (R) channel via\n// `Effect.provideService(start(deps), PluginContext, ctx)`. Delivering\n// ctx through the requirement channel — rather than as a 2nd positional\n// `start` argument — keeps `start` SINGLE-arg, which restores automatic\n// contextual typing of `deps` (no per-plugin `deps:` annotations), while\n// `ctx` stays always-present (the supervisor never omits it).\n//\n// -----------------------------------------------------------------------------\n// INV-5 — the closed 5-key set\n// -----------------------------------------------------------------------------\n//\n// `PluginCtx` has EXACTLY these 5 readonly keys and no more:\n//\n//   codegen · endpoint · snapshotExtra · publish · provides\n//\n// This is a HARD invariant (pinned by `plugin-ctx-keyset.test-d.ts`).\n// Growing the set re-builds a god-object surface. The rule for what may\n// live here:\n//\n//   - `codegen` / `endpoint` / `snapshotExtra` / `publish` are the four\n//     BUFFERED declarative verbs. Their backing services\n//     (CodegenOrchestratorService, RouterService +\n//     ManifestEndpointRegistryService, SnapshotOrchestratorService, the\n//     projection sink) are SUPERVISOR-FRAME-ONLY — they are absent from\n//     plugin scope. A verb call therefore cannot run its backing\n//     service inline; it pushes a typed buffer entry that the supervisor\n//     REPLAYS in its own frame after the plugin's `start` succeeds.\n//   - `provides` is the strategy bus writer (the faucet pattern\n//     generalized): a plugin contributes to a sibling's\n//     capability-keyed registry without a dep-graph edge. Siblings READ\n//     it with `yield* StrategyRegistryService` directly (no ctx verb).\n//\n// What stays OUT of `ctx`, and WHY: every other substrate service a\n// plugin needs is already in plugin scope and is reached with\n// `yield* Service` directly — `CacheService` (whose `.publish` is the\n// folded-in artifact-publisher cycle),\n// `ContainerRuntimeService`, `IdentityContext`,\n// `PortBrokerService`, `LeaseBrokerService`, etc. The infra\n// orchestrators that are NOT in plugin scope\n// (Snapshot/Codegen/Router/ManifestEndpoint) are precisely the four\n// buffered verbs above — and infra contributions stay `yield*`-shaped\n// declarations, NEVER imperative `ctx.tx`-style Sui leaks. Adding a\n// service to `ctx` that a plugin could already `yield*` is the drift\n// INV-5 forbids.\n\nimport { Context } from 'effect';\n\nimport type { CodegenableDecl } from '../contracts/codegenable.ts';\nimport type { ProjectionDecl } from '../contracts/projection.ts';\nimport type { RoutableDecl } from '../contracts/routable.ts';\nimport type { SnapshotableDecl } from '../contracts/snapshotable.ts';\nimport type { StrategyContributorDecl } from '../contracts/strategy-contributor.ts';\n\n/**\n * The CLOSED union of contribution decls a plugin emits via the four\n * buffered verbs + `provides`. Discriminated by `kind`. A plugin's `start`\n * emits these inline — either by direct `ctx.*` verb calls or, for a\n * conditional/variadic set, through the shared {@link emitContributions}\n * router below. The supervisor's static dispatch switches over exactly\n * these five kinds.\n */\nexport type Contribution =\n\t| CodegenableDecl<string>\n\t| RoutableDecl\n\t| SnapshotableDecl\n\t| ProjectionDecl\n\t| StrategyContributorDecl<string, unknown>;\n\n/**\n * The ONE shared contribution router. A plugin's `start` builds an ordered\n * (possibly conditional/variadic) list of {@link Contribution} decls and\n * feeds it here; this routes each decl to its matching `ctx` verb by its\n * `kind` discriminant, IN LIST ORDER:\n *\n *   snapshotable          → `ctx.snapshotExtra`\n *   codegenable           → `ctx.codegen`\n *   routable              → `ctx.endpoint`\n *   projection            → `ctx.publish`\n *   strategy-contributor  → `ctx.provides`\n *\n * This is the single exhaustive `switch` over the closed `Contribution`\n * union — replacing the per-plugin `build*`/`emit*` wrapper pairs that each\n * re-implemented this same routing. The supervisor mirrors this dispatch\n * when it REPLAYS the buffered decls (`acquire-node.ts`); the verbs simply\n * buffer here. For a fixed, unconditional set of decls a plugin may prefer\n * direct `ctx.*` calls — but any conditional or variadic emission should\n * route through this helper so the routing lives in exactly one place.\n *\n * Exhaustive: the `default` arm narrows `decl` to `never`, so adding a\n * sixth `Contribution` kind is a compile error here until handled.\n */\nexport const emitContributions = (ctx: PluginCtx, decls: ReadonlyArray<Contribution>): void => {\n\tfor (const decl of decls) {\n\t\tswitch (decl.kind) {\n\t\t\tcase 'snapshotable':\n\t\t\t\tctx.snapshotExtra(decl);\n\t\t\t\tbreak;\n\t\t\tcase 'codegenable':\n\t\t\t\tctx.codegen(decl);\n\t\t\t\tbreak;\n\t\t\tcase 'routable':\n\t\t\t\tctx.endpoint(decl);\n\t\t\t\tbreak;\n\t\t\tcase 'projection':\n\t\t\t\tctx.publish(decl);\n\t\t\t\tbreak;\n\t\t\tcase 'strategy-contributor':\n\t\t\t\tctx.provides(decl);\n\t\t\t\tbreak;\n\t\t\tdefault: {\n\t\t\t\tconst _exhaustive: never = decl;\n\t\t\t\tvoid _exhaustive;\n\t\t\t}\n\t\t}\n\t}\n};\n\n/**\n * The minimal typed plugin-authoring context. A plugin reaches it from\n * `start` with `const ctx = yield* PluginContext` (the service tag\n * below); the supervisor provides a per-plugin instance into `start`'s\n * requirement channel.\n *\n * EXACTLY 5 keys (INV-5 — see file header). Do not add a 6th.\n */\nexport interface PluginCtx {\n\t/** Buffered: contribute the plugin's LIVE codegen decl to the codegen\n\t *  orchestrator. Replayed in the supervisor frame after a successful\n\t *  `start` (it carries post-acquire runtime state — resolved ids, rpc —\n\t *  so it cannot be a static spec field; that is exactly why it is a\n\t *  buffered verb). Since codegen was decoupled from boot this is the\n\t *  LIVE half ONLY: at boot the orchestrator projects the decl into the\n\t *  loadable id-config (`assembleIdConfig`) and, for dev-only decls,\n\t *  writes the `generated-extras` tree (`emitExtras`) — it does NOT write\n\t *  the committed `src/generated` tree. That committed, stack-free tree is\n\t *  emitted separately by the `devstack codegen` verb from the plugin\n\t *  spec's `staticCodegen` hook, derived from the SAME `ConfigBindingSet`.\n\t *  Returns void (the orchestrator owns rendering). */\n\treadonly codegen: <E extends string>(decl: CodegenableDecl<E>) => void;\n\t/** Buffered: declare a routable endpoint for the router orchestrator.\n\t *  Replayed in the supervisor frame after a successful `start`.\n\t *  Returns VOID — no URL is echoed back to the plugin (the router\n\t *  mints and publishes the endpoint event itself). */\n\treadonly endpoint: (decl: RoutableDecl) => void;\n\t/** Buffered: declare extra snapshot subtrees / managed containers /\n\t *  identity-guard hooks for the snapshot orchestrator. Replayed in\n\t *  the supervisor frame after a successful `start`. */\n\treadonly snapshotExtra: (decl: SnapshotableDecl) => void;\n\t/** Buffered: publish a name-blind projection event through the\n\t *  projection sink. Replayed in the supervisor frame after a\n\t *  successful `start`. */\n\treadonly publish: (decl: ProjectionDecl) => void;\n\t/** Strategy bus (write): contribute a strategy under a capability\n\t *  key for a sibling to read via `StrategyRegistryService`. Registers\n\t *  on the scope-local StrategyRegistry, publishes `strategy.registered`,\n\t *  and arms a finalizer publishing `strategy.unregistered`. */\n\treadonly provides: <K extends string, S>(decl: StrategyContributorDecl<K, S>) => void;\n}\n\n/**\n * Effect service tag carrying the per-plugin {@link PluginCtx}.\n *\n * A plugin's `start` body reaches its ctx with `const ctx = yield*\n * PluginContext`. The supervisor builds a fresh per-plugin ctx (+ its\n * replay buffer) in `runtime/supervisor/acquire-node.ts` and PROVIDES it\n * into `start`'s requirement channel\n * (`Effect.provideService(start(deps), PluginContext, ctx)`), so the tag\n * is always satisfied for code the supervisor runs.\n *\n * This ambient requirement lives only in `start`'s R-channel; it does NOT\n * surface in the public `Plugin<Id, Value, Needs>` contract (`Needs` is\n * `dependsOn` only — see `plugin.ts`). Declaring it as a service rather\n * than a `start` argument is what keeps `start` single-arg, restoring\n * automatic `deps` inference.\n */\nexport class PluginContext extends Context.Service<PluginContext, PluginCtx>()(\n\t'@devstack/substrate/PluginContext',\n) {}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAkGA,MAAa,qBAAqB,KAAgB,UAA6C;CAC9F,KAAK,MAAM,QAAQ,OAClB,QAAQ,KAAK,MAAb;EACC,KAAK;GACJ,IAAI,cAAc,IAAI;GACtB;EACD,KAAK;GACJ,IAAI,QAAQ,IAAI;GAChB;EACD,KAAK;GACJ,IAAI,SAAS,IAAI;GACjB;EACD,KAAK;GACJ,IAAI,QAAQ,IAAI;GAChB;EACD,KAAK;GACJ,IAAI,SAAS,IAAI;GACjB;EACD;CAID;AAEF;;;;;;;;;;;;;;;;;AA4DA,IAAa,gBAAb,cAAmC,QAAQ,QAAkC,CAAC,CAC7E,mCACD,CAAC,CAAC,CAAC"}

package/dist/substrate/plugin.d.mts

@@ -1,8 +1,7 @@
-import { ChainId, PluginKey } from "./brand.mjs";
+import { PluginKey } from "./brand.mjs";
 import { PluginRole } from "./lifecycle.mjs";
 import { RowSection } from "./projection.mjs";
-import { CapabilityDecl } from "../contracts/capability-decl.mjs";
-import { Identity } from "./identity.mjs";
+import { StaticCodegenSource } from "../contracts/codegenable.mjs";
 import { Effect } from "effect";
 
 //#region src/substrate/plugin.d.ts
@@ -25,38 +24,28 @@ type DependencyList<Input> = Input extends readonly AnyResourceRef[] ? Input : I
 type ResolvedDependencyList<Dependencies extends readonly AnyResourceRef[]> = readonly [...{ readonly [K in keyof Dependencies]: Dependencies[K] extends AnyResourceRef ? ResourceValueOf<Dependencies[K]> : never }];
 type ResolvedDependencyObject<Dependencies extends Readonly<Record<string, AnyResourceRef>>> = { readonly [K in keyof Dependencies]: Dependencies[K] extends AnyResourceRef ? ResourceValueOf<Dependencies[K]> : never };
 type ResolvedDependencies<Input> = Input extends undefined ? undefined : Input extends readonly AnyResourceRef[] ? ResolvedDependencyList<Input> : Input extends AnyResourceRef ? ResourceValueOf<Input> : Input extends Readonly<Record<string, AnyResourceRef>> ? ResolvedDependencyObject<Input> : never;
-type AnyPluginStart = (...args: any[]) => Effect.Effect<unknown, unknown, unknown>;
+type AnyPluginStart = (deps: never) => Effect.Effect<unknown, unknown, unknown>;
 type PluginStart<Deps> = [Deps] extends [undefined] ? () => Effect.Effect<unknown, unknown, unknown> : (deps: Deps) => Effect.Effect<unknown, unknown, unknown>;
-type StartValue<Start> = Start extends ((...args: any[]) => Effect.Effect<infer Value, unknown, unknown>) ? Value : never;
-interface PluginErrorContribution {
-  readonly _tag: 'PluginErrorContribution';
-  readonly errorTags: ReadonlyArray<string>;
-  readonly formatter?: (value: {
-    readonly _tag: string;
-  } & Readonly<Record<string, unknown>>, recurse: (inner: unknown) => string) => string | null;
-}
+type StartValue<Start> = Start extends ((deps: any) => Effect.Effect<infer Value, unknown, unknown>) ? Value : never;
 interface WatchDecl {
   readonly paths: ReadonlyArray<string>;
   readonly cascade?: boolean;
 }
-interface AcquireContext {
-  readonly identity: Identity;
-  readonly chain: ChainId;
-  readonly runtimeRoot: string;
+interface StaticNodeInputContribution {
+  readonly kind: 'static';
+  readonly value: unknown;
+}
+interface ComputedNodeInputContribution {
+  readonly kind: 'computed';
+  readonly compute: () => Effect.Effect<unknown, unknown, never>;
 }
-type CapabilitiesFactory<Caps extends ReadonlyArray<CapabilityDecl>, Resolved> = (resolved: Resolved, ctx: AcquireContext) => Caps;
-type CapabilitySource<Value, Caps extends ReadonlyArray<CapabilityDecl>> = Caps | ((ctx: {
-  readonly value: Value;
-  readonly runtime: AcquireContext;
-}) => Caps);
-interface PluginSpecBase<Id extends string, Start extends AnyPluginStart, Caps extends ReadonlyArray<CapabilityDecl>> {
+type NodeInputContribution = StaticNodeInputContribution | ComputedNodeInputContribution;
+interface PluginSpecBase<Id extends string, Start extends AnyPluginStart> {
   readonly id: Id;
   readonly role: PluginRole;
   readonly pluginKey?: PluginKey | string;
   readonly watch?: WatchDecl;
   readonly start: Start;
-  readonly capabilities?: CapabilitySource<StartValue<Start>, Caps>;
-  readonly errorContributions?: ReadonlyArray<PluginErrorContribution>;
   /** Dashboard section bucket the plugin's rows belong to. Required so
    *  the renderer never has to pattern-match on plugin name substrings
    *  to compute it. The supervisor stamps this onto every row at
@@ -67,11 +56,29 @@ interface PluginSpecBase<Id extends string, Start extends AnyPluginStart, Caps e
    *  `endpointSection` instead of `section`. Use sparingly — the
    *  default is for the plugin's normal `section` to apply uniformly. */
   readonly endpointSection?: RowSection;
+  /** When `true`, a live snapshot-restore re-acquire leaves this plugin
+   *  running instead of draining it. Reserved for operator-transport
+   *  plugins that carry no restorable chain state and would tear down the
+   *  very connection a restore is answering on if drained. Substrate's
+   *  restore planner filters on this flag with NO knowledge of which
+   *  plugins set it. Full restart (`stack.restart` / CLI) drains
+   *  everything regardless. */
+  readonly keepAliveOnRestore?: true;
+  /** Desired-state inputs folded into this node's substrate input id.
+   *  Dependencies' node input ids are included automatically; this field is
+   *  for inputs owned by the node itself, including file hashes. */
+  readonly inputIdentity?: NodeInputContribution;
+  /** Stack-free codegen-decl source. When present, the `codegen` verb can
+   *  emit this plugin's committed-projection contributions from config
+   *  alone (no live acquire), drawing on-chain ids from the supplied
+   *  resolver. Plugins whose contributions need live resolution — or which
+   *  only land in the gitignored dev tree — omit it. */
+  readonly staticCodegen?: StaticCodegenSource;
 }
-type PluginSpec<Id extends string, DependsOn extends DependencyInput | undefined, Start extends AnyPluginStart, Caps extends ReadonlyArray<CapabilityDecl>> = PluginSpecBase<Id, Start, Caps> & {
+type PluginSpec<Id extends string, DependsOn extends DependencyInput | undefined, Start extends AnyPluginStart> = PluginSpecBase<Id, Start> & {
   readonly dependsOn?: DependsOn;
 };
-interface Plugin<Id extends string, Value, Needs extends readonly AnyResourceRef[], Caps extends ReadonlyArray<CapabilityDecl>> extends ResourceRef<Id, Value> {
+interface Plugin<Id extends string, Value, Needs extends readonly AnyResourceRef[]> extends ResourceRef<Id, Value> {
   readonly [pluginBrand]: true;
   readonly [dependencyInputBrand]: DependencyInput | undefined;
   readonly dependsOn: Needs;
@@ -79,24 +86,25 @@ interface Plugin<Id extends string, Value, Needs extends readonly AnyResourceRef
   readonly pluginKey?: PluginKey | string;
   readonly watch?: WatchDecl;
   readonly start: (deps: ResolvedDependencies<DependencyInput | undefined>) => Effect.Effect<Value, unknown, unknown>;
-  readonly capabilities?: Caps | CapabilitiesFactory<Caps, Value>;
-  readonly errorContributions?: ReadonlyArray<PluginErrorContribution>;
   readonly section: RowSection;
   readonly endpointSection?: RowSection;
+  readonly keepAliveOnRestore?: true;
+  readonly inputIdentity?: NodeInputContribution;
+  readonly staticCodegen?: StaticCodegenSource;
 }
-type AnyPlugin = Plugin<string, any, readonly AnyResourceRef[], ReadonlyArray<CapabilityDecl>>;
-declare function definePlugin<const Id extends string, const DependsOn extends readonly AnyResourceRef[], const Start extends PluginStart<ResolvedDependencyList<DependsOn>> = PluginStart<ResolvedDependencyList<DependsOn>>, const Caps extends ReadonlyArray<CapabilityDecl> = ReadonlyArray<CapabilityDecl>>(spec: PluginSpecBase<Id, Start, Caps> & {
+type AnyPlugin = Plugin<string, any, readonly AnyResourceRef[]>;
+declare function definePlugin<const Id extends string, const DependsOn extends readonly AnyResourceRef[], const Start extends AnyPluginStart = PluginStart<ResolvedDependencyList<DependsOn>>>(spec: PluginSpecBase<Id, Start> & {
   readonly dependsOn: DependsOn;
-}): Plugin<Id, StartValue<Start>, DependsOn, Caps>;
-declare function definePlugin<const Id extends string, const DependsOn extends Readonly<Record<string, AnyResourceRef>>, const Start extends PluginStart<ResolvedDependencyObject<DependsOn>> = PluginStart<ResolvedDependencyObject<DependsOn>>, const Caps extends ReadonlyArray<CapabilityDecl> = ReadonlyArray<CapabilityDecl>>(spec: PluginSpecBase<Id, Start, Caps> & {
+}): Plugin<Id, StartValue<Start>, DependsOn>;
+declare function definePlugin<const Id extends string, const DependsOn extends Readonly<Record<string, AnyResourceRef>>, const Start extends AnyPluginStart = PluginStart<ResolvedDependencyObject<DependsOn>>>(spec: PluginSpecBase<Id, Start> & {
   readonly dependsOn: DependsOn;
-}): Plugin<Id, StartValue<Start>, DependencyList<DependsOn>, Caps>;
-declare function definePlugin<const Id extends string, const DependsOn extends AnyResourceRef, const Start extends PluginStart<ResourceValueOf<DependsOn>> = PluginStart<ResourceValueOf<DependsOn>>, const Caps extends ReadonlyArray<CapabilityDecl> = ReadonlyArray<CapabilityDecl>>(spec: PluginSpecBase<Id, Start, Caps> & {
+}): Plugin<Id, StartValue<Start>, DependencyList<DependsOn>>;
+declare function definePlugin<const Id extends string, const DependsOn extends AnyResourceRef, const Start extends AnyPluginStart = PluginStart<ResourceValueOf<DependsOn>>>(spec: PluginSpecBase<Id, Start> & {
   readonly dependsOn: DependsOn;
-}): Plugin<Id, StartValue<Start>, readonly [DependsOn], Caps>;
-declare function definePlugin<const Id extends string, const Start extends PluginStart<undefined> = PluginStart<undefined>, const Caps extends ReadonlyArray<CapabilityDecl> = ReadonlyArray<CapabilityDecl>>(spec: PluginSpecBase<Id, Start, Caps> & {
+}): Plugin<Id, StartValue<Start>, readonly [DependsOn]>;
+declare function definePlugin<const Id extends string, const Start extends AnyPluginStart = PluginStart<undefined>>(spec: PluginSpecBase<Id, Start> & {
   readonly dependsOn?: undefined;
-}): Plugin<Id, StartValue<Start>, readonly [], Caps>;
+}): Plugin<Id, StartValue<Start>, readonly []>;
 type ProvidedIdsOf<Members> = Members extends ReadonlyArray<unknown> ? Members[number] extends {
   readonly id: infer Id extends string;
 } ? Id : never : never;
@@ -110,5 +118,5 @@ interface __MissingProvidersError<Missing extends string> {
   readonly __missing_providers: Missing;
 }
 //#endregion
-export { AnyPlugin, AnyResourceRef, CapabilitiesFactory, CapabilitySource, DependencyInput, DependencyList, MissingProviders, Plugin, PluginErrorContribution, PluginSpec, ResolvedDependencies, ResolvedDependencyList, ResolvedDependencyObject, ResourceIdOf, ResourceRef, ResourceValueOf, WatchDecl, __MissingProvidersError, defineId, definePlugin, resource };
+export { AnyPlugin, AnyResourceRef, DependencyInput, DependencyList, MissingProviders, NodeInputContribution, Plugin, PluginSpec, ResolvedDependencies, ResolvedDependencyList, ResolvedDependencyObject, ResourceIdOf, ResourceRef, ResourceValueOf, WatchDecl, __MissingProvidersError, defineId, definePlugin, resource };
 //# sourceMappingURL=plugin.d.mts.map

package/dist/substrate/plugin.mjs

@@ -8,6 +8,14 @@ const resource = (id) => ({
 	[resourceBrand]: true
 });
 const isResourceRef = (value) => typeof value === "object" && value !== null && value[resourceBrand] === true;
+const staticInputIdentity = (value) => ({
+	kind: "static",
+	value
+});
+const computedInputIdentity = (compute) => ({
+	kind: "computed",
+	compute
+});
 const isPlugin = (value) => typeof value === "object" && value !== null && value[pluginBrand] === true;
 const dependencyList = (dependsOn) => {
 	if (dependsOn === void 0) return [];
@@ -36,11 +44,6 @@ const resolvePluginDependencies = (plugin, read) => resolveDependencyValues(plug
 const pluginDependencyRefs = (plugin) => dependencyList(plugin[dependencyInputBrand]);
 function definePlugin(spec) {
 	const dependsOn = uniqueResourceRefs(dependencyList(spec.dependsOn));
-	const capabilitiesField = spec.capabilities;
-	const capabilities = typeof capabilitiesField === "function" ? (value, runtime) => capabilitiesField({
-		value,
-		runtime
-	}) : capabilitiesField;
 	return {
 		[resourceBrand]: true,
 		[pluginBrand]: true,
@@ -52,12 +55,13 @@ function definePlugin(spec) {
 		start: spec.start,
 		...spec.pluginKey === void 0 ? {} : { pluginKey: spec.pluginKey },
 		...spec.watch === void 0 ? {} : { watch: spec.watch },
-		...capabilities === void 0 ? {} : { capabilities },
-		...spec.errorContributions === void 0 ? {} : { errorContributions: spec.errorContributions },
-		...spec.endpointSection === void 0 ? {} : { endpointSection: spec.endpointSection }
+		...spec.endpointSection === void 0 ? {} : { endpointSection: spec.endpointSection },
+		...spec.keepAliveOnRestore === void 0 ? {} : { keepAliveOnRestore: spec.keepAliveOnRestore },
+		...spec.inputIdentity === void 0 ? {} : { inputIdentity: spec.inputIdentity },
+		...spec.staticCodegen === void 0 ? {} : { staticCodegen: spec.staticCodegen }
 	};
 }
 //#endregion
-export { defineId, definePlugin, dependencyList, isPlugin, isResourceRef, pluginDependencyRefs, resolveDependencyValues, resolvePluginDependencies, resource, uniqueResourceRefs };
+export { computedInputIdentity, defineId, definePlugin, dependencyList, isPlugin, isResourceRef, pluginDependencyRefs, resolveDependencyValues, resolvePluginDependencies, resource, staticInputIdentity, uniqueResourceRefs };
 
 //# sourceMappingURL=plugin.mjs.map