@retinue/agentkit 0.2.0 → 0.3.1

package/dist/server/boot.js

@@ -5,16 +5,37 @@
  * substance: configuration is validated *before* anything connects, so a misconfigured deployment
  * fails with a message about the variable rather than a connection error that names nothing useful.
  */
-import { provisionSchema } from "../entries/adapters-postgres.js";
+import { provisionSchema, } from "../entries/adapters-postgres.js";
+import { createTransactionScope } from "../adapters/postgres/transaction.js";
 import { loadConfig } from "./config.js";
 export const boot = async (options) => {
     const log = options.log ?? ((entry) => console.log(JSON.stringify(entry)));
     // Configuration first, and it throws. A half-configured process that boots is worse than one that
     // refuses: it passes its own health check and fails on the first real request.
     const config = loadConfig(options.env);
-    const { sql } = await options.connect(config);
+    const { sql: base, open } = await options.connect(config);
+    /**
+     * The transaction scope, when the caller can open a connection — found by #254.
+     *
+     * `runApiHost` never built one, so `app.deps({ config, sql })` was called without a runner and the reference
+     * app's coordinator refused: *"this process has no TransactionRunner, so the conversation run coordinator
+     * cannot be used. The API host supplies one"*. It did not. `sendMessage` — the mutation that starts every run
+     * — therefore failed with an internal error in the shipped API host and in `npm run api`, which is the
+     * documented way to run the reference app.
+     */
+    const scope = open === undefined ? undefined : createTransactionScope(open);
+    const sql = scope === undefined ? base : scope.scoped(base);
     const provisioned = await provisionSchema(sql, {
         mode: config.schemaMode,
+        /**
+         * Passed so `auto` mode serialises — #266.
+         *
+         * Several workers booting against a fresh database is the ordinary Kubernetes init pattern, and without
+         * this one of them crashes on Postgres's own type catalogue with an error naming nothing actionable.
+         * `undefined` for a process whose adapter cannot hold a connection, which is correct: those are
+         * single-process and have nothing to race with.
+         */
+        ...(open === undefined ? {} : { open }),
         // Routed through the structured log rather than printed, so `plan` mode's diff is machine-readable
         // in the same stream as everything else.
         log: (message) => log({ event: "schema", mode: config.schemaMode, message }),
@@ -31,6 +52,11 @@ export const boot = async (options) => {
         // The adapters actually selected, so a support question does not start with "which database?".
         adapters: { store: "postgres", queue: "bullmq", lock: "redis" },
     });
-    return { config, sql, schema: { mode: config.schemaMode, applied: provisioned.applied } };
+    return {
+        config,
+        sql,
+        ...(scope === undefined ? {} : { runner: scope.runner }),
+        schema: { mode: config.schemaMode, applied: provisioned.applied },
+    };
 };
 //# sourceMappingURL=boot.js.map

package/dist/server/cli-worker.js

@@ -25,9 +25,12 @@ export const runWorker = async (env = process.env) => {
     const { config, sql } = await boot({
         env,
         connect: async (loaded) => {
-            const { Pool } = await import("pg");
-            const { createPgExecutor } = await import("../entries/adapters-postgres.js");
-            return { sql: createPgExecutor(new Pool({ connectionString: loaded.databaseUrl })) };
+            const { openPostgres } = await import("./pool.js");
+            // Through the shared pool for the schema, which matters most here: the worker is the process whose
+            // writes nobody watches, so a worker in `public` while the host is in `retinue` is a split brain
+            // that shows up as runs that vanish rather than as an error.
+            const { sql } = await openPostgres(loaded);
+            return { sql };
         },
     });
     /**

package/dist/server/cli.d.ts

@@ -2,6 +2,7 @@ import { type Authenticate } from "./host.js";
 import { type RetinueConfig } from "./config.js";
 import type { ResolverDeps } from "../index.js";
 import type { SqlExecutor } from "../entries/adapters-postgres.js";
+import type { TransactionRunner } from "../adapters/postgres/transaction.js";
 /**
  * What a deployment's app module must default-export.
  *
@@ -10,9 +11,21 @@ import type { SqlExecutor } from "../entries/adapters-postgres.js";
  */
 export type RetinueApp = {
     readonly authenticate: Authenticate;
+    /**
+     * `runner` added by #254, and it was not optional in practice — it was missing.
+     *
+     * The reference app's `deps` has always accepted an optional `TransactionRunner`, and this host never passed
+     * one, so the conversation run coordinator refused with *"this process has no TransactionRunner… The API host
+     * supplies one"*. It did not. `sendMessage` — the mutation that starts every run — failed with an internal
+     * error in this command and in `npm run api`, which is the documented way to run the reference app.
+     *
+     * Still optional on the signature, because a worker genuinely does not need it and an app that ignores it
+     * keeps compiling.
+     */
     readonly deps: (input: {
         readonly config: RetinueConfig;
         readonly sql: SqlExecutor;
+        readonly runner?: TransactionRunner;
     }) => Promise<ResolverDeps> | ResolverDeps;
     /** Optional liveness/readiness extras beyond Postgres, Redis and the schema version. */
     readonly redis?: (config: RetinueConfig) => {

package/dist/server/cli.js

@@ -35,15 +35,20 @@ export const runApiHost = async (env = process.env) => {
     // twice: `loadConfig` is pure and `boot` validates again.
     loadConfig(env);
     const app = await loadApp(env);
-    const { config, sql } = await boot({
+    const { config, sql, runner } = await boot({
         env,
         connect: async (loaded) => {
-            const { Pool } = await import("pg");
-            const { createPgExecutor } = await import("../entries/adapters-postgres.js");
-            return { sql: createPgExecutor(new Pool({ connectionString: loaded.databaseUrl })) };
+            const { openPostgres } = await import("./pool.js");
+            // `open` is what lets `boot` build a transaction scope. Without it the API host had no runner and
+            // `sendMessage` could not claim a conversation — #254.
+            //
+            // The whole config is passed, not just the URL: `databaseSchema` has to reach the pool or the host
+            // reads and writes `public` while migrations ran somewhere else.
+            const { sql, open } = await openPostgres(loaded);
+            return { sql, open };
         },
     });
-    const deps = await app.deps({ config, sql });
+    const deps = await app.deps({ config, sql, ...(runner === undefined ? {} : { runner }) });
     const { createSchemaManager } = await import("../entries/adapters-postgres.js");
     const probes = [postgresProbe(sql), schemaProbe(createSchemaManager(sql))];
     if (app.redis)

package/dist/server/config.d.ts

@@ -4,6 +4,16 @@ export type RetinueConfig = {
     readonly redisUrl: string;
     /** How the schema is provisioned at boot. `off` in production, so managed migrations stay in control. */
     readonly schemaMode: SchemaMode;
+    /**
+     * The Postgres schema the platform's own tables live in, or `undefined` for the connection's default.
+     *
+     * Exists because a deployment may be sharing a database with a product that owns `public` — which is
+     * exactly the ShareFlow case: its adapters qualify every one of their queries as `public.`, so with this
+     * set to `retinue` one pool serves both, platform tables in one schema and product tables in the other.
+     * Without it the platform's 35 migrations land in `public` alongside the product's, and the first name
+     * they share is a migration that fails or, worse, one that succeeds against the wrong table.
+     */
+    readonly databaseSchema?: string;
     readonly port: number;
     readonly workerConcurrency: number;
     readonly logLevel: "debug" | "info" | "warn" | "error";
@@ -38,5 +48,5 @@ export declare const loadConfig: (env: Env) => RetinueConfig;
  * test that asserts the error names every missing variable is what found it.
  */
 export declare const REQUIRED_VARIABLES: readonly ["RETINUE_DATABASE_URL", "RETINUE_REDIS_URL"];
-export declare const OPTIONAL_VARIABLES: readonly ["SCHEMA_MODE", "WORKER_CONCURRENCY", "LOG_LEVEL", "PORT"];
+export declare const OPTIONAL_VARIABLES: readonly ["SCHEMA_MODE", "DATABASE_SCHEMA", "WORKER_CONCURRENCY", "LOG_LEVEL", "PORT"];
 //# sourceMappingURL=config.d.ts.map

package/dist/server/config.js

@@ -76,6 +76,20 @@ export const loadConfig = (env) => {
     if (!SCHEMA_MODES.includes(rawSchemaMode)) {
         fail(named("SCHEMA_MODE"), `must be one of ${SCHEMA_MODES.join(", ")}, got "${rawSchemaMode}"`);
     }
+    /**
+     * A schema name, validated as an identifier rather than quoted.
+     *
+     * `SET search_path` takes no parameters — it is not a value position, so there is no placeholder to bind
+     * and the name is concatenated into SQL. That makes this the one config value where a lax check is a SQL
+     * injection with the deployment's own credentials, so the pattern is deliberately narrow: what Postgres
+     * accepts unquoted, and nothing else. A rejected name fails boot, where it is one line to fix.
+     */
+    const rawSchema = lookup("DATABASE_SCHEMA");
+    const databaseSchema = rawSchema === undefined || rawSchema.trim() === "" ? undefined : rawSchema.trim();
+    if (databaseSchema !== undefined && !/^[A-Za-z_][A-Za-z0-9_$]*$/.test(databaseSchema)) {
+        fail(named("DATABASE_SCHEMA"), `must be an unquoted Postgres identifier — letters, digits, underscore and $, not starting with a ` +
+            `digit — got "${databaseSchema.slice(0, 24)}"`);
+    }
     const positiveInt = (suffix, fallback) => {
         // `PORT` has no prefix — it is the conventional name and always has been, so it is read directly.
         const variable = suffix === "PORT" ? "PORT" : named(suffix);
@@ -103,6 +117,9 @@ export const loadConfig = (env) => {
         databaseUrl,
         redisUrl,
         schemaMode: rawSchemaMode,
+        // Spread, not `databaseSchema: undefined` — `exactOptionalPropertyTypes` is on, so an explicit
+        // undefined is a different type from an absent key.
+        ...(databaseSchema === undefined ? {} : { databaseSchema }),
         port,
         workerConcurrency,
         logLevel: rawLogLevel,
@@ -120,6 +137,7 @@ export const loadConfig = (env) => {
 export const REQUIRED_VARIABLES = ["RETINUE_DATABASE_URL", "RETINUE_REDIS_URL"];
 export const OPTIONAL_VARIABLES = [
     "SCHEMA_MODE",
+    "DATABASE_SCHEMA",
     "WORKER_CONCURRENCY",
     "LOG_LEVEL",
     "PORT",

package/dist/server/doctor.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `retinue doctor` — task #252 AC-4.
+ *
+ * The one command here that is new rather than a wrapper, and the one that pays for itself: every failure it
+ * names is otherwise a support conversation. A deployment that will not start currently produces one error, from
+ * whichever check happened to run first, and the operator fixes it and runs again to find the next.
+ *
+ * ## Every failure, not the first
+ *
+ * The whole value is in the plural. A doctor that stops at the first problem sends the user round the loop once
+ * per problem — which is exactly what starting the server already does, so it would add nothing. Each check is
+ * therefore independent and its own failure is caught, so a Postgres that will not connect does not prevent the
+ * Redis check from running.
+ *
+ * ## Nothing here prints a secret
+ *
+ * A diagnostic tool is exactly where a URL with a password in it gets pasted into a support ticket. So a
+ * connection string is reported by its *shape* — host and database, never userinfo — and a failure message is
+ * the driver's, scrubbed. `mcp/egress.ts` already refuses credentials in a URL for the same reason.
+ */
+export type CheckResult = {
+    readonly name: string;
+    readonly ok: boolean;
+    /** What was found. Never a secret. */
+    readonly detail: string;
+    /** Present when `ok` is false: what to do about it. */
+    readonly remedy?: string;
+    /**
+     * A check that could not run rather than one that failed.
+     *
+     * Distinct because the two need different responses: a failed check is a broken deployment, and a skipped one
+     * is a deployment this tool cannot see into. Reporting a skip as a pass would be the "passes having checked
+     * nothing" failure; reporting it as a failure would tell an operator to fix something that is not wrong.
+     */
+    readonly skipped?: boolean;
+};
+export declare const describeUrl: (value: string) => string;
+/** The driver's message, with anything URL-shaped reduced. Errors quote the connection string routinely. */
+export declare const scrub: (message: string) => string;
+export type DoctorDeps = {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Injected so the checks are testable without a database or a Redis.
+     *
+     * Takes the whole connection setting rather than a URL, because `databaseSchema` changes the answer:
+     * the schema probe counts applied migrations, and reading `public` when the deployment configured
+     * `retinue` reports "0 of 35 applied → run migrate" about a schema that is fully migrated. The
+     * comment below already names that class of bug — a diagnostic sending an operator to fix the wrong
+     * thing — and a URL-only signature is how this one would have got in.
+     */
+    readonly connectPostgres?: (settings: {
+        readonly databaseUrl: string;
+        readonly databaseSchema?: string;
+    }) => Promise<{
+        query(text: string, params?: readonly unknown[]): Promise<unknown>;
+        end(): Promise<void>;
+    }>;
+    readonly connectRedis?: (url: string) => Promise<{
+        ping(): Promise<string>;
+        quit(): Promise<unknown>;
+    }>;
+    readonly schemaVersions?: (sql: {
+        query(text: string, params?: readonly unknown[]): Promise<unknown>;
+    }) => Promise<{
+        current: number;
+        target: number;
+    }>;
+};
+/** How long any one check may take before it is reported as a timeout. */
+export declare const CHECK_TIMEOUT_MS = 5000;
+/**
+ * A backstop, because **a diagnostic that hangs is worse than one that fails.**
+ *
+ * Found by running `doctor` against a refused port: `pg.Pool` has no default connect timeout and `ioredis`
+ * retries a refused connection for ever, so the command sat there silently instead of reporting the two
+ * failures it existed to report. Both drivers are now configured to fail fast, and this is the belt to that
+ * braces — a driver whose timeout option is wrong or renamed must not be able to hang the tool.
+ *
+ * The timer is unref'd so a completed check never holds the process open past its work.
+ */
+export declare const withTimeout: <T>(what: string, work: Promise<T>, ms?: number) => Promise<T>;
+export declare const runChecks: (deps?: DoctorDeps) => Promise<readonly CheckResult[]>;
+/** Human output. Returns the exit code, so the caller does not decide what a failure means. */
+export declare const report: (results: readonly CheckResult[], write?: (line: string) => void) => number;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/server/doctor.js

@@ -0,0 +1,280 @@
+/**
+ * `retinue doctor` — task #252 AC-4.
+ *
+ * The one command here that is new rather than a wrapper, and the one that pays for itself: every failure it
+ * names is otherwise a support conversation. A deployment that will not start currently produces one error, from
+ * whichever check happened to run first, and the operator fixes it and runs again to find the next.
+ *
+ * ## Every failure, not the first
+ *
+ * The whole value is in the plural. A doctor that stops at the first problem sends the user round the loop once
+ * per problem — which is exactly what starting the server already does, so it would add nothing. Each check is
+ * therefore independent and its own failure is caught, so a Postgres that will not connect does not prevent the
+ * Redis check from running.
+ *
+ * ## Nothing here prints a secret
+ *
+ * A diagnostic tool is exactly where a URL with a password in it gets pasted into a support ticket. So a
+ * connection string is reported by its *shape* — host and database, never userinfo — and a failure message is
+ * the driver's, scrubbed. `mcp/egress.ts` already refuses credentials in a URL for the same reason.
+ */
+import { ConfigurationError, loadConfig } from "./config.js";
+/**
+ * A connection string reduced to what is safe to print.
+ *
+ * Deliberately not a regex over the whole string: `URL` parsing means a password containing a `@` or a `/`
+ * cannot smuggle itself into the output. An unparseable value is reported as unparseable rather than echoed,
+ * because echoing it is how a secret reaches a log.
+ */
+/**
+ * A connection string reduced to what is safe to print, by **whitelist**.
+ *
+ * Two earlier versions of this leaked, and both leaked the same way — by trying to *remove* the secret from a
+ * string whose structure was not what they assumed:
+ *
+ * 1. Parsing with `URL` and printing `hostname`/`port`/`pathname`. For
+ *    `postgres://user:p@ss/word@db.internal:5432/app`, `URL` reads `user:p` as the userinfo and `ss` as the
+ *    hostname, so the "safe" output was `postgres://ss/word@db.internal:5432/app` — half the password, spread
+ *    across the host and path.
+ * 2. Refusing when the *authority* contained two `@`. The authority ends at the first `/`, and in that example
+ *    the second `@` is after it. So the check passed and the leak stood.
+ *
+ * A redaction function must therefore not try to find the secret. It matches a strict, unambiguous shape and
+ * prints only the groups it captured; anything else is refused unprinted. An unescaped `@` or `/` in a password
+ * is common, and it is exactly what makes a connection string ambiguous — so ambiguity is the thing to refuse,
+ * not to parse harder.
+ */
+const SAFE_URL = /^([a-z][a-z0-9+.-]*):\/\/(?:[^@/?#]*@)?([A-Za-z0-9._-]+|\[[0-9A-Fa-f:]+\])(?::(\d+))?(?:\/([A-Za-z0-9._-]*))?$/;
+export const describeUrl = (value) => {
+    const match = SAFE_URL.exec(value);
+    if (match === null)
+        return "(not printed — the value does not match an unambiguous connection-string shape)";
+    const [, scheme, host, port, database] = match;
+    return `${scheme}://${host}${port === undefined ? "" : `:${port}`}${database ? `/${database}` : ""}`;
+};
+/** The driver's message, with anything URL-shaped reduced. Errors quote the connection string routinely. */
+export const scrub = (message) => message.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s'"]+/gi, (m) => describeUrl(m));
+const message = (error) => scrub(error instanceof Error ? error.message : String(error));
+/** True when `describeUrl` refused to print a value, so nothing derived from it can be trusted either. */
+const unsafe = (described) => described.startsWith("(");
+/**
+ * What to say about a connection failure — the URL and the driver's message, or neither.
+ *
+ * A driver interpolates whatever *it* parsed, so `postgres://u:p@ss/word@host/db` fails with
+ * `getaddrinfo ENOTFOUND ss` — a fragment of the password, in a message no scrubber can recognise as one
+ * because `ss` is not URL-shaped. The rule that follows is simple and the only safe one: if the value could not
+ * be printed, the error derived from it is not printed either. The remedy still names the variable, which is
+ * what the operator needs.
+ */
+const failureDetail = (url, error) => {
+    const described = describeUrl(url);
+    return unsafe(described)
+        ? `${described} The driver's message is withheld for the same reason — it can quote the value it parsed.`
+        : `${described}: ${message(error)}`;
+};
+/** How long any one check may take before it is reported as a timeout. */
+export const CHECK_TIMEOUT_MS = 5_000;
+/**
+ * A backstop, because **a diagnostic that hangs is worse than one that fails.**
+ *
+ * Found by running `doctor` against a refused port: `pg.Pool` has no default connect timeout and `ioredis`
+ * retries a refused connection for ever, so the command sat there silently instead of reporting the two
+ * failures it existed to report. Both drivers are now configured to fail fast, and this is the belt to that
+ * braces — a driver whose timeout option is wrong or renamed must not be able to hang the tool.
+ *
+ * The timer is unref'd so a completed check never holds the process open past its work.
+ */
+export const withTimeout = async (what, work, ms = CHECK_TIMEOUT_MS) => {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${what} did not respond within ${ms}ms`)), ms);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+};
+export const runChecks = async (deps = {}) => {
+    const env = deps.env ?? process.env;
+    const results = [];
+    // 1. Configuration. Everything else needs it, so a failure here skips the rest rather than reporting
+    //    cascading failures that are all the same problem.
+    let config;
+    try {
+        config = loadConfig(env);
+        results.push({ name: "configuration", ok: true, detail: `schema mode ${config.schemaMode}, port ${config.port}` });
+    }
+    catch (error) {
+        results.push({
+            name: "configuration",
+            ok: false,
+            detail: message(error),
+            remedy: error instanceof ConfigurationError
+                ? `Set or correct: ${error.variables.join(", ")}. See .env.example.`
+                : "See .env.example for the variables this deployment needs.",
+        });
+        for (const name of ["postgres", "schema", "redis"]) {
+            results.push({
+                name,
+                ok: true,
+                skipped: true,
+                detail: "not checked — configuration is unusable, so this would fail for the same reason",
+            });
+        }
+        return results;
+    }
+    // 2. The app module, which `serve` and `worker` need and `migrate` does not.
+    const appModule = env["RETINUE_APP_MODULE"];
+    if (appModule === undefined || appModule.trim() === "") {
+        results.push({
+            name: "app module",
+            ok: true,
+            skipped: true,
+            detail: "RETINUE_APP_MODULE is unset — `migrate` and `doctor` work without it; `serve` and `worker` do not",
+            remedy: "Point RETINUE_APP_MODULE at a module default-exporting { authenticate, deps } before serving.",
+        });
+    }
+    else {
+        try {
+            const loaded = (await import(appModule));
+            const app = loaded.default;
+            const ok = typeof app?.authenticate === "function" && typeof app?.deps === "function";
+            results.push({
+                name: "app module",
+                ok,
+                detail: ok ? `${appModule} exports { authenticate, deps }` : `${appModule} loaded but is missing exports`,
+                ...(ok ? {} : { remedy: "It must default-export { authenticate, deps }. `authenticate` has no default." }),
+            });
+        }
+        catch (error) {
+            results.push({
+                name: "app module",
+                ok: false,
+                detail: `${appModule} could not be loaded: ${message(error)}`,
+                remedy: "Check the path is resolvable from the working directory, and that the module builds.",
+            });
+        }
+    }
+    // 3. Postgres, and 4. the schema — one connection, two findings.
+    const connectPostgres = deps.connectPostgres;
+    if (connectPostgres === undefined) {
+        results.push({ name: "postgres", ok: true, skipped: true, detail: "no driver supplied" });
+        results.push({ name: "schema", ok: true, skipped: true, detail: "no driver supplied" });
+    }
+    else {
+        let sql;
+        /**
+         * Whether Postgres *answered*, which is not the same as whether a pool object exists.
+         *
+         * `new Pool()` does not connect, so `sql` is defined even when the database is unreachable — and keying the
+         * schema check on `sql !== undefined` reported "0 of 30 migrations applied → Run `retinue migrate`" against
+         * a database nobody could reach. That is a diagnostic sending an operator to fix the wrong thing, which is
+         * worse than reporting nothing.
+         */
+        let reachable = false;
+        try {
+            sql = await withTimeout("postgres", connectPostgres(config));
+            await withTimeout("postgres", sql.query("select 1"));
+            reachable = true;
+            results.push({ name: "postgres", ok: true, detail: `reachable at ${describeUrl(config.databaseUrl)}` });
+        }
+        catch (error) {
+            results.push({
+                name: "postgres",
+                ok: false,
+                detail: failureDetail(config.databaseUrl, error),
+                remedy: "Check the database is running and RETINUE_DATABASE_URL points at it.",
+            });
+        }
+        if (reachable && sql !== undefined && deps.schemaVersions !== undefined) {
+            try {
+                const { current, target } = await withTimeout("schema", deps.schemaVersions(sql));
+                // Ahead is reported as a failure, not a pass: a database migrated by a newer build than this one is a
+                // deployment about to behave unpredictably, and "current >= target" would call it healthy.
+                const ok = current === target;
+                results.push({
+                    name: "schema",
+                    ok,
+                    detail: `${current} of ${target} migrations applied`,
+                    ...(ok
+                        ? {}
+                        : {
+                            remedy: current < target
+                                ? "Run `retinue migrate`."
+                                : "This database is ahead of this build. Deploy the matching version rather than migrating down.",
+                        }),
+                });
+            }
+            catch (error) {
+                results.push({
+                    name: "schema",
+                    ok: false,
+                    detail: message(error),
+                    remedy: "Run `retinue migrate --status` for detail.",
+                });
+            }
+        }
+        else if (reachable) {
+            results.push({ name: "schema", ok: true, skipped: true, detail: "no schema reader supplied" });
+        }
+        else {
+            results.push({
+                name: "schema",
+                ok: true,
+                skipped: true,
+                detail: "not checked — Postgres is unreachable, so this would fail for the same reason",
+            });
+        }
+        if (sql !== undefined)
+            await sql.end().catch(() => undefined);
+    }
+    // 5. Redis.
+    if (deps.connectRedis === undefined) {
+        results.push({ name: "redis", ok: true, skipped: true, detail: "no client supplied" });
+    }
+    else {
+        let redis;
+        try {
+            redis = await withTimeout("redis", deps.connectRedis(config.redisUrl));
+            const pong = await withTimeout("redis", redis.ping());
+            results.push({ name: "redis", ok: true, detail: `reachable at ${describeUrl(config.redisUrl)} (${pong})` });
+        }
+        catch (error) {
+            results.push({
+                name: "redis",
+                ok: false,
+                detail: failureDetail(config.redisUrl, error),
+                remedy: "Check Redis is running and RETINUE_REDIS_URL points at it.",
+            });
+        }
+        finally {
+            // Always, including after a failure. Leaving a client open kept the socket handle alive and the command
+            // never exited — a diagnostic that reports correctly and then hangs is still a diagnostic that hangs.
+            if (redis !== undefined)
+                await redis.quit().catch(() => undefined);
+        }
+    }
+    return results;
+};
+/** Human output. Returns the exit code, so the caller does not decide what a failure means. */
+export const report = (results, write = console.log) => {
+    const failed = results.filter((r) => !r.ok);
+    for (const r of results) {
+        const mark = !r.ok ? "✗" : r.skipped === true ? "–" : "✓";
+        write(`${mark} ${r.name}: ${r.detail}`);
+        if (r.remedy !== undefined)
+            write(`    → ${r.remedy}`);
+    }
+    write("");
+    write(failed.length === 0
+        ? `✓ ${results.filter((r) => r.skipped !== true).length} check(s) passed`
+        : `✗ ${failed.length} of ${results.length} check(s) failed`);
+    return failed.length === 0 ? 0 : 1;
+};
+//# sourceMappingURL=doctor.js.map

package/dist/server/pool.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The one place a `pg.Pool` is built for this host — REQ-041 (#190).
+ *
+ * There were four: `bin.ts` for `migrate`/`doctor`, `cli.ts` for the API host, `cli-worker.ts` for the
+ * worker, and the driver `doctor` is handed. Four copies of "how this deployment connects" is three
+ * copies too many, and the one that drifts is the one nobody exercises — the worker, whose writes are
+ * the ones that must land in the same schema as everything else.
+ *
+ * **What it adds over `new Pool`.** `RETINUE_DATABASE_SCHEMA` names the schema the platform's tables
+ * live in, and honouring it takes two things that must agree:
+ *
+ *  - `pool.on("connect")` sets `search_path` on **every** connection, because `createPgExecutor` runs
+ *    each query through `pool.query`, which takes a different connection per call. A pooled connection
+ *    carries whatever `search_path` its last user left, so setting it once at startup means the first
+ *    few statements land in the right schema and the rest land wherever. That failure is not loud: it
+ *    is a table created in `public` by a migration that reported success.
+ *  - `createPoolOpener(pool, …)` sets it again per checkout, which is what the transaction scope uses.
+ *    Redundant on paper and deliberately kept: the opener is the path that holds `SELECT … FOR UPDATE`
+ *    across statements, and it must not depend on a listener having fired.
+ *
+ * **`public` stays on the path** after the named schema. Two things need it: the `vector` type is
+ * pinned to `public` so it resolves from any schema (see the note in `migrations.ts`), and ShareFlow's
+ * adapters qualify all 70 of their queries as `public.`, which is what lets one pool serve a platform
+ * schema and a product schema at once.
+ */
+import type { SqlExecutor } from "../adapters/postgres/sql.js";
+import type { ConnectionOpener } from "../adapters/postgres/transaction.js";
+export type PostgresConnection = {
+    readonly sql: SqlExecutor;
+    readonly open: ConnectionOpener;
+    readonly end: () => Promise<void>;
+};
+export type PoolSettings = {
+    readonly databaseUrl: string;
+    readonly databaseSchema?: string;
+    /** Left unset by the host and the worker, which is node-postgres's default of no timeout. */
+    readonly connectionTimeoutMillis?: number;
+};
+/**
+ * The `search_path` for a named schema, or `undefined` to leave the connection's own.
+ *
+ * Exported because it is the only string in this file that ends up in SQL, and a test that pins it is
+ * cheaper than reading two call sites to find out what a deployment actually gets.
+ */
+export declare const searchPathFor: (schema: string | undefined) => string | undefined;
+export declare const openPostgres: (settings: PoolSettings) => Promise<PostgresConnection>;
+//# sourceMappingURL=pool.d.ts.map