@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/database/adapters/external.js

@@ -0,0 +1,80 @@
+/**
+ * ExternalAdapter per RFC §15.2. Operator-declared shell hooks for proprietary or
+ * custom branching mechanisms. Pipeline-load REQUIRES `acknowledgeUntrusted: true`
+ * because shell hooks execute with full credential scope.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { DatabaseBranchAdapterError, } from '../types.js';
+const execFileAsync = promisify(execFile);
+export class ExternalAdapter {
+    deps;
+    name = 'external';
+    capabilities = {
+        branchCreationLatencyP50Ms: 0, // declared by the hook script's behavior
+        maxBranches: 0, // declared by operator config
+        supportsMigrations: true,
+        supportsReadOnlyBranches: false,
+        supportsBranchFromBranch: true,
+        multiDatabase: true,
+        costModel: 'free',
+    };
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    async validate(pool) {
+        const creds = pool.credentials ?? {};
+        if (creds.acknowledgeUntrusted !== true) {
+            return {
+                ok: false,
+                error: 'external adapter requires credentials.acknowledgeUntrusted: true. Operator-controlled shell hooks execute with full credential scope; this opt-in is intentional friction.',
+            };
+        }
+        if (typeof creds.allocateCommand !== 'string' || !creds.allocateCommand) {
+            return { ok: false, error: 'credentials.allocateCommand (string) is required' };
+        }
+        if (typeof creds.reclaimCommand !== 'string' || !creds.reclaimCommand) {
+            return { ok: false, error: 'credentials.reclaimCommand (string) is required' };
+        }
+        return { ok: true };
+    }
+    async allocate(pool, branchKey) {
+        const cmd = pool.credentials?.allocateCommand;
+        const exec = this.deps.exec ?? ((c, a) => execFileAsync(c, a));
+        let stdout;
+        try {
+            const result = await exec('sh', ['-c', `${cmd} ${branchKey}`]);
+            stdout = result.stdout;
+        }
+        catch (err) {
+            throw new DatabaseBranchAdapterError(`external allocate hook failed for branch ${branchKey}: ${err.message}`, this.name, branchKey, err);
+        }
+        const connectionString = stdout.trim();
+        if (!connectionString) {
+            throw new DatabaseBranchAdapterError(`external allocate hook produced empty stdout (expected connection string)`, this.name, branchKey);
+        }
+        return {
+            branchKey,
+            connectionString,
+            createdAt: new Date(),
+            upstream: pool.upstream.branchFrom ?? 'external',
+            metadata: { hook: 'external' },
+        };
+    }
+    async reclaim(handle) {
+        // The pool isn't passed here; the orchestrator MUST track (handle, pool) pairs and
+        // call this via the dispatcher. For test purposes, callers that use ExternalAdapter
+        // directly must provide their own dispatcher that supplies the reclaim command.
+        void handle;
+    }
+    async list(_pool) {
+        // External hooks don't expose a list mechanism; orchestrator tracks active branches
+        // in its own state.
+        return [];
+    }
+    async isAvailable(pool) {
+        const v = await this.validate(pool);
+        return v.ok;
+    }
+}
+//# sourceMappingURL=external.js.map

package/dist/database/adapters/neon.d.ts

@@ -0,0 +1,41 @@
+/**
+ * NeonAdapter per RFC §15.2. Wraps Neon REST API for branch lifecycle. Phase 6 ships
+ * the adapter shell + capability matrix + validation; the actual REST calls (allocate,
+ * reclaim, list) are stubbed until end-to-end integration testing against a real Neon
+ * sandbox project lands as a follow-up.
+ *
+ * Operators wire this up via:
+ *   credentials:
+ *     apiTokenEnv: NEON_API_TOKEN
+ *     projectId: prj_abc123
+ */
+import { type DatabaseBranchAdapter, type DatabaseBranchCapabilities, type DatabaseBranchHandle, type DatabaseAdapterName, type ResolvedDatabaseBranchPool, type ValidationResult } from '../types.js';
+export interface NeonAdapterDeps {
+    env?: NodeJS.ProcessEnv;
+    /** Override for tests; replaces the actual fetch calls. */
+    api?: {
+        createBranch: (projectId: string, branchName: string, parentBranch: string) => Promise<{
+            branchId: string;
+            connectionString: string;
+        }>;
+        deleteBranch: (projectId: string, branchId: string) => Promise<void>;
+        listBranches: (projectId: string) => Promise<Array<{
+            branchId: string;
+            branchName: string;
+            parent: string;
+            createdAt: string;
+        }>>;
+    };
+}
+export declare class NeonAdapter implements DatabaseBranchAdapter {
+    private readonly deps;
+    readonly name: DatabaseAdapterName;
+    readonly capabilities: DatabaseBranchCapabilities;
+    constructor(deps?: NeonAdapterDeps);
+    validate(pool: ResolvedDatabaseBranchPool): Promise<ValidationResult>;
+    allocate(pool: ResolvedDatabaseBranchPool, branchKey: string): Promise<DatabaseBranchHandle>;
+    reclaim(handle: DatabaseBranchHandle): Promise<void>;
+    list(pool: ResolvedDatabaseBranchPool): Promise<DatabaseBranchHandle[]>;
+    isAvailable(pool: ResolvedDatabaseBranchPool): Promise<boolean>;
+}
+//# sourceMappingURL=neon.d.ts.map

