@ai-sdlc/orchestrator 0.6.0 → 0.9.0

package/dist/config.js

@@ -9,9 +9,8 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { validateResource, createAdapterRegistry, scanLocalAdapters, } from '@ai-sdlc/reference';
-/** Resource kinds that allow only a single instance. */
+/** Resource kinds that allow only a single instance. Multi-instance kinds are excluded. */
 const KIND_KEY = {
-    Pipeline: 'pipeline',
     AgentRole: 'agentRole',
     QualityGate: 'qualityGate',
     AutonomyPolicy: 'autonomyPolicy',
@@ -27,21 +26,54 @@ export function loadConfig(configDir) {
     }
     const files = readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
     const config = {};
+    const warnings = [];
     for (const file of files) {
-        // Skip non-resource YAML files (e.g. manifest.yaml)
-        if (file === 'manifest.yaml')
+        let doc;
+        try {
+            const raw = readFileSync(resolve(dir, file), 'utf-8');
+            doc = parseYaml(raw);
+        }
+        catch (err) {
+            // Malformed YAML — record and continue. One bad file should not
+            // poison the rest of the config (forward-looking YAMLs in active
+            // adoption are common).
+            warnings.push({ file, error: `parse error: ${err.message}` });
+            continue;
+        }
+        // Skip non-resource YAML files (review-exemplars.yaml, manifest.yaml, etc.)
+        // AI-SDLC resources always have an apiVersion field.
+        if (!doc || typeof doc !== 'object' || !('apiVersion' in doc) || !('kind' in doc)) {
             continue;
-        const raw = readFileSync(resolve(dir, file), 'utf-8');
-        const doc = parseYaml(raw);
+        }
         const result = validateResource(doc);
         if (!result.valid) {
-            const msgs = (result.errors ?? []).map((e) => `  ${e.path}: ${e.message}`).join('\n');
-            throw new Error(`Validation failed for ${file}:\n${msgs}`);
+            const msgs = (result.errors ?? []).map((e) => `${e.path}: ${e.message}`).join('; ');
+            // Forward-looking schemas are common during incremental adoption
+            // (RFC-0008 §A.4 readers landing in phases). Record + skip rather
+            // than throw — callers see the warning, the rest of the config
+            // (the parts that DO validate) continues to drive admission.
+            warnings.push({ file, error: `validation failed: ${msgs}` });
+            continue;
         }
         const resource = result.data;
         if (resource.kind === 'AdapterBinding') {
             (config.adapterBindings ??= []).push(resource);
         }
+        else if (resource.kind === 'DesignSystemBinding') {
+            (config.designSystemBindings ??= []).push(resource);
+        }
+        else if (resource.kind === 'DesignIntentDocument') {
+            (config.designIntentDocuments ??= []).push(resource);
+        }
+        else if (resource.kind === 'Pipeline') {
+            (config.pipelines ??= []).push(resource);
+            // Backward-compat: `config.pipeline` (singular) = the canonical one.
+            // Prefer the file literally named `pipeline.yaml` (the default workflow).
+            // Fall back to the first loaded otherwise.
+            if (file === 'pipeline.yaml' || file === 'pipeline.yml' || !config.pipeline) {
+                config.pipeline = resource;
+            }
+        }
         else {
             const key = KIND_KEY[resource.kind];
             if (key) {
@@ -50,12 +82,50 @@ export function loadConfig(configDir) {
             }
         }
     }
+    if (warnings.length > 0) {
+        config.warnings = warnings;
+    }
     // Backward compat: set adapterBinding to the first binding
     if (config.adapterBindings?.length) {
         config.adapterBinding = config.adapterBindings[0];
     }
+    // RFC-0008: validate DID → DSB cross-references
+    if (config.designIntentDocuments?.length) {
+        validateDesignIntentDocumentReferences(config);
+    }
     return config;
 }
+/**
+ * Validate that every DesignIntentDocument's `spec.designSystemRef.name`
+ * resolves to a loaded DesignSystemBinding. Namespace match is required
+ * only when both resources declare a namespace (RFC-0008 §4.5).
+ *
+ * Unidirectional: DID → DSB. DesignSystemBinding surface is not modified.
+ */
+export function validateDesignIntentDocumentReferences(config) {
+    const dids = config.designIntentDocuments ?? [];
+    const dsbs = config.designSystemBindings ?? [];
+    const unresolved = [];
+    for (const did of dids) {
+        const targetName = did.spec.designSystemRef.name;
+        const targetNamespace = did.spec.designSystemRef.namespace;
+        const match = dsbs.find((dsb) => {
+            if (dsb.metadata.name !== targetName)
+                return false;
+            if (targetNamespace && dsb.metadata.namespace && dsb.metadata.namespace !== targetNamespace) {
+                return false;
+            }
+            return true;
+        });
+        if (!match) {
+            const nsSuffix = targetNamespace ? `/${targetNamespace}` : '';
+            unresolved.push(`  DesignIntentDocument "${did.metadata.name}" references "${targetName}${nsSuffix}" which does not resolve to any loaded DesignSystemBinding`);
+        }
+    }
+    if (unresolved.length > 0) {
+        throw new Error(`DID → DesignSystemBinding reference validation failed:\n${unresolved.join('\n')}`);
+    }
+}
 /**
  * Async variant of loadConfig that also scans for local adapter plugins.
  */

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

@@ -0,0 +1,24 @@
+/**
+ * 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 { type DatabaseBranchAdapter, type DatabaseBranchCapabilities, type DatabaseBranchHandle, type DatabaseAdapterName, type ResolvedDatabaseBranchPool, type ValidationResult } from '../types.js';
+export interface ExternalAdapterDeps {
+    exec?: (cmd: string, args: string[]) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare class ExternalAdapter implements DatabaseBranchAdapter {
+    private readonly deps;
+    readonly name: DatabaseAdapterName;
+    readonly capabilities: DatabaseBranchCapabilities;
+    constructor(deps?: ExternalAdapterDeps);
+    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=external.d.ts.map

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