@mysten-incubation/devstack 0.0.0

package/dist/plugins/package/registry.mjs

@@ -0,0 +1,30 @@
+import { defineScopedRefMap } from "../../substrate/runtime/scoped-ref-map/service.mjs";
+import { Context, Effect, Layer } from "effect";
+//#region src/plugins/package/registry.ts
+const PackageRefMap = defineScopedRefMap("PackageRegistry");
+const wrapRefMap = (refMap) => ({
+	set: refMap.set,
+	find: refMap.find,
+	has: refMap.has,
+	entries: refMap.entries,
+	changes: refMap.changes
+});
+/** 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") {};
+/** 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
+*  SAME instance via Context. */
+const layerPackageRegistry = Layer.effect(PackageRegistryService, Effect.gen(function* () {
+	const refMap = yield* PackageRefMap.Service;
+	return PackageRegistryService.of(wrapRefMap(refMap));
+})).pipe(Layer.provide(PackageRefMap.layer));
+/** Capability-key constant for the per-stack registry — siblings
+*  (Coin, Action, manifest emitter, faucet strategies) look it up
+*  through the StrategyContributor registry. */
+const PACKAGE_REGISTRY_CAPABILITY_KEY = "package-registry";
+//#endregion
+export { PACKAGE_REGISTRY_CAPABILITY_KEY, PackageRegistryService, layerPackageRegistry };
+
+//# sourceMappingURL=registry.mjs.map

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

@@ -0,0 +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"}

package/dist/plugins/package/service.mjs

@@ -0,0 +1,20 @@
+import { acquireKnown } from "./mode-known.mjs";
+import { acquireLocal } from "./mode-local.mjs";
+import { Effect } from "effect";
+//#region src/plugins/package/service.ts
+function bootPackageService(publisher, probe, registry, opts) {
+	switch (opts.mode) {
+		case "local": return acquireLocal(publisher, probe, registry, opts).pipe(Effect.map(({ resolved, output }) => ({
+			resolved,
+			output
+		})));
+		case "known": return acquireKnown(probe, registry, opts).pipe(Effect.map(({ resolved }) => ({
+			resolved,
+			output: null
+		})));
+	}
+}
+//#endregion
+export { bootPackageService };
+
+//# sourceMappingURL=service.mjs.map

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

@@ -0,0 +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"}

package/dist/plugins/package/snapshot.mjs

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+//#region src/plugins/package/snapshot.ts
+/** Build the Snapshotable contribution.
+*
+*  Identity guard: contributes the package's symbolic name + content
+*  hash to the pre-restore identity record. A snapshot taken under
+*  source-hash A restored against source-hash A is OK (verify probe
+*  re-confirms); a mismatch lets the substrate decide (typically:
+*  also OK — re-publish). The identity guard is mostly informational
+*  here. */
+const makeSnapshotable = (packageName, sourceHash) => ({
+	kind: "snapshotable",
+	subtrees: [],
+	missingTolerance: "fine",
+	preRestore: Effect.succeed({
+		kind: "package",
+		name: packageName,
+		sourceHash
+	}),
+	postRestore: Effect.void
+});
+//#endregion
+export { makeSnapshotable };
+
+//# sourceMappingURL=snapshot.mjs.map

