@ai-sdlc/orchestrator 0.5.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/cycle-utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Utility functions for cycle detection and handling.
+ */
+import type { IssueTracker } from '@ai-sdlc/reference';
+import { PipelineCycleDetector, type PipelineStage } from './pipeline-cycle-detector.js';
+export interface CycleHandlerOptions {
+    /** Issue or PR identifier. */
+    issueOrPrId: string;
+    /** Stage being invoked. */
+    stage: PipelineStage;
+    /** Issue tracker for fetching/posting comments. */
+    tracker: IssueTracker;
+    /** Cycle detector instance. */
+    detector: PipelineCycleDetector;
+    /** Optional Slack notification callback. */
+    notifySlack?: (message: string) => Promise<void>;
+    /** Custom cycle notification template (optional). */
+    cycleTemplate?: {
+        title: string;
+        body: string;
+    };
+}
+export interface CycleCheckResult {
+    /** Whether a cycle was detected. */
+    cycleDetected: boolean;
+    /** Marker to append to comments for tracking. */
+    marker: string;
+    /** Formatted message describing the cycle (if detected). */
+    cycleMessage?: string;
+}
+/**
+ * Check for pipeline cycles and post notification if detected.
+ *
+ * The marker is generated upfront so the caller can append it to comments
+ * BEFORE executing the stage (records intent, prevents race conditions).
+ * Cycle detection accounts for the pending invocation (+1 to current count).
+ */
+export declare function checkAndHandleCycle(options: CycleHandlerOptions): Promise<CycleCheckResult>;
+/**
+ * Create a cycle detector from pipeline config.
+ * Reads maxRetries from stage configurations.
+ */
+export declare function createCycleDetectorFromConfig(config: {
+    stages?: Array<{
+        name: string;
+        onFailure?: {
+            maxRetries?: number;
+        };
+    }>;
+}): PipelineCycleDetector;
+//# sourceMappingURL=cycle-utils.d.ts.map

package/dist/cycle-utils.js

@@ -0,0 +1,77 @@
+/**
+ * Utility functions for cycle detection and handling.
+ */
+import { PipelineCycleDetector } from './pipeline-cycle-detector.js';
+import { NOTIFICATION_TITLES } from './defaults.js';
+/**
+ * Sanitize template content to prevent markdown/HTML injection.
+ * Strips HTML tags and limits length.
+ */
+function sanitizeTemplate(text) {
+    return text.replace(/<[^>]*>/g, '').slice(0, 2000);
+}
+/**
+ * Check for pipeline cycles and post notification if detected.
+ *
+ * The marker is generated upfront so the caller can append it to comments
+ * BEFORE executing the stage (records intent, prevents race conditions).
+ * Cycle detection accounts for the pending invocation (+1 to current count).
+ */
+export async function checkAndHandleCycle(options) {
+    const { issueOrPrId, stage, tracker, detector, notifySlack, cycleTemplate } = options;
+    // Detect cycles from existing comment markers (no +1 — marker is separate)
+    const cycleResult = await detector.detectCycle(tracker, issueOrPrId);
+    // Generate marker for the caller to append to comments
+    const marker = detector.recordInvocation(stage);
+    if (cycleResult.cycleDetected) {
+        const loopingSummary = cycleResult.loopingStages
+            .map((s) => `- **${s.stage}**: ${s.count}/${s.max} invocations`)
+            .join('\n');
+        const title = sanitizeTemplate(cycleTemplate?.title ?? NOTIFICATION_TITLES.pipelineCycleDetected);
+        const body = sanitizeTemplate(cycleTemplate?.body ??
+            `The pipeline has detected an infinite loop across the following stages:\n\n${loopingSummary}\n\n**Manual intervention is required** to resolve the cycle. Please review the issue and PR to determine the root cause.`);
+        const cycleMessage = `## ${title}\n\n${body}`;
+        // Post cycle detection comment
+        await tracker.addComment(issueOrPrId, cycleMessage);
+        // Send Slack notification if configured
+        if (notifySlack) {
+            const slackMessage = `:warning: *Pipeline Cycle Detected* for #${issueOrPrId}\n\nLooping stages:\n${cycleResult.loopingStages.map((s) => `• ${s.stage}: ${s.count}/${s.max}`).join('\n')}`;
+            await notifySlack(slackMessage).catch((err) => {
+                console.error('[cycle-detector] Slack notification failed:', err instanceof Error ? err.message : String(err));
+            });
+        }
+        return { cycleDetected: true, marker, cycleMessage };
+    }
+    return { cycleDetected: false, marker };
+}
+/**
+ * Create a cycle detector from pipeline config.
+ * Reads maxRetries from stage configurations.
+ */
+export function createCycleDetectorFromConfig(config) {
+    const detector = new PipelineCycleDetector();
+    if (config.stages) {
+        const overrides = {};
+        for (const stage of config.stages) {
+            const maxRetries = stage.onFailure?.maxRetries;
+            if (maxRetries !== undefined) {
+                if (stage.name === 'code') {
+                    overrides['fix-ci'] = maxRetries;
+                }
+                else if (stage.name === 'review') {
+                    overrides['fix-review'] = maxRetries;
+                }
+                else if (stage.name === 'admission' ||
+                    stage.name === 'triage' ||
+                    stage.name === 'agent') {
+                    overrides[stage.name] = maxRetries;
+                }
+            }
+        }
+        if (Object.keys(overrides).length > 0) {
+            detector.updateMaxInvocations(overrides);
+        }
+    }
+    return detector;
+}
+//# sourceMappingURL=cycle-utils.js.map

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