@emseepea/create-multi-instance-postgres-server 0.0.1

package/README.md

@@ -0,0 +1,115 @@
+# `@emseepea/create-multi-instance-postgres-server`
+
+This directory is the maintained example and the candidate source for its
+public npm initializer.
+
+## Use This Template
+
+Use this template when independently deployed server instances must share one
+PostgreSQL-backed store and repeated request IDs must resolve to one stored
+result. Choose the [tool server](../tool-server/README.md) when one process and
+in-memory data are enough. [Compare all eight templates](https://emseepea.github.io/emseepea/examples/).
+
+## Create a Project
+
+Publication is pending exact Quality checks. After publication, use:
+
+```sh
+npm init @emseepea/multi-instance-postgres-server -- my-server
+```
+
+<!-- generated-project-readme -->
+
+## Multi-Instance PostgreSQL Server
+
+Choose this project when separate server instances may receive the same retry
+and must avoid creating duplicate stored work.
+
+Each server has its own Em See Pea app and PostgreSQL connection pool. The
+servers coordinate through one shared database without sharing a local
+filesystem.
+
+The same request ID creates one stored pea harvest report. A retry through any
+instance returns the original report, including the name of the instance that
+created it.
+
+## Run Locally
+
+You need Node.js 22 or 24 and Docker Compose. Install dependencies, then start
+PostgreSQL and both server instances with one run command:
+
+```sh
+npm install
+npm run dev
+```
+
+The run command applies the database schema, starts two independent server
+processes, and prints both MCP addresses. Stop them with Control-C. Remove the
+database container and local volume when you no longer need them:
+
+```sh
+docker compose down --volumes
+```
+
+## Use Managed PostgreSQL
+
+Set `DATABASE_URL` to a PostgreSQL connection string that every deployed
+instance can reach. Apply the included schema once, then start each instance
+with its own name:
+
+```sh
+npm run build
+npm run db:setup
+EMSEEPEA_INSTANCE=instance-a PORT=3000 npm run start:instance
+```
+
+Run the final command for each deployed instance, changing
+`EMSEEPEA_INSTANCE` for each instance. Protect `DATABASE_URL` as a secret. Do
+not put it in source control or send it to an MCP client.
+
+## Tools
+
+- `create-shared-harvest-report` atomically creates or returns one stored report
+  for a request ID. The result identifies its original server instance.
+- `describe-instance` returns the instance handling the current request and
+  does not query PostgreSQL.
+
+PostgreSQL enforces one report per request ID with a unique constraint. The
+tool uses one atomic upsert, without an application-side existence check or a
+distributed lock.
+
+If PostgreSQL is unavailable, `/readyz` returns 503 and the report tool returns
+a generic failure. Independent endpoints and `describe-instance` remain
+available for diagnosis.
+
+## Exact Scope
+
+- Independently deployable server instances connected to one PostgreSQL database.
+- One bounded connection pool per process.
+- One atomic database statement per report request.
+- PostgreSQL bounds database statements to 1.5 seconds. The driver cannot
+  cancel an in-flight query from an AbortSignal, so the database timeout is the
+  cancellation boundary.
+- No claim that an external service change happens exactly once.
+- No latency, throughput, or unlimited-scale claim.
+
+## Check This Project
+
+[Ordinary tests](test/) live in `test/`. The
+[AI tool-choice and understanding test](eval/meaning.test.mjs) lives separately
+in `eval/`. Docker Compose is required because both suites exercise real
+PostgreSQL behavior.
+
+Run the build and two-server MCP checks:
+
+```sh
+npm test
+```
+
+Check that Claude understands report replay correctly:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Windy Road Technology Pty. Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/initializer-dist/create.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+const [destination, ...extra] = process.argv.slice(2);
+if (extra.length > 0 || !destination || !/^[a-z0-9][a-z0-9._-]*$/.test(destination)) {
+  throw new Error("Provide one simple lowercase destination name, such as my-server");
+}
+
+const target = resolve(destination);
+if (basename(target) !== destination) throw new Error("The destination must not contain a path");
+const staging = await mkdtemp(join(dirname(target), ".emseepea-create-"));
+
+try {
+  await copyContents(new URL("./template/", import.meta.url), staging);
+  const manifestPath = resolve(staging, "package.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: destination }, null, 2)}\n`);
+  await mkdir(target);
+  try {
+    await copyContents(staging, target);
+  } catch (error) {
+    await rm(target, { recursive: true, force: true });
+    throw error;
+  }
+} catch (error) {
+  if (["EEXIST", "ENOTEMPTY"].includes(error.code)) {
+    throw new Error(`The destination already exists: ${destination}`);
+  }
+  throw error;
+} finally {
+  await rm(staging, { recursive: true, force: true });
+}
+
+async function copyContents(source, destination) {
+  for (const entry of await readdir(source)) {
+    const from = source instanceof URL ? new URL(entry, source) : join(source, entry);
+    await cp(from, join(destination, entry), { recursive: true, errorOnExist: true, force: false });
+  }
+}
+
+console.log(`Created ${destination}.`);
+console.log(`Next: cd ${destination}; npm install; npm test; npm start`);

package/initializer-dist/template/README.md

@@ -0,0 +1,93 @@
+# Multi-Instance PostgreSQL Server
+
+Choose this project when separate server instances may receive the same retry
+and must avoid creating duplicate stored work.
+
+Each server has its own Em See Pea app and PostgreSQL connection pool. The
+servers coordinate through one shared database without sharing a local
+filesystem.
+
+The same request ID creates one stored pea harvest report. A retry through any
+instance returns the original report, including the name of the instance that
+created it.
+
+## Run Locally
+
+You need Node.js 22 or 24 and Docker Compose. Install dependencies, then start
+PostgreSQL and both server instances with one run command:
+
+```sh
+npm install
+npm run dev
+```
+
+The run command applies the database schema, starts two independent server
+processes, and prints both MCP addresses. Stop them with Control-C. Remove the
+database container and local volume when you no longer need them:
+
+```sh
+docker compose down --volumes
+```
+
+## Use Managed PostgreSQL
+
+Set `DATABASE_URL` to a PostgreSQL connection string that every deployed
+instance can reach. Apply the included schema once, then start each instance
+with its own name:
+
+```sh
+npm run build
+npm run db:setup
+EMSEEPEA_INSTANCE=instance-a PORT=3000 npm run start:instance
+```
+
+Run the final command for each deployed instance, changing
+`EMSEEPEA_INSTANCE` for each instance. Protect `DATABASE_URL` as a secret. Do
+not put it in source control or send it to an MCP client.
+
+## Tools
+
+- `create-shared-harvest-report` atomically creates or returns one stored report
+  for a request ID. The result identifies its original server instance.
+- `describe-instance` returns the instance handling the current request and
+  does not query PostgreSQL.
+
+PostgreSQL enforces one report per request ID with a unique constraint. The
+tool uses one atomic upsert, without an application-side existence check or a
+distributed lock.
+
+If PostgreSQL is unavailable, `/readyz` returns 503 and the report tool returns
+a generic failure. Independent endpoints and `describe-instance` remain
+available for diagnosis.
+
+## Exact Scope
+
+- Independently deployable server instances connected to one PostgreSQL database.
+- One bounded connection pool per process.
+- One atomic database statement per report request.
+- PostgreSQL bounds database statements to 1.5 seconds. The driver cannot
+  cancel an in-flight query from an AbortSignal, so the database timeout is the
+  cancellation boundary.
+- No claim that an external service change happens exactly once.
+- No latency, throughput, or unlimited-scale claim.
+
+## Check This Project
+
+[Ordinary tests](test/) live in `test/`. The
+[AI tool-choice and understanding test](eval/meaning.test.mjs) lives separately
+in `eval/`. Docker Compose is required because both suites exercise real
+PostgreSQL behavior.
+
+Run the build and two-server MCP checks:
+
+```sh
+npm test
+```
+
+Check that Claude understands report replay correctly:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/template/compose.yaml

@@ -0,0 +1,20 @@
+services:
+  database:
+    image: postgres:18.6-alpine3.23
+    environment:
+      POSTGRES_DB: emseepea
+      POSTGRES_PASSWORD: emseepea
+      POSTGRES_USER: emseepea
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U emseepea -d emseepea"]
+      interval: 1s
+      timeout: 3s
+      retries: 20
+    ports:
+      - "127.0.0.1:${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql
+      - ./schema.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
+
+volumes:
+  postgres-data:

package/initializer-dist/template/eval/meaning.test.mjs

@@ -0,0 +1,44 @@
+import test from "node:test";
+import {
+  assertNoToolCalls,
+  assertResponseContains,
+  assertResponseMeaning,
+  assertToolCalls,
+  createConversation,
+} from "@emseepea/testing/semantic";
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) throw new Error("DATABASE_URL is required for the PostgreSQL semantic test");
+
+test("reuses the original shared report across server instances", async (t) => {
+  const chat = await createConversation(t, {
+    server: new URL("../dist/server.js", import.meta.url),
+    environment: { DATABASE_URL: databaseUrl, EMSEEPEA_INSTANCE: "eval-instance" },
+  });
+
+  // Cross-process concurrency stays in ordinary tests because asking the model
+  // to simulate routing would not exercise it. Only the comparison turn needs
+  // a semantic judge; the other turns use exact tool and literal assertions.
+  const created = await chat.send(
+    "Create a shared harvest report with request ID daily-harvest-report.",
+  );
+  assertToolCalls(created, [
+    { name: "create-shared-harvest-report", arguments: { requestId: "daily-harvest-report" } },
+  ]);
+  const repeated = await chat.send(
+    "Create that report again with the same request ID. Is its report ID the " +
+    "same as before?",
+  );
+  assertToolCalls(repeated, [
+    { name: "create-shared-harvest-report", arguments: { requestId: "daily-harvest-report" } },
+  ]);
+  await assertResponseMeaning(repeated, {
+    expected: "The repeated request returned the same report ID.",
+  });
+
+  const creator = await chat.send(
+    "What exact createdByInstance value did those tool results return?",
+  );
+  assertNoToolCalls(creator);
+  assertResponseContains(creator, "eval-instance");
+});

package/initializer-dist/template/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "emseepea-starter",
+  "version": "0.0.0",
+  "description": "Create multiple Em See Pea server instances backed by PostgreSQL.",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/start-two.js",
+    "dev": "docker compose up --detach --wait database && npm run build && npm run db:setup && npm start",
+    "start:instance": "node dist/server.js",
+    "db:setup": "node dist/setup-database.js",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node test/with-postgres.mjs node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "node test/with-postgres.mjs emseepea-test eval",
+    "lint": "oxlint src test eval"
+  },
+  "devDependencies": {
+    "@emseepea/testing": "0.5.2",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "@types/pg": "8.23.1",
+    "typescript": "6.0.3",
+    "oxlint": "1.80.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "private": true,
+  "dependencies": {
+    "@emseepea/server": "0.3.3",
+    "pg": "8.23.0",
+    "zod": "4.4.3"
+  }
+}