package/dist/plugins/package/snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../src/plugins/package/snapshot.ts"],"sourcesContent":["// Package plugin — Snapshotable contribution.\n//\n// Distilled doc §Cross-component references §snapshot: \"persisted\n// Package cache entries survive snapshot save/restore; the chain\n// containers are tarred separately and on restore the verify probe\n// re-confirms.\"\n//\n// The Package plugin OWNS the publishMove cache entries in the\n// StateStore — those land under the substrate's runtime-dir root\n// at `state-store/<plugin-key>/...` and are auto-captured by the\n// substrate without an explicit subtree decl. We declare a\n// `missingTolerance: 'fine'` shape because:\n//\n//   - A restored stack with a missing cache entry simply re-publishes\n//     (cache miss). No data loss.\n//   - A restored stack with a present cache entry runs the lenient\n//     verify probe; if the chain snapshot also restored, the probe\n//     resolves the cached id; otherwise it misses and re-publishes.\n//\n// No managed containers — the build container belongs to the Sui\n// plugin (per-app, declared there). The Move build cache lives at\n// `~/.move/git` on the host (NOT in a container) and is intentionally\n// NOT captured: distilled doc §Cross-component references — vendored\n// deps are content-addressed by sui-cli, re-fetched on demand.\n\nimport { Effect } from 'effect';\n\nimport type { SnapshotableDecl } from '../../contracts/snapshotable.ts';\n\n/** Build the Snapshotable contribution.\n *\n *  Identity guard: contributes the package's symbolic name + content\n *  hash to the pre-restore identity record. A snapshot taken under\n *  source-hash A restored against source-hash A is OK (verify probe\n *  re-confirms); a mismatch lets the substrate decide (typically:\n *  also OK — re-publish). The identity guard is mostly informational\n *  here. */\nexport const makeSnapshotable = (packageName: string, sourceHash: string): SnapshotableDecl => ({\n\tkind: 'snapshotable',\n\tsubtrees: [],\n\tmissingTolerance: 'fine',\n\tpreRestore: Effect.succeed({\n\t\tkind: 'package' as const,\n\t\tname: packageName,\n\t\tsourceHash,\n\t}),\n\tpostRestore: Effect.void,\n});\n"],"mappings":";;;;;;;;;;AAqCA,MAAa,oBAAoB,aAAqB,gBAA0C;CAC/F,MAAM;CACN,UAAU,EAAE;CACZ,kBAAkB;CAClB,YAAY,OAAO,QAAQ;EAC1B,MAAM;EACN,MAAM;EACN;EACA,CAAC;CACF,aAAa,OAAO;CACpB"}

package/dist/plugins/postgres/codegen.mjs

@@ -0,0 +1,42 @@
+import { credentialedUrl, plainUrl } from "./connection.mjs";
+import { Effect } from "effect";
+//#region src/plugins/postgres/codegen.ts
+/** Construct the Codegenable contribution. Emit is byte-deterministic
+*  on unchanged input (architecture: no mtime churn on no-op cycles).
+*
+*  The emitted shape carries both the credentialed URL (for in-app
+*  dialers) and the plain URL (for code paths that log or persist the
+*  endpoint). */
+const makeCodegenable = (opts) => {
+	const parts = {
+		user: opts.user,
+		password: opts.password,
+		host: opts.host,
+		port: opts.port
+	};
+	return {
+		kind: "codegenable",
+		emitterName: "postgres-connection",
+		outputPath: `postgres/${opts.name}.ts`,
+		sensitive: true,
+		emit: (ctx) => Effect.sync(() => {
+			const bindings = {
+				name: opts.name,
+				host: opts.host,
+				port: opts.port,
+				user: opts.user,
+				password: opts.password,
+				databases: opts.databases,
+				url: credentialedUrl(parts),
+				plainUrl: plainUrl(opts.host, opts.port),
+				database: opts.databases[0]
+			};
+			ctx.exportConst("postgresConnection", bindings);
+			return ctx.done();
+		})
+	};
+};
+//#endregion
+export { makeCodegenable };
+
+//# sourceMappingURL=codegen.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/postgres/codegen.ts"],"sourcesContent":["// Postgres plugin — Codegenable contribution.\n//\n// Architecture §6: plugins emit typed `CodegenableDecl`s; the codegen\n// orchestrator stages files into the user's source tree WITHOUT\n// naming the plugin. Postgres's contribution is the connection\n// surface — credentialed URL + parsed parts so downstream user-app\n// code can construct `DATABASE_URL` strings (or feed a typed\n// connection record into a pg client) without re-deriving creds.\n//\n// Sensitive flag: the emitted file carries the password, so the\n// codegen orchestrator marks it 0o600 inside its parent (0o700). The\n// manifest projection (separate from codegen) strips the password\n// via the substrate's secret-redactor pattern.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\nimport {\n\tcredentialedUrl,\n\tplainUrl,\n\ttype PostgresConnectionBindings,\n\ttype PostgresConnectionParts,\n} from './connection.ts';\n\nexport interface MakeCodegenableOptions {\n\treadonly name: string;\n\treadonly user: string;\n\treadonly password: string;\n\treadonly host: string;\n\treadonly port: number;\n\treadonly databases: ReadonlyArray<string>;\n}\n\n/** Construct the Codegenable contribution. Emit is byte-deterministic\n *  on unchanged input (architecture: no mtime churn on no-op cycles).\n *\n *  The emitted shape carries both the credentialed URL (for in-app\n *  dialers) and the plain URL (for code paths that log or persist the\n *  endpoint). */\nexport const makeCodegenable = (\n\topts: MakeCodegenableOptions,\n): CodegenableDecl<'postgres-connection'> => {\n\tconst parts: PostgresConnectionParts = {\n\t\tuser: opts.user,\n\t\tpassword: opts.password,\n\t\thost: opts.host,\n\t\tport: opts.port,\n\t};\n\n\treturn {\n\t\tkind: 'codegenable',\n\t\temitterName: 'postgres-connection',\n\t\t// One file per postgres instance. Multiple postgres()\n\t\t// instances on the same stack would collide here — distilled\n\t\t// doc § Edge cases notes this as a name-collision foot-gun;\n\t\t// the substrate's codegen layer detects the collision and\n\t\t// fails with a typed error before write.\n\t\toutputPath: `postgres/${opts.name}.ts`,\n\t\tsensitive: true,\n\t\temit: (ctx) =>\n\t\t\tEffect.sync(() => {\n\t\t\t\tconst bindings: PostgresConnectionBindings = {\n\t\t\t\t\tname: opts.name,\n\t\t\t\t\thost: opts.host,\n\t\t\t\t\tport: opts.port,\n\t\t\t\t\tuser: opts.user,\n\t\t\t\t\tpassword: opts.password,\n\t\t\t\t\tdatabases: opts.databases,\n\t\t\t\t\turl: credentialedUrl(parts),\n\t\t\t\t\tplainUrl: plainUrl(opts.host, opts.port),\n\t\t\t\t\tdatabase: opts.databases[0]!,\n\t\t\t\t};\n\t\t\t\tctx.exportConst('postgresConnection', bindings);\n\t\t\t\treturn ctx.done();\n\t\t\t}),\n\t};\n};\n"],"mappings":";;;;;;;;;AAuCA,MAAa,mBACZ,SAC4C;CAC5C,MAAM,QAAiC;EACtC,MAAM,KAAK;EACX,UAAU,KAAK;EACf,MAAM,KAAK;EACX,MAAM,KAAK;EACX;AAED,QAAO;EACN,MAAM;EACN,aAAa;EAMb,YAAY,YAAY,KAAK,KAAK;EAClC,WAAW;EACX,OAAO,QACN,OAAO,WAAW;GACjB,MAAM,WAAuC;IAC5C,MAAM,KAAK;IACX,MAAM,KAAK;IACX,MAAM,KAAK;IACX,MAAM,KAAK;IACX,UAAU,KAAK;IACf,WAAW,KAAK;IAChB,KAAK,gBAAgB,MAAM;IAC3B,UAAU,SAAS,KAAK,MAAM,KAAK,KAAK;IACxC,UAAU,KAAK,UAAU;IACzB;AACD,OAAI,YAAY,sBAAsB,SAAS;AAC/C,UAAO,IAAI,MAAM;IAChB;EACH"}

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