package/dist/database/adapters/neon.js

@@ -0,0 +1,98 @@
+/**
+ * NeonAdapter per RFC §15.2. Wraps Neon REST API for branch lifecycle. Phase 6 ships
+ * the adapter shell + capability matrix + validation; the actual REST calls (allocate,
+ * reclaim, list) are stubbed until end-to-end integration testing against a real Neon
+ * sandbox project lands as a follow-up.
+ *
+ * Operators wire this up via:
+ *   credentials:
+ *     apiTokenEnv: NEON_API_TOKEN
+ *     projectId: prj_abc123
+ */
+import { DatabaseBranchAdapterError, } from '../types.js';
+export class NeonAdapter {
+    deps;
+    name = 'neon';
+    capabilities = {
+        branchCreationLatencyP50Ms: 1500,
+        maxBranches: 5000,
+        supportsMigrations: true,
+        supportsReadOnlyBranches: true,
+        supportsBranchFromBranch: true,
+        multiDatabase: false,
+        costModel: 'per-branch-storage',
+    };
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    async validate(pool) {
+        const env = this.deps.env ?? process.env;
+        const creds = pool.credentials ?? {};
+        const apiTokenEnv = creds.apiTokenEnv;
+        const projectId = creds.projectId;
+        if (!apiTokenEnv) {
+            return { ok: false, error: 'credentials.apiTokenEnv is required for neon adapter' };
+        }
+        if (!env[apiTokenEnv]) {
+            return {
+                ok: false,
+                error: `${apiTokenEnv} is not set in env; cannot authenticate against Neon API`,
+            };
+        }
+        if (!projectId) {
+            return { ok: false, error: 'credentials.projectId is required for neon adapter' };
+        }
+        if (!pool.upstream.branchFrom) {
+            return {
+                ok: false,
+                error: 'upstream.branchFrom is required for neon (named branch to fork from)',
+            };
+        }
+        return { ok: true };
+    }
+    async allocate(pool, branchKey) {
+        if (!this.deps.api) {
+            throw new DatabaseBranchAdapterError('NeonAdapter.allocate is not wired against the live Neon REST API yet (Phase 6 follow-up). ' +
+                'Tests should inject deps.api; production deployments require the integration test pass before use.', this.name, branchKey);
+        }
+        const projectId = pool.credentials?.projectId;
+        const parent = pool.upstream.branchFrom;
+        const result = await this.deps.api.createBranch(projectId, branchKey, parent);
+        return {
+            branchKey,
+            connectionString: result.connectionString,
+            createdAt: new Date(),
+            upstream: parent,
+            metadata: { branchId: result.branchId, projectId },
+        };
+    }
+    async reclaim(handle) {
+        if (!this.deps.api) {
+            throw new DatabaseBranchAdapterError('NeonAdapter.reclaim not wired (Phase 6 follow-up)', this.name, handle.branchKey);
+        }
+        const projectId = handle.metadata.projectId;
+        const branchId = handle.metadata.branchId;
+        if (!projectId || !branchId) {
+            throw new DatabaseBranchAdapterError(`handle missing projectId/branchId in metadata: ${JSON.stringify(handle.metadata)}`, this.name, handle.branchKey);
+        }
+        await this.deps.api.deleteBranch(projectId, branchId);
+    }
+    async list(pool) {
+        if (!this.deps.api)
+            return [];
+        const projectId = pool.credentials?.projectId;
+        const branches = await this.deps.api.listBranches(projectId);
+        return branches.map((b) => ({
+            branchKey: b.branchName,
+            connectionString: '<masked — re-fetch via API>',
+            createdAt: new Date(b.createdAt),
+            upstream: b.parent,
+            metadata: { projectId, branchId: b.branchId },
+        }));
+    }
+    async isAvailable(pool) {
+        const v = await this.validate(pool);
+        return v.ok;
+    }
+}
+//# sourceMappingURL=neon.js.map