package/initializer-dist/template/schema.sql

@@ -0,0 +1,20 @@
+CREATE TABLE IF NOT EXISTS pea_plants (
+  name text PRIMARY KEY,
+  pea_type text NOT NULL CHECK (pea_type IN ('shelling', 'snap'))
+);
+
+INSERT INTO pea_plants (name, pea_type) VALUES
+  ('Harbour Gem', 'shelling'),
+  ('Highland Snap', 'snap'),
+  ('Meadow Sweet', 'snap'),
+  ('Garden Pearl', 'shelling')
+ON CONFLICT (name) DO NOTHING;
+
+CREATE TABLE IF NOT EXISTS reports (
+  report_id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  idempotency_key text NOT NULL UNIQUE,
+  created_by_instance text NOT NULL,
+  total_plants integer NOT NULL,
+  shelling_count integer NOT NULL,
+  snap_count integer NOT NULL
+);

package/initializer-dist/template/src/app.ts

@@ -0,0 +1,56 @@
+import { createEmseepea, discoverCapabilities } from "@emseepea/server";
+import { Pool } from "pg";
+import { z } from "zod";
+
+export interface MultiInstanceExampleOptions {
+  readonly databaseUrl: string;
+  readonly instanceName: string;
+}
+
+export async function createMultiInstanceExample(options: MultiInstanceExampleOptions) {
+  const instanceName = z.string().min(1).max(64).parse(options.instanceName);
+  const databaseUrl = z.string().url().refine(
+    (value) => ["postgres:", "postgresql:"].includes(new URL(value).protocol),
+    "databaseUrl must use PostgreSQL",
+  ).parse(options.databaseUrl);
+  let database: Pool | undefined = new Pool({
+    connectionString: databaseUrl,
+    connectionTimeoutMillis: 2_000,
+    idleTimeoutMillis: 10_000,
+    max: 4,
+    query_timeout: 2_000,
+    statement_timeout: 1_500,
+  });
+  database.on("error", () => {
+    // Readiness and tool calls report provider failure without stopping unrelated features.
+  });
+
+  const app = createEmseepea({
+    name: "emseepea-multi-instance-postgres-server",
+    version: "0.0.0",
+    instructions: "Use create-shared-harvest-report for a stored pea harvest report. Reusing a request ID returns the original report.",
+    readiness: async ({ signal }) => {
+      if (!database) return false;
+      try {
+        signal.throwIfAborted();
+        await database.query("SELECT 1 FROM reports LIMIT 1");
+        signal.throwIfAborted();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    readinessTimeoutMs: 2_500,
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), {
+      database: () => database,
+      instanceName,
+    }),
+  });
+  const closeProvider = async () => {
+    const activeDatabase = database;
+    database = undefined;
+    await activeDatabase?.end();
+  };
+  app.addHook("onClose", closeProvider);
+  return { app, closeProvider };
+}