@@ -0,0 +1,33 @@
+//#region src/plugins/postgres/connection.d.ts
+/** Components of a postgres connection. The plugin keeps these in
+ *  one record so URL construction is a single function call. */
+interface PostgresConnectionParts {
+  readonly user: string;
+  readonly password: string;
+  readonly host: string;
+  readonly port: number;
+}
+/** Public typed shape emitted into codegen.
+ *
+ *  The credentialed URL is INCLUDED so consumers in the same user
+ *  app process can dial. The manifest projection (substrate-level)
+ *  strips it via the secret-redactor pattern — codegen and manifest
+ *  are different artifacts. */
+interface PostgresConnectionBindings {
+  readonly name: string;
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  /** Sensitive — never crosses to the on-disk manifest. */
+  readonly password: string;
+  readonly databases: ReadonlyArray<string>;
+  /** Cluster-level URL with credentials. */
+  readonly url: string;
+  /** Cluster-level URL without credentials — manifest-safe. */
+  readonly plainUrl: string;
+  /** First (bootstrap) database name. Convenience for single-DB apps. */
+  readonly database: string;
+}
+//#endregion
+export { PostgresConnectionBindings, PostgresConnectionParts };
+//# sourceMappingURL=connection.d.mts.map

package/dist/plugins/postgres/connection.mjs