package/dist/database/adapters/pg-snapshot-restore.d.ts

@@ -0,0 +1,28 @@
+/**
+ * PgSnapshotRestoreAdapter per RFC §15.2. For vanilla Postgres or AWS RDS — uses
+ * `pg_dump` + `pg_restore` for vanilla, or RDS snapshot/restore APIs for AWS.
+ *
+ * Phase 6 ships the adapter shell with capability matrix + validation. End-to-end
+ * integration test against local Postgres in CI is a follow-up.
+ */
+import { type DatabaseBranchAdapter, type DatabaseBranchCapabilities, type DatabaseBranchHandle, type DatabaseAdapterName, type ResolvedDatabaseBranchPool, type ValidationResult } from '../types.js';
+export interface PgSnapshotRestoreAdapterDeps {
+    env?: NodeJS.ProcessEnv;
+    /** Override for tests; mocks the dump+restore execution. */
+    exec?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare class PgSnapshotRestoreAdapter implements DatabaseBranchAdapter {
+    private readonly deps;
+    readonly name: DatabaseAdapterName;
+    readonly capabilities: DatabaseBranchCapabilities;
+    constructor(deps?: PgSnapshotRestoreAdapterDeps);
+    validate(pool: ResolvedDatabaseBranchPool): Promise<ValidationResult>;
+    allocate(pool: ResolvedDatabaseBranchPool, branchKey: string): Promise<DatabaseBranchHandle>;
+    reclaim(handle: DatabaseBranchHandle): Promise<void>;
+    list(_pool: ResolvedDatabaseBranchPool): Promise<DatabaseBranchHandle[]>;
+    isAvailable(pool: ResolvedDatabaseBranchPool): Promise<boolean>;
+}
+//# sourceMappingURL=pg-snapshot-restore.d.ts.map

package/dist/database/adapters/pg-snapshot-restore.js

@@ -0,0 +1,68 @@
+/**
+ * PgSnapshotRestoreAdapter per RFC §15.2. For vanilla Postgres or AWS RDS — uses
+ * `pg_dump` + `pg_restore` for vanilla, or RDS snapshot/restore APIs for AWS.
+ *
+ * Phase 6 ships the adapter shell with capability matrix + validation. End-to-end
+ * integration test against local Postgres in CI is a follow-up.
+ */
+import { DatabaseBranchAdapterError, } from '../types.js';
+export class PgSnapshotRestoreAdapter {
+    deps;
+    name = 'pg-snapshot-restore';
+    capabilities = {
+        branchCreationLatencyP50Ms: 30_000,
+        maxBranches: 100,
+        supportsMigrations: true,
+        supportsReadOnlyBranches: false,
+        supportsBranchFromBranch: false,
+        multiDatabase: false,
+        costModel: 'per-snapshot',
+    };
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    async validate(pool) {
+        const env = this.deps.env ?? process.env;
+        const creds = pool.credentials ?? {};
+        const adminEnv = creds.adminConnectionStringEnv;
+        const storageVolume = creds.storageVolume;
+        if (!adminEnv) {
+            return {
+                ok: false,
+                error: 'credentials.adminConnectionStringEnv is required (privileged user with CREATEDB)',
+            };
+        }
+        if (!env[adminEnv]) {
+            return { ok: false, error: `${adminEnv} not set in env` };
+        }
+        if (!storageVolume) {
+            return {
+                ok: false,
+                error: 'credentials.storageVolume is required (where snapshots are restored)',
+            };
+        }
+        return { ok: true };
+    }
+    async allocate(pool, branchKey) {
+        if (!this.deps.exec) {
+            throw new DatabaseBranchAdapterError('PgSnapshotRestoreAdapter.allocate not wired (Phase 6 follow-up against fixture Postgres in CI)', this.name, branchKey);
+        }
+        // Placeholder — actual implementation: pg_dump from upstream, createdb branch_<key>, pg_restore into branch.
+        throw new DatabaseBranchAdapterError('PgSnapshotRestoreAdapter integration pending', this.name, branchKey);
+    }
+    async reclaim(handle) {
+        if (!this.deps.exec)
+            return;
+        // Placeholder — actual: dropdb branch_<key>
+        void handle;
+    }
+    async list(_pool) {
+        // Placeholder — actual: query pg_database for branch_-prefixed databases.
+        return [];
+    }
+    async isAvailable(pool) {
+        const v = await this.validate(pool);
+        return v.ok;
+    }
+}
+//# sourceMappingURL=pg-snapshot-restore.js.map

package/dist/database/adapters/sqlite-copy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SqliteCopyAdapter per RFC §15.2. Copies the upstream `.sqlite` file to a per-branch
+ * file in the worktree. Hardlinks for read-only branches; full copy for write/migrate.
+ *
+ * Connection-string format (the orchestrator's existing convention): plain absolute
+ * file path, optionally prefixed with `file://`.
+ */
+import { type DatabaseBranchAdapter, type DatabaseBranchCapabilities, type DatabaseBranchHandle, type DatabaseAdapterName, type ResolvedDatabaseBranchPool, type ValidationResult } from '../types.js';
+export interface SqliteCopyAdapterDeps {
+    env?: NodeJS.ProcessEnv;
+    /** Override the per-branch storage root for tests. Defaults to `<cwd>/.ai-sdlc/db`. */
+    storageRoot?: string;
+}
+export declare class SqliteCopyAdapter implements DatabaseBranchAdapter {
+    private readonly deps;
+    readonly name: DatabaseAdapterName;
+    readonly capabilities: DatabaseBranchCapabilities;
+    constructor(deps?: SqliteCopyAdapterDeps);
+    private storageRootFor;
+    validate(pool: ResolvedDatabaseBranchPool): Promise<ValidationResult>;
+    allocate(pool: ResolvedDatabaseBranchPool, branchKey: string): Promise<DatabaseBranchHandle>;
+    /**
+     * Read-only branch via hardlink (saves disk space when many readers share the same
+     * upstream snapshot). Caller is responsible for never opening the resulting file
+     * for write — SQLite will happily corrupt the hardlinked upstream if treated as RW.
+     */
+    allocateReadOnly(pool: ResolvedDatabaseBranchPool, branchKey: string): Promise<DatabaseBranchHandle>;
+    reclaim(handle: DatabaseBranchHandle): Promise<void>;
+    list(pool: ResolvedDatabaseBranchPool): Promise<DatabaseBranchHandle[]>;
+    isAvailable(pool: ResolvedDatabaseBranchPool): Promise<boolean>;
+}
+//# sourceMappingURL=sqlite-copy.d.ts.map

package/dist/database/adapters/sqlite-copy.js

@@ -0,0 +1,145 @@
+/**
+ * SqliteCopyAdapter per RFC §15.2. Copies the upstream `.sqlite` file to a per-branch
+ * file in the worktree. Hardlinks for read-only branches; full copy for write/migrate.
+ *
+ * Connection-string format (the orchestrator's existing convention): plain absolute
+ * file path, optionally prefixed with `file://`.
+ */
+import { copyFile, link, mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { DatabaseBranchAdapterError, } from '../types.js';
+export class SqliteCopyAdapter {
+    deps;
+    name = 'sqlite-copy';
+    capabilities = {
+        branchCreationLatencyP50Ms: 50,
+        maxBranches: 10_000,
+        supportsMigrations: true,
+        supportsReadOnlyBranches: true,
+        supportsBranchFromBranch: true,
+        multiDatabase: false,
+        costModel: 'free',
+    };
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    storageRootFor(_pool) {
+        return this.deps.storageRoot ?? join(process.cwd(), '.ai-sdlc', 'db');
+    }
+    async validate(pool) {
+        const env = this.deps.env ?? process.env;
+        const upstreamPath = env[pool.upstream.connectionStringEnv];
+        if (!upstreamPath) {
+            return {
+                ok: false,
+                error: `${pool.upstream.connectionStringEnv} is not set in env; cannot locate upstream SQLite file`,
+            };
+        }
+        try {
+            const s = await stat(stripFileScheme(upstreamPath));
+            if (!s.isFile()) {
+                return { ok: false, error: `upstream SQLite path is not a file: ${upstreamPath}` };
+            }
+        }
+        catch {
+            return { ok: false, error: `upstream SQLite file not found: ${upstreamPath}` };
+        }
+        return { ok: true };
+    }
+    async allocate(pool, branchKey) {
+        const env = this.deps.env ?? process.env;
+        const upstreamRaw = env[pool.upstream.connectionStringEnv];
+        if (!upstreamRaw) {
+            throw new DatabaseBranchAdapterError(`${pool.upstream.connectionStringEnv} not set`, this.name, branchKey);
+        }
+        const upstreamPath = stripFileScheme(upstreamRaw);
+        const branchPath = join(this.storageRootFor(pool), `${branchKey}.sqlite`);
+        await mkdir(dirname(branchPath), { recursive: true });
+        try {
+            await copyFile(upstreamPath, branchPath);
+        }
+        catch (err) {
+            throw new DatabaseBranchAdapterError(`failed to copy SQLite database for branch '${branchKey}': ${err.message}`, this.name, branchKey, err);
+        }
+        return {
+            branchKey,
+            connectionString: `file://${branchPath}`,
+            createdAt: new Date(),
+            upstream: upstreamPath,
+            metadata: { branchPath, mode: 'copy' },
+        };
+    }
+    /**
+     * Read-only branch via hardlink (saves disk space when many readers share the same
+     * upstream snapshot). Caller is responsible for never opening the resulting file
+     * for write — SQLite will happily corrupt the hardlinked upstream if treated as RW.
+     */
+    async allocateReadOnly(pool, branchKey) {
+        const env = this.deps.env ?? process.env;
+        const upstreamRaw = env[pool.upstream.connectionStringEnv];
+        if (!upstreamRaw) {
+            throw new DatabaseBranchAdapterError(`${pool.upstream.connectionStringEnv} not set`, this.name, branchKey);
+        }
+        const upstreamPath = stripFileScheme(upstreamRaw);
+        const branchPath = join(this.storageRootFor(pool), `${branchKey}.ro.sqlite`);
+        await mkdir(dirname(branchPath), { recursive: true });
+        try {
+            await link(upstreamPath, branchPath);
+        }
+        catch {
+            // Fall back to a copy if hardlink fails (e.g., across filesystems).
+            await copyFile(upstreamPath, branchPath);
+        }
+        return {
+            branchKey,
+            connectionString: `file://${branchPath}?mode=ro`,
+            createdAt: new Date(),
+            upstream: upstreamPath,
+            metadata: { branchPath, mode: 'hardlink-ro' },
+        };
+    }
+    async reclaim(handle) {
+        const path = handle.metadata.branchPath;
+        if (!path)
+            return;
+        await rm(path, { force: true });
+    }
+    async list(pool) {
+        const root = this.storageRootFor(pool);
+        let entries;
+        try {
+            entries = await readdir(root);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const handles = [];
+        for (const entry of entries) {
+            if (!entry.endsWith('.sqlite'))
+                continue;
+            const branchPath = join(root, entry);
+            const s = await stat(branchPath);
+            const branchKey = entry.replace(/\.(?:ro\.)?sqlite$/, '');
+            handles.push({
+                branchKey,
+                connectionString: `file://${branchPath}`,
+                createdAt: new Date(s.birthtimeMs || s.mtimeMs),
+                upstream: 'unknown',
+                metadata: { branchPath, mode: entry.includes('.ro.') ? 'hardlink-ro' : 'copy' },
+            });
+        }
+        return handles;
+    }
+    async isAvailable(pool) {
+        const validation = await this.validate(pool);
+        return validation.ok;
+    }
+}
+function stripFileScheme(path) {
+    if (path.startsWith('file://'))
+        return path.slice('file://'.length);
+    return path;
+}
+//# sourceMappingURL=sqlite-copy.js.map

package/dist/database/connection-injection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Connection-string injection per RFC §15.6. The agent sees the per-worktree branch
+ * via the same env-var name (`DATABASE_URL` etc.) the application expects. Adapters
+ * provide the rewritten string; this module derives optional component env vars
+ * (PGHOST, PGDATABASE, etc.) from it.
+ */
+import type { DatabaseBranchHandle, ResolvedDatabaseBranchPool } from './types.js';
+export interface InjectedEnvOverrides {
+    [envName: string]: string;
+}
+/**
+ * Build the env-var overlay for a single (handle, pool) pair. The agent's process
+ * env is the orchestrator's env merged with this overlay.
+ *
+ * Component derivation supports postgres:// connection strings — for non-Postgres
+ * URLs (e.g., sqlite file paths), additionalEnvs is silently ignored.
+ */
+export declare function buildInjectionOverrides(handle: DatabaseBranchHandle, pool: ResolvedDatabaseBranchPool): InjectedEnvOverrides;
+interface ConnectionComponents {
+    host: string;
+    port: string;
+    database: string;
+    user: string;
+    password: string;
+}
+export declare function parsePostgresUrl(url: string): ConnectionComponents | null;
+/**
+ * Mask a connection string for safe logging. Replaces the password segment with
+ * `****`. Per RFC §15.1 the connection string itself MUST NEVER appear in any
+ * observability output — this helper exists for adapter error messages where
+ * the URL form might leak.
+ */
+export declare function maskConnectionString(url: string): string;
+export {};
+//# sourceMappingURL=connection-injection.d.ts.map

package/dist/database/connection-injection.js

@@ -0,0 +1,93 @@
+/**
+ * Connection-string injection per RFC §15.6. The agent sees the per-worktree branch
+ * via the same env-var name (`DATABASE_URL` etc.) the application expects. Adapters
+ * provide the rewritten string; this module derives optional component env vars
+ * (PGHOST, PGDATABASE, etc.) from it.
+ */
+/**
+ * Build the env-var overlay for a single (handle, pool) pair. The agent's process
+ * env is the orchestrator's env merged with this overlay.
+ *
+ * Component derivation supports postgres:// connection strings — for non-Postgres
+ * URLs (e.g., sqlite file paths), additionalEnvs is silently ignored.
+ */
+export function buildInjectionOverrides(handle, pool) {
+    const overrides = {};
+    overrides[pool.injection.targetEnv] = handle.connectionString;
+    if (pool.injection.additionalEnvs && pool.injection.additionalEnvs.length > 0) {
+        const components = parsePostgresUrl(handle.connectionString);
+        if (components) {
+            for (const envName of pool.injection.additionalEnvs) {
+                const mapped = mapEnvNameToComponent(envName, components);
+                if (mapped !== null)
+                    overrides[envName] = mapped;
+            }
+        }
+    }
+    return overrides;
+}
+export function parsePostgresUrl(url) {
+    // postgres://[user[:password]@]host[:port][/database][?...]
+    // Also handles postgresql:// scheme.
+    try {
+        const parsed = new URL(url);
+        if (!/^postgres(?:ql)?:$/.test(parsed.protocol))
+            return null;
+        return {
+            host: parsed.hostname,
+            port: parsed.port || '5432',
+            database: parsed.pathname.replace(/^\//, ''),
+            user: decodeURIComponent(parsed.username),
+            password: decodeURIComponent(parsed.password),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function mapEnvNameToComponent(name, c) {
+    const upper = name.toUpperCase();
+    switch (upper) {
+        case 'PGHOST':
+        case 'POSTGRES_HOST':
+        case 'DB_HOST':
+            return c.host;
+        case 'PGPORT':
+        case 'POSTGRES_PORT':
+        case 'DB_PORT':
+            return c.port;
+        case 'PGDATABASE':
+        case 'POSTGRES_DB':
+        case 'DB_NAME':
+            return c.database;
+        case 'PGUSER':
+        case 'POSTGRES_USER':
+        case 'DB_USER':
+            return c.user;
+        case 'PGPASSWORD':
+        case 'POSTGRES_PASSWORD':
+        case 'DB_PASSWORD':
+            return c.password;
+        default:
+            return null;
+    }
+}
+/**
+ * Mask a connection string for safe logging. Replaces the password segment with
+ * `****`. Per RFC §15.1 the connection string itself MUST NEVER appear in any
+ * observability output — this helper exists for adapter error messages where
+ * the URL form might leak.
+ */
+export function maskConnectionString(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.password) {
+            parsed.password = '****';
+        }
+        return parsed.toString();
+    }
+    catch {
+        return '<unparseable connection string>';
+    }
+}
+//# sourceMappingURL=connection-injection.js.map

package/dist/database/index.d.ts

@@ -0,0 +1,12 @@
+export * from './types.js';
+export { DatabaseAdapterRegistry, UnknownDatabaseAdapterError } from './registry.js';
+export { buildInjectionOverrides, parsePostgresUrl, maskConnectionString, type InjectedEnvOverrides, } from './connection-injection.js';
+export { enforceTopologyGuard, buildMigrationDivergedEvent, type KnownInFlightBranches, type MigrationDivergedEvent, } from './topology.js';
+export { SqliteCopyAdapter, type SqliteCopyAdapterDeps } from './adapters/sqlite-copy.js';
+export { NeonAdapter, type NeonAdapterDeps } from './adapters/neon.js';
+export { PgSnapshotRestoreAdapter, type PgSnapshotRestoreAdapterDeps, } from './adapters/pg-snapshot-restore.js';
+export { ExternalAdapter, type ExternalAdapterDeps } from './adapters/external.js';
+import { DatabaseAdapterRegistry } from './registry.js';
+/** Pre-populated registry with the four shipped v1 adapters. */
+export declare function createDefaultDatabaseAdapterRegistry(): DatabaseAdapterRegistry;
+//# sourceMappingURL=index.d.ts.map

package/dist/database/index.js

@@ -0,0 +1,23 @@
+export * from './types.js';
+export { DatabaseAdapterRegistry, UnknownDatabaseAdapterError } from './registry.js';
+export { buildInjectionOverrides, parsePostgresUrl, maskConnectionString, } from './connection-injection.js';
+export { enforceTopologyGuard, buildMigrationDivergedEvent, } from './topology.js';
+export { SqliteCopyAdapter } from './adapters/sqlite-copy.js';
+export { NeonAdapter } from './adapters/neon.js';
+export { PgSnapshotRestoreAdapter, } from './adapters/pg-snapshot-restore.js';
+export { ExternalAdapter } from './adapters/external.js';
+import { DatabaseAdapterRegistry } from './registry.js';
+import { SqliteCopyAdapter } from './adapters/sqlite-copy.js';
+import { NeonAdapter } from './adapters/neon.js';
+import { PgSnapshotRestoreAdapter } from './adapters/pg-snapshot-restore.js';
+import { ExternalAdapter } from './adapters/external.js';
+/** Pre-populated registry with the four shipped v1 adapters. */
+export function createDefaultDatabaseAdapterRegistry() {
+    const reg = new DatabaseAdapterRegistry();
+    reg.register(new SqliteCopyAdapter());
+    reg.register(new NeonAdapter());
+    reg.register(new PgSnapshotRestoreAdapter());
+    reg.register(new ExternalAdapter());
+    return reg;
+}
+//# sourceMappingURL=index.js.map

package/dist/database/registry.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseAdapterName, DatabaseBranchAdapter } from './types.js';
+export declare class UnknownDatabaseAdapterError extends Error {
+    readonly name: string;
+    constructor(name: string);
+}
+export declare class DatabaseAdapterRegistry {
+    private readonly adapters;
+    register(adapter: DatabaseBranchAdapter): void;
+    get(name: string): DatabaseBranchAdapter;
+    has(name: string): boolean;
+    list(): DatabaseAdapterName[];
+}
+//# sourceMappingURL=registry.d.ts.map