package/initializer-dist/template/src/capabilities/context.ts

@@ -0,0 +1,6 @@
+import type { Pool } from "pg";
+
+export interface MultiInstanceContext {
+  readonly database: () => Pool | undefined;
+  readonly instanceName: string;
+}

package/initializer-dist/template/src/capabilities/tool.create-shared-harvest-report.ts

@@ -0,0 +1,81 @@
+import { defineMappedTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import type { MultiInstanceContext } from "./context.js";
+
+const requestIdSchema = z.string().min(3).max(64).regex(/^[a-z0-9][a-z0-9-]*$/)
+  .describe("Idempotency key. Reusing it returns the existing report instead of creating another.");
+const inputSchema = z.object({ requestId: requestIdSchema });
+const outputSchema = z.object({
+  reportId: z.number().int().positive().describe("Stored report identifier."),
+  requestId: requestIdSchema,
+  createdByInstance: z.string().min(1).max(64).describe("Server instance that originally created the report."),
+  totalPlants: z.number().int().nonnegative().describe("Total pea plants counted in the report."),
+  peaTypeCounts: z.object({
+    shelling: z.number().int().nonnegative().describe("Shelling pea plants counted in the report."),
+    snap: z.number().int().nonnegative().describe("Snap pea plants counted in the report."),
+  }).describe("Plant counts grouped by pea type."),
+});
+const backendInputSchema = z.object({ idempotency_key: requestIdSchema });
+const backendOutputSchema = z.object({
+  report_id: z.number().int().positive(),
+  idempotency_key: requestIdSchema,
+  created_by_instance: z.string().min(1).max(64),
+  total_plants: z.number().int().nonnegative(),
+  shelling_count: z.number().int().nonnegative(),
+  snap_count: z.number().int().nonnegative(),
+});
+
+export default ((context) => defineMappedTool({
+  name: "create-shared-harvest-report",
+  access: "public",
+  description: "Create or return one stored pea harvest report per request ID. The result identifies its original server instance.",
+  inputSchema,
+  outputSchema,
+  backendInputSchema,
+  backendOutputSchema,
+  isAvailable: () => {
+    return context.database() !== undefined;
+  },
+  mapInput: ({ requestId }) => ({ idempotency_key: requestId }),
+  async adapter({ idempotency_key }, { signal }) {
+    const database = context.database();
+    if (!database) throw new Error("Report provider unavailable");
+    signal.throwIfAborted();
+    const result = await database.query({
+      text: `
+        INSERT INTO reports (
+          idempotency_key, created_by_instance, total_plants,
+          shelling_count, snap_count
+        )
+        SELECT
+          $1,
+          $2,
+          COUNT(*)::integer,
+          COUNT(*) FILTER (WHERE pea_type = 'shelling')::integer,
+          COUNT(*) FILTER (WHERE pea_type = 'snap')::integer
+        FROM pea_plants
+        ON CONFLICT (idempotency_key) DO UPDATE
+          SET idempotency_key = EXCLUDED.idempotency_key
+        RETURNING
+          report_id, idempotency_key, created_by_instance, total_plants,
+          shelling_count, snap_count
+      `,
+      values: [idempotency_key, context.instanceName],
+    });
+    signal.throwIfAborted();
+    return result.rows[0] as z.input<typeof backendOutputSchema>;
+  },
+  mapOutput: (report) => {
+    const data = {
+      reportId: report.report_id,
+      requestId: report.idempotency_key,
+      createdByInstance: report.created_by_instance,
+      totalPlants: report.total_plants,
+      peaTypeCounts: {
+        shelling: report.shelling_count,
+        snap: report.snap_count,
+      },
+    };
+    return { data };
+  },
+})) satisfies CapabilityModuleFactory<MultiInstanceContext>;

package/initializer-dist/template/src/capabilities/tool.describe-instance.ts

@@ -0,0 +1,14 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import type { MultiInstanceContext } from "./context.js";
+
+export default (({ instanceName }) => defineTool({
+  name: "describe-instance",
+  access: "public",
+  description: "Return the server instance handling this request, not the instance that created a stored report.",
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    instanceName: z.string().describe("Server instance that handled this request."),
+  }),
+  handler: () => ({ data: { instanceName } }),
+})) satisfies CapabilityModuleFactory<MultiInstanceContext>;