@@ -0,0 +1,19 @@
+//#region src/plugins/postgres/connection.ts
+/** Build the credentialed URL.
+*
+*  Caller convention: this URL MUST NOT be logged or persisted to
+*  disk. The substrate's observability redactor strips it on best-
+*  effort; the structural cure is to use `plainUrl` everywhere the
+*  password isn't needed. */
+const credentialedUrl = (parts) => {
+	const { user, password, host, port } = parts;
+	return `postgres://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}`;
+};
+/** Build the no-credentials URL. Manifest-safe by construction. */
+const plainUrl = (host, port) => `postgres://${host}:${port}`;
+/** Compose a database segment onto a base URL. */
+const withDatabase = (baseUrl, db) => `${baseUrl}/${encodeURIComponent(db)}`;
+//#endregion
+export { credentialedUrl, plainUrl, withDatabase };
+
+//# sourceMappingURL=connection.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.mjs","names":[],"sources":["../../../src/plugins/postgres/connection.ts"],"sourcesContent":["// Postgres connection-string builders + the public typed shape used\n// by codegen and consumers.\n//\n// Distilled-doc § Postgres-specific concerns: two URL shapes must exit\n// the plugin —\n//\n//   1. CREDENTIALED form (`postgres://<user>:<pw>@<host>:<port>`) for\n//      in-process / in-stack dialers that need to issue real queries.\n//   2. PLAIN form (`postgres://<host>:<port>`) for the on-disk manifest\n//      and for the flat-endpoint registry. NEVER carries the password.\n//\n// Both shapes can be extended with a database name segment via\n// `withDatabase`. The plain form's existence is the structural cure\n// for the \"credentialed URL leaks via console.log\" foot-gun called\n// out in the distilled doc's learnings — the manifest projection\n// refuses anything but the plain form.\n\n/** Components of a postgres connection. The plugin keeps these in\n *  one record so URL construction is a single function call. */\nexport interface PostgresConnectionParts {\n\treadonly user: string;\n\treadonly password: string;\n\treadonly host: string;\n\treadonly port: number;\n}\n\n/** Build the credentialed URL.\n *\n *  Caller convention: this URL MUST NOT be logged or persisted to\n *  disk. The substrate's observability redactor strips it on best-\n *  effort; the structural cure is to use `plainUrl` everywhere the\n *  password isn't needed. */\nexport const credentialedUrl = (parts: PostgresConnectionParts): string => {\n\tconst { user, password, host, port } = parts;\n\treturn `postgres://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}`;\n};\n\n/** Build the no-credentials URL. Manifest-safe by construction. */\nexport const plainUrl = (host: string, port: number): string => `postgres://${host}:${port}`;\n\n/** Compose a database segment onto a base URL. */\nexport const withDatabase = (baseUrl: string, db: string): string =>\n\t`${baseUrl}/${encodeURIComponent(db)}`;\n\n/** Public typed shape emitted into codegen.\n *\n *  The credentialed URL is INCLUDED so consumers in the same user\n *  app process can dial. The manifest projection (substrate-level)\n *  strips it via the secret-redactor pattern — codegen and manifest\n *  are different artifacts. */\nexport interface PostgresConnectionBindings {\n\treadonly name: string;\n\treadonly host: string;\n\treadonly port: number;\n\treadonly user: string;\n\t/** Sensitive — never crosses to the on-disk manifest. */\n\treadonly password: string;\n\treadonly databases: ReadonlyArray<string>;\n\t/** Cluster-level URL with credentials. */\n\treadonly url: string;\n\t/** Cluster-level URL without credentials — manifest-safe. */\n\treadonly plainUrl: string;\n\t/** First (bootstrap) database name. Convenience for single-DB apps. */\n\treadonly database: string;\n\t/** Per-database credentialed URL composer is NOT included on the\n\t *  emitted shape — codegen output is a static record, not a closure.\n\t *  Consumers compose `${url}/${db}` themselves, or import the helper\n\t *  from the plugin's runtime surface. */\n}\n"],"mappings":";;;;;;;AAgCA,MAAa,mBAAmB,UAA2C;CAC1E,MAAM,EAAE,MAAM,UAAU,MAAM,SAAS;AACvC,QAAO,cAAc,mBAAmB,KAAK,CAAC,GAAG,mBAAmB,SAAS,CAAC,GAAG,KAAK,GAAG;;;AAI1F,MAAa,YAAY,MAAc,SAAyB,cAAc,KAAK,GAAG;;AAGtF,MAAa,gBAAgB,SAAiB,OAC7C,GAAG,QAAQ,GAAG,mBAAmB,GAAG"}

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

