vgxness 0.1.0

package/dist/runs/run-snapshot-export-service.js

@@ -0,0 +1,31 @@
+import { redactJsonValue } from '../export/redaction.js';
+import { runSnapshotPackageKind } from './schema.js';
+export class RunSnapshotExportService {
+    runs;
+    constructor(runs) {
+        this.runs = runs;
+    }
+    exportSnapshot(input) {
+        const details = this.runs.getRun(input.runId);
+        if (!details.ok)
+            return details;
+        if (details.value.project !== input.project) {
+            return validationFailure(`Run project mismatch: expected ${input.project}, got ${details.value.project}`);
+        }
+        const redactedRun = redactJsonValue(details.value);
+        return {
+            ok: true,
+            value: {
+                kind: runSnapshotPackageKind,
+                version: 1,
+                exportedAt: new Date().toISOString(),
+                project: input.project,
+                runId: input.runId,
+                run: redactedRun,
+            },
+        };
+    }
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/runs/sandbox-process-execution.js

@@ -0,0 +1,218 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+const defaultTimeoutMs = 10_000;
+const defaultOutputLimitBytes = 64 * 1024;
+const allowedEnvKey = /^[A-Z_][A-Z0-9_]*$/u;
+const shellMetaCharacters = /[\s;&|<>$`\\]/u;
+export function buildSandboxExecutionPlan(request) {
+    const workspaceRoot = realpathOrUndefined(request.workspaceRoot);
+    if (workspaceRoot === undefined)
+        return rejected('workspace-root-not-found', `Workspace root does not exist: ${request.workspaceRoot}`);
+    const cwd = realpathOrUndefined(request.cwd ?? request.workspaceRoot);
+    if (cwd === undefined)
+        return rejected('cwd-not-found', `Process cwd does not exist: ${request.cwd ?? request.workspaceRoot}`, workspaceRoot);
+    if (!isInside(cwd, workspaceRoot))
+        return rejected('cwd-escapes-workspace', `Process cwd escapes workspace boundary: ${request.cwd ?? request.workspaceRoot}`, workspaceRoot, cwd);
+    if (isProviderConfigPath(cwd, workspaceRoot))
+        return rejected('provider-config-cwd-rejected', `Process cwd targets provider/OpenCode config: ${request.cwd ?? request.workspaceRoot}`, workspaceRoot, cwd);
+    if (request.command.length === 0)
+        return rejected('empty-command', 'Process command is required.', workspaceRoot, cwd);
+    if (isAbsolute(request.command) || request.command.includes(sep) || shellMetaCharacters.test(request.command)) {
+        return rejected('shell-or-path-command-rejected', 'Command must be a single allowlisted executable name; shell strings and paths are rejected.', workspaceRoot, cwd);
+    }
+    if (!request.allowedCommands.includes(request.command)) {
+        return rejected('command-not-allowlisted', `Command is not allowlisted: ${request.command}`, workspaceRoot, cwd);
+    }
+    const argv = request.args ?? [];
+    if (!argv.every((arg) => typeof arg === 'string'))
+        return rejected('invalid-argv', 'Arguments must be an argv array of strings.', workspaceRoot, cwd);
+    const targetPaths = request.targetPaths ?? [];
+    if (!targetPaths.every((targetPath) => typeof targetPath === 'string'))
+        return rejected('invalid-target-paths', 'Target paths must be an array of strings.', workspaceRoot, cwd);
+    const providerConfigTargetPath = targetPaths.find((targetPath) => isProviderConfigPath(targetPath, workspaceRoot));
+    if (providerConfigTargetPath !== undefined)
+        return rejected('provider-config-target-path-rejected', `Process plan target path targets provider/OpenCode config: ${providerConfigTargetPath}`, workspaceRoot, cwd);
+    const env = request.env ?? {};
+    const envKeys = Object.keys(env).sort();
+    const invalidEnvKey = envKeys.find((key) => !allowedEnvKey.test(key));
+    if (invalidEnvKey !== undefined)
+        return rejected('invalid-env-key', `Environment key is not in the limited allow shape: ${invalidEnvKey}`, workspaceRoot, cwd);
+    const timeoutMs = request.timeoutMs ?? defaultTimeoutMs;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+        return rejected('invalid-timeout', 'Timeout must be an integer between 1 and 60000 ms.', workspaceRoot, cwd);
+    const outputLimitBytes = request.outputLimitBytes ?? defaultOutputLimitBytes;
+    if (!Number.isInteger(outputLimitBytes) || outputLimitBytes < 1 || outputLimitBytes > 1024 * 1024)
+        return rejected('invalid-output-limit', 'Output limit must be an integer between 1 byte and 1 MiB.', workspaceRoot, cwd);
+    const evidence = acceptedEvidence(workspaceRoot, cwd, [
+        'workspace-root-realpath-resolved',
+        'cwd-realpath-inside-workspace',
+        'command-is-executable-name-not-shell-string',
+        'command-allowlisted',
+        'argv-array-only',
+        'limited-env-keys-validated',
+        'timeout-configured',
+        'output-cap-configured',
+        'provider-config-paths-not-targeted-by-process-plan',
+    ]);
+    return {
+        ok: true,
+        value: {
+            strategy: 'bounded-process',
+            executable: true,
+            request: { workspaceRoot, cwd, command: request.command, argv, envKeys, timeoutMs, outputLimitBytes },
+            evidence,
+        },
+    };
+}
+export async function executeSandboxedProcess(request) {
+    const plan = buildSandboxExecutionPlan(request);
+    if (!plan.ok)
+        return plan;
+    const { command, argv, cwd, timeoutMs, outputLimitBytes } = plan.value.request;
+    const env = limitedEnv(request.env ?? {});
+    return await new Promise((resolvePromise) => {
+        const child = spawn(command, argv, { cwd, env, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let outputBytes = 0;
+        let outputTruncated = false;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        const append = (chunk, target) => {
+            if (outputBytes >= outputLimitBytes) {
+                outputTruncated = true;
+                return;
+            }
+            const remaining = outputLimitBytes - outputBytes;
+            const slice = chunk.subarray(0, Math.max(0, remaining));
+            outputBytes += slice.byteLength;
+            if (slice.byteLength < chunk.byteLength)
+                outputTruncated = true;
+            if (target === 'stdout')
+                stdout += slice.toString('utf8');
+            else
+                stderr += slice.toString('utf8');
+        };
+        child.stdout?.on('data', (chunk) => append(chunk, 'stdout'));
+        child.stderr?.on('data', (chunk) => append(chunk, 'stderr'));
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            resolvePromise({ ok: false, error: { code: 'process-launch-failed', message: error.message, evidence: plan.value.evidence } });
+        });
+        child.on('close', (exitCode, signal) => {
+            clearTimeout(timer);
+            resolvePromise({ ok: true, value: { exitCode, signal, stdout, stderr, timedOut, outputTruncated, evidence: plan.value.evidence } });
+        });
+    });
+}
+export function executeSandboxedProcessSync(request) {
+    const plan = buildSandboxExecutionPlan(request);
+    if (!plan.ok)
+        return plan;
+    const { command, argv, cwd, timeoutMs, outputLimitBytes } = plan.value.request;
+    const executed = spawnSync(command, argv, {
+        cwd,
+        env: limitedEnv(request.env ?? {}),
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+        encoding: 'buffer',
+        maxBuffer: outputLimitBytes,
+    });
+    if (executed.error !== undefined && executed.error.message.includes('maxBuffer')) {
+        // Keep the bounded-process contract explicit: output beyond maxBuffer is truncated.
+    }
+    else if (executed.error !== undefined && !isTimeoutError(executed.error)) {
+        return { ok: false, error: { code: 'process-launch-failed', message: executed.error.message, evidence: plan.value.evidence } };
+    }
+    const stdout = bufferToLimitedString(executed.stdout, outputLimitBytes);
+    const remaining = Math.max(0, outputLimitBytes - Buffer.byteLength(stdout));
+    const stderr = bufferToLimitedString(executed.stderr, remaining);
+    const outputTruncated = Buffer.byteLength(stdout) + Buffer.byteLength(stderr) >= outputLimitBytes || (executed.error?.message.includes('maxBuffer') ?? false);
+    return {
+        ok: true,
+        value: {
+            exitCode: executed.status,
+            signal: executed.signal,
+            stdout,
+            stderr,
+            timedOut: isTimeoutError(executed.error),
+            outputTruncated,
+            evidence: plan.value.evidence,
+        },
+    };
+}
+function isTimeoutError(error) {
+    return error?.code === 'ETIMEDOUT';
+}
+function bufferToLimitedString(buffer, limit) {
+    if (buffer === null || buffer === undefined || limit <= 0)
+        return '';
+    const source = typeof buffer === 'string' ? Buffer.from(buffer) : buffer;
+    return source.subarray(0, limit).toString('utf8');
+}
+function acceptedEvidence(workspaceRoot, cwd, checks) {
+    return {
+        strategy: 'bounded-process',
+        enforceable: true,
+        workspaceRoot,
+        cwd,
+        capabilities: {
+            sandboxEnforceable: true,
+            processExecutionEnforceable: true,
+            workspaceBoundaryEnforced: true,
+            providerConfigWritesBlocked: true,
+            shellDisabled: true,
+            argvArrayOnly: true,
+            limitedEnvironment: true,
+            timeoutEnforced: true,
+            outputCapEnforced: true,
+            filesystemIsolation: false,
+            networkIsolation: false,
+        },
+        limitations: [
+            'bounded-process enforces local process launch constraints only; it is not an OS-level filesystem sandbox',
+            'bounded-process does not prove network isolation',
+        ],
+        validation: { accepted: true, checks },
+    };
+}
+function rejected(code, message, workspaceRoot, cwd) {
+    const evidence = workspaceRoot === undefined || cwd === undefined
+        ? undefined
+        : { ...acceptedEvidence(workspaceRoot, cwd, []), enforceable: false, validation: { accepted: false, checks: [code] } };
+    return { ok: false, error: { code, message, ...(evidence === undefined ? {} : { evidence }) } };
+}
+function realpathOrUndefined(path) {
+    try {
+        return realpathSync.native(resolve(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isInside(path, workspaceRoot) {
+    return path === workspaceRoot || path.startsWith(`${workspaceRoot}${sep}`);
+}
+function isProviderConfigPath(path, workspaceRoot) {
+    const absolutePath = resolve(workspaceRoot, path);
+    const projectOpenCodeDirectory = resolve(workspaceRoot, '.opencode');
+    if (absolutePath === projectOpenCodeDirectory || isInside(absolutePath, projectOpenCodeDirectory))
+        return true;
+    if (absolutePath === resolve(workspaceRoot, 'opencode.json') || absolutePath === resolve(workspaceRoot, 'opencode.jsonc'))
+        return true;
+    const userOpenCodeDirectory = resolve(homedir(), '.config', 'opencode');
+    return absolutePath === userOpenCodeDirectory || isInside(absolutePath, userOpenCodeDirectory);
+}
+function limitedEnv(input) {
+    const env = { PATH: process.env.PATH ?? '' };
+    for (const [key, value] of Object.entries(input))
+        if (value !== undefined)
+            env[key] = value;
+    return env;
+}

package/dist/runs/sandbox-worktree-planning.js

@@ -0,0 +1,59 @@
+import { sep } from 'node:path';
+import { resolveWorkspaceContainedPath } from '../permissions/policy-evaluator.js';
+const uncheckedGitBoundary = {
+    status: 'uncertain',
+    reason: 'git boundary validation was not reached',
+};
+export function planWorktreeSandbox(input) {
+    const contained = resolveWorkspaceContainedPath(input.workspaceRoot, input.targetPath);
+    if (!contained.ok)
+        return rejected(input.workspaceRoot, uncheckedGitBoundary, 'sandbox_boundary', contained.reason);
+    const configPath = providerConfigPath(contained.targetPath, contained.workspaceRoot);
+    if (configPath !== undefined) {
+        return rejected(contained.workspaceRoot, uncheckedGitBoundary, 'provider_config_write', `Provider config target is prohibited: ${configPath}`);
+    }
+    const gitBoundary = input.gitBoundaryInspector({ workspaceRoot: contained.workspaceRoot, targetPath: contained.targetPath });
+    if (gitBoundary.status !== 'compatible')
+        return rejected(contained.workspaceRoot, gitBoundary, 'git_boundary', gitBoundary.reason);
+    return {
+        strategy: 'worktree',
+        decision: 'accepted',
+        workspaceRoot: contained.workspaceRoot,
+        targetPath: contained.targetPath,
+        gitBoundary,
+        providerConfigMutation: false,
+        createsWorktree: false,
+        executesProvider: false,
+        audit: {
+            workspaceRoot: contained.workspaceRoot,
+            strategy: 'worktree',
+            decision: 'accepted',
+            validationSummary: gitBoundary.reason,
+        },
+    };
+}
+function rejected(workspaceRoot, gitBoundary, reason, validationSummary) {
+    return {
+        strategy: 'worktree',
+        decision: 'rejected',
+        workspaceRoot,
+        gitBoundary,
+        providerConfigMutation: false,
+        createsWorktree: false,
+        executesProvider: false,
+        reason,
+        audit: {
+            workspaceRoot,
+            strategy: 'worktree',
+            decision: 'rejected',
+            validationSummary,
+        },
+    };
+}
+function providerConfigPath(targetPath, workspaceRoot) {
+    const relative = targetPath.slice(workspaceRoot.length).split(sep).filter(Boolean);
+    const firstSegment = relative[0];
+    if (firstSegment === '.opencode' || firstSegment === '.claude')
+        return firstSegment;
+    return undefined;
+}

package/dist/runs/schema.js

@@ -0,0 +1 @@
+export const runSnapshotPackageKind = 'vgxness.run-snapshot-package';

package/dist/sdd/artifact-portability-service.js

@@ -0,0 +1,118 @@
+import { redactJsonValue } from '../export/redaction.js';
+import { isSddPhase, sddTopicKey } from './schema.js';
+export const artifactPackageKind = 'vgxness.sdd-artifact-package';
+const defaultContext = { actor: 'artifact-portability-service' };
+const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export class ArtifactPortabilityService {
+    memory;
+    workflow;
+    context;
+    constructor(memory, workflow, context = defaultContext) {
+        this.memory = memory;
+        this.workflow = workflow;
+        this.context = context;
+    }
+    exportPackage(input) {
+        const validIdentity = validateIdentity(input.project, input.change);
+        if (!validIdentity.ok)
+            return validIdentity;
+        const listed = this.memory.listArtifactsByTopicPrefix(input.project, `sdd/${input.change}/`, this.context);
+        if (!listed.ok)
+            return listed;
+        const artifacts = listed.value.filter(isCanonicalArtifact).map(toPortableArtifact);
+        if (artifacts.length === 0)
+            return failure(`No SDD artifacts found for ${input.project}/${input.change}`);
+        const artifactPackage = { kind: artifactPackageKind, version: 1, project: input.project, change: input.change, exportedAt: new Date().toISOString(), artifacts };
+        return { ok: true, value: redactJsonValue(artifactPackage) };
+    }
+    validatePackage(input) {
+        if (!isRecord(input))
+            return failure('Package must be a JSON object');
+        if (input.kind !== artifactPackageKind)
+            return failure('Package kind is invalid');
+        if (input.version !== 1)
+            return failure('Package version is invalid');
+        if (typeof input.project !== 'string' || input.project.trim().length === 0)
+            return failure('Package project is required');
+        if (typeof input.change !== 'string' || !validChangePattern.test(input.change))
+            return failure('Package change is invalid');
+        if (typeof input.exportedAt !== 'string' || input.exportedAt.trim().length === 0)
+            return failure('Package exportedAt is required');
+        if (!Array.isArray(input.artifacts) || input.artifacts.length === 0)
+            return failure('Package artifacts must not be empty');
+        const artifacts = [];
+        for (const item of input.artifacts) {
+            if (!isRecord(item))
+                return failure('Artifact entry must be an object');
+            if (typeof item.phase !== 'string' || !isSddPhase(item.phase))
+                return failure('Artifact phase is invalid');
+            if (item.topicKey !== sddTopicKey(input.change, item.phase))
+                return failure(`Artifact topicKey must be ${sddTopicKey(input.change, item.phase)}`);
+            if (typeof item.content !== 'string' || item.content.trim().length === 0)
+                return failure('Artifact content must not be empty');
+            artifacts.push({ phase: item.phase, topicKey: item.topicKey, content: item.content, ...(typeof item.updatedAt === 'string' ? { updatedAt: item.updatedAt } : {}) });
+        }
+        return { ok: true, value: { kind: artifactPackageKind, version: 1, project: input.project, change: input.change, exportedAt: input.exportedAt, artifacts } };
+    }
+    planImport(input) {
+        const validated = this.validateImport(input);
+        if (!validated.ok)
+            return validated;
+        const plan = { toCreate: [], toOverwrite: [], skipped: [], errors: [] };
+        for (const artifact of validated.value.artifacts) {
+            const existing = this.memory.getArtifact(input.project, artifact.topicKey, this.context);
+            if (existing.ok && input.overwrite === true)
+                plan.toOverwrite.push(artifact.topicKey);
+            else if (existing.ok) {
+                plan.skipped.push(artifact.topicKey);
+                plan.errors.push(`Artifact already exists: ${artifact.topicKey}`);
+            }
+            else
+                plan.toCreate.push(artifact.topicKey);
+        }
+        return { ok: true, value: plan };
+    }
+    importPackage(input) {
+        const plan = this.planImport(input);
+        if (!plan.ok)
+            return plan;
+        if (plan.value.errors.length > 0)
+            return failure(plan.value.errors.join('; '));
+        const validated = this.validateImport(input);
+        if (!validated.ok)
+            return validated;
+        for (const artifact of validated.value.artifacts) {
+            const saved = this.workflow.saveArtifact({ project: input.project, change: input.change, phase: artifact.phase, content: artifact.content });
+            if (!saved.ok)
+                return saved;
+        }
+        return plan;
+    }
+    validateImport(input) {
+        const identity = validateIdentity(input.project, input.change);
+        if (!identity.ok)
+            return identity;
+        const parsed = this.validatePackage(input.package);
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value.project !== input.project || parsed.value.change !== input.change)
+            return failure('Package identity does not match import target');
+        return parsed;
+    }
+}
+function isCanonicalArtifact(artifact) {
+    const phase = artifact.topicKey.split('/').at(-1);
+    return phase !== undefined && isSddPhase(phase) && artifact.topicKey === sddTopicKey(artifact.topicKey.split('/')[1] ?? '', phase);
+}
+function toPortableArtifact(artifact) {
+    return { phase: artifact.phase, topicKey: artifact.topicKey, content: artifact.content, updatedAt: artifact.updatedAt };
+}
+function validateIdentity(project, change) {
+    if (project.trim().length === 0)
+        return failure('Project must not be empty');
+    if (!validChangePattern.test(change))
+        return failure(`Invalid SDD change id: ${change}`);
+    return { ok: true, value: { project, change } };
+}
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+function failure(message) { return { ok: false, error: { code: 'validation_failed', message } }; }

package/dist/sdd/schema.js

@@ -0,0 +1,17 @@
+export const sddPhases = ['explore', 'proposal', 'spec', 'design', 'tasks', 'apply-progress', 'verify', 'archive'];
+export const sddPrerequisites = {
+    explore: [],
+    proposal: ['explore'],
+    spec: ['proposal'],
+    design: ['proposal', 'spec'],
+    tasks: ['proposal', 'spec', 'design'],
+    'apply-progress': ['tasks'],
+    verify: ['apply-progress'],
+    archive: ['verify'],
+};
+export function isSddPhase(value) {
+    return sddPhases.includes(value);
+}
+export function sddTopicKey(change, phase) {
+    return `sdd/${change}/${phase}`;
+}

package/dist/sdd/sdd-workflow-service.js

@@ -0,0 +1,217 @@
+import { isSddPhase, sddPhases, sddPrerequisites, sddTopicKey } from './schema.js';
+const defaultContext = { actor: 'sdd-workflow-service' };
+const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export class SddWorkflowService {
+    memory;
+    context;
+    constructor(memory, context = defaultContext) {
+        this.memory = memory;
+        this.context = context;
+    }
+    getWorkflow(change) {
+        return sddPhases.map((phase) => ({
+            phase,
+            topicKey: sddTopicKey(change, phase),
+            prerequisites: [...sddPrerequisites[phase]],
+        }));
+    }
+    getReady(input) {
+        const validated = this.validatePhaseInput(input);
+        if (!validated.ok)
+            return validated;
+        const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
+        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases);
+        return {
+            ok: true,
+            value: {
+                change: validated.value.change,
+                phase: validated.value.phase,
+                ...readiness,
+            },
+        };
+    }
+    getStatus(input) {
+        const validated = validateProjectAndChange(input.project, input.change);
+        if (!validated.ok)
+            return validated;
+        const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
+        return statusFromPhases(validated.value.change, phases);
+    }
+    getDashboardStatus(input) {
+        const validated = validateProjectAndChange(input.project, input.change);
+        if (!validated.ok)
+            return validated;
+        const phases = this.getPhaseStatusesNoTrace(validated.value.project, validated.value.change);
+        if (!phases.ok)
+            return phases;
+        return statusFromPhases(validated.value.change, phases.value);
+    }
+    getPhaseStatusesNoTrace(project, change) {
+        const statuses = [];
+        for (const phase of sddPhases) {
+            const topicKey = sddTopicKey(change, phase);
+            const present = this.memory.hasArtifactNoTrace(project, topicKey);
+            if (!present.ok)
+                return present;
+            statuses.push({ phase, topicKey, present: present.value });
+        }
+        return { ok: true, value: statuses };
+    }
+    getNext(input) {
+        const validated = validateProjectAndChange(input.project, input.change);
+        if (!validated.ok)
+            return validated;
+        const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
+        const blockedPresentPhase = phases.find((status) => {
+            if (!status.present)
+                return false;
+            return getReadinessFromStatuses(validated.value.change, status.phase, phases).missingArtifactTopicKeys.length > 0;
+        });
+        if (blockedPresentPhase !== undefined) {
+            const readiness = getReadinessFromStatuses(validated.value.change, blockedPresentPhase.phase, phases);
+            return {
+                ok: true,
+                value: {
+                    change: validated.value.change,
+                    status: 'blocked',
+                    nextPhase: blockedPresentPhase.phase,
+                    missingArtifactTopicKeys: readiness.missingArtifactTopicKeys,
+                    reason: `${blockedPresentPhase.phase} is blocked by missing prerequisite artifacts.`,
+                    recommendedAction: `Create or restore ${readiness.missingArtifactTopicKeys.join(', ')} before continuing.`,
+                },
+            };
+        }
+        const nextMissingPhase = phases.find((status) => !status.present)?.phase;
+        if (nextMissingPhase === undefined) {
+            return {
+                ok: true,
+                value: {
+                    change: validated.value.change,
+                    status: 'complete',
+                    missingArtifactTopicKeys: [],
+                    reason: 'All canonical SDD phases are complete.',
+                    recommendedAction: 'No next SDD phase remains for this change.',
+                },
+            };
+        }
+        const readiness = getReadinessFromStatuses(validated.value.change, nextMissingPhase, phases);
+        if (!readiness.ready) {
+            return {
+                ok: true,
+                value: {
+                    change: validated.value.change,
+                    status: 'blocked',
+                    nextPhase: nextMissingPhase,
+                    missingArtifactTopicKeys: readiness.missingArtifactTopicKeys,
+                    reason: `${nextMissingPhase} is blocked by missing prerequisite artifacts.`,
+                    recommendedAction: `Create or restore ${readiness.missingArtifactTopicKeys.join(', ')} before running ${nextMissingPhase}.`,
+                },
+            };
+        }
+        return {
+            ok: true,
+            value: {
+                change: validated.value.change,
+                status: 'runnable',
+                nextPhase: nextMissingPhase,
+                missingArtifactTopicKeys: [],
+                reason: `${nextMissingPhase} is ready to run.`,
+                recommendedAction: `Run the ${nextMissingPhase} SDD phase for ${validated.value.change}.`,
+            },
+        };
+    }
+    saveArtifact(input) {
+        const validated = this.validatePhaseInput(input);
+        if (!validated.ok)
+            return validated;
+        if (input.content.trim().length === 0)
+            return validationFailure('SDD artifact content must not be empty');
+        return this.memory.saveArtifact({
+            project: validated.value.project,
+            topicKey: sddTopicKey(validated.value.change, validated.value.phase),
+            phase: validated.value.phase,
+            content: input.content,
+        }, this.context);
+    }
+    getArtifact(input) {
+        const validated = this.validatePhaseInput(input);
+        if (!validated.ok)
+            return validated;
+        return this.memory.getArtifact(validated.value.project, sddTopicKey(validated.value.change, validated.value.phase), this.context);
+    }
+    listArtifacts(input) {
+        const validated = validateProjectAndChange(input.project, input.change);
+        if (!validated.ok)
+            return validated;
+        const listed = this.memory.listArtifactsByTopicPrefix(validated.value.project, `sdd/${validated.value.change}/`, this.context);
+        if (!listed.ok)
+            return listed;
+        const artifactsByTopicKey = new Map(listed.value.map((artifact) => [artifact.topicKey, artifact]));
+        const artifacts = sddPhases
+            .map((phase) => artifactsByTopicKey.get(sddTopicKey(validated.value.change, phase)))
+            .filter((artifact) => artifact !== undefined);
+        return {
+            ok: true,
+            value: {
+                project: validated.value.project,
+                change: validated.value.change,
+                artifacts,
+            },
+        };
+    }
+    validatePhaseInput(input) {
+        const validated = validateProjectAndChange(input.project, input.change);
+        if (!validated.ok)
+            return validated;
+        if (!isSddPhase(input.phase))
+            return validationFailure(`Unknown SDD phase: ${input.phase}`);
+        return { ok: true, value: { ...validated.value, phase: input.phase } };
+    }
+    getPhaseStatuses(project, change) {
+        return sddPhases.map((phase) => {
+            const topicKey = sddTopicKey(change, phase);
+            return {
+                phase,
+                topicKey,
+                present: this.memory.getArtifact(project, topicKey, this.context).ok,
+            };
+        });
+    }
+}
+function statusFromPhases(change, phases) {
+    const nextReadyPhase = sddPhases.find((phase) => {
+        if (phases.find((status) => status.phase === phase)?.present)
+            return false;
+        return getReadinessFromStatuses(change, phase, phases).ready;
+    });
+    const status = { change, phases };
+    if (nextReadyPhase !== undefined)
+        status.nextReadyPhase = nextReadyPhase;
+    return { ok: true, value: status };
+}
+function getReadinessFromStatuses(change, phase, phases) {
+    const satisfiedPrerequisites = [];
+    const missingArtifactTopicKeys = [];
+    for (const prerequisite of sddPrerequisites[phase]) {
+        const status = phases.find((candidate) => candidate.phase === prerequisite);
+        if (status?.present)
+            satisfiedPrerequisites.push(prerequisite);
+        else
+            missingArtifactTopicKeys.push(sddTopicKey(change, prerequisite));
+    }
+    return {
+        ready: missingArtifactTopicKeys.length === 0,
+        satisfiedPrerequisites,
+        missingArtifactTopicKeys,
+    };
+}
+function validateProjectAndChange(project, change) {
+    if (project.trim().length === 0)
+        return validationFailure('Project must not be empty');
+    if (!validChangePattern.test(change))
+        return validationFailure(`Invalid SDD change id: ${change}`);
+    return { ok: true, value: { project, change } };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}