package/initializer-dist/template/src/server.ts

@@ -0,0 +1,29 @@
+import { serveEmseepea } from "@emseepea/server";
+import { createMultiInstanceExample } from "./app.js";
+
+const instanceName = process.env.EMSEEPEA_INSTANCE ?? `instance-${process.pid}`;
+const databaseUrl = process.env.DATABASE_URL ?? "postgres://emseepea:emseepea@127.0.0.1:5432/emseepea";
+const { app, closeProvider } = await createMultiInstanceExample({ databaseUrl, instanceName });
+const running = await serveEmseepea(app, {
+  port: Number.parseInt(process.env.PORT ?? "3000", 10),
+});
+
+console.log(`Em See Pea multi-instance-postgres-server example ${instanceName} listening at ${running.url}`);
+process.send?.({ type: "ready", instanceName, url: running.url.href });
+process.on("message", (message) => {
+  if (message === "close-provider") {
+    void closeProvider().then(() => process.send?.({ type: "provider-closed", instanceName }));
+  }
+});
+
+let shuttingDown = false;
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  await running.close();
+  if (process.connected) process.disconnect();
+  process.exitCode = 0;
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/initializer-dist/template/src/setup-database.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import { Pool } from "pg";
+import { z } from "zod";
+
+const databaseUrl = z.string().url().parse(process.env.DATABASE_URL);
+const schema = await readFile(new URL("../schema.sql", import.meta.url), "utf8");
+const database = new Pool({ connectionString: databaseUrl, max: 1 });
+try {
+  await database.query(schema);
+  console.log("PostgreSQL schema ready");
+} finally {
+  await database.end();
+}