@@ -0,0 +1,100 @@
+import { ProbeTimeoutError, exitCodeProbeResult, waitForProbe } from "../../substrate/runtime/probes.mjs";
+import { databaseCreateFailed, postgresConnectionTimeout } from "./errors.mjs";
+import { Effect } from "effect";
+//#region src/plugins/postgres/db-ensure.ts
+const READY_PROBE_INTERVAL_MS = 500;
+/** Wait until `pg_isready -U <user> -d <db>` exits zero or the
+*  overall deadline elapses.
+*
+*  Distilled doc § "Postgres-specific concerns" — server-aware probe;
+*  TCP-listener readiness alone is insufficient (postgres opens the
+*  port before it accepts queries). */
+const awaitReady = (exec, user, database, timeoutMs) => Effect.gen(function* () {
+	let attempts = 0;
+	let lastResult;
+	const startedAt = Date.now();
+	return yield* waitForProbe({
+		label: `postgres:${database}`,
+		timeoutMs,
+		intervalMs: READY_PROBE_INTERVAL_MS,
+		probe: () => Effect.gen(function* () {
+			attempts += 1;
+			const result = yield* exec.run([
+				"pg_isready",
+				"-U",
+				user,
+				"-d",
+				database
+			]);
+			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
+	} }));
+});
+/** Idempotently ensure a logical database exists.
+*
+*  Algorithm:
+*    1. `psql -tAc "SELECT 1 FROM pg_database WHERE datname = '<db>'"`.
+*       Exit 0 + non-empty stdout => exists, return.
+*       Exit != 0                 => DatabaseCreateFailed(exists-check).
+*    2. `createdb -U <user> <db>`.
+*       Exit 0  => done.
+*       Exit != 0 => DatabaseCreateFailed(createdb).
+*
+*  Identifier quoting note: this implementation passes the database
+*  name as a CLI argument (createdb) and as a SQL string literal
+*  (the existence query). Postgres folds unquoted identifiers; if
+*  the caller passes `MyDB`, postgres stores it as `mydb`. The
+*  current plugin contract doesn't quote — distilled doc § Edge
+*  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 exists = yield* exec.run([
+		"psql",
+		"-U",
+		user,
+		"-tAc",
+		`SELECT 1 FROM pg_database WHERE datname = '${dbName}'`
+	]);
+	if (exists.exitCode !== 0) return yield* Effect.fail(databaseCreateFailed({
+		database: dbName,
+		op: "exists-check",
+		exitCode: exists.exitCode,
+		stdout: exists.stdout,
+		stderr: exists.stderr
+	}));
+	if (exists.stdout.trim().length > 0) return;
+	const created = yield* exec.run([
+		"createdb",
+		"-U",
+		user,
+		dbName
+	]);
+	if (created.exitCode !== 0) return yield* Effect.fail(databaseCreateFailed({
+		database: dbName,
+		op: "createdb",
+		exitCode: created.exitCode,
+		stdout: created.stdout,
+		stderr: created.stderr
+	}));
+}).pipe(Effect.withSpan("postgres.ensureDatabase", { attributes: { "postgres.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. */
+const ensureDatabases = (exec, user, databases) => Effect.gen(function* () {
+	for (let i = 1; i < databases.length; i++) yield* ensureDatabase(exec, user, databases[i]);
+});
+//#endregion
+export { awaitReady, ensureDatabases };
+
+//# sourceMappingURL=db-ensure.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,55 @@
+import { ConfigIssue } from "../../substrate/runtime/config-validation.mjs";
+
+//#region src/plugins/postgres/errors.d.ts
+/** Phases for `PostgresPluginError`. Closed sum — additions land in
+ *  the distilled-doc catalog first. */
+type PostgresPhase = 'network-create' | 'image-build' | 'container-start' | 'ready-probe' | 'db-ensure' | 'unknown';
+/** Generic plugin error. Most failure surfaces collapse onto this
+ *  shape; specific failure modes that warrant their own catchable
+ *  tag (timeout, createdb-collision) get their own type below. */
+interface PostgresPluginError {
+  readonly _tag: 'PostgresPluginError';
+  readonly phase: PostgresPhase;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+interface PostgresConfigError extends ConfigIssue {
+  readonly _tag: 'PostgresConfigError';
+}
+/** `pg_isready` returned non-zero past the deadline. Carries the
+ *  database name + last exit code + captured streams so the cause
+ *  walker can render an actionable hint (slow disk, port mismatch,
+ *  perms on data dir).
+ *
+ *  Distilled-doc § Edge cases: this is the most common "what went
+ *  wrong" failure during first boot of a freshly-built image; it
+ *  deserves its own tag so the renderer can show a slow-disk hint
+ *  before users guess. */
+interface PostgresConnectionTimeout {
+  readonly _tag: 'PostgresConnectionTimeout';
+  readonly database: string;
+  readonly attempts: number;
+  readonly elapsedMs: number;
+  readonly lastExitCode?: number;
+  readonly lastStdout?: string;
+  readonly lastStderr?: string;
+}
+/** Logical-database creation failed. Distinct from a network /
+ *  container / probe failure because the typical root cause is
+ *  case-sensitivity collision in postgres identifier folding —
+ *  surfaced explicitly via its own tag so consumers can render a
+ *  "quote the identifier" hint. */
+interface DatabaseCreateFailed {
+  readonly _tag: 'DatabaseCreateFailed';
+  readonly database: string;
+  readonly op: 'exists-check' | 'createdb';
+  readonly exitCode?: number;
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly cause?: unknown;
+}
+/** Union of every error a Postgres-plugin caller may encounter. */
+type PostgresError = PostgresPluginError | PostgresConfigError | PostgresConnectionTimeout | DatabaseCreateFailed;
+//#endregion
+export { DatabaseCreateFailed, PostgresConfigError, PostgresConnectionTimeout, PostgresError, PostgresPhase, PostgresPluginError };
+//# sourceMappingURL=errors.d.mts.map

package/dist/plugins/postgres/errors.mjs

@@ -0,0 +1,29 @@
+import { defineConfigError } from "../../substrate/runtime/config-validation.mjs";
+//#region src/plugins/postgres/errors.ts
+const postgresPluginError = (phase, message, cause) => ({
+	_tag: "PostgresPluginError",
+	phase,
+	message,
+	cause
+});
+const postgresConfigError = defineConfigError("PostgresConfigError");
+const postgresConnectionTimeout = (parts) => ({
+	_tag: "PostgresConnectionTimeout",
+	...parts
+});
+const databaseCreateFailed = (parts) => ({
+	_tag: "DatabaseCreateFailed",
+	...parts
+});
+/** Error tags this plugin contributes — surfaced to the cause walker
+*  via `PluginErrorContribution`. */
+const POSTGRES_ERROR_TAGS = [
+	"PostgresPluginError",
+	"PostgresConfigError",
+	"PostgresConnectionTimeout",
+	"DatabaseCreateFailed"
+];
+//#endregion
+export { POSTGRES_ERROR_TAGS, databaseCreateFailed, postgresConfigError, postgresConnectionTimeout, postgresPluginError };
+
+//# sourceMappingURL=errors.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,37 @@
+import { CodegenableDecl } from "../../contracts/codegenable.mjs";
+import { RoutableDecl } from "../../contracts/routable.mjs";
+import { SnapshotableDecl } from "../../contracts/snapshotable.mjs";
+import { Plugin } from "../../substrate/plugin.mjs";
+import { DatabaseCreateFailed, PostgresConfigError, PostgresConnectionTimeout, PostgresError, PostgresPhase, PostgresPluginError } from "./errors.mjs";
+import { Postgres, PostgresServiceOptions } from "./service.mjs";
+import { PostgresConnectionBindings, PostgresConnectionParts } from "./connection.mjs";
+//#region src/plugins/postgres/index.d.ts
+type PostgresCapabilities = readonly [SnapshotableDecl, CodegenableDecl<'postgres-connection'>] | readonly [SnapshotableDecl, CodegenableDecl<'postgres-connection'>, RoutableDecl];
+/** User-facing options on top of the service options — currently just
+ *  the routable opt-in. We split this out so the service body's
+ *  `PostgresServiceOptions` stays focused on container/boot knobs and
+ *  the plugin-level surface owns capability gating. */
+interface PostgresPluginOptions extends PostgresServiceOptions {
+  /** When `true`, the plugin contributes a `wireProtocol: 'tcp'`
+   *  Routable decl that fronts the postgres container on the
+   *  `postgres-tcp` entrypoint (host port 5432 by default). Default
+   *  `false` — parallel stacks coexist via the in-network DNS alias
+   *  and the optional `hostPort` mapping, neither of which involves
+   *  the router.
+   *
+   *  Architecture parallel-stack note: TCP entrypoints serve ONE
+   *  backend at a time (no Host-header fan-out), so only one stack
+   *  on the host may set `route: true` at a given moment. The router
+   *  orchestrator's collision detector fails fast on the second
+   *  contribution. */
+  readonly route?: boolean;
+}
+/** Postgres-as-a-container plugin. One per `(stack, name)` pair.
+ *
+ *  Single-mode: only local container exists today. The plain-endpoint
+ *  shape anticipates a future "live" mode (Cloud SQL / Neon / RDS)
+ *  that emits the same endpoint shape without spawning. */
+declare const postgres: (opts?: PostgresPluginOptions) => Plugin<"postgres", Postgres, readonly [], PostgresCapabilities>;
+//#endregion
+export { PostgresPluginOptions, postgres };
+//# sourceMappingURL=index.d.mts.map

package/dist/plugins/postgres/index.mjs

@@ -0,0 +1,75 @@
+import { definePlugin, resource } from "../../substrate/plugin.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import { IdentityContext } 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 "./connection.mjs";
+import { makeCodegenable } from "./codegen.mjs";
+import { POSTGRES_ERROR_TAGS, postgresConfigError, postgresPluginError } from "./errors.mjs";
+import { bootPostgresService } from "./service.mjs";
+import { makeSnapshotable } from "./snapshot.mjs";
+import { Effect } from "effect";
+//#region src/plugins/postgres/index.ts
+/** The Postgres plugin's resource identity. */
+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",
+		start: () => Effect.gen(function* () {
+			const { handle } = yield* bootPostgresService(yield* ContainerRuntimeService, yield* IdentityContext, 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)))),
+		errorContributions: postgresErrorContributions,
+		capabilities: ({ value, runtime }) => {
+			const snap = makeSnapshotable({
+				app: runtime.identity.app,
+				stack: runtime.identity.stack,
+				name,
+				databases
+			});
+			const codegen = makeCodegenable({
+				name,
+				user: value.user,
+				password: value.password,
+				host: value.networkAlias,
+				port: value.port,
+				databases: value.databases
+			});
+			const routable = opts.route ? makePostgresRoutable({
+				app: runtime.identity.app,
+				stack: runtime.identity.stack,
+				name,
+				containerName: `${runtime.identity.app}-${runtime.identity.stack}-${name}`
+			}) : null;
+			return routable === null ? [snap, codegen] : [
+				snap,
+				codegen,
+				routable
+			];
+		}
+	});
+};
+/** Postgres-as-a-container plugin. One per `(stack, name)` pair.
+*
+*  Single-mode: only local container exists today. The plain-endpoint
+*  shape anticipates a future "live" mode (Cloud SQL / Neon / RDS)
+*  that emits the same endpoint shape without spawning. */
+const postgres = (opts = {}) => buildPlugin(opts);
+//#endregion
+export { postgres };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +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"}

