@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/plugins/package/registry.mjs

@@ -1,4 +1,5 @@
 import { defineScopedRefMap } from "../../substrate/runtime/scoped-ref-map/service.mjs";
+import "../../substrate/runtime/scoped-ref-map/index.mjs";
 import { Context, Effect, Layer } from "effect";
 //#region src/plugins/package/registry.ts
 const PackageRefMap = defineScopedRefMap("PackageRegistry");
@@ -11,7 +12,7 @@ const wrapRefMap = (refMap) => ({
 });
 /** Context.Service tag for the per-stack `PackageRegistry`. Plugins
 *  yield this in their acquire body. */
-var PackageRegistryService = class extends Context.Service()("@devstack-rewrite/plugins/package/PackageRegistry") {};
+var PackageRegistryService = class extends Context.Service()("@devstack/plugins/package/PackageRegistry") {};
 /** Scope-bound Layer materializing one `PackageRegistry` per stack
 *  scope. Boot wiring (CLI / e2e) provides this once per stack;
 *  every package/coin/wallet/faucet plugin in the stack yields the

package/dist/plugins/package/registry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"registry.mjs","names":[],"sources":["../../../src/plugins/package/registry.ts"],"sourcesContent":["// Per-stack PackageRegistry — owned by the L2 Package plugin.\n//\n// Architecture (ARCHITECTURE.md § Substrate name-blindness): the\n// substrate exposes ONLY the generic `defineScopedRefMap<K, V>` factory;\n// the package-domain shape (`ResolvedLocalPackage` / `ResolvedKnownPackage`)\n// lives here at L2 where it belongs. Two `localPackage(...)` calls in\n// the same stack see the same Service instance (one per stack scope),\n// so cross-plugin lookups stay consistent and warm-restart verify can\n// use the previously-resolved `packageId` as a hint.\n//\n// Wrapper-service pattern (STYLE_GUIDE §6 / \"L2 wrapper-service around\n// defineScopedRefMap\"): the module-private inner `PackageRefMap` is the\n// raw substrate primitive; the publicly-exported `PackageRegistryService`\n// is the L2 wrapper that the rest of the plugin (and external siblings)\n// yield. Today the wrapper only re-exposes the four substrate ops\n// (`set` / `find` / `has` / `entries` + `changes`), but the shape\n// matches Coin's wrapper so future plugin-specific lookups (e.g.\n// `byPublisher`, `byPackageId`) land in one place instead of every\n// consumer reaching into the raw map.\n\nimport { Context, Effect, Layer, type Stream } from 'effect';\n\nimport {\n\tdefineScopedRefMap,\n\ttype ScopedRefMap,\n} from '../../substrate/runtime/scoped-ref-map/index.ts';\n\n/** Resolved package handle for a local (built + published) package. */\nexport interface ResolvedLocalPackage {\n\treadonly kind: 'local';\n\treadonly name: string;\n\treadonly packageId: string;\n\treadonly upgradeCapId?: string;\n\treadonly sourcePath: string;\n\treadonly mvrPlaceholder: string;\n\t/** Captured object ids — keyed by user-declared name. */\n\treadonly captured: Readonly<Record<string, string>>;\n}\n\n/** Resolved package handle for a known (verify-only) package. */\nexport interface ResolvedKnownPackage {\n\treadonly kind: 'known';\n\treadonly name: string;\n\treadonly packageId: string;\n\treadonly upgradeCapId?: string;\n\treadonly mvrPlaceholder: string;\n}\n\nexport type ResolvedPackage = ResolvedLocalPackage | ResolvedKnownPackage;\n\n/** Registry key — the user-declared symbolic package name. Kept as a\n *  type alias (not a brand) because the same string flows verbatim\n *  through `localPackage(name, ...)` / `knownPackage(name, ...)` and\n *  out via `entries()` to consumers (codegen, snapshot identity). */\nexport type PackageKey = string;\n\n/** L2 wrapper shape — the operations exposed on `PackageRegistryService`.\n *  Today these are a 1:1 re-projection of the substrate primitive's\n *  generic `ScopedRefMap<K, V>`; future plugin-specific lookups land\n *  here without forcing every consumer to learn a new shape. */\nexport interface PackageRegistry {\n\treadonly set: (key: PackageKey, value: ResolvedPackage) => Effect.Effect<void>;\n\treadonly find: (key: PackageKey) => Effect.Effect<ResolvedPackage | null>;\n\treadonly has: (key: PackageKey) => Effect.Effect<boolean>;\n\treadonly entries: () => Effect.Effect<ReadonlyArray<readonly [PackageKey, ResolvedPackage]>>;\n\treadonly changes: Stream.Stream<ReadonlyArray<readonly [PackageKey, ResolvedPackage]>>;\n}\n\n// Module-private inner substrate primitive — instantiated once per\n// logical registry. The service identity is namespaced by the `name`\n// argument; substrate stays name-blind (it sees only `K` and `V`).\nconst PackageRefMap = defineScopedRefMap<PackageKey, ResolvedPackage>('PackageRegistry');\n\nconst wrapRefMap = (refMap: ScopedRefMap<PackageKey, ResolvedPackage>): PackageRegistry => ({\n\tset: refMap.set,\n\tfind: refMap.find,\n\thas: refMap.has,\n\tentries: refMap.entries,\n\tchanges: refMap.changes,\n});\n\n/** Context.Service tag for the per-stack `PackageRegistry`. Plugins\n *  yield this in their acquire body. */\nexport class PackageRegistryService extends Context.Service<\n\tPackageRegistryService,\n\tPackageRegistry\n>()('@devstack-rewrite/plugins/package/PackageRegistry') {}\n\n/** Scope-bound Layer materializing one `PackageRegistry` per stack\n *  scope. Boot wiring (CLI / e2e) provides this once per stack;\n *  every package/coin/wallet/faucet plugin in the stack yields the\n *  SAME instance via Context. */\nexport const layerPackageRegistry: Layer.Layer<PackageRegistryService> = Layer.effect(\n\tPackageRegistryService,\n\tEffect.gen(function* () {\n\t\tconst refMap = yield* PackageRefMap.Service;\n\t\treturn PackageRegistryService.of(wrapRefMap(refMap));\n\t}),\n).pipe(Layer.provide(PackageRefMap.layer));\n\n/** Capability-key constant for the per-stack registry — siblings\n *  (Coin, Action, manifest emitter, faucet strategies) look it up\n *  through the StrategyContributor registry. */\nexport const PACKAGE_REGISTRY_CAPABILITY_KEY = 'package-registry' as const;\n"],"mappings":";;;AAuEA,MAAM,gBAAgB,mBAAgD,kBAAkB;AAExF,MAAM,cAAc,YAAwE;CAC3F,KAAK,OAAO;CACZ,MAAM,OAAO;CACb,KAAK,OAAO;CACZ,SAAS,OAAO;CAChB,SAAS,OAAO;CAChB;;;AAID,IAAa,yBAAb,cAA4C,QAAQ,SAGjD,CAAC,oDAAoD,CAAC;;;;;AAMzD,MAAa,uBAA4D,MAAM,OAC9E,wBACA,OAAO,IAAI,aAAa;CACvB,MAAM,SAAS,OAAO,cAAc;AACpC,QAAO,uBAAuB,GAAG,WAAW,OAAO,CAAC;EACnD,CACF,CAAC,KAAK,MAAM,QAAQ,cAAc,MAAM,CAAC;;;;AAK1C,MAAa,kCAAkC"}
+{"version":3,"file":"registry.mjs","names":[],"sources":["../../../src/plugins/package/registry.ts"],"sourcesContent":["// Per-stack PackageRegistry — owned by the L2 Package plugin.\n//\n// Architecture (ARCHITECTURE.md § Substrate name-blindness): the\n// substrate exposes ONLY the generic `defineScopedRefMap<K, V>` factory;\n// the package-domain shape (`ResolvedLocalPackage` / `ResolvedKnownPackage`)\n// lives here at L2 where it belongs. Two `localPackage(...)` calls in\n// the same stack see the same Service instance (one per stack scope),\n// so cross-plugin lookups stay consistent and warm-restart verify can\n// use the previously-resolved `packageId` as a hint.\n//\n// Wrapper-service pattern (STYLE_GUIDE §6 / \"L2 wrapper-service around\n// defineScopedRefMap\"): the module-private inner `PackageRefMap` is the\n// raw substrate primitive; the publicly-exported `PackageRegistryService`\n// is the L2 wrapper that the rest of the plugin (and external siblings)\n// yield. Today the wrapper only re-exposes the four substrate ops\n// (`set` / `find` / `has` / `entries` + `changes`), but the shape\n// matches Coin's wrapper so future plugin-specific lookups (e.g.\n// `byPublisher`, `byPackageId`) land in one place instead of every\n// consumer reaching into the raw map.\n\nimport { Context, Effect, Layer, type Stream } from 'effect';\n\nimport {\n\tdefineScopedRefMap,\n\ttype ScopedRefMap,\n} from '../../substrate/runtime/scoped-ref-map/index.ts';\n\n/** Resolved package handle for a local (built + published) package. */\nexport interface ResolvedLocalPackage {\n\treadonly kind: 'local';\n\treadonly name: string;\n\treadonly packageId: string;\n\treadonly upgradeCapId?: string;\n\treadonly sourcePath: string;\n\treadonly mvrPlaceholder: string;\n\t/** Captured object ids — keyed by user-declared name. */\n\treadonly captured: Readonly<Record<string, string>>;\n}\n\n/** Resolved package handle for a known (verify-only) package. */\nexport interface ResolvedKnownPackage {\n\treadonly kind: 'known';\n\treadonly name: string;\n\treadonly packageId: string;\n\treadonly upgradeCapId?: string;\n\treadonly mvrPlaceholder: string;\n}\n\nexport type ResolvedPackage = ResolvedLocalPackage | ResolvedKnownPackage;\n\n/** Registry key — the user-declared symbolic package name. Kept as a\n *  type alias (not a brand) because the same string flows verbatim\n *  through `localPackage(name, ...)` / `knownPackage(name, ...)` and\n *  out via `entries()` to consumers (codegen, snapshot identity). */\nexport type PackageKey = string;\n\n/** L2 wrapper shape — the operations exposed on `PackageRegistryService`.\n *  Today these are a 1:1 re-projection of the substrate primitive's\n *  generic `ScopedRefMap<K, V>`; future plugin-specific lookups land\n *  here without forcing every consumer to learn a new shape. */\nexport interface PackageRegistry {\n\treadonly set: (key: PackageKey, value: ResolvedPackage) => Effect.Effect<void>;\n\treadonly find: (key: PackageKey) => Effect.Effect<ResolvedPackage | null>;\n\treadonly has: (key: PackageKey) => Effect.Effect<boolean>;\n\treadonly entries: () => Effect.Effect<ReadonlyArray<readonly [PackageKey, ResolvedPackage]>>;\n\treadonly changes: Stream.Stream<ReadonlyArray<readonly [PackageKey, ResolvedPackage]>>;\n}\n\n// Module-private inner substrate primitive — instantiated once per\n// logical registry. The service identity is namespaced by the `name`\n// argument; substrate stays name-blind (it sees only `K` and `V`).\nconst PackageRefMap = defineScopedRefMap<PackageKey, ResolvedPackage>('PackageRegistry');\n\nconst wrapRefMap = (refMap: ScopedRefMap<PackageKey, ResolvedPackage>): PackageRegistry => ({\n\tset: refMap.set,\n\tfind: refMap.find,\n\thas: refMap.has,\n\tentries: refMap.entries,\n\tchanges: refMap.changes,\n});\n\n/** Context.Service tag for the per-stack `PackageRegistry`. Plugins\n *  yield this in their acquire body. */\nexport class PackageRegistryService extends Context.Service<\n\tPackageRegistryService,\n\tPackageRegistry\n>()('@devstack/plugins/package/PackageRegistry') {}\n\n/** Scope-bound Layer materializing one `PackageRegistry` per stack\n *  scope. Boot wiring (CLI / e2e) provides this once per stack;\n *  every package/coin/wallet/faucet plugin in the stack yields the\n *  SAME instance via Context. */\nexport const layerPackageRegistry: Layer.Layer<PackageRegistryService> = Layer.effect(\n\tPackageRegistryService,\n\tEffect.gen(function* () {\n\t\tconst refMap = yield* PackageRefMap.Service;\n\t\treturn PackageRegistryService.of(wrapRefMap(refMap));\n\t}),\n).pipe(Layer.provide(PackageRefMap.layer));\n\n/** Capability-key constant for the per-stack registry — siblings\n *  (Coin, Action, manifest emitter, faucet strategies) look it up\n *  through the StrategyContributor registry. */\nexport const PACKAGE_REGISTRY_CAPABILITY_KEY = 'package-registry' as const;\n"],"mappings":";;;;AAuEA,MAAM,gBAAgB,mBAAgD,kBAAkB;AAExF,MAAM,cAAc,YAAwE;CAC3F,KAAK,OAAO;CACZ,MAAM,OAAO;CACb,KAAK,OAAO;CACZ,SAAS,OAAO;CAChB,SAAS,OAAO;CAChB;;;AAID,IAAa,yBAAb,cAA4C,QAAQ,SAGjD,CAAC,4CAA4C,CAAC;;;;;AAMjD,MAAa,uBAA4D,MAAM,OAC9E,wBACA,OAAO,IAAI,aAAa;CACvB,MAAM,SAAS,OAAO,cAAc;AACpC,QAAO,uBAAuB,GAAG,WAAW,OAAO,CAAC;EACnD,CACF,CAAC,KAAK,MAAM,QAAQ,cAAc,MAAM,CAAC;;;;AAK1C,MAAa,kCAAkC"}

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