package/initializer-dist/template/src/start-two.ts

@@ -0,0 +1,32 @@
+import { fork, type ChildProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const databaseUrl = process.env.DATABASE_URL ?? "postgres://emseepea:emseepea@127.0.0.1:5432/emseepea";
+const serverPath = fileURLToPath(new URL("./server.js", import.meta.url));
+const children = [start("instance-a"), start("instance-b")];
+
+function start(instanceName: string): ChildProcess {
+  return fork(serverPath, [], {
+    env: {
+      ...process.env,
+      DATABASE_URL: databaseUrl,
+      EMSEEPEA_INSTANCE: instanceName,
+      PORT: "0",
+    },
+    stdio: ["inherit", "inherit", "inherit", "ipc"],
+  });
+}
+
+let stopping = false;
+async function shutdown(): Promise<void> {
+  if (stopping) return;
+  stopping = true;
+  for (const child of children) child.kill("SIGTERM");
+  await Promise.all(children.map((child) => new Promise<void>((resolve) => {
+    if (child.exitCode !== null) resolve();
+    else child.once("exit", () => resolve());
+  })));
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/initializer-dist/template/test/server.test.mjs

@@ -0,0 +1,241 @@
+import assert from "node:assert/strict";
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import test, { after } from "node:test";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { Pool } from "pg";
+
+const serverPath = fileURLToPath(new URL("../dist/server.js", import.meta.url));
+const databaseUrl = process.env.DATABASE_URL;
+assert.ok(databaseUrl, "DATABASE_URL is required");
+const database = new Pool({ connectionString: databaseUrl, max: 2 });
+after(() => database.end());
+const requestMeta = {
+  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+  "io.modelcontextprotocol/clientInfo": { name: "multi-instance-test", version: "0.0.0" },
+  "io.modelcontextprotocol/clientCapabilities": {},
+};
+
+test("two server processes share one atomic report store", async (t) => {
+  const first = await startInstance("instance-a", databaseUrl);
+  const second = await startInstance("instance-b", databaseUrl);
+  const firstClient = await connect(first.url);
+  const secondClient = await connect(second.url);
+  t.after(async () => {
+    await Promise.allSettled([firstClient.close(), secondClient.close()]);
+    await Promise.all([stopInstance(first.child), stopInstance(second.child)]);
+  });
+
+  const localRace = await Promise.all(Array.from({ length: 6 }, () => (
+    createReport(firstClient, "single-instance-race")
+  )));
+  assert.equal(new Set(localRace.map(({ reportId }) => reportId)).size, 1);
+  assert.equal(await reportCount("single-instance-race"), 1);
+
+  const [fromFirst, fromSecond] = await Promise.all([
+    createReport(firstClient, "shared-instance-race"),
+    createReport(secondClient, "shared-instance-race"),
+  ]);
+  assert.deepEqual(fromFirst, fromSecond);
+  assert.match(fromFirst.createdByInstance, /^instance-[ab]$/);
+  assert.deepEqual(fromFirst.peaTypeCounts, { shelling: 2, snap: 2 });
+  assert.equal(fromFirst.totalPlants, 4);
+  assert.equal(await reportCount("shared-instance-race"), 1);
+
+  const replay = await createReport(
+    fromFirst.createdByInstance === "instance-a" ? secondClient : firstClient,
+    "shared-instance-race",
+  );
+  assert.deepEqual(replay, fromFirst);
+
+  const raw = await rawCreateReport(first.url, "raw-http-report");
+  assert.equal(raw.response.status, 200);
+  assert.equal(raw.body.result.isError, false);
+  assert.equal(raw.body.result.structuredContent.requestId, "raw-http-report");
+  assert.equal(raw.body.result.content[0].text, JSON.stringify(raw.body.result.structuredContent));
+  assert.equal(await reportCount("raw-http-report"), 1);
+
+  await closeProvider(first.child);
+  const unavailable = await rawCreateReport(first.url, "must-not-be-created");
+  assert.equal(unavailable.response.status, 200);
+  assert.equal(unavailable.body.result.content[0].text, "Tool execution failed");
+  assert.doesNotMatch(
+    JSON.stringify({ ...unavailable.body.result, _meta: undefined }),
+    /postgres|database|connection|provider/i,
+  );
+  assert.equal(await reportCount("must-not-be-created"), 0);
+
+  const independent = await firstClient.callTool({ name: "describe-instance", arguments: {} });
+  assert.deepEqual(independent.structuredContent, { instanceName: "instance-a" });
+  const readiness = await fetch(new URL("/readyz", first.url));
+  assert.equal(readiness.status, 503);
+  assert.equal(await readiness.text(), "not ready\n");
+
+  const secondStillWorks = await createReport(secondClient, "provider-b-still-works");
+  assert.equal(secondStillWorks.requestId, "provider-b-still-works");
+});
+
+test("describes every multi-instance tool property", async (t) => {
+  const instance = await startInstance("schema-instance", databaseUrl);
+  const client = await connect(instance.url);
+  t.after(async () => {
+    await client.close();
+    await stopInstance(instance.child);
+  });
+
+  const listed = await client.listTools();
+  assert.deepEqual(listed.tools.map(({ name }) => name), [
+    "create-shared-harvest-report",
+    "describe-instance",
+  ]);
+  const reportInput = listed.tools[0].inputSchema.properties;
+  const reportOutput = listed.tools[0].outputSchema.properties;
+  assert.equal(reportInput.requestId.description, "Idempotency key. Reusing it returns the existing report instead of creating another.");
+  assert.equal(reportOutput.reportId.description, "Stored report identifier.");
+  assert.equal(reportOutput.requestId.description, reportInput.requestId.description);
+  assert.equal(reportOutput.createdByInstance.description, "Server instance that originally created the report.");
+  assert.equal(reportOutput.totalPlants.description, "Total pea plants counted in the report.");
+  assert.equal(reportOutput.peaTypeCounts.description, "Plant counts grouped by pea type.");
+  assert.equal(reportOutput.peaTypeCounts.properties.shelling.description, "Shelling pea plants counted in the report.");
+  assert.equal(reportOutput.peaTypeCounts.properties.snap.description, "Snap pea plants counted in the report.");
+  assert.equal(listed.tools[1].outputSchema.properties.instanceName.description, "Server instance that handled this request.");
+});
+
+test("an unavailable PostgreSQL provider fails readiness but not independent tools", async (t) => {
+  const instance = await startInstance(
+    "unavailable-before-start",
+    "postgres://emseepea:emseepea@127.0.0.1:1/emseepea",
+  );
+  const client = await connect(instance.url);
+  t.after(async () => {
+    await client.close();
+    await stopInstance(instance.child);
+  });
+
+  assert.deepEqual(
+    (await client.callTool({ name: "describe-instance", arguments: {} })).structuredContent,
+    { instanceName: "unavailable-before-start" },
+  );
+  const unavailable = await rawCreateReport(instance.url, "provider-never-connected");
+  assert.equal(unavailable.body.result.content[0].text, "Tool execution failed");
+  assert.doesNotMatch(
+    JSON.stringify({ ...unavailable.body.result, _meta: undefined }),
+    /postgres|database|connection|ECONNREFUSED|provider/i,
+  );
+  const readiness = await fetch(new URL("/readyz", instance.url));
+  assert.equal(readiness.status, 503);
+  assert.equal(await readiness.text(), "not ready\n");
+});
+
+test("blocked PostgreSQL work finishes at the database timeout", async (t) => {
+  const instance = await startInstance("blocked-query", databaseUrl);
+  const blocker = await database.connect();
+  t.after(async () => {
+    await blocker.query("ROLLBACK").catch(() => {});
+    blocker.release();
+    await stopInstance(instance.child);
+  });
+  await blocker.query("BEGIN");
+  await blocker.query("LOCK TABLE reports IN ACCESS EXCLUSIVE MODE");
+
+  const started = Date.now();
+  const [readiness, report] = await Promise.all([
+    fetch(new URL("/readyz", instance.url)),
+    rawCreateReport(instance.url, "blocked-report"),
+  ]);
+
+  assert.ok(Date.now() - started < 3_000, "blocked database work exceeded its bounded timeout");
+  assert.equal(readiness.status, 503);
+  assert.equal(report.body.result.content[0].text, "Tool execution failed");
+  await blocker.query("ROLLBACK");
+  assert.equal(await reportCount("blocked-report"), 0);
+});
+
+async function startInstance(instanceName, connectionString) {
+  const child = fork(serverPath, [], {
+    env: { ...process.env, DATABASE_URL: connectionString, EMSEEPEA_INSTANCE: instanceName, PORT: "0" },
+    stdio: ["ignore", "pipe", "pipe", "ipc"],
+  });
+  let errors = "";
+  child.stderr.on("data", (chunk) => { errors = `${errors}${chunk}`.slice(-2_000); });
+  const message = await waitForMessage(child, ({ type }) => type === "ready")
+    .catch((error) => { throw new Error(`${error.message}: ${errors}`); });
+  return { child, url: new URL(message.url) };
+}
+
+async function connect(url) {
+  const client = new Client(
+    { name: "emseepea-multi-instance-client", version: "0.0.0" },
+    { versionNegotiation: { mode: { pin: "2026-07-28" } } },
+  );
+  await client.connect(new StreamableHTTPClientTransport(url));
+  return client;
+}
+
+async function createReport(client, requestId) {
+  const result = await client.callTool({ name: "create-shared-harvest-report", arguments: { requestId } });
+  assert.equal(result.isError, false);
+  return result.structuredContent;
+}
+
+async function rawCreateReport(url, requestId) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json, text/event-stream",
+      "Content-Type": "application/json",
+      "MCP-Protocol-Version": "2026-07-28",
+      "Mcp-Method": "tools/call",
+      "Mcp-Name": "create-shared-harvest-report",
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: crypto.randomUUID(),
+      method: "tools/call",
+      params: { name: "create-shared-harvest-report", arguments: { requestId }, _meta: requestMeta },
+    }),
+  });
+  return { response, body: await response.json() };
+}
+
+async function reportCount(requestId) {
+  const result = await database.query(
+    "SELECT COUNT(*)::integer AS count FROM reports WHERE idempotency_key = $1",
+    [requestId],
+  );
+  return result.rows[0].count;
+}
+
+async function closeProvider(child) {
+  const closed = waitForMessage(child, ({ type }) => type === "provider-closed");
+  child.send("close-provider");
+  await closed;
+}
+
+function waitForMessage(child, predicate) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => finish(new Error("child message timed out")), 10_000);
+    const onMessage = (message) => {
+      if (message && typeof message === "object" && predicate(message)) finish(undefined, message);
+    };
+    const onExit = (code) => finish(new Error(`child exited ${code}`));
+    const finish = (error, message) => {
+      clearTimeout(timer);
+      child.off("message", onMessage);
+      child.off("exit", onExit);
+      if (error) reject(error);
+      else resolve(message);
+    };
+    child.on("message", onMessage);
+    child.once("exit", onExit);
+  });
+}
+
+async function stopInstance(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  child.kill("SIGTERM");
+  await Promise.race([
+    new Promise((resolve) => child.once("exit", resolve)),
+    new Promise((_, reject) => setTimeout(() => reject(new Error("server child did not stop")), 2_000)),
+  ]);
+}