package/dist/plugins/postgres/routable.mjs

@@ -0,0 +1,33 @@
+//#region src/plugins/postgres/routable.ts
+/** Canonical endpoint name — matches this plugin's router entrypoint. */
+const POSTGRES_TCP_ENDPOINT_NAME = "postgres-tcp";
+const POSTGRES_TCP_ENTRYPOINT_PORT = 5432;
+const POSTGRES_ENTRYPOINTS = [{
+	name: POSTGRES_TCP_ENDPOINT_NAME,
+	port: POSTGRES_TCP_ENTRYPOINT_PORT,
+	protocol: "tcp"
+}];
+/** Construct the Postgres TCP Routable decl.
+*
+*  The `containerName` is whatever name the postgres `ensureContainer`
+*  call uses for its container — the router's upstream resolver maps
+*  the key back to the container's shared-network IP at dispatch-file
+*  write time. */
+const makePostgresRoutable = (parts) => ({
+	kind: "routable",
+	endpointName: POSTGRES_TCP_ENDPOINT_NAME,
+	dispatchId: {
+		serviceKey: `postgres.${parts.app}.${parts.stack}.${parts.name}`,
+		role: parts.name
+	},
+	upstream: {
+		type: "container",
+		containerName: parts.containerName,
+		containerPort: POSTGRES_TCP_ENTRYPOINT_PORT
+	},
+	wireProtocol: "tcp"
+});
+//#endregion
+export { POSTGRES_ENTRYPOINTS, POSTGRES_TCP_ENDPOINT_NAME, makePostgresRoutable };
+
+//# sourceMappingURL=routable.mjs.map