@@ -1 +1 @@
-{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/package/service.ts"],"sourcesContent":["// Package plugin — main acquire body.\n//\n// Dispatch on `opts.mode` ∈ {local, known} and delegate to the\n// per-mode acquire. This file is INTENTIONALLY thin: the substrate\n// concerns (cache key, verify, produce, register) live inside the\n// ArtifactPublisher primitive; the toolchain concerns (build,\n// scrub) live in `build.ts`. We just route.\n//\n// Substrate dependencies arrive via `definePlugin({ dependsOn })`:\n//\n//   - suiResource           — resolved SuiClient + chainId\n//   - publisher account     — publisher address + sign-and-execute\n//\n// And via the StrategyContributor registry (by capability key):\n//\n//   - chain-probe:<chainId> — ChainProbe<SuiProbeKey>\n//   - artifact-publisher     — the ArtifactPublisher (substrate\n//                             primitive, available everywhere)\n//\n// And via the plugin-owned PackageRegistry service (instantiated from\n// the substrate's generic ScopedRefMap primitive — see `registry.ts`).\n//\n// The wiring of these lookups happens at the barrel (`index.ts`); this\n// file accepts them as parameters so it stays testable.\n\nimport { Effect, type Scope } from 'effect';\n\nimport type {\n\tArtifactPublishError,\n\tArtifactPublisher,\n} from '../../primitives/artifact-publisher.ts';\nimport type { ChainProbe } from '../../contracts/chain-probe.ts';\nimport type { SuiProbeKey } from '../sui/chain-probe.ts';\nimport { acquireKnown, type KnownModeInputs } from './mode-known.ts';\nimport { acquireLocal, type LocalModeInputs } from './mode-local.ts';\nimport type {\n\tPackageRegistry,\n\tResolvedKnownPackage,\n\tResolvedLocalPackage,\n\tResolvedPackage,\n} from './registry.ts';\nimport type { LocalPackagePublishOutput } from './publish-output.ts';\nimport type { PublishError } from './errors.ts';\n\n/** Discriminated mode union — mirrors the public factory shape\n *  (`localPackage(...)` and `knownPackage(...)`). The barrel\n *  constructs ONE of these per declared package and the body below\n *  routes. */\nexport type PackageMode =\n\t| ({ readonly mode: 'local' } & LocalModeInputs)\n\t| ({ readonly mode: 'known' } & KnownModeInputs);\n\nexport interface BootPackageResult {\n\treadonly resolved: ResolvedPackage;\n\t/** Fresh publish output — populated on cache MISS (the produce\n\t *  path ran), `null` on cache hit (verify path). Threaded out so\n\t *  the barrel can fan out coin auto-discovery (and any other\n\t *  output-consuming siblings) once per fresh publish.\n\t *\n\t *  Known mode never publishes, so this is always `null` there. */\n\treadonly output: LocalPackagePublishOutput | null;\n}\n\nexport interface BootLocalPackageResult {\n\treadonly resolved: ResolvedLocalPackage;\n\treadonly output: LocalPackagePublishOutput | null;\n}\n\nexport interface BootKnownPackageResult {\n\treadonly resolved: ResolvedKnownPackage;\n\treadonly output: null;\n}\n\n/** Dispatch on the typed mode. */\nexport function bootPackageService(\n\tpublisher: ArtifactPublisher,\n\tprobe: ChainProbe<SuiProbeKey>,\n\tregistry: PackageRegistry,\n\topts: { readonly mode: 'local' } & LocalModeInputs,\n): Effect.Effect<BootLocalPackageResult, PublishError | ArtifactPublishError, Scope.Scope>;\nexport function bootPackageService(\n\tpublisher: ArtifactPublisher,\n\tprobe: ChainProbe<SuiProbeKey>,\n\tregistry: PackageRegistry,\n\topts: { readonly mode: 'known' } & KnownModeInputs,\n): Effect.Effect<BootKnownPackageResult, PublishError | ArtifactPublishError, Scope.Scope>;\nexport function bootPackageService(\n\tpublisher: ArtifactPublisher,\n\tprobe: ChainProbe<SuiProbeKey>,\n\tregistry: PackageRegistry,\n\topts: PackageMode,\n): Effect.Effect<BootPackageResult, PublishError | ArtifactPublishError, Scope.Scope> {\n\tswitch (opts.mode) {\n\t\tcase 'local':\n\t\t\treturn acquireLocal(publisher, probe, registry, opts).pipe(\n\t\t\t\tEffect.map(({ resolved, output }) => ({ resolved, output })),\n\t\t\t);\n\t\tcase 'known':\n\t\t\treturn acquireKnown(probe, registry, opts).pipe(\n\t\t\t\tEffect.map(({ resolved }) => ({ resolved, output: null })),\n\t\t\t);\n\t}\n}\n"],"mappings":";;;;AAsFA,SAAgB,mBACf,WACA,OACA,UACA,MACqF;AACrF,SAAQ,KAAK,MAAb;EACC,KAAK,QACJ,QAAO,aAAa,WAAW,OAAO,UAAU,KAAK,CAAC,KACrD,OAAO,KAAK,EAAE,UAAU,cAAc;GAAE;GAAU;GAAQ,EAAE,CAC5D;EACF,KAAK,QACJ,QAAO,aAAa,OAAO,UAAU,KAAK,CAAC,KAC1C,OAAO,KAAK,EAAE,gBAAgB;GAAE;GAAU,QAAQ;GAAM,EAAE,CAC1D"}
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/package/service.ts"],"sourcesContent":["// Package plugin — main acquire body.\n//\n// Dispatch on `opts.mode` ∈ {local, known} and delegate to the\n// per-mode acquire. This file is INTENTIONALLY thin: the substrate\n// concerns (cache key, verify, produce, register) live inside the\n// ArtifactPublisher primitive; the toolchain concerns (build,\n// scrub) live in `build.ts`. We just route.\n//\n// Substrate dependencies arrive via `definePlugin({ dependsOn })`:\n//\n//   - suiResource           — resolved SuiClient + chainId\n//   - publisher account     — publisher address + sign-and-execute\n//\n// And via the StrategyContributor registry (by capability key):\n//\n//   - chain-probe:<chainId> — ChainProbe<SuiProbeKey>\n//   - artifact-publisher     — the ArtifactPublisher (substrate\n//                             primitive, available everywhere)\n//\n// And via the plugin-owned PackageRegistry service (instantiated from\n// the substrate's generic ScopedRefMap primitive — see `registry.ts`).\n//\n// The wiring of these lookups happens at the barrel (`index.ts`); this\n// file accepts them as parameters so it stays testable.\n\nimport { Effect, type Scope } from 'effect';\n\nimport type {\n\tArtifactPublishError,\n\tArtifactPublisher,\n} from '../../primitives/artifact-publisher.ts';\nimport type { ChainProbe } from '../../contracts/chain-probe.ts';\nimport type { SuiProbeKey } from '../sui/index.ts';\nimport { acquireKnown, type KnownModeInputs } from './mode-known.ts';\nimport { acquireLocal, type LocalModeInputs } from './mode-local.ts';\nimport type {\n\tPackageRegistry,\n\tResolvedKnownPackage,\n\tResolvedLocalPackage,\n\tResolvedPackage,\n} from './registry.ts';\nimport type { LocalPackagePublishOutput } from './publish-output.ts';\nimport type { PublishError } from './errors.ts';\n\n/** Discriminated mode union — mirrors the public factory shape\n *  (`localPackage(...)` and `knownPackage(...)`). The barrel\n *  constructs ONE of these per declared package and the body below\n *  routes. */\nexport type PackageMode =\n\t| ({ readonly mode: 'local' } & LocalModeInputs)\n\t| ({ readonly mode: 'known' } & KnownModeInputs);\n\nexport interface BootPackageResult {\n\treadonly resolved: ResolvedPackage;\n\t/** Fresh publish output — populated on cache MISS (the produce\n\t *  path ran), `null` on cache hit (verify path). Threaded out so\n\t *  the barrel can fan out coin auto-discovery (and any other\n\t *  output-consuming siblings) once per fresh publish.\n\t *\n\t *  Known mode never publishes, so this is always `null` there. */\n\treadonly output: LocalPackagePublishOutput | null;\n}\n\nexport interface BootLocalPackageResult {\n\treadonly resolved: ResolvedLocalPackage;\n\treadonly output: LocalPackagePublishOutput | null;\n}\n\nexport interface BootKnownPackageResult {\n\treadonly resolved: ResolvedKnownPackage;\n\treadonly output: null;\n}\n\n/** Dispatch on the typed mode. */\nexport function bootPackageService(\n\tpublisher: ArtifactPublisher,\n\tprobe: ChainProbe<SuiProbeKey>,\n\tregistry: PackageRegistry,\n\topts: { readonly mode: 'local' } & LocalModeInputs,\n): Effect.Effect<BootLocalPackageResult, PublishError | ArtifactPublishError, Scope.Scope>;\nexport function bootPackageService(\n\tpublisher: ArtifactPublisher,\n\tprobe: ChainProbe<SuiProbeKey>,\n\tregistry: PackageRegistry,\n\topts: { readonly mode: 'known' } & KnownModeInputs,\n): Effect.Effect<BootKnownPackageResult, PublishError | ArtifactPublishError, Scope.Scope>;\nexport function bootPackageService(\n\tpublisher: ArtifactPublisher,\n\tprobe: ChainProbe<SuiProbeKey>,\n\tregistry: PackageRegistry,\n\topts: PackageMode,\n): Effect.Effect<BootPackageResult, PublishError | ArtifactPublishError, Scope.Scope> {\n\tswitch (opts.mode) {\n\t\tcase 'local':\n\t\t\treturn acquireLocal(publisher, probe, registry, opts).pipe(\n\t\t\t\tEffect.map(({ resolved, output }) => ({ resolved, output })),\n\t\t\t);\n\t\tcase 'known':\n\t\t\treturn acquireKnown(probe, registry, opts).pipe(\n\t\t\t\tEffect.map(({ resolved }) => ({ resolved, output: null })),\n\t\t\t);\n\t}\n}\n"],"mappings":";;;;AAsFA,SAAgB,mBACf,WACA,OACA,UACA,MACqF;AACrF,SAAQ,KAAK,MAAb;EACC,KAAK,QACJ,QAAO,aAAa,WAAW,OAAO,UAAU,KAAK,CAAC,KACrD,OAAO,KAAK,EAAE,UAAU,cAAc;GAAE;GAAU;GAAQ,EAAE,CAC5D;EACF,KAAK,QACJ,QAAO,aAAa,OAAO,UAAU,KAAK,CAAC,KAC1C,OAAO,KAAK,EAAE,gBAAgB;GAAE;GAAU,QAAQ;GAAM,EAAE,CAC1D"}

package/dist/plugins/package/spans.mjs

@@ -0,0 +1,14 @@
+//#region src/plugins/package/spans.ts
+const PackageSpans = { publish: {
+	phase: "package.publish.phase",
+	package: "package.publish.package",
+	packageName: "package.publish.packageName",
+	packageId: "package.publish.packageId",
+	sourcePath: "package.publish.sourcePath",
+	chainId: "package.publish.chainId",
+	publisher: "package.publish.publisher"
+} };
+//#endregion
+export { PackageSpans };
+
+//# sourceMappingURL=spans.mjs.map

package/dist/plugins/package/spans.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"spans.mjs","names":[],"sources":["../../../src/plugins/package/spans.ts"],"sourcesContent":["// Package plugin span-attribute vocabulary. Plugin-local — substrate's\n// `SpanAttr` carries only engine-dimensional + http/process generic\n// keys; plugin-domain keys live next to the plugin that owns them.\n//\n// Callsite pattern: `Effect.annotateCurrentSpan({\n// [PackageSpans.publish.phase]: 'build' })`. Free-form string literals\n// are a STYLE_GUIDE §16 violation.\n\nexport const PackageSpans = {\n\tpublish: {\n\t\tphase: 'package.publish.phase',\n\t\tpackage: 'package.publish.package',\n\t\tpackageName: 'package.publish.packageName',\n\t\tpackageId: 'package.publish.packageId',\n\t\tsourcePath: 'package.publish.sourcePath',\n\t\tchainId: 'package.publish.chainId',\n\t\tpublisher: 'package.publish.publisher',\n\t},\n} as const;\n"],"mappings":";AAQA,MAAa,eAAe,EAC3B,SAAS;CACR,OAAO;CACP,SAAS;CACT,aAAa;CACb,WAAW;CACX,YAAY;CACZ,SAAS;CACT,WAAW;CACX,EACD"}

package/dist/plugins/postgres/db-ensure.mjs

@@ -1,5 +1,6 @@
 import { ProbeTimeoutError, exitCodeProbeResult, waitForProbe } from "../../substrate/runtime/probes.mjs";
 import { databaseCreateFailed, postgresConnectionTimeout } from "./errors.mjs";
+import { PostgresSpans } from "./spans.mjs";
 import { Effect } from "effect";
 //#region src/plugins/postgres/db-ensure.ts
 const READY_PROBE_INTERVAL_MS = 500;
@@ -29,16 +30,20 @@ const awaitReady = (exec, user, database, timeoutMs) => Effect.gen(function* ()
 			lastResult = result;
 			return exitCodeProbeResult(result);
 		})