package/initializer-dist/template/test/with-postgres.mjs

@@ -0,0 +1,59 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+
+const [command, ...args] = process.argv.slice(2);
+if (!command) throw new Error("A test command is required");
+
+const project = `emseepea-test-${process.pid}`;
+const port = await availablePort();
+const composeEnvironment = { ...process.env, POSTGRES_PORT: String(port) };
+const compose = (...composeArgs) => run(
+  "docker",
+  ["compose", "--project-name", project, ...composeArgs],
+  composeEnvironment,
+  120_000,
+);
+
+let exitCode = 1;
+try {
+  if (await compose("up", "--detach", "--wait", "database") !== 0) {
+    throw new Error("Could not start the PostgreSQL test service");
+  }
+  exitCode = await run(command, args, {
+    ...process.env,
+    DATABASE_URL: `postgres://emseepea:emseepea@127.0.0.1:${port}/emseepea`,
+  });
+} finally {
+  await compose("down", "--volumes");
+}
+process.exitCode = exitCode;
+
+function run(executable, executableArgs, env, timeout = 600_000) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, executableArgs, { env, stdio: "inherit" });
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeout);
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      resolve(code ?? 1);
+    });
+  });
+}
+
+function availablePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close((error) => {
+        if (error) reject(error);
+        else if (address && typeof address === "object") resolve(address.port);
+        else reject(new Error("Could not choose a PostgreSQL test port"));
+      });
+    });
+  });
+}

package/initializer-dist/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "target": "ES2023",
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@emseepea/create-multi-instance-postgres-server",
+  "version": "0.0.1",
+  "description": "Create multiple Em See Pea server instances backed by PostgreSQL.",
+  "license": "MIT",
+  "type": "module",
+  "starterDependencies": [
+    "@emseepea/server",
+    "pg",
+    "zod"
+  ],
+  "scripts": {
+    "build": "npm run build:example && npm run build:initializer",
+    "build:example": "tsc -p tsconfig.json",
+    "build:initializer": "node ../../scripts/build-initializer.mjs",
+    "start": "node dist/start-two.js",
+    "dev": "docker compose up --detach --wait database && npm run build && npm run db:setup && npm start",
+    "start:instance": "node dist/server.js",
+    "db:setup": "node dist/setup-database.js",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node test/with-postgres.mjs node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "node test/with-postgres.mjs emseepea-test eval",
+    "lint": "oxlint src test eval",
+    "prepack": "npm run build:initializer"
+  },
+  "devDependencies": {
+    "@emseepea/server": "0.3.3",
+    "@emseepea/testing": "0.5.2",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "@types/pg": "8.23.1",
+    "oxlint": "1.80.0",
+    "pg": "8.23.0",
+    "typescript": "6.0.3",
+    "zod": "4.4.3"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emseepea/emseepea.git",
+    "directory": "examples/multi-instance-postgres-server"
+  },
+  "homepage": "https://emseepea.github.io/emseepea/examples/",
+  "bugs": "https://github.com/emseepea/emseepea/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "create-multi-instance-postgres-server": "./initializer-dist/create.mjs"
+  },
+  "files": [
+    "initializer-dist"
+  ]
+}