-	}).pipe(Effect.mapError((cause) => postgresConnectionTimeout({
-		database,
-		attempts: cause instanceof ProbeTimeoutError ? cause.attempts : attempts,
-		elapsedMs: Date.now() - startedAt,
-		lastExitCode: lastResult?.exitCode,
-		lastStdout: lastResult?.stdout,
-		lastStderr: lastResult?.stderr
-	})), Effect.withSpan("postgres.awaitReady", { attributes: {
-		"postgres.database": database,
-		"postgres.timeoutMs": timeoutMs
+	}).pipe(Effect.mapError((cause) => {
+		const lastError = cause instanceof ProbeTimeoutError ? cause.lastError : cause;
+		return postgresConnectionTimeout({
+			database,
+			attempts: cause instanceof ProbeTimeoutError ? cause.attempts : attempts,
+			elapsedMs: Date.now() - startedAt,
+			lastExitCode: lastResult?.exitCode,
+			lastStdout: lastResult?.stdout,
+			lastStderr: lastResult?.stderr,
+			...lastError === void 0 ? {} : { lastError }
+		});
+	}), Effect.withSpan("devstack.plugin.postgres.awaitReady", { attributes: {
+		[PostgresSpans.database]: database,
+		[PostgresSpans.timeoutMs]: timeoutMs
 	} }));
 });
 /** Idempotently ensure a logical database exists.
@@ -59,12 +64,13 @@ const awaitReady = (exec, user, database, timeoutMs) => Effect.gen(function* ()
 *  cases flags this as a known foot-gun, and the recommended cure
 *  is "use lowercase names". */
 const ensureDatabase = (exec, user, dbName) => Effect.gen(function* () {
+	const escapedDbName = dbName.replace(/'/g, "''");
 	const exists = yield* exec.run([
 		"psql",
 		"-U",
 		user,
 		"-tAc",
-		`SELECT 1 FROM pg_database WHERE datname = '${dbName}'`
+		`SELECT 1 FROM pg_database WHERE datname = '${escapedDbName}'`
 	]);
 	if (exists.exitCode !== 0) return yield* Effect.fail(databaseCreateFailed({
 		database: dbName,
@@ -78,6 +84,7 @@ const ensureDatabase = (exec, user, dbName) => Effect.gen(function* () {
 		"createdb",
 		"-U",
 		user,
+		"--",
 		dbName
 	]);
 	if (created.exitCode !== 0) return yield* Effect.fail(databaseCreateFailed({
@@ -87,7 +94,7 @@ const ensureDatabase = (exec, user, dbName) => Effect.gen(function* () {
 		stdout: created.stdout,
 		stderr: created.stderr
 	}));
-}).pipe(Effect.withSpan("postgres.ensureDatabase", { attributes: { "postgres.database": dbName } }));
+}).pipe(Effect.withSpan("devstack.plugin.postgres.ensureDatabase", { attributes: { [PostgresSpans.database]: dbName } }));
 /** Sequentially ensure every non-bootstrap database exists. The
 *  bootstrap (first entry) is created by `POSTGRES_DB` at image
 *  entrypoint and MUST be skipped here. */

package/dist/plugins/postgres/db-ensure.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"db-ensure.mjs","names":[],"sources":["../../../src/plugins/postgres/db-ensure.ts"],"sourcesContent":["// Postgres plugin — idempotent logical-database creation via\n// `docker exec ... psql`.\n//\n// Why exec, not a TS pg client:\n//   - Production path keeps a zero-runtime-dep posture (distilled doc\n//     § Postgres-specific concerns: \"avoids carrying a TS `pg` runtime\n//     dependency in the production path\").\n//   - The probe binary already lives inside the image; the dev\n//     machine doesn't need a libpq install.\n//   - The same machinery serves `pg_isready` (readiness probe) and\n//     `psql` (existence check + createdb), so one exec primitive\n//     covers both side-channels.\n//\n// Idempotency contract:\n//   - The first database is bootstrapped by the upstream image's\n//     entrypoint via `POSTGRES_DB`. The plugin's acquire body MUST\n//     skip it here — passing it through `ensureDatabase` is harmless\n//     (we short-circuit on existence) but wastes a round-trip.\n//   - Subsequent databases land via SELECT 1 / createdb. SELECT 1\n//     against `pg_database WHERE datname = '<name>'` returns \"1\\n\" on\n//     hit; we treat any non-empty trimmed stdout as a hit so a\n//     trailing newline doesn't trigger a duplicate-createdb path.\n//\n// The `ContainerExec` capability is consumed via the plugin's service\n// body (`service.ts:containerExec`), which thin-wraps the\n// `ContainerRuntime.exec` contract surface. Daemon-level failures\n// project to a synthetic non-zero `ExecResult` so the retry loop\n// observes them and the typed timeout error carries the captured\n// streams.\n\nimport { Effect } from 'effect';\n\nimport {\n\tdatabaseCreateFailed,\n\tpostgresConnectionTimeout,\n\ttype DatabaseCreateFailed,\n\ttype PostgresConnectionTimeout,\n} from './errors.ts';\nimport {\n\tProbeTimeoutError,\n\texitCodeProbeResult,\n\twaitForProbe,\n} from '../../substrate/runtime/probes.ts';\n\n/** One captured exec invocation. Mirrors the shape returned by\n *  `docker exec` (stdout + stderr + exit code), without naming docker\n *  — any container runtime that supports an exec primitive can\n *  satisfy this. */\nexport interface ExecResult {\n\treadonly exitCode: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\n/** Exec callable injected by the plugin's service body. Wraps\n *  `ContainerRuntime.exec` (see contract) into the local seam shape so\n *  the retry / existence-check loops here stay runtime-agnostic. */\nexport interface ContainerExec {\n\treadonly run: (argv: ReadonlyArray<string>) => Effect.Effect<ExecResult>;\n}\n\nconst READY_PROBE_INTERVAL_MS = 500;\n\n/** Wait until `pg_isready -U <user> -d <db>` exits zero or the\n *  overall deadline elapses.\n *\n *  Distilled doc § \"Postgres-specific concerns\" — server-aware probe;\n *  TCP-listener readiness alone is insufficient (postgres opens the\n *  port before it accepts queries). */\nexport const awaitReady = (\n\texec: ContainerExec,\n\tuser: string,\n\tdatabase: string,\n\ttimeoutMs: number,\n): Effect.Effect<void, PostgresConnectionTimeout> =>\n\tEffect.gen(function* () {\n\t\tlet attempts = 0;\n\t\tlet lastResult: ExecResult | undefined;\n\t\tconst startedAt = Date.now();\n\n\t\treturn yield* waitForProbe({\n\t\t\tlabel: `postgres:${database}`,\n\t\t\ttimeoutMs,\n\t\t\tintervalMs: READY_PROBE_INTERVAL_MS,\n\t\t\tprobe: () =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tattempts += 1;\n\t\t\t\t\tconst result = yield* exec.run(['pg_isready', '-U', user, '-d', database]);\n\t\t\t\t\tlastResult = result;\n\t\t\t\t\treturn exitCodeProbeResult(result);\n\t\t\t\t}),\n\t\t}).pipe(\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\tpostgresConnectionTimeout({\n\t\t\t\t\tdatabase,\n\t\t\t\t\tattempts: cause instanceof ProbeTimeoutError ? cause.attempts : attempts,\n\t\t\t\t\telapsedMs: Date.now() - startedAt,\n\t\t\t\t\tlastExitCode: lastResult?.exitCode,\n\t\t\t\t\tlastStdout: lastResult?.stdout,\n\t\t\t\t\tlastStderr: lastResult?.stderr,\n\t\t\t\t}),\n\t\t\t),\n\t\t\tEffect.withSpan('postgres.awaitReady', {\n\t\t\t\tattributes: { 'postgres.database': database, 'postgres.timeoutMs': timeoutMs },\n\t\t\t}),\n\t\t);\n\t});\n\n/** Idempotently ensure a logical database exists.\n *\n *  Algorithm:\n *    1. `psql -tAc \"SELECT 1 FROM pg_database WHERE datname = '<db>'\"`.\n *       Exit 0 + non-empty stdout => exists, return.\n *       Exit != 0                 => DatabaseCreateFailed(exists-check).\n *    2. `createdb -U <user> <db>`.\n *       Exit 0  => done.\n *       Exit != 0 => DatabaseCreateFailed(createdb).\n *\n *  Identifier quoting note: this implementation passes the database\n *  name as a CLI argument (createdb) and as a SQL string literal\n *  (the existence query). Postgres folds unquoted identifiers; if\n *  the caller passes `MyDB`, postgres stores it as `mydb`. The\n *  current plugin contract doesn't quote — distilled doc § Edge\n *  cases flags this as a known foot-gun, and the recommended cure\n *  is \"use lowercase names\". */\nexport const ensureDatabase = (\n\texec: ContainerExec,\n\tuser: string,\n\tdbName: string,\n): Effect.Effect<void, DatabaseCreateFailed> =>\n\tEffect.gen(function* () {\n\t\tconst exists = yield* exec.run([\n\t\t\t'psql',\n\t\t\t'-U',\n\t\t\tuser,\n\t\t\t'-tAc',\n\t\t\t`SELECT 1 FROM pg_database WHERE datname = '${dbName}'`,\n\t\t]);\n\t\tif (exists.exitCode !== 0) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tdatabaseCreateFailed({\n\t\t\t\t\tdatabase: dbName,\n\t\t\t\t\top: 'exists-check',\n\t\t\t\t\texitCode: exists.exitCode,\n\t\t\t\t\tstdout: exists.stdout,\n\t\t\t\t\tstderr: exists.stderr,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tif (exists.stdout.trim().length > 0) {\n\t\t\treturn; // already present\n\t\t}\n\n\t\tconst created = yield* exec.run(['createdb', '-U', user, dbName]);\n\t\tif (created.exitCode !== 0) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tdatabaseCreateFailed({\n\t\t\t\t\tdatabase: dbName,\n\t\t\t\t\top: 'createdb',\n\t\t\t\t\texitCode: created.exitCode,\n\t\t\t\t\tstdout: created.stdout,\n\t\t\t\t\tstderr: created.stderr,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t}).pipe(\n\t\tEffect.withSpan('postgres.ensureDatabase', {\n\t\t\tattributes: { 'postgres.database': dbName },\n\t\t}),\n\t);\n\n/** Sequentially ensure every non-bootstrap database exists. The\n *  bootstrap (first entry) is created by `POSTGRES_DB` at image\n *  entrypoint and MUST be skipped here. */\nexport const ensureDatabases = (\n\texec: ContainerExec,\n\tuser: string,\n\tdatabases: ReadonlyArray<string>,\n): Effect.Effect<void, DatabaseCreateFailed> =>\n\tEffect.gen(function* () {\n\t\tfor (let i = 1; i < databases.length; i++) {\n\t\t\tyield* ensureDatabase(exec, user, databases[i]!);\n\t\t}\n\t});\n"],"mappings":";;;;AA6DA,MAAM,0BAA0B;;;;;;;AAQhC,MAAa,cACZ,MACA,MACA,UACA,cAEA,OAAO,IAAI,aAAa;CACvB,IAAI,WAAW;CACf,IAAI;CACJ,MAAM,YAAY,KAAK,KAAK;AAE5B,QAAO,OAAO,aAAa;EAC1B,OAAO,YAAY;EACnB;EACA,YAAY;EACZ,aACC,OAAO,IAAI,aAAa;AACvB,eAAY;GACZ,MAAM,SAAS,OAAO,KAAK,IAAI;IAAC;IAAc;IAAM;IAAM;IAAM;IAAS,CAAC;AAC1E,gBAAa;AACb,UAAO,oBAAoB,OAAO;IACjC;EACH,CAAC,CAAC,KACF,OAAO,UAAU,UAChB,0BAA0B;EACzB;EACA,UAAU,iBAAiB,oBAAoB,MAAM,WAAW;EAChE,WAAW,KAAK,KAAK,GAAG;EACxB,cAAc,YAAY;EAC1B,YAAY,YAAY;EACxB,YAAY,YAAY;EACxB,CAAC,CACF,EACD,OAAO,SAAS,uBAAuB,EACtC,YAAY;EAAE,qBAAqB;EAAU,sBAAsB;EAAW,EAC9E,CAAC,CACF;EACA;;;;;;;;;;;;;;;;;;AAmBH,MAAa,kBACZ,MACA,MACA,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,SAAS,OAAO,KAAK,IAAI;EAC9B;EACA;EACA;EACA;EACA,8CAA8C,OAAO;EACrD,CAAC;AACF,KAAI,OAAO,aAAa,EACvB,QAAO,OAAO,OAAO,KACpB,qBAAqB;EACpB,UAAU;EACV,IAAI;EACJ,UAAU,OAAO;EACjB,QAAQ,OAAO;EACf,QAAQ,OAAO;EACf,CAAC,CACF;AAEF,KAAI,OAAO,OAAO,MAAM,CAAC,SAAS,EACjC;CAGD,MAAM,UAAU,OAAO,KAAK,IAAI;EAAC;EAAY;EAAM;EAAM;EAAO,CAAC;AACjE,KAAI,QAAQ,aAAa,EACxB,QAAO,OAAO,OAAO,KACpB,qBAAqB;EACpB,UAAU;EACV,IAAI;EACJ,UAAU,QAAQ;EAClB,QAAQ,QAAQ;EAChB,QAAQ,QAAQ;EAChB,CAAC,CACF;EAED,CAAC,KACF,OAAO,SAAS,2BAA2B,EAC1C,YAAY,EAAE,qBAAqB,QAAQ,EAC3C,CAAC,CACF;;;;AAKF,MAAa,mBACZ,MACA,MACA,cAEA,OAAO,IAAI,aAAa;AACvB,MAAK,IAAI,IAAI,GAAG,IAAI,UAAU,QAAQ,IACrC,QAAO,eAAe,MAAM,MAAM,UAAU,GAAI;EAEhD"}
+{"version":3,"file":"db-ensure.mjs","names":[],"sources":["../../../src/plugins/postgres/db-ensure.ts"],"sourcesContent":["// Postgres plugin — idempotent logical-database creation via\n// `docker exec ... psql`.\n//\n// Why exec, not a TS pg client:\n//   - Production path keeps a zero-runtime-dep posture (distilled doc\n//     § Postgres-specific concerns: \"avoids carrying a TS `pg` runtime\n//     dependency in the production path\").\n//   - The probe binary already lives inside the image; the dev\n//     machine doesn't need a libpq install.\n//   - The same machinery serves `pg_isready` (readiness probe) and\n//     `psql` (existence check + createdb), so one exec primitive\n//     covers both side-channels.\n//\n// Idempotency contract:\n//   - The first database is bootstrapped by the upstream image's\n//     entrypoint via `POSTGRES_DB`. The plugin's acquire body MUST\n//     skip it here — passing it through `ensureDatabase` is harmless\n//     (we short-circuit on existence) but wastes a round-trip.\n//   - Subsequent databases land via SELECT 1 / createdb. SELECT 1\n//     against `pg_database WHERE datname = '<name>'` returns \"1\\n\" on\n//     hit; we treat any non-empty trimmed stdout as a hit so a\n//     trailing newline doesn't trigger a duplicate-createdb path.\n//\n// The `ContainerExec` capability is consumed via the plugin's service\n// body (`service.ts:containerExec`), which thin-wraps the\n// `ContainerRuntime.exec` contract surface. Daemon-level failures (no\n// such container, daemon unreachable) map to a typed\n// `PostgresPluginError({phase: 'container-start'})` rather than a\n// fabricated non-zero `ExecResult`; `waitForProbe` treats that typed\n// failure as retryable and preserves the underlying cause on the\n// timeout error's `lastError` field.\n\nimport { Effect } from 'effect';\n\nimport {\n\tdatabaseCreateFailed,\n\tpostgresConnectionTimeout,\n\ttype DatabaseCreateFailed,\n\ttype PostgresConnectionTimeout,\n\ttype PostgresPluginError,\n} from './errors.ts';\nimport { PostgresSpans } from './spans.ts';\nimport {\n\tProbeTimeoutError,\n\texitCodeProbeResult,\n\twaitForProbe,\n} from '../../substrate/runtime/probes.ts';\n\n/** One captured exec invocation. Mirrors the shape returned by\n *  `docker exec` (stdout + stderr + exit code), without naming docker\n *  — any container runtime that supports an exec primitive can\n *  satisfy this. */\nexport interface ExecResult {\n\treadonly exitCode: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n}\n\n/** Exec callable injected by the plugin's service body. Wraps\n *  `ContainerRuntime.exec` (see contract) into the local seam shape so\n *  the retry / existence-check loops here stay runtime-agnostic.\n *\n *  Daemon-level failures surface as `PostgresPluginError`; non-zero\n *  exit codes (eg `pg_isready` not ready yet) are returned in the\n *  `ExecResult` for the caller to interpret. */\nexport interface ContainerExec {\n\treadonly run: (\n\t\targv: ReadonlyArray<string>,\n\t) => Effect.Effect<ExecResult, PostgresPluginError>;\n}\n\nconst READY_PROBE_INTERVAL_MS = 500;\n\n/** Wait until `pg_isready -U <user> -d <db>` exits zero or the\n *  overall deadline elapses.\n *\n *  Distilled doc § \"Postgres-specific concerns\" — server-aware probe;\n *  TCP-listener readiness alone is insufficient (postgres opens the\n *  port before it accepts queries). */\nexport const awaitReady = (\n\texec: ContainerExec,\n\tuser: string,\n\tdatabase: string,\n\ttimeoutMs: number,\n): Effect.Effect<void, PostgresConnectionTimeout> =>\n\tEffect.gen(function* () {\n\t\tlet attempts = 0;\n\t\tlet lastResult: ExecResult | undefined;\n\t\tconst startedAt = Date.now();\n\n\t\treturn yield* waitForProbe({\n\t\t\tlabel: `postgres:${database}`,\n\t\t\ttimeoutMs,\n\t\t\tintervalMs: READY_PROBE_INTERVAL_MS,\n\t\t\tprobe: () =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tattempts += 1;\n\t\t\t\t\tconst result = yield* exec.run(['pg_isready', '-U', user, '-d', database]);\n\t\t\t\t\tlastResult = result;\n\t\t\t\t\treturn exitCodeProbeResult(result);\n\t\t\t\t}),\n\t\t}).pipe(\n\t\t\tEffect.mapError((cause) => {\n\t\t\t\tconst lastError =\n\t\t\t\t\tcause instanceof ProbeTimeoutError ? cause.lastError : (cause as unknown);\n\t\t\t\treturn postgresConnectionTimeout({\n\t\t\t\t\tdatabase,\n\t\t\t\t\tattempts: cause instanceof ProbeTimeoutError ? cause.attempts : attempts,\n\t\t\t\t\telapsedMs: Date.now() - startedAt,\n\t\t\t\t\tlastExitCode: lastResult?.exitCode,\n\t\t\t\t\tlastStdout: lastResult?.stdout,\n\t\t\t\t\tlastStderr: lastResult?.stderr,\n\t\t\t\t\t...(lastError === undefined ? {} : { lastError }),\n\t\t\t\t});\n\t\t\t}),\n\t\t\tEffect.withSpan('devstack.plugin.postgres.awaitReady', {\n\t\t\t\tattributes: {\n\t\t\t\t\t[PostgresSpans.database]: database,\n\t\t\t\t\t[PostgresSpans.timeoutMs]: timeoutMs,\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n\t});\n\n/** Idempotently ensure a logical database exists.\n *\n *  Algorithm:\n *    1. `psql -tAc \"SELECT 1 FROM pg_database WHERE datname = '<db>'\"`.\n *       Exit 0 + non-empty stdout => exists, return.\n *       Exit != 0                 => DatabaseCreateFailed(exists-check).\n *    2. `createdb -U <user> <db>`.\n *       Exit 0  => done.\n *       Exit != 0 => DatabaseCreateFailed(createdb).\n *\n *  Identifier quoting note: this implementation passes the database\n *  name as a CLI argument (createdb) and as a SQL string literal\n *  (the existence query). Postgres folds unquoted identifiers; if\n *  the caller passes `MyDB`, postgres stores it as `mydb`. The\n *  current plugin contract doesn't quote — distilled doc § Edge\n *  cases flags this as a known foot-gun, and the recommended cure\n *  is \"use lowercase names\". */\nexport const ensureDatabase = (\n\texec: ContainerExec,\n\tuser: string,\n\tdbName: string,\n): Effect.Effect<void, DatabaseCreateFailed | PostgresPluginError> =>\n\tEffect.gen(function* () {\n\t\t// Quote-escape per SQL literal rules (double single-quotes inside\n\t\t// the literal). The plugin's own contract restricts callers to\n\t\t// lowercase database identifiers (see distilled-doc § Edge cases\n\t\t// above), but the literal interpolation here is still a foot-\n\t\t// gun: a name containing `'` would break the WHERE clause and\n\t\t// either fail the existence check or, worse, alter its\n\t\t// semantics. Escaping locks the wire shape independent of the\n\t\t// upstream contract.\n\t\tconst escapedDbName = dbName.replace(/'/g, \"''\");\n\t\tconst exists = yield* exec.run([\n\t\t\t'psql',\n\t\t\t'-U',\n\t\t\tuser,\n\t\t\t'-tAc',\n\t\t\t`SELECT 1 FROM pg_database WHERE datname = '${escapedDbName}'`,\n\t\t]);\n\t\tif (exists.exitCode !== 0) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tdatabaseCreateFailed({\n\t\t\t\t\tdatabase: dbName,\n\t\t\t\t\top: 'exists-check',\n\t\t\t\t\texitCode: exists.exitCode,\n\t\t\t\t\tstdout: exists.stdout,\n\t\t\t\t\tstderr: exists.stderr,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tif (exists.stdout.trim().length > 0) {\n\t\t\treturn; // already present\n\t\t}\n\n\t\t// The `--` argv separator stops `createdb`'s flag parsing — a\n\t\t// `dbName` starting with `-` (e.g. `--help`) would otherwise be\n\t\t// interpreted as a flag rather than a positional database name.\n\t\t// Argv form already neutralizes shell-metacharacter injection;\n\t\t// the separator closes the remaining flag-shape gap.\n\t\tconst created = yield* exec.run(['createdb', '-U', user, '--', dbName]);\n\t\tif (created.exitCode !== 0) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tdatabaseCreateFailed({\n\t\t\t\t\tdatabase: dbName,\n\t\t\t\t\top: 'createdb',\n\t\t\t\t\texitCode: created.exitCode,\n\t\t\t\t\tstdout: created.stdout,\n\t\t\t\t\tstderr: created.stderr,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.postgres.ensureDatabase', {\n\t\t\tattributes: { [PostgresSpans.database]: dbName },\n\t\t}),\n\t);\n\n/** Sequentially ensure every non-bootstrap database exists. The\n *  bootstrap (first entry) is created by `POSTGRES_DB` at image\n *  entrypoint and MUST be skipped here. */\nexport const ensureDatabases = (\n\texec: ContainerExec,\n\tuser: string,\n\tdatabases: ReadonlyArray<string>,\n): Effect.Effect<void, DatabaseCreateFailed | PostgresPluginError> =>\n\tEffect.gen(function* () {\n\t\tfor (let i = 1; i < databases.length; i++) {\n\t\t\tyield* ensureDatabase(exec, user, databases[i]!);\n\t\t}\n\t});\n"],"mappings":";;;;;AAuEA,MAAM,0BAA0B;;;;;;;AAQhC,MAAa,cACZ,MACA,MACA,UACA,cAEA,OAAO,IAAI,aAAa;CACvB,IAAI,WAAW;CACf,IAAI;CACJ,MAAM,YAAY,KAAK,KAAK;AAE5B,QAAO,OAAO,aAAa;EAC1B,OAAO,YAAY;EACnB;EACA,YAAY;EACZ,aACC,OAAO,IAAI,aAAa;AACvB,eAAY;GACZ,MAAM,SAAS,OAAO,KAAK,IAAI;IAAC;IAAc;IAAM;IAAM;IAAM;IAAS,CAAC;AAC1E,gBAAa;AACb,UAAO,oBAAoB,OAAO;IACjC;EACH,CAAC,CAAC,KACF,OAAO,UAAU,UAAU;EAC1B,MAAM,YACL,iBAAiB,oBAAoB,MAAM,YAAa;AACzD,SAAO,0BAA0B;GAChC;GACA,UAAU,iBAAiB,oBAAoB,MAAM,WAAW;GAChE,WAAW,KAAK,KAAK,GAAG;GACxB,cAAc,YAAY;GAC1B,YAAY,YAAY;GACxB,YAAY,YAAY;GACxB,GAAI,cAAc,KAAA,IAAY,EAAE,GAAG,EAAE,WAAW;GAChD,CAAC;GACD,EACF,OAAO,SAAS,uCAAuC,EACtD,YAAY;GACV,cAAc,WAAW;GACzB,cAAc,YAAY;EAC3B,EACD,CAAC,CACF;EACA;;;;;;;;;;;;;;;;;;AAmBH,MAAa,kBACZ,MACA,MACA,WAEA,OAAO,IAAI,aAAa;CASvB,MAAM,gBAAgB,OAAO,QAAQ,MAAM,KAAK;CAChD,MAAM,SAAS,OAAO,KAAK,IAAI;EAC9B;EACA;EACA;EACA;EACA,8CAA8C,cAAc;EAC5D,CAAC;AACF,KAAI,OAAO,aAAa,EACvB,QAAO,OAAO,OAAO,KACpB,qBAAqB;EACpB,UAAU;EACV,IAAI;EACJ,UAAU,OAAO;EACjB,QAAQ,OAAO;EACf,QAAQ,OAAO;EACf,CAAC,CACF;AAEF,KAAI,OAAO,OAAO,MAAM,CAAC,SAAS,EACjC;CAQD,MAAM,UAAU,OAAO,KAAK,IAAI;EAAC;EAAY;EAAM;EAAM;EAAM;EAAO,CAAC;AACvE,KAAI,QAAQ,aAAa,EACxB,QAAO,OAAO,OAAO,KACpB,qBAAqB;EACpB,UAAU;EACV,IAAI;EACJ,UAAU,QAAQ;EAClB,QAAQ,QAAQ;EAChB,QAAQ,QAAQ;EAChB,CAAC,CACF;EAED,CAAC,KACF,OAAO,SAAS,2CAA2C,EAC1D,YAAY,GAAG,cAAc,WAAW,QAAQ,EAChD,CAAC,CACF;;;;AAKF,MAAa,mBACZ,MACA,MACA,cAEA,OAAO,IAAI,aAAa;AACvB,MAAK,IAAI,IAAI,GAAG,IAAI,UAAU,QAAQ,IACrC,QAAO,eAAe,MAAM,MAAM,UAAU,GAAI;EAEhD"}

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

@@ -33,6 +33,11 @@ interface PostgresConnectionTimeout {
   readonly lastExitCode?: number;
   readonly lastStdout?: string;
   readonly lastStderr?: string;
+  /** Underlying typed error from the last probe attempt — populated
+   *  when the probe itself failed (eg daemon-level container-start
+   *  error) rather than `pg_isready` returning a non-zero exit. The
+   *  cause walker reads this to render the actionable hint. */
+  readonly lastError?: unknown;
 }
 /** Logical-database creation failed. Distinct from a network /
  *  container / probe failure because the typical root cause is

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

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/postgres/errors.ts"],"sourcesContent":["// Postgres plugin — typed errors.\n//\n// Per-plugin tagged errors (architecture § Effect; substrate-redesign\n// directive: errors live with the plugin that raises and consumes\n// them). Postgres is a topological leaf — every raise site AND every\n// consumer is inside `src/plugins/postgres/`, so this file owns the\n// complete error surface.\n//\n// Phase tags mirror the lifecycle states from the distilled doc\n// (10-postgres § Lifecycle states): one phase per failure boundary\n// so the cause walker / TUI / regression tests can pin behaviour by\n// label rather than by message-substring matching.\n//\n// Effect v4: errors are plain interfaces with a `_tag` discriminator.\n// `Effect.catchTag` / `catchTags` match on the `_tag` literal — we do\n// NOT subclass an Effect base class. See architecture § Effect.\n\nimport { defineConfigError, type ConfigIssue } from '../../substrate/runtime/config-validation.ts';\n\n/** Phases for `PostgresPluginError`. Closed sum — additions land in\n *  the distilled-doc catalog first. */\nexport type PostgresPhase =\n\t| 'network-create'\n\t| 'image-build'\n\t| 'container-start'\n\t| 'ready-probe'\n\t| 'db-ensure'\n\t| 'unknown';\n\n/** Generic plugin error. Most failure surfaces collapse onto this\n *  shape; specific failure modes that warrant their own catchable\n *  tag (timeout, createdb-collision) get their own type below. */\nexport interface PostgresPluginError {\n\treadonly _tag: 'PostgresPluginError';\n\treadonly phase: PostgresPhase;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const postgresPluginError = (\n\tphase: PostgresPhase,\n\tmessage: string,\n\tcause?: unknown,\n): PostgresPluginError => ({ _tag: 'PostgresPluginError', phase, message, cause });\n\nexport interface PostgresConfigError extends ConfigIssue {\n\treadonly _tag: 'PostgresConfigError';\n}\n\nexport const postgresConfigError = defineConfigError('PostgresConfigError');\n\n/** `pg_isready` returned non-zero past the deadline. Carries the\n *  database name + last exit code + captured streams so the cause\n *  walker can render an actionable hint (slow disk, port mismatch,\n *  perms on data dir).\n *\n *  Distilled-doc § Edge cases: this is the most common \"what went\n *  wrong\" failure during first boot of a freshly-built image; it\n *  deserves its own tag so the renderer can show a slow-disk hint\n *  before users guess. */\nexport interface PostgresConnectionTimeout {\n\treadonly _tag: 'PostgresConnectionTimeout';\n\treadonly database: string;\n\treadonly attempts: number;\n\treadonly elapsedMs: number;\n\treadonly lastExitCode?: number;\n\treadonly lastStdout?: string;\n\treadonly lastStderr?: string;\n}\n\nexport const postgresConnectionTimeout = (\n\tparts: Omit<PostgresConnectionTimeout, '_tag'>,\n): PostgresConnectionTimeout => ({ _tag: 'PostgresConnectionTimeout', ...parts });\n\n/** Logical-database creation failed. Distinct from a network /\n *  container / probe failure because the typical root cause is\n *  case-sensitivity collision in postgres identifier folding —\n *  surfaced explicitly via its own tag so consumers can render a\n *  \"quote the identifier\" hint. */\nexport interface DatabaseCreateFailed {\n\treadonly _tag: 'DatabaseCreateFailed';\n\treadonly database: string;\n\treadonly op: 'exists-check' | 'createdb';\n\treadonly exitCode?: number;\n\treadonly stdout?: string;\n\treadonly stderr?: string;\n\treadonly cause?: unknown;\n}\n\nexport const databaseCreateFailed = (\n\tparts: Omit<DatabaseCreateFailed, '_tag'>,\n): DatabaseCreateFailed => ({ _tag: 'DatabaseCreateFailed', ...parts });\n\n/** Union of every error a Postgres-plugin caller may encounter. */\nexport type PostgresError =\n\t| PostgresPluginError\n\t| PostgresConfigError\n\t| PostgresConnectionTimeout\n\t| DatabaseCreateFailed;\n\n/** Error tags this plugin contributes — surfaced to the cause walker\n *  via `PluginErrorContribution`. */\nexport const POSTGRES_ERROR_TAGS: ReadonlyArray<PostgresError['_tag']> = [\n\t'PostgresPluginError',\n\t'PostgresConfigError',\n\t'PostgresConnectionTimeout',\n\t'DatabaseCreateFailed',\n] as const;\n"],"mappings":";;AAuCA,MAAa,uBACZ,OACA,SACA,WAC0B;CAAE,MAAM;CAAuB;CAAO;CAAS;CAAO;AAMjF,MAAa,sBAAsB,kBAAkB,sBAAsB;AAqB3E,MAAa,6BACZ,WACgC;CAAE,MAAM;CAA6B,GAAG;CAAO;AAiBhF,MAAa,wBACZ,WAC2B;CAAE,MAAM;CAAwB,GAAG;CAAO;;;AAWtE,MAAa,sBAA4D;CACxE;CACA;CACA;CACA;CACA"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/postgres/errors.ts"],"sourcesContent":["// Postgres plugin — typed errors.\n//\n// Per-plugin tagged errors (architecture § Effect; substrate-redesign\n// directive: errors live with the plugin that raises and consumes\n// them). Postgres is a topological leaf — every raise site AND every\n// consumer is inside `src/plugins/postgres/`, so this file owns the\n// complete error surface.\n//\n// Phase tags mirror the lifecycle states from the distilled doc\n// (10-postgres § Lifecycle states): one phase per failure boundary\n// so the cause walker / TUI / regression tests can pin behaviour by\n// label rather than by message-substring matching.\n//\n// Effect v4: errors are plain interfaces with a `_tag` discriminator.\n// `Effect.catchTag` / `catchTags` match on the `_tag` literal — we do\n// NOT subclass an Effect base class. See architecture § Effect.\n\nimport { defineConfigError, type ConfigIssue } from '../../substrate/runtime/config-validation.ts';\n\n/** Phases for `PostgresPluginError`. Closed sum — additions land in\n *  the distilled-doc catalog first. */\nexport type PostgresPhase =\n\t| 'network-create'\n\t| 'image-build'\n\t| 'container-start'\n\t| 'ready-probe'\n\t| 'db-ensure'\n\t| 'unknown';\n\n/** Generic plugin error. Most failure surfaces collapse onto this\n *  shape; specific failure modes that warrant their own catchable\n *  tag (timeout, createdb-collision) get their own type below. */\nexport interface PostgresPluginError {\n\treadonly _tag: 'PostgresPluginError';\n\treadonly phase: PostgresPhase;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const postgresPluginError = (\n\tphase: PostgresPhase,\n\tmessage: string,\n\tcause?: unknown,\n): PostgresPluginError => ({ _tag: 'PostgresPluginError', phase, message, cause });\n\nexport interface PostgresConfigError extends ConfigIssue {\n\treadonly _tag: 'PostgresConfigError';\n}\n\nexport const postgresConfigError = defineConfigError('PostgresConfigError');\n\n/** `pg_isready` returned non-zero past the deadline. Carries the\n *  database name + last exit code + captured streams so the cause\n *  walker can render an actionable hint (slow disk, port mismatch,\n *  perms on data dir).\n *\n *  Distilled-doc § Edge cases: this is the most common \"what went\n *  wrong\" failure during first boot of a freshly-built image; it\n *  deserves its own tag so the renderer can show a slow-disk hint\n *  before users guess. */\nexport interface PostgresConnectionTimeout {\n\treadonly _tag: 'PostgresConnectionTimeout';\n\treadonly database: string;\n\treadonly attempts: number;\n\treadonly elapsedMs: number;\n\treadonly lastExitCode?: number;\n\treadonly lastStdout?: string;\n\treadonly lastStderr?: string;\n\t/** Underlying typed error from the last probe attempt — populated\n\t *  when the probe itself failed (eg daemon-level container-start\n\t *  error) rather than `pg_isready` returning a non-zero exit. The\n\t *  cause walker reads this to render the actionable hint. */\n\treadonly lastError?: unknown;\n}\n\nexport const postgresConnectionTimeout = (\n\tparts: Omit<PostgresConnectionTimeout, '_tag'>,\n): PostgresConnectionTimeout => ({ _tag: 'PostgresConnectionTimeout', ...parts });\n\n/** Logical-database creation failed. Distinct from a network /\n *  container / probe failure because the typical root cause is\n *  case-sensitivity collision in postgres identifier folding —\n *  surfaced explicitly via its own tag so consumers can render a\n *  \"quote the identifier\" hint. */\nexport interface DatabaseCreateFailed {\n\treadonly _tag: 'DatabaseCreateFailed';\n\treadonly database: string;\n\treadonly op: 'exists-check' | 'createdb';\n\treadonly exitCode?: number;\n\treadonly stdout?: string;\n\treadonly stderr?: string;\n\treadonly cause?: unknown;\n}\n\nexport const databaseCreateFailed = (\n\tparts: Omit<DatabaseCreateFailed, '_tag'>,\n): DatabaseCreateFailed => ({ _tag: 'DatabaseCreateFailed', ...parts });\n\n/** Union of every error a Postgres-plugin caller may encounter. */\nexport type PostgresError =\n\t| PostgresPluginError\n\t| PostgresConfigError\n\t| PostgresConnectionTimeout\n\t| DatabaseCreateFailed;\n\n/** Error tags this plugin contributes — surfaced to the cause walker\n *  via `PluginErrorContribution`. */\nexport const POSTGRES_ERROR_TAGS: ReadonlyArray<PostgresError['_tag']> = [\n\t'PostgresPluginError',\n\t'PostgresConfigError',\n\t'PostgresConnectionTimeout',\n\t'DatabaseCreateFailed',\n] as const;\n"],"mappings":";;AAuCA,MAAa,uBACZ,OACA,SACA,WAC0B;CAAE,MAAM;CAAuB;CAAO;CAAS;CAAO;AAMjF,MAAa,sBAAsB,kBAAkB,sBAAsB;AA0B3E,MAAa,6BACZ,WACgC;CAAE,MAAM;CAA6B,GAAG;CAAO;AAiBhF,MAAa,wBACZ,WAC2B;CAAE,MAAM;CAAwB,GAAG;CAAO;;;AAWtE,MAAa,sBAA4D;CACxE;CACA;CACA;CACA;CACA"}

package/dist/plugins/postgres/index.mjs

@@ -1,12 +1,14 @@
 import { definePlugin, resource } from "../../substrate/plugin.mjs";
-import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
-import { IdentityContext } from "../../substrate/runtime/paths.mjs";
+import "../../api/define-plugin.mjs";
+import { IdentityContext, StackPathsService } from "../../substrate/runtime/paths.mjs";
 import { ContainerRuntimeService } from "../../runtime/docker/service.mjs";
-import { expectNonEmptyArray } from "../../substrate/runtime/config-validation.mjs";
 import { makePostgresRoutable } from "./routable.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import { passthroughOrWrap } from "../../substrate/runtime/passthrough-or-wrap.mjs";
 import "./connection.mjs";
 import { makeCodegenable } from "./codegen.mjs";
-import { POSTGRES_ERROR_TAGS, postgresConfigError, postgresPluginError } from "./errors.mjs";
+import { POSTGRES_ERROR_TAGS, postgresPluginError } from "./errors.mjs";
+import "./spans.mjs";
 import { bootPostgresService } from "./service.mjs";
 import { makeSnapshotable } from "./snapshot.mjs";
 import { Effect } from "effect";
@@ -16,30 +18,21 @@ const postgresResource = resource("postgres");
 const postgresErrorContributions = pluginErrorContributions(POSTGRES_ERROR_TAGS);
 const buildPlugin = (opts) => {
 	const name = opts.name ?? "postgres";
-	const databases = expectNonEmptyArray(opts.databases ?? ["devstack"], {
-		field: "databases",
-		message: "postgres(): `databases` must be non-empty",
-		mkError: postgresConfigError
-	});
 	return definePlugin({
 		id: postgresResource.id,
 		role: "service",
+		section: "service",
 		start: () => Effect.gen(function* () {
-			const { handle } = yield* bootPostgresService(yield* ContainerRuntimeService, yield* IdentityContext, opts);
+			const { handle } = yield* bootPostgresService(yield* ContainerRuntimeService, yield* IdentityContext, (yield* StackPathsService).stackRoot, opts);
 			return handle;
-		}).pipe(Effect.catchTags({
-			PostgresPluginError: Effect.fail,
-			PostgresConfigError: Effect.fail,
-			PostgresConnectionTimeout: Effect.fail,
-			DatabaseCreateFailed: Effect.fail
-		}), Effect.catch((cause) => Effect.fail(postgresPluginError("unknown", `postgres(${name}): unknown failure`, cause)))),
+		}).pipe(passthroughOrWrap.for()(POSTGRES_ERROR_TAGS, (cause) => postgresPluginError("unknown", `postgres(${name}): unknown failure`, cause))),
 		errorContributions: postgresErrorContributions,
 		capabilities: ({ value, runtime }) => {
 			const snap = makeSnapshotable({
 				app: runtime.identity.app,
 				stack: runtime.identity.stack,
 				name,
-				databases
+				databases: value.databases
 			});
 			const codegen = makeCodegenable({
 				name,

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

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/plugins/postgres/index.ts"],"sourcesContent":["// Postgres plugin — barrel + `postgres(opts?)` factory.\n//\n// Architecture: Postgres is a topological leaf (no upstream service\n// dependencies) and a single-mode service (local container only;\n// \"live\" modes — Cloud SQL / Neon / RDS — are a deferred decision in\n// the distilled doc, anticipated by the plain-endpoint shape but not\n// implemented). One factory; no mode-narrowed namespace.\n//\n// Capabilities emitted:\n//   1. Snapshotable — container's writable layer (PGDATA-relocated),\n//      identity guard contributes server name + ordered db list.\n//   2. Codegenable — typed connection bindings for user-app code.\n//   3. Routable (TCP, optional) — gated by `opts.route`. When true,\n//      the postgres container fronts the `postgres-tcp` Traefik\n//      entrypoint (host port 5432 by default). Disabled by default to\n//      preserve the existing parallel-stack story (TCP has no Host\n//      header, so an entrypoint serves one backend at a time).\n//      Stacks that want host-side reachability can set `route: true`\n//      OR set `hostPort` directly (the two are mutually exclusive\n//      escape hatches — `route: true` is recommended for in-network\n//      composition with traefik, `hostPort` for direct host-port\n//      publication).\n//\n// Substrate wiring:\n//   - `ContainerRuntimeService` yielded in the acquire body for the\n//     container + image + exec contract.\n//   - `IdentityContext` yielded for the app/stack identity strings.\n//   - `errorContributions` declares POSTGRES_ERROR_TAGS so the\n//     supervisor's harvest loop registers them with the\n//     FormatterRegistry.\n\nimport { Effect } from 'effect';\n\nimport { definePlugin, resource } from '../../api/define-plugin.ts';\nimport { pluginErrorContributions } from '../../api/plugin-errors.ts';\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\nimport type { RoutableDecl } from '../../contracts/routable.ts';\nimport type { SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport { ContainerRuntimeService } from '../../runtime/docker/service.ts';\nimport { expectNonEmptyArray } from '../../substrate/runtime/config-validation.ts';\nimport { IdentityContext } from '../../substrate/runtime/paths.ts';\n\nimport { makeCodegenable } from './codegen.ts';\nimport { POSTGRES_ERROR_TAGS, postgresConfigError, postgresPluginError } from './errors.ts';\nimport { makePostgresRoutable } from './routable.ts';\nimport { bootPostgresService, type Postgres, type PostgresServiceOptions } from './service.ts';\nimport { makeSnapshotable } from './snapshot.ts';\n\ntype PostgresCapabilities =\n\t| readonly [SnapshotableDecl, CodegenableDecl<'postgres-connection'>]\n\t| readonly [SnapshotableDecl, CodegenableDecl<'postgres-connection'>, RoutableDecl];\n\n// ---------------------------------------------------------------------------\n// Resource identity\n// ---------------------------------------------------------------------------\n\n/** The Postgres plugin's resource identity. */\nconst postgresResource = resource<'postgres', Postgres>('postgres');\nconst postgresErrorContributions = pluginErrorContributions(POSTGRES_ERROR_TAGS);\n\n// ---------------------------------------------------------------------------\n// Plugin construction\n// ---------------------------------------------------------------------------\n\n/** User-facing options on top of the service options — currently just\n *  the routable opt-in. We split this out so the service body's\n *  `PostgresServiceOptions` stays focused on container/boot knobs and\n *  the plugin-level surface owns capability gating. */\nexport interface PostgresPluginOptions extends PostgresServiceOptions {\n\t/** When `true`, the plugin contributes a `wireProtocol: 'tcp'`\n\t *  Routable decl that fronts the postgres container on the\n\t *  `postgres-tcp` entrypoint (host port 5432 by default). Default\n\t *  `false` — parallel stacks coexist via the in-network DNS alias\n\t *  and the optional `hostPort` mapping, neither of which involves\n\t *  the router.\n\t *\n\t *  Architecture parallel-stack note: TCP entrypoints serve ONE\n\t *  backend at a time (no Host-header fan-out), so only one stack\n\t *  on the host may set `route: true` at a given moment. The router\n\t *  orchestrator's collision detector fails fast on the second\n\t *  contribution. */\n\treadonly route?: boolean;\n}\n\nconst buildPlugin = (opts: PostgresPluginOptions) => {\n\tconst name = opts.name ?? 'postgres';\n\tconst databases = expectNonEmptyArray(opts.databases ?? ['devstack'], {\n\t\tfield: 'databases',\n\t\tmessage: 'postgres(): `databases` must be non-empty',\n\t\tmkError: postgresConfigError,\n\t});\n\n\treturn definePlugin({\n\t\tid: postgresResource.id,\n\t\trole: 'service',\n\t\tstart: () =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\t// Substrate-context plumbing supplies real\n\t\t\t\t// `ContainerRuntime` + `Identity` instances; the\n\t\t\t\t// supervisor's plugin acquisition path provides these\n\t\t\t\t// before this body runs.\n\t\t\t\tconst runtime = yield* ContainerRuntimeService;\n\t\t\t\tconst identity = yield* IdentityContext;\n\t\t\t\tconst { handle } = yield* bootPostgresService(runtime, identity, opts);\n\t\t\t\treturn handle;\n\t\t\t}).pipe(\n\t\t\t\t// Distilled-doc § Invariants: already-typed errors must\n\t\t\t\t// NOT be re-wrapped by the catch-all unknown handler.\n\t\t\t\t// `catchTag` runs first; anything unknown falls into the\n\t\t\t\t// catch-all and surfaces as `phase: 'unknown'`.\n\t\t\t\tEffect.catchTags({\n\t\t\t\t\tPostgresPluginError: Effect.fail,\n\t\t\t\t\tPostgresConfigError: Effect.fail,\n\t\t\t\t\tPostgresConnectionTimeout: Effect.fail,\n\t\t\t\t\tDatabaseCreateFailed: Effect.fail,\n\t\t\t\t}),\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tEffect.fail(postgresPluginError('unknown', `postgres(${name}): unknown failure`, cause)),\n\t\t\t\t),\n\t\t\t),\n\t\terrorContributions: postgresErrorContributions,\n\t\t// Dynamic capability factory: receives the resolved\n\t\t// `Postgres` handle + acquire context. Stamps the REAL\n\t\t// app/stack into the snapshot decl and the REAL\n\t\t// networkAlias + derived password into the codegen\n\t\t// bindings — the static-form placeholders (`<app>`,\n\t\t// `<stack>`, `<network-alias>`, `<derived-at-acquire>`)\n\t\t// are gone.\n\t\tcapabilities: ({ value, runtime }): PostgresCapabilities => {\n\t\t\tconst snap = makeSnapshotable({\n\t\t\t\tapp: runtime.identity.app,\n\t\t\t\tstack: runtime.identity.stack,\n\t\t\t\tname,\n\t\t\t\tdatabases,\n\t\t\t});\n\t\t\tconst codegen = makeCodegenable({\n\t\t\t\tname,\n\t\t\t\tuser: value.user,\n\t\t\t\tpassword: value.password,\n\t\t\t\thost: value.networkAlias,\n\t\t\t\tport: value.port,\n\t\t\t\tdatabases: value.databases,\n\t\t\t});\n\t\t\tconst routable = opts.route\n\t\t\t\t? makePostgresRoutable({\n\t\t\t\t\t\tapp: runtime.identity.app,\n\t\t\t\t\t\tstack: runtime.identity.stack,\n\t\t\t\t\t\tname,\n\t\t\t\t\t\tcontainerName: `${runtime.identity.app}-${runtime.identity.stack}-${name}`,\n\t\t\t\t\t})\n\t\t\t\t: null;\n\t\t\treturn routable === null ? ([snap, codegen] as const) : ([snap, codegen, routable] as const);\n\t\t},\n\t});\n};\n\n// ---------------------------------------------------------------------------\n// User-facing factory\n// ---------------------------------------------------------------------------\n\n/** Postgres-as-a-container plugin. One per `(stack, name)` pair.\n *\n *  Single-mode: only local container exists today. The plain-endpoint\n *  shape anticipates a future \"live\" mode (Cloud SQL / Neon / RDS)\n *  that emits the same endpoint shape without spawning. */\nexport const postgres = (opts: PostgresPluginOptions = {}) => buildPlugin(opts);\n\n// Re-export the canonical TCP endpoint name for downstream consumers\n// (codegen lookups, doctor / inventory rendering, etc.).\nexport { POSTGRES_TCP_ENDPOINT_NAME } from './routable.ts';\n\n// ---------------------------------------------------------------------------\n// Re-exports for consumers + sibling plugins\n// ---------------------------------------------------------------------------\n\nexport type { Postgres, PostgresServiceOptions } from './service.ts';\nexport type { PostgresConnectionBindings, PostgresConnectionParts } from './connection.ts';\nexport type {\n\tPostgresError,\n\tPostgresPluginError,\n\tPostgresConfigError,\n\tPostgresConnectionTimeout,\n\tDatabaseCreateFailed,\n\tPostgresPhase,\n} from './errors.ts';\nexport { POSTGRES_ERROR_TAGS } from './errors.ts';\nexport type { PostgresIdentityPayload } from './snapshot.ts';\n\n// Connection-string builders — exposed for downstream consumers that\n// need to compose URLs without the resolved handle (e.g. user-app\n// code that reads the codegen output and builds a per-database URL\n// at runtime).\nexport { credentialedUrl, plainUrl, withDatabase } from './connection.ts';\n"],"mappings":";;;;;;;;;;;;;;AAyDA,MAAM,mBAAmB,SAA+B,WAAW;AACnE,MAAM,6BAA6B,yBAAyB,oBAAoB;AA0BhF,MAAM,eAAe,SAAgC;CACpD,MAAM,OAAO,KAAK,QAAQ;CAC1B,MAAM,YAAY,oBAAoB,KAAK,aAAa,CAAC,WAAW,EAAE;EACrE,OAAO;EACP,SAAS;EACT,SAAS;EACT,CAAC;AAEF,QAAO,aAAa;EACnB,IAAI,iBAAiB;EACrB,MAAM;EACN,aACC,OAAO,IAAI,aAAa;GAOvB,MAAM,EAAE,WAAW,OAAO,oBAAoB,OAFvB,yBAEgC,OAD/B,iBACyC,KAAK;AACtE,UAAO;IACN,CAAC,KAKF,OAAO,UAAU;GAChB,qBAAqB,OAAO;GAC5B,qBAAqB,OAAO;GAC5B,2BAA2B,OAAO;GAClC,sBAAsB,OAAO;GAC7B,CAAC,EACF,OAAO,OAAO,UACb,OAAO,KAAK,oBAAoB,WAAW,YAAY,KAAK,qBAAqB,MAAM,CAAC,CACxF,CACD;EACF,oBAAoB;EAQpB,eAAe,EAAE,OAAO,cAAoC;GAC3D,MAAM,OAAO,iBAAiB;IAC7B,KAAK,QAAQ,SAAS;IACtB,OAAO,QAAQ,SAAS;IACxB;IACA;IACA,CAAC;GACF,MAAM,UAAU,gBAAgB;IAC/B;IACA,MAAM,MAAM;IACZ,UAAU,MAAM;IAChB,MAAM,MAAM;IACZ,MAAM,MAAM;IACZ,WAAW,MAAM;IACjB,CAAC;GACF,MAAM,WAAW,KAAK,QACnB,qBAAqB;IACrB,KAAK,QAAQ,SAAS;IACtB,OAAO,QAAQ,SAAS;IACxB;IACA,eAAe,GAAG,QAAQ,SAAS,IAAI,GAAG,QAAQ,SAAS,MAAM,GAAG;IACpE,CAAC,GACD;AACH,UAAO,aAAa,OAAQ,CAAC,MAAM,QAAQ,GAAc;IAAC;IAAM;IAAS;IAAS;;EAEnF,CAAC;;;;;;;AAYH,MAAa,YAAY,OAA8B,EAAE,KAAK,YAAY,KAAK"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/plugins/postgres/index.ts"],"sourcesContent":["// Postgres plugin — barrel + `postgres(opts?)` factory.\n//\n// Architecture: Postgres is a topological leaf (no upstream service\n// dependencies) and a single-mode service (local container only;\n// \"live\" modes — Cloud SQL / Neon / RDS — are a deferred decision in\n// the distilled doc, anticipated by the plain-endpoint shape but not\n// implemented). One factory; no mode-narrowed namespace.\n//\n// Capabilities emitted:\n//   1. Snapshotable — container's writable layer (PGDATA-relocated),\n//      identity guard contributes server name + ordered db list.\n//   2. Codegenable — typed connection bindings for user-app code.\n//   3. Routable (TCP, optional) — gated by `opts.route`. When true,\n//      the postgres container fronts the `postgres-tcp` Traefik\n//      entrypoint (host port 5432 by default). Disabled by default to\n//      preserve the existing parallel-stack story (TCP has no Host\n//      header, so an entrypoint serves one backend at a time).\n//      Stacks that want host-side reachability can set `route: true`\n//      OR set `hostPort` directly (the two are mutually exclusive\n//      escape hatches — `route: true` is recommended for in-network\n//      composition with traefik, `hostPort` for direct host-port\n//      publication).\n//\n// Substrate wiring:\n//   - `ContainerRuntimeService` yielded in the acquire body for the\n//     container + image + exec contract.\n//   - `IdentityContext` yielded for the app/stack identity strings.\n//   - `errorContributions` declares POSTGRES_ERROR_TAGS so the\n//     supervisor's harvest loop registers them with the\n//     FormatterRegistry.\n\nimport { Effect } from 'effect';\n\nimport { definePlugin, resource } from '../../api/define-plugin.ts';\nimport { pluginErrorContributions } from '../../api/plugin-errors.ts';\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\nimport type { RoutableDecl } from '../../contracts/routable.ts';\nimport type { SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport { ContainerRuntimeService } from '../../runtime/docker/service.ts';\nimport { passthroughOrWrap } from '../../substrate/runtime/passthrough-or-wrap.ts';\nimport { IdentityContext, StackPathsService } from '../../substrate/runtime/paths.ts';\n\nimport { makeCodegenable } from './codegen.ts';\nimport { POSTGRES_ERROR_TAGS, postgresPluginError, type PostgresError } from './errors.ts';\nimport { makePostgresRoutable } from './routable.ts';\nimport { bootPostgresService, type Postgres, type PostgresServiceOptions } from './service.ts';\nimport { makeSnapshotable } from './snapshot.ts';\n\ntype PostgresCapabilities =\n\t| readonly [SnapshotableDecl, CodegenableDecl<'postgres-connection'>]\n\t| readonly [SnapshotableDecl, CodegenableDecl<'postgres-connection'>, RoutableDecl];\n\n// ---------------------------------------------------------------------------\n// Resource identity\n// ---------------------------------------------------------------------------\n\n/** The Postgres plugin's resource identity. */\nconst postgresResource = resource<'postgres', Postgres>('postgres');\nconst postgresErrorContributions = pluginErrorContributions(POSTGRES_ERROR_TAGS);\n\n// ---------------------------------------------------------------------------\n// Plugin construction\n// ---------------------------------------------------------------------------\n\n/** User-facing options on top of the service options — currently just\n *  the routable opt-in. We split this out so the service body's\n *  `PostgresServiceOptions` stays focused on container/boot knobs and\n *  the plugin-level surface owns capability gating. */\nexport interface PostgresPluginOptions extends PostgresServiceOptions {\n\t/** When `true`, the plugin contributes a `wireProtocol: 'tcp'`\n\t *  Routable decl that fronts the postgres container on the\n\t *  `postgres-tcp` entrypoint (host port 5432 by default). Default\n\t *  `false` — parallel stacks coexist via the in-network DNS alias\n\t *  and the optional `hostPort` mapping, neither of which involves\n\t *  the router.\n\t *\n\t *  Architecture parallel-stack note: TCP entrypoints serve ONE\n\t *  backend at a time (no Host-header fan-out), so only one stack\n\t *  on the host may set `route: true` at a given moment. The router\n\t *  orchestrator's collision detector fails fast on the second\n\t *  contribution. */\n\treadonly route?: boolean;\n}\n\nconst buildPlugin = (opts: PostgresPluginOptions) => {\n\tconst name = opts.name ?? 'postgres';\n\t// Validation (databases non-empty) runs inside `bootPostgresService` via\n\t// `resolveOptions`; the resolved bundle's `databases` flows through to\n\t// the snapshot + codegen decls.\n\n\treturn definePlugin({\n\t\tid: postgresResource.id,\n\t\trole: 'service',\n\t\tsection: 'service',\n\t\tstart: () =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\t// Substrate-context plumbing supplies real\n\t\t\t\t// `ContainerRuntime` + `Identity` instances; the\n\t\t\t\t// supervisor's plugin acquisition path provides these\n\t\t\t\t// before this body runs.\n\t\t\t\tconst runtime = yield* ContainerRuntimeService;\n\t\t\t\tconst identity = yield* IdentityContext;\n\t\t\t\tconst paths = yield* StackPathsService;\n\t\t\t\tconst { handle } = yield* bootPostgresService(runtime, identity, paths.stackRoot, opts);\n\t\t\t\treturn handle;\n\t\t\t}).pipe(\n\t\t\t\t// Distilled-doc § Invariants: already-typed errors must\n\t\t\t\t// NOT be re-wrapped by the catch-all unknown handler.\n\t\t\t\t// `passthroughOrWrap` lets the POSTGRES_ERROR_TAGS union\n\t\t\t\t// through unchanged; anything else surfaces as\n\t\t\t\t// `phase: 'unknown'`.\n\t\t\t\tpassthroughOrWrap.for<PostgresError>()(POSTGRES_ERROR_TAGS, (cause) =>\n\t\t\t\t\tpostgresPluginError('unknown', `postgres(${name}): unknown failure`, cause),\n\t\t\t\t),\n\t\t\t),\n\t\terrorContributions: postgresErrorContributions,\n\t\t// Dynamic capability factory: receives the resolved\n\t\t// `Postgres` handle + acquire context. Stamps the REAL\n\t\t// app/stack into the snapshot decl and the per-stack\n\t\t// network alias + derived password into the codegen\n\t\t// bindings.\n\t\t//\n\t\t// Codegen `host` is `value.networkAlias` — the per-stack\n\t\t// alias Docker registers via `--network-alias` on the\n\t\t// container's primary network. Dialing the alias resolves\n\t\t// in-container regardless of which parallel stack the\n\t\t// caller belongs to; the per-stack container name still\n\t\t// resolves too, but is not parallel-stack-portable when\n\t\t// emitted into committed codegen output.\n\t\tcapabilities: ({ value, runtime }): PostgresCapabilities => {\n\t\t\tconst snap = makeSnapshotable({\n\t\t\t\tapp: runtime.identity.app,\n\t\t\t\tstack: runtime.identity.stack,\n\t\t\t\tname,\n\t\t\t\tdatabases: value.databases,\n\t\t\t});\n\t\t\tconst codegen = makeCodegenable({\n\t\t\t\tname,\n\t\t\t\tuser: value.user,\n\t\t\t\tpassword: value.password,\n\t\t\t\thost: value.networkAlias,\n\t\t\t\tport: value.port,\n\t\t\t\tdatabases: value.databases,\n\t\t\t});\n\t\t\tconst routable = opts.route\n\t\t\t\t? makePostgresRoutable({\n\t\t\t\t\t\tapp: runtime.identity.app,\n\t\t\t\t\t\tstack: runtime.identity.stack,\n\t\t\t\t\t\tname,\n\t\t\t\t\t\tcontainerName: `${runtime.identity.app}-${runtime.identity.stack}-${name}`,\n\t\t\t\t\t})\n\t\t\t\t: null;\n\t\t\treturn routable === null ? ([snap, codegen] as const) : ([snap, codegen, routable] as const);\n\t\t},\n\t});\n};\n\n// ---------------------------------------------------------------------------\n// User-facing factory\n// ---------------------------------------------------------------------------\n\n/** Postgres-as-a-container plugin. One per `(stack, name)` pair.\n *\n *  Single-mode: only local container exists today. The plain-endpoint\n *  shape anticipates a future \"live\" mode (Cloud SQL / Neon / RDS)\n *  that emits the same endpoint shape without spawning. */\nexport const postgres = (opts: PostgresPluginOptions = {}) => buildPlugin(opts);\n\n// Re-export the canonical TCP endpoint name for downstream consumers\n// (codegen lookups, doctor / inventory rendering, etc.).\nexport { POSTGRES_TCP_ENDPOINT_NAME } from './routable.ts';\n\n// ---------------------------------------------------------------------------\n// Re-exports for consumers + sibling plugins\n// ---------------------------------------------------------------------------\n\nexport type { Postgres, PostgresServiceOptions } from './service.ts';\nexport type { PostgresConnectionBindings, PostgresConnectionParts } from './connection.ts';\nexport type {\n\tPostgresError,\n\tPostgresPluginError,\n\tPostgresConfigError,\n\tPostgresConnectionTimeout,\n\tDatabaseCreateFailed,\n\tPostgresPhase,\n} from './errors.ts';\nexport { POSTGRES_ERROR_TAGS } from './errors.ts';\nexport type { PostgresIdentityPayload } from './snapshot.ts';\n\n// Connection-string builders — exposed for downstream consumers that\n// need to compose URLs without the resolved handle (e.g. user-app\n// code that reads the codegen output and builds a per-database URL\n// at runtime).\nexport { credentialedUrl, plainUrl, withDatabase } from './connection.ts';\n\nexport { PostgresSpans } from './spans.ts';\n"],"mappings":";;;;;;;;;;;;;;;;AAyDA,MAAM,mBAAmB,SAA+B,WAAW;AACnE,MAAM,6BAA6B,yBAAyB,oBAAoB;AA0BhF,MAAM,eAAe,SAAgC;CACpD,MAAM,OAAO,KAAK,QAAQ;AAK1B,QAAO,aAAa;EACnB,IAAI,iBAAiB;EACrB,MAAM;EACN,SAAS;EACT,aACC,OAAO,IAAI,aAAa;GAQvB,MAAM,EAAE,WAAW,OAAO,oBAAoB,OAHvB,yBAGgC,OAF/B,kBAEyC,OAD5C,mBACkD,WAAW,KAAK;AACvF,UAAO;IACN,CAAC,KAMF,kBAAkB,KAAoB,CAAC,sBAAsB,UAC5D,oBAAoB,WAAW,YAAY,KAAK,qBAAqB,MAAM,CAC3E,CACD;EACF,oBAAoB;EAcpB,eAAe,EAAE,OAAO,cAAoC;GAC3D,MAAM,OAAO,iBAAiB;IAC7B,KAAK,QAAQ,SAAS;IACtB,OAAO,QAAQ,SAAS;IACxB;IACA,WAAW,MAAM;IACjB,CAAC;GACF,MAAM,UAAU,gBAAgB;IAC/B;IACA,MAAM,MAAM;IACZ,UAAU,MAAM;IAChB,MAAM,MAAM;IACZ,MAAM,MAAM;IACZ,WAAW,MAAM;IACjB,CAAC;GACF,MAAM,WAAW,KAAK,QACnB,qBAAqB;IACrB,KAAK,QAAQ,SAAS;IACtB,OAAO,QAAQ,SAAS;IACxB;IACA,eAAe,GAAG,QAAQ,SAAS,IAAI,GAAG,QAAQ,SAAS,MAAM,GAAG;IACpE,CAAC,GACD;AACH,UAAO,aAAa,OAAQ,CAAC,MAAM,QAAQ,GAAc;IAAC;IAAM;IAAS;IAAS;;EAEnF,CAAC;;;;;;;AAYH,MAAa,YAAY,OAA8B,EAAE,KAAK,YAAY,KAAK"}

package/dist/plugins/postgres/service.mjs

@@ -1,9 +1,11 @@
-import { expectNonEmptyArray } from "../../substrate/runtime/config-validation.mjs";
 import { ensureManagedContainer } from "../../substrate/runtime/managed-container.mjs";
 import { credentialedUrl, plainUrl, withDatabase } from "./connection.mjs";
 import { postgresConfigError, postgresPluginError } from "./errors.mjs";
+import { PostgresSpans } from "./spans.mjs";
 import { awaitReady, ensureDatabases } from "./db-ensure.mjs";
 import { Effect } from "effect";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
 //#region src/plugins/postgres/service.ts
 const DEFAULT_VERSION = "17-alpine";
 const DEFAULT_USER = "devstack";
@@ -11,27 +13,45 @@ const DEFAULT_DATABASES = ["devstack"];
 const DEFAULT_READY_TIMEOUT_MS = 3e4;
 const DEFAULT_STOP_GRACE_SECONDS = 20;
 const POSTGRES_PORT = 5432;
-/** Deterministic dev password from `(app, stack)`. Tradeoff
+/** Deterministic dev password from `(app, stack, stackRoot)`. Tradeoff
 *  documented in the distilled doc § Postgres-specific concerns:
 *  fine for a single-user dev tool, foot-gun if `hostPort` is set in
 *  a multi-user environment. The user-supplied `password` override on
-*  `PostgresServiceOptions` is the escape hatch. */
-const derivePassword = (app, stack) => `pg-${(app + stack).replace(/[^a-zA-Z0-9]/g, "")}`;
+*  `PostgresServiceOptions` is the escape hatch.
+*
+*  The short hash + separator disambiguate three collision classes:
+*  - (app, stack) pairs whose sanitized concatenation would collide
+*    (e.g. `("my-app", "dev")` vs `("my", "appdev")` both sanitize to
+*    the same body, but the hash binds the unambiguous boundary).
+*  - Two checkouts of the SAME `(app, stack)` on the same machine
+*    (different working directories) — folding `stackRoot` into the
+*    hash means each checkout's postgres password is distinct. (Note:
+*    the `pg_isready` liveness probe does NOT authenticate, so this
+*    does not gate the probe.) The benefit is that the per-checkout
+*    CREDENTIALED endpoint URL — and any `psql`/`createdb` that
+*    actually authenticates — differs per checkout, so one checkout's
+*    connection string cannot silently land on the other's container.
+*  - The `\x1f` (US, ASCII 31) separator between fields is unambiguous
+*    because identity strings and absolute paths cannot legally
+*    contain it. */
+const derivePassword = (app, stack, stackRoot) => {
+	return `pg-${(app + stack).replace(/[^a-zA-Z0-9]/g, "")}-${createHash("sha256").update(`${app}\x1f${stack}\x1f${stackRoot}`).digest("hex").slice(0, 8)}`;
+};
 const sanitizeAlias = (s) => s.replace(/[^a-zA-Z0-9-]/g, "-");
 /** Resolve user-supplied options against defaults + identity-derived
 *  values. Pure; safe to call before the Effect body runs. */
-const resolveOptions = (identity, opts) => {
+const resolveOptions = (identity, stackRoot, opts) => {
 	const name = opts.name ?? "postgres";
-	const databases = expectNonEmptyArray(opts.databases ?? DEFAULT_DATABASES, {
+	const databases = opts.databases ?? DEFAULT_DATABASES;
+	if (!Array.isArray(databases) || databases.length === 0) throw postgresConfigError({
 		field: "databases",
-		message: "postgres(): `databases` must be non-empty",
-		mkError: postgresConfigError
+		message: "postgres(): `databases` must be non-empty"
 	});
 	return {
 		name,
 		version: opts.version ?? DEFAULT_VERSION,
 		user: opts.user ?? DEFAULT_USER,
-		password: opts.password ?? derivePassword(identity.app, identity.stack),
+		password: opts.password ?? derivePassword(identity.app, identity.stack, stackRoot),
 		databases,
 		hostPort: opts.hostPort,
 		extraNetworks: opts.extraNetworks ?? [],
@@ -52,24 +72,29 @@ const resolveOptions = (identity, opts) => {
 *  local to the plugin. */
 const resolveImageContextPath = () => {
 	const here = new URL(import.meta.url);
-	const ctxUrl = new URL("../../../images/postgres/", here);
-	return decodeURIComponent(ctxUrl.pathname);
+	return fileURLToPath(new URL("../../../images/postgres/", here));
 };
 /** Build a `ContainerExec` view bound to a specific container handle.
 *  Thin adapter from the runtime's contract surface to the plugin's
 *  local exec seam. The runtime never promotes non-zero exit to
 *  failure here — the caller (pg_isready retry loop, createdb
-*  existence-check) decides. */
-const containerExec = (runtime, handle) => ({ run: (argv) => runtime.exec(handle, argv).pipe(Effect.catch((err) => Effect.succeed({
-	exitCode: 255,
-	stdout: "",
-	stderr: `runtime.exec failed: ${err.reason} — ${err.detail}`
-}))) });
+*  existence-check) decides.
+*
+*  Daemon-level failures (no such container, daemon unreachable)
+*  surface as a typed `PostgresPluginError({phase: 'container-start'})`
+*  rather than a fabricated `exitCode: 255` ExecResult. STYLE_GUIDE
+*  §16 — typed errors must carry the actual failure shape, not lie
+*  about it being a tx-level non-zero exit. The retry loops in
+*  `awaitReady` / `ensureDatabase` treat the typed failure as
+*  retryable via `waitForProbe`'s default retry behavior; the
+*  underlying cause is preserved on the timeout error's `lastError`
+*  field for the cause walker. */
+const containerExec = (runtime, handle) => ({ run: (argv) => runtime.exec(handle, argv).pipe(Effect.catch((err) => Effect.fail(postgresPluginError("container-start", `runtime.exec failed: ${err.reason} — ${err.detail}`, err)))) });
 /** Boot the postgres service. The barrel composes this with the
 *  capability decls. */
-const bootPostgresService = (runtime, identity, opts) => Effect.gen(function* () {
+const bootPostgresService = (runtime, identity, stackRoot, opts) => Effect.gen(function* () {
 	const resolved = yield* Effect.try({
-		try: () => resolveOptions(identity, opts),
+		try: () => resolveOptions(identity, stackRoot, opts),
 		catch: (cause) => cause
 	});
 	const networkAlias = sanitizeAlias(`${resolved.name}-${identity.stack}`);
@@ -82,7 +107,13 @@ const bootPostgresService = (runtime, identity, opts) => Effect.gen(function* ()
 	const imageRef = yield* runtime.ensureImage({
 		contextPath: resolveImageContextPath(),
 		dockerfile: "Dockerfile",
-		buildArgs: { POSTGRES_VERSION: resolved.version }
+		buildArgs: { POSTGRES_VERSION: resolved.version },
+		owner: {
+			app: identity.app,
+			stack: identity.stack,
+			plugin: "postgres",
+			role: "db"
+		}
 	}).pipe(Effect.catch((cause) => Effect.fail(postgresPluginError("image-build", `failed to build postgres image (${resolved.version})`, cause))));
 	const containerHandle = yield* ensureManagedContainer({
 		runtime,
@@ -103,7 +134,10 @@ const bootPostgresService = (runtime, identity, opts) => Effect.gen(function* ()
 				hostPort: resolved.hostPort
 			}] : void 0,
 			stopGraceSeconds: resolved.stopGraceSeconds,
-			networkAttach: [containerNetwork, ...resolved.extraNetworks]
+			networkAttach: [{
+				name: containerNetwork,
+				aliases: [networkAlias]
+			}, ...resolved.extraNetworks]
 		},
 		mapError: (cause) => postgresPluginError("container-start", `failed to start postgres container '${resolved.name}'`, cause)
 	});
@@ -135,9 +169,9 @@ const bootPostgresService = (runtime, identity, opts) => Effect.gen(function* ()
 		},
 		containerHandle
 	};
-}).pipe(Effect.withSpan("postgres.boot", { attributes: {
-	"postgres.name": opts.name ?? "postgres",
-	"postgres.version": opts.version ?? DEFAULT_VERSION
+}).pipe(Effect.withSpan("devstack.plugin.postgres.boot", { attributes: {
+	[PostgresSpans.name]: opts.name ?? "postgres",
+	[PostgresSpans.version]: opts.version ?? DEFAULT_VERSION
 } }));
 //#endregion
 export { bootPostgresService };

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

@@ -1 +1 @@
-{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/postgres/service.ts"],"sourcesContent":["// Postgres plugin — service body (real boot).\n//\n// Lifecycle (distilled doc § Lifecycle states):\n//   1. Pre-start: identity (app + stack) resolved, deterministic\n//      strings (network name, alias, default password) computed.\n//   2. Per-stack docker network ensured (idempotent; survives the\n//      cycle that creates it).\n//   3. Vendored image ensured. The Dockerfile at\n//      `<package>/images/postgres/Dockerfile` does ONE thing:\n//      `ENV PGDATA=/var/lib/postgresql/data-devstack` so writes land in\n//      the container's writable layer rather than the upstream\n//      `VOLUME /var/lib/postgresql/data` path (which `docker commit`\n//      excludes). This is the single load-bearing invariant for\n//      snapshot integrity.\n//   4. Container started with `POSTGRES_USER` / `POSTGRES_PASSWORD` /\n//      `POSTGRES_DB` env. Joined to the per-stack network under a\n//      deterministic alias. Optional host-port publication.\n//   5. `pg_isready` retry loop runs against the bootstrap database\n//      via `runtime.exec`, bounded by `readyTimeoutMs`.\n//   6. Subsequent databases ensured idempotently via `psql -tAc`\n//      existence-check + `createdb`.\n//   7. Resolved `Postgres` handle returned. The substrate's outer\n//      machinery publishes the manifest projection (plain URL only).\n//\n// What this file does NOT do:\n//   - Pause/unpause around `docker commit` — engine-level (snapshot\n//     orchestrator walks `managedContainers` labels emitted by\n//     `snapshot.ts` and pauses them).\n//   - Manage schema migrations or run init SQL — schema is plugin-\n//     owned by consumers (distilled doc § Generic database-service\n//     requirements: \"no migrations, no init SQL, no schema\n//     management\").\n//   - Register the stop finalizer — `ContainerRuntime.ensureContainer`\n//     owns the container's scope finalizer. The 20s WAL-flush grace is\n//     threaded into the container spec so Docker does not escalate busy\n//     databases at the runtime default.\n\nimport { Duration, Effect, type Scope } from 'effect';\n\nimport type { ContainerHandle, ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport type { Identity } from '../../substrate/identity.ts';\nimport { expectNonEmptyArray } from '../../substrate/runtime/config-validation.ts';\nimport { ensureManagedContainer } from '../../substrate/runtime/managed-container.ts';\nimport {\n\tcredentialedUrl,\n\tplainUrl,\n\twithDatabase,\n\ttype PostgresConnectionParts,\n} from './connection.ts';\nimport { awaitReady, ensureDatabases, type ContainerExec } from './db-ensure.ts';\nimport {\n\tpostgresPluginError,\n\tpostgresConfigError,\n\ttype DatabaseCreateFailed,\n\ttype PostgresConfigError,\n\ttype PostgresConnectionTimeout,\n\ttype PostgresPluginError,\n} from './errors.ts';\n\n/** Resolved Postgres handle — the tag's resolved value.\n *\n *  Distilled doc § Outputs: consumers read this to compose\n *  `DATABASE_URL` strings. `url(db)` is the per-database composer;\n *  `endpoint` is the cluster-level credentialed URL; `plainEndpoint`\n *  is the manifest-safe URL (no password). */\nexport interface Postgres {\n\treadonly name: string;\n\treadonly user: string;\n\t/** Credential. Held in-memory on the resolved value; manifest\n\t *  projection strips it. Logging convention: never `console.log`\n\t *  the entire handle — log `plainEndpoint` instead. */\n\treadonly password: string;\n\treadonly host: string;\n\treadonly port: number;\n\treadonly databases: ReadonlyArray<string>;\n\t/** Cluster-level credentialed URL. */\n\treadonly endpoint: string;\n\t/** Cluster-level no-credentials URL. Manifest-safe. */\n\treadonly plainEndpoint: string;\n\t/** Per-database credentialed URL composer. */\n\treadonly url: (db: string) => string;\n\t/** Per-stack docker network the container is joined to. */\n\treadonly containerNetwork: string;\n\t/** In-network DNS alias siblings dial. */\n\treadonly networkAlias: string;\n}\n\n/** Service options. Defaults track distilled-doc recommendations:\n *  postgres 17-alpine is the latest LTS-stable at the time of writing\n *  (one major up from the v3 service's 16-alpine pin). */\nexport interface PostgresServiceOptions {\n\treadonly name?: string;\n\treadonly version?: string;\n\treadonly user?: string;\n\treadonly password?: string;\n\treadonly databases?: ReadonlyArray<string>;\n\treadonly hostPort?: number;\n\treadonly extraNetworks?: ReadonlyArray<string>;\n\treadonly readyTimeoutMs?: number;\n\t/** WAL-flush budget on `docker stop`. Default 20s (matches the\n\t *  sui-indexer-db sidecar in v3). 10s (docker default) risks\n\t *  SIGKILL on busy DBs → recovery mode on next boot. */\n\treadonly stopGraceSeconds?: number;\n}\n\n/** Internal canonicalised options after defaults applied. */\nexport interface ResolvedPostgresOptions {\n\treadonly name: string;\n\treadonly version: string;\n\treadonly user: string;\n\treadonly password: string;\n\treadonly databases: ReadonlyArray<string>;\n\treadonly hostPort: number | undefined;\n\treadonly extraNetworks: ReadonlyArray<string>;\n\treadonly readyTimeoutMs: number;\n\treadonly stopGraceSeconds: number;\n}\n\nconst DEFAULT_VERSION = '17-alpine';\nconst DEFAULT_USER = 'devstack';\nconst DEFAULT_DATABASES = ['devstack'] as const;\nconst DEFAULT_READY_TIMEOUT_MS = 30_000;\nconst DEFAULT_STOP_GRACE_SECONDS = 20;\nconst POSTGRES_PORT = 5432;\n\n/** Deterministic dev password from `(app, stack)`. Tradeoff\n *  documented in the distilled doc § Postgres-specific concerns:\n *  fine for a single-user dev tool, foot-gun if `hostPort` is set in\n *  a multi-user environment. The user-supplied `password` override on\n *  `PostgresServiceOptions` is the escape hatch. */\nconst derivePassword = (app: string, stack: string): string =>\n\t`pg-${(app + stack).replace(/[^a-zA-Z0-9]/g, '')}`;\n\nconst sanitizeAlias = (s: string): string => s.replace(/[^a-zA-Z0-9-]/g, '-');\n\n/** Resolve user-supplied options against defaults + identity-derived\n *  values. Pure; safe to call before the Effect body runs. */\nexport const resolveOptions = (\n\tidentity: Identity,\n\topts: PostgresServiceOptions,\n): ResolvedPostgresOptions => {\n\tconst name = opts.name ?? 'postgres';\n\tconst databases = expectNonEmptyArray(opts.databases ?? DEFAULT_DATABASES, {\n\t\tfield: 'databases',\n\t\tmessage: 'postgres(): `databases` must be non-empty',\n\t\tmkError: postgresConfigError,\n\t});\n\treturn {\n\t\tname,\n\t\tversion: opts.version ?? DEFAULT_VERSION,\n\t\tuser: opts.user ?? DEFAULT_USER,\n\t\tpassword: opts.password ?? derivePassword(identity.app, identity.stack),\n\t\tdatabases,\n\t\thostPort: opts.hostPort,\n\t\textraNetworks: opts.extraNetworks ?? [],\n\t\treadyTimeoutMs: opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,\n\t\tstopGraceSeconds: opts.stopGraceSeconds ?? DEFAULT_STOP_GRACE_SECONDS,\n\t};\n};\n\n/** Bundled boot result for the barrel. The dynamic-capability factory\n *  projects resolved options + identity-derived strings onto the\n *  snapshot + codegen decls. */\nexport interface PostgresBootResult {\n\treadonly resolved: ResolvedPostgresOptions;\n\treadonly handle: Postgres;\n\treadonly containerHandle: ContainerHandle;\n}\n\n/** Resolve the vendored Dockerfile context path for THIS package.\n *\n *  The build context is the directory containing the Dockerfile\n *  (`<package>/images/postgres/`). We resolve it relative to this\n *  source file via `import.meta.url`, which works in both source\n *  (tsx) and built (.js) form because the layout is preserved.\n *\n *  Distilled doc § Open questions: long-term, this should move to\n *  the substrate's L1 image-build helper so all plugins resolve\n *  their build contexts the same way. For now, the resolution is\n *  local to the plugin. */\nconst resolveImageContextPath = (): string => {\n\t// `import.meta.url` is the URL of this module file. From\n\t// `<pkg>/src/plugins/postgres/service.ts` we walk up three\n\t// directories (`plugins/`, `src/`, `<pkg>/`) and then down into\n\t// `images/postgres/`.\n\tconst here = new URL(import.meta.url);\n\tconst ctxUrl = new URL('../../../images/postgres/', here);\n\t// File: URLs need decoding back to a host path for the docker CLI.\n\treturn decodeURIComponent(ctxUrl.pathname);\n};\n\n/** Build a `ContainerExec` view bound to a specific container handle.\n *  Thin adapter from the runtime's contract surface to the plugin's\n *  local exec seam. The runtime never promotes non-zero exit to\n *  failure here — the caller (pg_isready retry loop, createdb\n *  existence-check) decides. */\nconst containerExec = (runtime: ContainerRuntime, handle: ContainerHandle): ContainerExec => ({\n\trun: (argv) =>\n\t\truntime.exec(handle, argv).pipe(\n\t\t\t// Daemon-level failures (no such container, daemon\n\t\t\t// unreachable) collapse to a synthetic non-zero ExecResult\n\t\t\t// so the retry loop sees them and the typed timeout error\n\t\t\t// carries the daemon stderr as `lastStderr` for the cause\n\t\t\t// walker. We do NOT surface ContainerRuntimeError here —\n\t\t\t// the plugin's typed errors are the only failure shapes\n\t\t\t// `awaitReady` / `ensureDatabases` produce, and they\n\t\t\t// already carry the captured streams.\n\t\t\tEffect.catch((err) =>\n\t\t\t\tEffect.succeed({\n\t\t\t\t\texitCode: 255,\n\t\t\t\t\tstdout: '',\n\t\t\t\t\tstderr: `runtime.exec failed: ${err.reason} — ${err.detail}`,\n\t\t\t\t}),\n\t\t\t),\n\t\t),\n});\n\n/** Boot the postgres service. The barrel composes this with the\n *  capability decls. */\nexport const bootPostgresService = (\n\truntime: ContainerRuntime,\n\tidentity: Identity,\n\topts: PostgresServiceOptions,\n): Effect.Effect<\n\tPostgresBootResult,\n\tPostgresPluginError | PostgresConfigError | PostgresConnectionTimeout | DatabaseCreateFailed,\n\tScope.Scope\n> =>\n\tEffect.gen(function* () {\n\t\tconst resolved = yield* Effect.try({\n\t\t\ttry: () => resolveOptions(identity, opts),\n\t\t\tcatch: (cause) => cause as PostgresConfigError,\n\t\t});\n\n\t\t// Identity-derived strings. The naming pattern must match what\n\t\t// snapshot label-discovery uses — both call sites converge on\n\t\t// `(app, stack, plugin='postgres', role=<name>)`.\n\t\tconst networkAlias = sanitizeAlias(`${resolved.name}-${identity.stack}`);\n\t\tconst containerNetwork = sanitizeAlias(`devstack-${identity.app}-${identity.stack}-postgres`);\n\n\t\t// 1. Ensure the per-stack docker network. Idempotent — no-op\n\t\t//    if the network already exists (warm resume).\n\t\tyield* runtime\n\t\t\t.ensureNetwork({\n\t\t\t\tname: containerNetwork,\n\t\t\t\tapp: identity.app,\n\t\t\t\tstack: identity.stack,\n\t\t\t})\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tpostgresPluginError(\n\t\t\t\t\t\t\t'network-create',\n\t\t\t\t\t\t\t`failed to ensure postgres network '${containerNetwork}'`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\t// 2. Ensure the vendored image. The Dockerfile sets PGDATA off\n\t\t//    the upstream VOLUME path so the writable layer captures\n\t\t//    PGDATA — the single load-bearing snapshot invariant\n\t\t//    (distilled doc § Postgres-specific concerns).\n\t\tconst imageRef = yield* runtime\n\t\t\t.ensureImage({\n\t\t\t\tcontextPath: resolveImageContextPath(),\n\t\t\t\tdockerfile: 'Dockerfile',\n\t\t\t\tbuildArgs: { POSTGRES_VERSION: resolved.version },\n\t\t\t})\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tpostgresPluginError(\n\t\t\t\t\t\t\t'image-build',\n\t\t\t\t\t\t\t`failed to build postgres image (${resolved.version})`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\t// 3. Start container. `networkAttach`'s first entry becomes the\n\t\t//    `--network` flag on `docker run -d`; subsequent entries\n\t\t//    are attached post-start with IP-readback (runtime owns\n\t\t//    that detail).\n\t\t//\n\t\t//    The runtime adapter does NOT yet thread the in-network\n\t\t//    alias through `--network-alias`; the network alias the\n\t\t//    handle exposes is the architecture-mandated value, but\n\t\t//    siblings should dial by `name` (the container name)\n\t\t//    which docker also publishes under the network. The\n\t\t//    architecture revision to add `networkAlias` to\n\t\t//    EnsureContainerSpec is flagged in `index.ts`.\n\t\tconst containerHandle = yield* ensureManagedContainer({\n\t\t\truntime,\n\t\t\tidentity,\n\t\t\tplugin: 'postgres',\n\t\t\trole: resolved.name,\n\t\t\tspec: {\n\t\t\t\tname: `${identity.app}-${identity.stack}-${resolved.name}`,\n\t\t\t\timage: imageRef,\n\t\t\t\trecreate: 'on-config-change',\n\t\t\t\tenv: {\n\t\t\t\t\tPOSTGRES_USER: resolved.user,\n\t\t\t\t\tPOSTGRES_PASSWORD: resolved.password,\n\t\t\t\t\tPOSTGRES_DB: resolved.databases[0]!,\n\t\t\t\t},\n\t\t\t\tports:\n\t\t\t\t\tresolved.hostPort !== undefined\n\t\t\t\t\t\t? [{ containerPort: POSTGRES_PORT, hostPort: resolved.hostPort }]\n\t\t\t\t\t\t: undefined,\n\t\t\t\tstopGraceSeconds: resolved.stopGraceSeconds,\n\t\t\t\tnetworkAttach: [containerNetwork, ...resolved.extraNetworks],\n\t\t\t},\n\t\t\tmapError: (cause) =>\n\t\t\t\tpostgresPluginError(\n\t\t\t\t\t'container-start',\n\t\t\t\t\t`failed to start postgres container '${resolved.name}'`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t});\n\n\t\t// 4. Probe readiness via `pg_isready` against the bootstrap\n\t\t//    database. Server-aware probe — distilled doc § Postgres-\n\t\t//    specific concerns: TCP-listener readiness alone is\n\t\t//    insufficient (postgres opens the port before accepting\n\t\t//    queries).\n\t\tconst exec = containerExec(runtime, containerHandle);\n\t\tyield* awaitReady(exec, resolved.user, resolved.databases[0]!, resolved.readyTimeoutMs);\n\n\t\t// 5. Ensure subsequent databases idempotently. The bootstrap\n\t\t//    database (index 0) is image-entrypoint-created via\n\t\t//    POSTGRES_DB and skipped by `ensureDatabases`.\n\t\tyield* ensureDatabases(exec, resolved.user, resolved.databases);\n\n\t\t// 6. Resolve the handle. Host for in-stack siblings is the\n\t\t//    container name (which docker registers as a DNS entry on\n\t\t//    the attached network). When the substrate's\n\t\t//    `networkAlias` plumbing lands we'll swap to that; until\n\t\t//    then the container name is the stable in-network handle.\n\t\tconst dnsName = `${identity.app}-${identity.stack}-${resolved.name}`;\n\t\tconst parts: PostgresConnectionParts = {\n\t\t\tuser: resolved.user,\n\t\t\tpassword: resolved.password,\n\t\t\thost: dnsName,\n\t\t\tport: POSTGRES_PORT,\n\t\t};\n\t\tconst endpoint = credentialedUrl(parts);\n\t\tconst plainEndpoint = plainUrl(dnsName, POSTGRES_PORT);\n\n\t\tconst handle: Postgres = {\n\t\t\tname: resolved.name,\n\t\t\tuser: resolved.user,\n\t\t\tpassword: resolved.password,\n\t\t\thost: dnsName,\n\t\t\tport: POSTGRES_PORT,\n\t\t\tdatabases: resolved.databases,\n\t\t\tendpoint,\n\t\t\tplainEndpoint,\n\t\t\turl: (db) => withDatabase(endpoint, db),\n\t\t\tcontainerNetwork,\n\t\t\tnetworkAlias,\n\t\t};\n\n\t\treturn { resolved, handle, containerHandle };\n\t}).pipe(\n\t\tEffect.withSpan('postgres.boot', {\n\t\t\tattributes: {\n\t\t\t\t'postgres.name': opts.name ?? 'postgres',\n\t\t\t\t'postgres.version': opts.version ?? DEFAULT_VERSION,\n\t\t\t},\n\t\t}),\n\t);\n\n/** Stop-grace duration. The substrate's finalizer plumbing reads this\n *  to set the docker-stop SIGTERM→SIGKILL window. 20s default avoids\n *  busy-DB SIGKILL → recovery-mode on next boot. */\nexport const stopGrace = (resolved: ResolvedPostgresOptions): Duration.Duration =>\n\tDuration.seconds(resolved.stopGraceSeconds);\n"],"mappings":";;;;;;;AAsHA,MAAM,kBAAkB;AACxB,MAAM,eAAe;AACrB,MAAM,oBAAoB,CAAC,WAAW;AACtC,MAAM,2BAA2B;AACjC,MAAM,6BAA6B;AACnC,MAAM,gBAAgB;;;;;;AAOtB,MAAM,kBAAkB,KAAa,UACpC,OAAO,MAAM,OAAO,QAAQ,iBAAiB,GAAG;AAEjD,MAAM,iBAAiB,MAAsB,EAAE,QAAQ,kBAAkB,IAAI;;;AAI7E,MAAa,kBACZ,UACA,SAC6B;CAC7B,MAAM,OAAO,KAAK,QAAQ;CAC1B,MAAM,YAAY,oBAAoB,KAAK,aAAa,mBAAmB;EAC1E,OAAO;EACP,SAAS;EACT,SAAS;EACT,CAAC;AACF,QAAO;EACN;EACA,SAAS,KAAK,WAAW;EACzB,MAAM,KAAK,QAAQ;EACnB,UAAU,KAAK,YAAY,eAAe,SAAS,KAAK,SAAS,MAAM;EACvE;EACA,UAAU,KAAK;EACf,eAAe,KAAK,iBAAiB,EAAE;EACvC,gBAAgB,KAAK,kBAAkB;EACvC,kBAAkB,KAAK,oBAAoB;EAC3C;;;;;;;;;;;;;AAuBF,MAAM,gCAAwC;CAK7C,MAAM,OAAO,IAAI,IAAI,OAAO,KAAK,IAAI;CACrC,MAAM,SAAS,IAAI,IAAI,6BAA6B,KAAK;AAEzD,QAAO,mBAAmB,OAAO,SAAS;;;;;;;AAQ3C,MAAM,iBAAiB,SAA2B,YAA4C,EAC7F,MAAM,SACL,QAAQ,KAAK,QAAQ,KAAK,CAAC,KAS1B,OAAO,OAAO,QACb,OAAO,QAAQ;CACd,UAAU;CACV,QAAQ;CACR,QAAQ,wBAAwB,IAAI,OAAO,KAAK,IAAI;CACpD,CAAC,CACF,CACD,EACF;;;AAID,MAAa,uBACZ,SACA,UACA,SAMA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,OAAO,IAAI;EAClC,WAAW,eAAe,UAAU,KAAK;EACzC,QAAQ,UAAU;EAClB,CAAC;CAKF,MAAM,eAAe,cAAc,GAAG,SAAS,KAAK,GAAG,SAAS,QAAQ;CACxE,MAAM,mBAAmB,cAAc,YAAY,SAAS,IAAI,GAAG,SAAS,MAAM,WAAW;AAI7F,QAAO,QACL,cAAc;EACd,MAAM;EACN,KAAK,SAAS;EACd,OAAO,SAAS;EAChB,CAAC,CACD,KACA,OAAO,OAAO,UACb,OAAO,KACN,oBACC,kBACA,sCAAsC,iBAAiB,IACvD,MACA,CACD,CACD,CACD;CAMF,MAAM,WAAW,OAAO,QACtB,YAAY;EACZ,aAAa,yBAAyB;EACtC,YAAY;EACZ,WAAW,EAAE,kBAAkB,SAAS,SAAS;EACjD,CAAC,CACD,KACA,OAAO,OAAO,UACb,OAAO,KACN,oBACC,eACA,mCAAmC,SAAS,QAAQ,IACpD,MACA,CACD,CACD,CACD;CAcF,MAAM,kBAAkB,OAAO,uBAAuB;EACrD;EACA;EACA,QAAQ;EACR,MAAM,SAAS;EACf,MAAM;GACL,MAAM,GAAG,SAAS,IAAI,GAAG,SAAS,MAAM,GAAG,SAAS;GACpD,OAAO;GACP,UAAU;GACV,KAAK;IACJ,eAAe,SAAS;IACxB,mBAAmB,SAAS;IAC5B,aAAa,SAAS,UAAU;IAChC;GACD,OACC,SAAS,aAAa,KAAA,IACnB,CAAC;IAAE,eAAe;IAAe,UAAU,SAAS;IAAU,CAAC,GAC/D,KAAA;GACJ,kBAAkB,SAAS;GAC3B,eAAe,CAAC,kBAAkB,GAAG,SAAS,cAAc;GAC5D;EACD,WAAW,UACV,oBACC,mBACA,uCAAuC,SAAS,KAAK,IACrD,MACA;EACF,CAAC;CAOF,MAAM,OAAO,cAAc,SAAS,gBAAgB;AACpD,QAAO,WAAW,MAAM,SAAS,MAAM,SAAS,UAAU,IAAK,SAAS,eAAe;AAKvF,QAAO,gBAAgB,MAAM,SAAS,MAAM,SAAS,UAAU;CAO/D,MAAM,UAAU,GAAG,SAAS,IAAI,GAAG,SAAS,MAAM,GAAG,SAAS;CAO9D,MAAM,WAAW,gBAAgB;EALhC,MAAM,SAAS;EACf,UAAU,SAAS;EACnB,MAAM;EACN,MAAM;EAE+B,CAAC;CACvC,MAAM,gBAAgB,SAAS,SAAS,cAAc;AAgBtD,QAAO;EAAE;EAAU,QAAA;GAblB,MAAM,SAAS;GACf,MAAM,SAAS;GACf,UAAU,SAAS;GACnB,MAAM;GACN,MAAM;GACN,WAAW,SAAS;GACpB;GACA;GACA,MAAM,OAAO,aAAa,UAAU,GAAG;GACvC;GACA;GAGwB;EAAE;EAAiB;EAC3C,CAAC,KACF,OAAO,SAAS,iBAAiB,EAChC,YAAY;CACX,iBAAiB,KAAK,QAAQ;CAC9B,oBAAoB,KAAK,WAAW;CACpC,EACD,CAAC,CACF"}
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/postgres/service.ts"],"sourcesContent":["// Postgres plugin — service body (real boot).\n//\n// Lifecycle (distilled doc § Lifecycle states):\n//   1. Pre-start: identity (app + stack) resolved, deterministic\n//      strings (network name, alias, default password) computed.\n//   2. Per-stack docker network ensured (idempotent; survives the\n//      cycle that creates it).\n//   3. Vendored image ensured. The Dockerfile at\n//      `<package>/images/postgres/Dockerfile` does ONE thing:\n//      `ENV PGDATA=/var/lib/postgresql/data-devstack` so writes land in\n//      the container's writable layer rather than the upstream\n//      `VOLUME /var/lib/postgresql/data` path (which `docker commit`\n//      excludes). This is the single load-bearing invariant for\n//      snapshot integrity.\n//   4. Container started with `POSTGRES_USER` / `POSTGRES_PASSWORD` /\n//      `POSTGRES_DB` env. Joined to the per-stack network under a\n//      deterministic alias. Optional host-port publication.\n//   5. `pg_isready` retry loop runs against the bootstrap database\n//      via `runtime.exec`, bounded by `readyTimeoutMs`.\n//   6. Subsequent databases ensured idempotently via `psql -tAc`\n//      existence-check + `createdb`.\n//   7. Resolved `Postgres` handle returned. The substrate's outer\n//      machinery publishes the manifest projection (plain URL only).\n//\n// What this file does NOT do:\n//   - Pause/unpause around `docker commit` — engine-level (snapshot\n//     orchestrator walks `managedContainers` labels emitted by\n//     `snapshot.ts` and pauses them).\n//   - Manage schema migrations or run init SQL — schema is plugin-\n//     owned by consumers (distilled doc § Generic database-service\n//     requirements: \"no migrations, no init SQL, no schema\n//     management\").\n//   - Register the stop finalizer — `ContainerRuntime.ensureContainer`\n//     owns the container's scope finalizer. The 20s WAL-flush grace is\n//     threaded into the container spec so Docker does not escalate busy\n//     databases at the runtime default.\n\nimport { Duration, Effect, type Scope } from 'effect';\nimport { createHash } from 'node:crypto';\nimport { fileURLToPath } from 'node:url';\n\nimport type { ContainerHandle, ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport type { Identity } from '../../substrate/identity.ts';\nimport { ensureManagedContainer } from '../../substrate/runtime/managed-container.ts';\nimport {\n\tcredentialedUrl,\n\tplainUrl,\n\twithDatabase,\n\ttype PostgresConnectionParts,\n} from './connection.ts';\nimport { awaitReady, ensureDatabases, type ContainerExec } from './db-ensure.ts';\nimport {\n\tpostgresPluginError,\n\tpostgresConfigError,\n\ttype DatabaseCreateFailed,\n\ttype PostgresConfigError,\n\ttype PostgresConnectionTimeout,\n\ttype PostgresPluginError,\n} from './errors.ts';\nimport { PostgresSpans } from './spans.ts';\n\n/** Resolved Postgres handle — the tag's resolved value.\n *\n *  Distilled doc § Outputs: consumers read this to compose\n *  `DATABASE_URL` strings. `url(db)` is the per-database composer;\n *  `endpoint` is the cluster-level credentialed URL; `plainEndpoint`\n *  is the manifest-safe URL (no password). */\nexport interface Postgres {\n\treadonly name: string;\n\treadonly user: string;\n\t/** Credential. Held in-memory on the resolved value; manifest\n\t *  projection strips it. Logging convention: never `console.log`\n\t *  the entire handle — log `plainEndpoint` instead. */\n\treadonly password: string;\n\treadonly host: string;\n\treadonly port: number;\n\treadonly databases: ReadonlyArray<string>;\n\t/** Cluster-level credentialed URL. */\n\treadonly endpoint: string;\n\t/** Cluster-level no-credentials URL. Manifest-safe. */\n\treadonly plainEndpoint: string;\n\t/** Per-database credentialed URL composer. */\n\treadonly url: (db: string) => string;\n\t/** Per-stack docker network the container is joined to. */\n\treadonly containerNetwork: string;\n\t/** In-network DNS alias siblings dial. */\n\treadonly networkAlias: string;\n}\n\n/** Service options. Defaults track distilled-doc recommendations:\n *  postgres 17-alpine is the latest LTS-stable at the time of writing\n *  (one major up from the v3 service's 16-alpine pin). */\nexport interface PostgresServiceOptions {\n\treadonly name?: string;\n\treadonly version?: string;\n\treadonly user?: string;\n\treadonly password?: string;\n\treadonly databases?: ReadonlyArray<string>;\n\treadonly hostPort?: number;\n\treadonly extraNetworks?: ReadonlyArray<string>;\n\treadonly readyTimeoutMs?: number;\n\t/** WAL-flush budget on `docker stop`. Default 20s (matches the\n\t *  sui-indexer-db sidecar in v3). 10s (docker default) risks\n\t *  SIGKILL on busy DBs → recovery mode on next boot. */\n\treadonly stopGraceSeconds?: number;\n}\n\n/** Internal canonicalised options after defaults applied. */\nexport interface ResolvedPostgresOptions {\n\treadonly name: string;\n\treadonly version: string;\n\treadonly user: string;\n\treadonly password: string;\n\treadonly databases: ReadonlyArray<string>;\n\treadonly hostPort: number | undefined;\n\treadonly extraNetworks: ReadonlyArray<string>;\n\treadonly readyTimeoutMs: number;\n\treadonly stopGraceSeconds: number;\n}\n\nconst DEFAULT_VERSION = '17-alpine';\nconst DEFAULT_USER = 'devstack';\nconst DEFAULT_DATABASES = ['devstack'] as const;\nconst DEFAULT_READY_TIMEOUT_MS = 30_000;\nconst DEFAULT_STOP_GRACE_SECONDS = 20;\nconst POSTGRES_PORT = 5432;\n\n/** Deterministic dev password from `(app, stack, stackRoot)`. Tradeoff\n *  documented in the distilled doc § Postgres-specific concerns:\n *  fine for a single-user dev tool, foot-gun if `hostPort` is set in\n *  a multi-user environment. The user-supplied `password` override on\n *  `PostgresServiceOptions` is the escape hatch.\n *\n *  The short hash + separator disambiguate three collision classes:\n *  - (app, stack) pairs whose sanitized concatenation would collide\n *    (e.g. `(\"my-app\", \"dev\")` vs `(\"my\", \"appdev\")` both sanitize to\n *    the same body, but the hash binds the unambiguous boundary).\n *  - Two checkouts of the SAME `(app, stack)` on the same machine\n *    (different working directories) — folding `stackRoot` into the\n *    hash means each checkout's postgres password is distinct. (Note:\n *    the `pg_isready` liveness probe does NOT authenticate, so this\n *    does not gate the probe.) The benefit is that the per-checkout\n *    CREDENTIALED endpoint URL — and any `psql`/`createdb` that\n *    actually authenticates — differs per checkout, so one checkout's\n *    connection string cannot silently land on the other's container.\n *  - The `\\x1f` (US, ASCII 31) separator between fields is unambiguous\n *    because identity strings and absolute paths cannot legally\n *    contain it. */\nexport const derivePassword = (app: string, stack: string, stackRoot: string): string => {\n\tconst body = (app + stack).replace(/[^a-zA-Z0-9]/g, '');\n\tconst fingerprint = createHash('sha256')\n\t\t.update(`${app}\\x1f${stack}\\x1f${stackRoot}`)\n\t\t.digest('hex')\n\t\t.slice(0, 8);\n\treturn `pg-${body}-${fingerprint}`;\n};\n\nconst sanitizeAlias = (s: string): string => s.replace(/[^a-zA-Z0-9-]/g, '-');\n\n/** Resolve user-supplied options against defaults + identity-derived\n *  values. Pure; safe to call before the Effect body runs. */\nexport const resolveOptions = (\n\tidentity: Identity,\n\tstackRoot: string,\n\topts: PostgresServiceOptions,\n): ResolvedPostgresOptions => {\n\tconst name = opts.name ?? 'postgres';\n\tconst databases = opts.databases ?? DEFAULT_DATABASES;\n\tif (!Array.isArray(databases) || databases.length === 0) {\n\t\tthrow postgresConfigError({\n\t\t\tfield: 'databases',\n\t\t\tmessage: 'postgres(): `databases` must be non-empty',\n\t\t});\n\t}\n\treturn {\n\t\tname,\n\t\tversion: opts.version ?? DEFAULT_VERSION,\n\t\tuser: opts.user ?? DEFAULT_USER,\n\t\tpassword: opts.password ?? derivePassword(identity.app, identity.stack, stackRoot),\n\t\tdatabases,\n\t\thostPort: opts.hostPort,\n\t\textraNetworks: opts.extraNetworks ?? [],\n\t\treadyTimeoutMs: opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,\n\t\tstopGraceSeconds: opts.stopGraceSeconds ?? DEFAULT_STOP_GRACE_SECONDS,\n\t};\n};\n\n/** Bundled boot result for the barrel. The dynamic-capability factory\n *  projects resolved options + identity-derived strings onto the\n *  snapshot + codegen decls. */\nexport interface PostgresBootResult {\n\treadonly resolved: ResolvedPostgresOptions;\n\treadonly handle: Postgres;\n\treadonly containerHandle: ContainerHandle;\n}\n\n/** Resolve the vendored Dockerfile context path for THIS package.\n *\n *  The build context is the directory containing the Dockerfile\n *  (`<package>/images/postgres/`). We resolve it relative to this\n *  source file via `import.meta.url`, which works in both source\n *  (tsx) and built (.js) form because the layout is preserved.\n *\n *  Distilled doc § Open questions: long-term, this should move to\n *  the substrate's L1 image-build helper so all plugins resolve\n *  their build contexts the same way. For now, the resolution is\n *  local to the plugin. */\nconst resolveImageContextPath = (): string => {\n\t// `import.meta.url` is the URL of this module file. From\n\t// `<pkg>/src/plugins/postgres/service.ts` we walk up three\n\t// directories (`plugins/`, `src/`, `<pkg>/`) and then down into\n\t// `images/postgres/`.\n\tconst here = new URL(import.meta.url);\n\tconst ctxUrl = new URL('../../../images/postgres/', here);\n\t// `fileURLToPath` handles the platform-specific decode (the\n\t// `file:///C:/...` → `C:\\...` round-trip on Windows, plus\n\t// percent-decoding everywhere). `decodeURIComponent(pathname)`\n\t// would leave the leading `/` on Windows paths.\n\treturn fileURLToPath(ctxUrl);\n};\n\n/** Build a `ContainerExec` view bound to a specific container handle.\n *  Thin adapter from the runtime's contract surface to the plugin's\n *  local exec seam. The runtime never promotes non-zero exit to\n *  failure here — the caller (pg_isready retry loop, createdb\n *  existence-check) decides.\n *\n *  Daemon-level failures (no such container, daemon unreachable)\n *  surface as a typed `PostgresPluginError({phase: 'container-start'})`\n *  rather than a fabricated `exitCode: 255` ExecResult. STYLE_GUIDE\n *  §16 — typed errors must carry the actual failure shape, not lie\n *  about it being a tx-level non-zero exit. The retry loops in\n *  `awaitReady` / `ensureDatabase` treat the typed failure as\n *  retryable via `waitForProbe`'s default retry behavior; the\n *  underlying cause is preserved on the timeout error's `lastError`\n *  field for the cause walker. */\nconst containerExec = (runtime: ContainerRuntime, handle: ContainerHandle): ContainerExec => ({\n\trun: (argv) =>\n\t\truntime.exec(handle, argv).pipe(\n\t\t\tEffect.catch((err) =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\tpostgresPluginError(\n\t\t\t\t\t\t'container-start',\n\t\t\t\t\t\t`runtime.exec failed: ${err.reason} — ${err.detail}`,\n\t\t\t\t\t\terr,\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t),\n\t\t),\n});\n\n/** Boot the postgres service. The barrel composes this with the\n *  capability decls. */\nexport const bootPostgresService = (\n\truntime: ContainerRuntime,\n\tidentity: Identity,\n\tstackRoot: string,\n\topts: PostgresServiceOptions,\n): Effect.Effect<\n\tPostgresBootResult,\n\tPostgresPluginError | PostgresConfigError | PostgresConnectionTimeout | DatabaseCreateFailed,\n\tScope.Scope\n> =>\n\tEffect.gen(function* () {\n\t\tconst resolved = yield* Effect.try({\n\t\t\ttry: () => resolveOptions(identity, stackRoot, opts),\n\t\t\tcatch: (cause) => cause as PostgresConfigError,\n\t\t});\n\n\t\t// Identity-derived strings. The naming pattern must match what\n\t\t// snapshot label-discovery uses — both call sites converge on\n\t\t// `(app, stack, plugin='postgres', role=<name>)`.\n\t\tconst networkAlias = sanitizeAlias(`${resolved.name}-${identity.stack}`);\n\t\tconst containerNetwork = sanitizeAlias(`devstack-${identity.app}-${identity.stack}-postgres`);\n\n\t\t// 1. Ensure the per-stack docker network. Idempotent — no-op\n\t\t//    if the network already exists (warm resume).\n\t\tyield* runtime\n\t\t\t.ensureNetwork({\n\t\t\t\tname: containerNetwork,\n\t\t\t\tapp: identity.app,\n\t\t\t\tstack: identity.stack,\n\t\t\t})\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tpostgresPluginError(\n\t\t\t\t\t\t\t'network-create',\n\t\t\t\t\t\t\t`failed to ensure postgres network '${containerNetwork}'`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\t// 2. Ensure the vendored image. The Dockerfile sets PGDATA off\n\t\t//    the upstream VOLUME path so the writable layer captures\n\t\t//    PGDATA — the single load-bearing snapshot invariant\n\t\t//    (distilled doc § Postgres-specific concerns).\n\t\tconst imageRef = yield* runtime\n\t\t\t.ensureImage({\n\t\t\t\tcontextPath: resolveImageContextPath(),\n\t\t\t\tdockerfile: 'Dockerfile',\n\t\t\t\tbuildArgs: { POSTGRES_VERSION: resolved.version },\n\t\t\t\towner: { app: identity.app, stack: identity.stack, plugin: 'postgres', role: 'db' },\n\t\t\t})\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tpostgresPluginError(\n\t\t\t\t\t\t\t'image-build',\n\t\t\t\t\t\t\t`failed to build postgres image (${resolved.version})`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\n\t\t// 3. Start container. `networkAttach`'s first entry becomes the\n\t\t//    `--network` flag on `docker run -d`; subsequent entries\n\t\t//    are attached post-start with IP-readback (runtime owns\n\t\t//    that detail). The first attach carries the per-network\n\t\t//    DNS alias (`networkAlias`) — Docker registers it as a\n\t\t//    secondary DNS name on the per-stack network so siblings\n\t\t//    can dial by the parallel-stack-stable alias rather than\n\t\t//    the per-stack container name.\n\t\tconst containerHandle = yield* ensureManagedContainer({\n\t\t\truntime,\n\t\t\tidentity,\n\t\t\tplugin: 'postgres',\n\t\t\trole: resolved.name,\n\t\t\tspec: {\n\t\t\t\tname: `${identity.app}-${identity.stack}-${resolved.name}`,\n\t\t\t\timage: imageRef,\n\t\t\t\trecreate: 'on-config-change',\n\t\t\t\tenv: {\n\t\t\t\t\tPOSTGRES_USER: resolved.user,\n\t\t\t\t\tPOSTGRES_PASSWORD: resolved.password,\n\t\t\t\t\tPOSTGRES_DB: resolved.databases[0]!,\n\t\t\t\t},\n\t\t\t\tports:\n\t\t\t\t\tresolved.hostPort !== undefined\n\t\t\t\t\t\t? [{ containerPort: POSTGRES_PORT, hostPort: resolved.hostPort }]\n\t\t\t\t\t\t: undefined,\n\t\t\t\tstopGraceSeconds: resolved.stopGraceSeconds,\n\t\t\t\tnetworkAttach: [\n\t\t\t\t\t{ name: containerNetwork, aliases: [networkAlias] },\n\t\t\t\t\t...resolved.extraNetworks,\n\t\t\t\t],\n\t\t\t},\n\t\t\tmapError: (cause) =>\n\t\t\t\tpostgresPluginError(\n\t\t\t\t\t'container-start',\n\t\t\t\t\t`failed to start postgres container '${resolved.name}'`,\n\t\t\t\t\tcause,\n\t\t\t\t),\n\t\t});\n\n\t\t// 4. Probe readiness via `pg_isready` against the bootstrap\n\t\t//    database. Server-aware probe — distilled doc § Postgres-\n\t\t//    specific concerns: TCP-listener readiness alone is\n\t\t//    insufficient (postgres opens the port before accepting\n\t\t//    queries).\n\t\tconst exec = containerExec(runtime, containerHandle);\n\t\tyield* awaitReady(exec, resolved.user, resolved.databases[0]!, resolved.readyTimeoutMs);\n\n\t\t// 5. Ensure subsequent databases idempotently. The bootstrap\n\t\t//    database (index 0) is image-entrypoint-created via\n\t\t//    POSTGRES_DB and skipped by `ensureDatabases`.\n\t\tyield* ensureDatabases(exec, resolved.user, resolved.databases);\n\n\t\t// 6. Resolve the handle. Host for in-stack siblings is the\n\t\t//    container DNS name (always resolves on the attached\n\t\t//    network). The per-stack `networkAlias` is registered via\n\t\t//    `--network-alias` on the primary attach (see step 3) and\n\t\t//    is the parallel-stack-portable DNS name; codegen consumes\n\t\t//    it through `index.ts`.\n\t\tconst dnsName = `${identity.app}-${identity.stack}-${resolved.name}`;\n\t\tconst parts: PostgresConnectionParts = {\n\t\t\tuser: resolved.user,\n\t\t\tpassword: resolved.password,\n\t\t\thost: dnsName,\n\t\t\tport: POSTGRES_PORT,\n\t\t};\n\t\tconst endpoint = credentialedUrl(parts);\n\t\tconst plainEndpoint = plainUrl(dnsName, POSTGRES_PORT);\n\n\t\tconst handle: Postgres = {\n\t\t\tname: resolved.name,\n\t\t\tuser: resolved.user,\n\t\t\tpassword: resolved.password,\n\t\t\thost: dnsName,\n\t\t\tport: POSTGRES_PORT,\n\t\t\tdatabases: resolved.databases,\n\t\t\tendpoint,\n\t\t\tplainEndpoint,\n\t\t\turl: (db) => withDatabase(endpoint, db),\n\t\t\tcontainerNetwork,\n\t\t\tnetworkAlias,\n\t\t};\n\n\t\treturn { resolved, handle, containerHandle };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.postgres.boot', {\n\t\t\tattributes: {\n\t\t\t\t[PostgresSpans.name]: opts.name ?? 'postgres',\n\t\t\t\t[PostgresSpans.version]: opts.version ?? DEFAULT_VERSION,\n\t\t\t},\n\t\t}),\n\t);\n\n/** Stop-grace duration. The substrate's finalizer plumbing reads this\n *  to set the docker-stop SIGTERM→SIGKILL window. 20s default avoids\n *  busy-DB SIGKILL → recovery-mode on next boot. */\nexport const stopGrace = (resolved: ResolvedPostgresOptions): Duration.Duration =>\n\tDuration.seconds(resolved.stopGraceSeconds);\n"],"mappings":"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"}