@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/dist/core/sdd/quality-validation.js

@@ -0,0 +1,239 @@
+import { z } from 'zod';
+import { pluginArtifactManifestSchema, } from './plugin-broker.js';
+import { pluginComplianceIndexSchema, pluginValidationManifestSchema, } from './plugin-evidence.js';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const SCENARIO_ID_PATTERN = /^QVAL-\d{4}$/;
+const ARCHITECTURE_SCHEMA_ID_PATTERN = /^ARCH-GATE-[a-z0-9][a-z0-9-]*$/;
+const RUN_ID_PATTERN = /^qrun-[0-9]{8}t[0-9]{6}z-[a-z0-9-]+$/;
+const ISSUE_CODE_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+const WINDOWS_ABSOLUTE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const safeRelativePathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => isSafeRelativePath(value), {
+    message: 'Path must be relative to the project root and must not contain traversal segments.',
+});
+export const qualityAuthorityRefSchema = z.object({
+    type: z.enum(['adr', 'skill', 'foundation', 'debate', 'epic', 'feature', 'schema']),
+    ref: z.string().min(1),
+    path: safeRelativePathSchema.optional(),
+    version: z.string().min(1).optional(),
+    update_policy: z.string().min(1),
+});
+export const qualityGateRefSchema = z.object({
+    id: z.string().min(1),
+    type: z.enum(['schema', 'filesystem', 'import', 'runtime', 'evidence', 'certification', 'drift']),
+    severity: z.enum(['warn', 'fail']).default('warn'),
+    issue_codes: z.array(z.string().regex(ISSUE_CODE_PATTERN)).default([]),
+    remediation: z.string().min(1),
+});
+export const qualityScenarioExpectedArtifactSchema = z.object({
+    path_pattern: z.string().min(1),
+    required: z.boolean().default(true),
+    artifact_class: z.string().min(1),
+    checksum_required: z.boolean().default(false),
+});
+export const qualityScenarioSchema = z.object({
+    schema_version: z.literal(1),
+    id: z.string().regex(SCENARIO_ID_PATTERN),
+    title: z.string().min(10),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN).optional(),
+    mode: z.enum(['dry_run', 'apply_sandbox', 'runtime', 'traceability']),
+    intent: z.string().min(30),
+    authority: z.array(qualityAuthorityRefSchema).min(1),
+    input: z.object({
+        prompt: z.string().min(1).optional(),
+        fixture_path: safeRelativePathSchema.optional(),
+        payload: jsonObjectSchema.default({}),
+    }),
+    expected_artifacts: z.array(qualityScenarioExpectedArtifactSchema).default([]),
+    gates: z.array(qualityGateRefSchema).min(1),
+    negative_variants: z
+        .array(z.object({
+        id: z.string().min(1),
+        description: z.string().min(10),
+        expected_issue_codes: z.array(z.string().regex(ISSUE_CODE_PATTERN)).min(1),
+    }))
+        .default([]),
+    allowed_nondeterminism: z.array(z.string().min(1)).default([]),
+    required_evidence: z.array(z.string().min(1)).min(1),
+});
+export const architectureLayerRuleSchema = z.object({
+    path_patterns: z.array(z.string().min(1)).min(1),
+    allowed_file_patterns: z.array(z.string().min(1)).default([]),
+    forbidden_file_patterns: z.array(z.string().min(1)).default([]),
+    allowed_imports: z.array(z.string().min(1)).default([]),
+    forbidden_imports: z.array(z.string().min(1)).default([]),
+    required_evidence: z.array(z.string().min(1)).default([]),
+});
+export const qualityArchitectureSchema = z.object({
+    schema_version: z.literal(1),
+    id: z.string().regex(ARCHITECTURE_SCHEMA_ID_PATTERN),
+    title: z.string().min(10),
+    stack: z.string().min(1),
+    authority: z.array(qualityAuthorityRefSchema).min(1),
+    applies_to: z.object({
+        plugin: z.string().min(1).optional(),
+        capability: z.string().min(1).optional(),
+        project_kind: z.string().min(1).optional(),
+    }),
+    layers: z.record(z.string().min(1), architectureLayerRuleSchema).refine((layers) => Object.keys(layers).length > 0, { message: 'At least one architecture layer rule is required.' }),
+    exceptions: z.object({
+        require_adr: z.boolean().default(true),
+        require_expiration: z.boolean().default(true),
+        allowed_refs: z.array(z.string().min(1)).default([]),
+    }),
+    update_policy: z.object({
+        owner: z.string().min(1),
+        review_trigger: z.string().min(1),
+        stale_after_days: z.number().int().positive().optional(),
+    }),
+});
+export const qualityRunFindingSchema = z.object({
+    code: z.string().regex(ISSUE_CODE_PATTERN),
+    severity: z.enum(['info', 'warn', 'error', 'blocker']),
+    message: z.string().min(1),
+    remediation: z.string().min(1),
+    path: safeRelativePathSchema.optional(),
+    gate_id: z.string().min(1).optional(),
+});
+export const qualityRunSchema = z.object({
+    schema_version: z.literal(1),
+    run_id: z.string().regex(RUN_ID_PATTERN),
+    scenario_ref: z.string().regex(SCENARIO_ID_PATTERN),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    started_at: z.string().datetime(),
+    finished_at: z.string().datetime().optional(),
+    mode: z.enum(['dry_run', 'apply_sandbox', 'runtime', 'traceability']),
+    status: z.enum(['passed', 'warning', 'failed', 'blocked']),
+    plugin_ref: z
+        .object({
+        id: z.string().min(1),
+        version: z.string().min(1),
+        capability: z.string().min(1),
+    })
+        .optional(),
+    command: z.object({
+        argv: z.array(z.string().min(1)).min(1),
+        cwd: safeRelativePathSchema.default('.'),
+        env_keys: z.array(z.string().min(1)).default([]),
+    }),
+    schema_versions: z.record(z.string(), z.string()).default({}),
+    artifacts: z.array(safeRelativePathSchema).default([]),
+    findings: z.array(qualityRunFindingSchema).default([]),
+    evidence_bundle_path: safeRelativePathSchema.optional(),
+    metadata: jsonObjectSchema.default({}),
+});
+export const qualityFilesystemSnapshotSchema = z.object({
+    root: safeRelativePathSchema.default('.'),
+    files: z.array(z.object({
+        path: safeRelativePathSchema,
+        size_bytes: z.number().int().nonnegative(),
+        sha256: z.string().min(1).optional(),
+    })).default([]),
+});
+export const qualityImportGraphSchema = z.object({
+    nodes: z.array(safeRelativePathSchema).default([]),
+    edges: z.array(z.object({
+        from: safeRelativePathSchema,
+        to: z.string().min(1),
+        kind: z.enum(['relative', 'package', 'alias']).default('relative'),
+    })).default([]),
+});
+export const qualityEvidenceBundleSchema = z
+    .object({
+    schema_version: z.literal(1),
+    run: qualityRunSchema,
+    scenario: qualityScenarioSchema,
+    architecture_schema: qualityArchitectureSchema.optional(),
+    artifact_manifest: pluginArtifactManifestSchema.optional(),
+    validation_manifest: pluginValidationManifestSchema.optional(),
+    compliance_index: pluginComplianceIndexSchema.optional(),
+    filesystem_snapshot: qualityFilesystemSnapshotSchema,
+    import_graph: qualityImportGraphSchema,
+    command_log_ref: safeRelativePathSchema.optional(),
+    exceptions: z.array(z.object({
+        ref: z.string().min(1),
+        reason: z.string().min(1),
+        expires_at: z.string().datetime().optional(),
+        compensating_control: z.string().min(1),
+    })).default([]),
+    checksums: z.array(z.object({
+        path: safeRelativePathSchema,
+        sha256: z.string().min(1),
+    })).default([]),
+})
+    .superRefine((bundle, context) => {
+    if (bundle.run.scenario_ref !== bundle.scenario.id) {
+        context.addIssue({
+            code: 'custom',
+            path: ['run', 'scenario_ref'],
+            message: `Run scenario_ref ${bundle.run.scenario_ref} must match scenario id ${bundle.scenario.id}.`,
+        });
+    }
+    if (bundle.scenario.feature_ref && bundle.run.feature_ref !== bundle.scenario.feature_ref) {
+        context.addIssue({
+            code: 'custom',
+            path: ['run', 'feature_ref'],
+            message: `Run feature_ref ${bundle.run.feature_ref} must match scenario feature_ref ${bundle.scenario.feature_ref}.`,
+        });
+    }
+    if (bundle.run.evidence_bundle_path) {
+        const expectedPrefix = `.sdd/reports/quality-runs/${bundle.run.run_id}/`;
+        if (!bundle.run.evidence_bundle_path.startsWith(expectedPrefix)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['run', 'evidence_bundle_path'],
+                message: `Evidence bundle path must live under ${expectedPrefix}.`,
+            });
+        }
+    }
+    for (const requiredEvidence of bundle.scenario.required_evidence) {
+        if (!bundleHasRequiredEvidence(bundle, requiredEvidence)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['scenario', 'required_evidence'],
+                message: `Required evidence "${requiredEvidence}" is missing from the evidence bundle.`,
+            });
+        }
+    }
+});
+export function parseQualityScenario(value) {
+    return qualityScenarioSchema.parse(value);
+}
+export function parseQualityArchitectureSchema(value) {
+    return qualityArchitectureSchema.parse(value);
+}
+export function parseQualityRun(value) {
+    return qualityRunSchema.parse(value);
+}
+export function parseQualityEvidenceBundle(value) {
+    return qualityEvidenceBundleSchema.parse(value);
+}
+function isSafeRelativePath(value) {
+    if (value.startsWith('/') || WINDOWS_ABSOLUTE_PATH_PATTERN.test(value)) {
+        return false;
+    }
+    return !value.split(/[\\/]+/u).some((segment) => segment === '..');
+}
+function bundleHasRequiredEvidence(bundle, evidence) {
+    if (evidence === 'artifact_manifest')
+        return Boolean(bundle.artifact_manifest);
+    if (evidence === 'validation_manifest')
+        return Boolean(bundle.validation_manifest);
+    if (evidence === 'compliance_index')
+        return Boolean(bundle.compliance_index);
+    if (evidence === 'architecture_schema')
+        return Boolean(bundle.architecture_schema);
+    if (evidence === 'filesystem_snapshot')
+        return bundle.filesystem_snapshot.files.length > 0;
+    if (evidence === 'import_graph')
+        return bundle.import_graph.nodes.length > 0 || bundle.import_graph.edges.length > 0;
+    if (evidence === 'command_log')
+        return Boolean(bundle.command_log_ref);
+    if (evidence === 'checksums')
+        return bundle.checksums.length > 0;
+    return bundle.run.artifacts.some((artifact) => artifact.includes(evidence));
+}
+//# sourceMappingURL=quality-validation.js.map

package/dist/core/sdd/resolve-project-root.d.ts

@@ -1,7 +1,7 @@
 /**
  * Resolves the project root by walking up from `startDir` until we find a
- * directory that looks like a project root (contains `openspec/`, `package.json`,
- * or `.git`).
+ * directory that looks like a project root (contains `.sdd/`, `legacy-spec/`,
+ * `package.json`, or `.git`).
  *
  * This handles the common case where the CLI is invoked from inside `.sdd/` or
  * another subdirectory, preventing the double-nesting bug (e.g. `.sdd/.sdd`).

package/dist/core/sdd/resolve-project-root.js

@@ -2,8 +2,8 @@ import path from 'node:path';
 import { existsSync } from 'node:fs';
 /**
  * Resolves the project root by walking up from `startDir` until we find a
- * directory that looks like a project root (contains `openspec/`, `package.json`,
- * or `.git`).
+ * directory that looks like a project root (contains `.sdd/`, `legacy-spec/`,
+ * `package.json`, or `.git`).
  *
  * This handles the common case where the CLI is invoked from inside `.sdd/` or
  * another subdirectory, preventing the double-nesting bug (e.g. `.sdd/.sdd`).
@@ -24,7 +24,7 @@ export function resolveProjectRoot(startDir = process.cwd()) {
         if (parent === current) {
             // Reached filesystem root without finding a project root.
             // Fall back to original startDir so the existing error messages
-            // (e.g. "Run opensdd sdd init") still make sense.
+            // (e.g. "Run codesdd sdd init") still make sense.
             break;
         }
         current = parent;
@@ -32,8 +32,14 @@ export function resolveProjectRoot(startDir = process.cwd()) {
     return absoluteStart;
 }
 function isProjectRoot(dir) {
-    // openspec/ is the canonical config directory for this tool
-    if (existsSync(path.join(dir, 'openspec')))
+    // .sdd/ is the canonical CodeSDD governance directory.
+    if (existsSync(path.join(dir, '.sdd')))
+        return true;
+    // legacy-spec/ is a legacy compatibility root.
+    if (existsSync(path.join(dir, 'legacy-spec')))
+        return true;
+    // codesdd/ may exist in projects created during the transition window.
+    if (existsSync(path.join(dir, 'codesdd')))
         return true;
     // package.json is a strong signal for Node.js project roots
     if (existsSync(path.join(dir, 'package.json')))

package/dist/core/sdd/sanitize.d.ts

@@ -1,4 +1,6 @@
-import { type StructuralDiagnosticReport, type StructuralSanitizerReport, type StructuralSanitizerTransactionManifest } from './structural-health.js';
+import { type StructuralDiagnosticReport, type StructuralSanitizerReport, type StructuralSanitizerTransactionManifest, type StructuralSanitizerTransactionOperation } from './structural-health.js';
+export type Finding = StructuralDiagnosticReport['findings'][number];
+export type SanitizerAction = StructuralSanitizerReport['actions'][number];
 export interface SddSanitizeCommandOptions {
     dryRun?: boolean;
     apply?: boolean;
@@ -27,6 +29,33 @@ export declare class SddSanitizeOptionsError extends Error {
 export declare class SddSanitizeApplyError extends Error {
     constructor(message: string);
 }
+export declare function actionToken(input: string): string;
+export declare function createSourceReportId(report: StructuralDiagnosticReport): string;
+export declare function isInsidePath(rootPath: string, candidatePath: string): boolean;
+export declare function toAuditTimestampToken(value?: Date): string;
+export declare function createTransactionId(sourceReportId: string, value?: Date): string;
+export declare function pathExists(targetPath: string): Promise<boolean>;
+export declare function hashPath(targetPath: string): Promise<string | undefined>;
+export declare function resolveInSddRoot(projectRoot: string, memoryRoot: string, candidatePath: string, label: string): Promise<string>;
+export declare function transactionDirs(projectRoot: string, transactionId: string): {
+    sanitizeRoot: string;
+    backupRoot: string;
+    manifestPath: string;
+    auditLogPath: string;
+};
+export declare function backupPath(targetPath: string, backupRoot: string): Promise<string | undefined>;
+export declare function removePathSafely(targetPath: string): Promise<void>;
+export declare function toLifecycleTargetPath(finding: Finding): string | undefined;
+export declare function toQuarantinePath(location?: string): string | undefined;
+export declare function toWorkspaceBackupPath(location?: string): string | undefined;
+export declare function inferOperation(finding: Finding): SanitizerAction['operation'];
+export declare function makeActionFromFinding(finding: Finding, index: number): SanitizerAction;
+export declare function buildSanitizerDryRunReport(report: StructuralDiagnosticReport): StructuralSanitizerReport;
+export declare function manifestSummary(operations: StructuralSanitizerTransactionOperation[]): StructuralSanitizerTransactionManifest['summary'];
+export declare function writeAuditLog(auditLogPath: string, lines: Array<Record<string, unknown>>): Promise<void>;
+export declare function rollbackOperation(projectRoot: string, memoryRoot: string, rollback: StructuralSanitizerTransactionOperation['rollback']): Promise<void>;
+export declare function applySanitizerPlan(projectRoot: string, source: 'diagnose' | 'report', diagnosticReport: StructuralDiagnosticReport, dryRunReport: StructuralSanitizerReport): Promise<SddSanitizeResult>;
+export declare function loadDiagnosticReportFromFile(projectRoot: string, reportPath: string): Promise<StructuralDiagnosticReport>;
 export declare function formatSanitizerText(report: StructuralSanitizerReport): string;
 export declare class SddSanitizeCommand {
     execute(projectRoot: string, options?: SddSanitizeCommandOptions): Promise<SddSanitizeResult>;

package/dist/core/sdd/sanitize.js

@@ -19,11 +19,11 @@ export class SddSanitizeApplyError extends Error {
         this.name = 'SddSanitizeApplyError';
     }
 }
-function actionToken(input) {
+export function actionToken(input) {
     const normalized = input.toUpperCase().replace(/[^A-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
     return normalized.length > 0 ? normalized : 'GENERIC';
 }
-function createSourceReportId(report) {
+export function createSourceReportId(report) {
     const digest = createHash('sha1')
         .update(JSON.stringify({
         root_path: report.root_path,
@@ -43,19 +43,19 @@ function createSourceReportId(report) {
         .toUpperCase();
     return `SH-REPORT-${digest}`;
 }
-function isInsidePath(rootPath, candidatePath) {
+export function isInsidePath(rootPath, candidatePath) {
     const relative = path.relative(rootPath, candidatePath);
     return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
 }
-function toAuditTimestampToken(value = new Date()) {
+export function toAuditTimestampToken(value = new Date()) {
     return value.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
 }
-function createTransactionId(sourceReportId, value = new Date()) {
+export function createTransactionId(sourceReportId, value = new Date()) {
     const timestamp = toAuditTimestampToken(value);
     const suffix = createHash('sha1').update(`${sourceReportId}:${value.toISOString()}`).digest('hex').slice(0, 8).toUpperCase();
     return `SAN-${timestamp}-${suffix}`;
 }
-async function pathExists(targetPath) {
+export async function pathExists(targetPath) {
     try {
         await lstat(targetPath);
         return true;
@@ -64,7 +64,7 @@ async function pathExists(targetPath) {
         return false;
     }
 }
-async function hashPath(targetPath) {
+export async function hashPath(targetPath) {
     let stat;
     try {
         stat = await lstat(targetPath);
@@ -88,7 +88,7 @@ async function hashPath(targetPath) {
     }
     return `other:${stat.mode}`;
 }
-async function resolveInSddRoot(projectRoot, memoryRoot, candidatePath, label) {
+export async function resolveInSddRoot(projectRoot, memoryRoot, candidatePath, label) {
     try {
         return await RootResolver.verifyRealpathContainment(projectRoot, memoryRoot, candidatePath, label);
     }
@@ -99,7 +99,7 @@ async function resolveInSddRoot(projectRoot, memoryRoot, candidatePath, label) {
         throw error;
     }
 }
-function transactionDirs(projectRoot, transactionId) {
+export function transactionDirs(projectRoot, transactionId) {
     const sanitizeRoot = path.resolve(projectRoot, '.sdd', 'reports', 'sanitize');
     const backupRoot = path.join(sanitizeRoot, transactionId, 'backups');
     return {
@@ -109,7 +109,7 @@ function transactionDirs(projectRoot, transactionId) {
         auditLogPath: path.join(sanitizeRoot, `${transactionId}-audit.jsonl`),
     };
 }
-async function backupPath(targetPath, backupRoot) {
+export async function backupPath(targetPath, backupRoot) {
     if (!(await pathExists(targetPath)))
         return undefined;
     const suffix = createHash('sha1').update(targetPath).digest('hex').slice(0, 10);
@@ -118,7 +118,7 @@ async function backupPath(targetPath, backupRoot) {
     await cp(targetPath, backupPathResolved, { recursive: true });
     return backupPathResolved;
 }
-async function removePathSafely(targetPath) {
+export async function removePathSafely(targetPath) {
     const stat = await lstat(targetPath).catch(() => null);
     if (!stat)
         return;
@@ -128,7 +128,7 @@ async function removePathSafely(targetPath) {
     }
     await unlink(targetPath);
 }
-function toLifecycleTargetPath(finding) {
+export function toLifecycleTargetPath(finding) {
     const evidence = finding.evidence;
     const expectedRoot = typeof evidence.expected_root === 'string' ? evidence.expected_root : undefined;
     const itemId = typeof evidence.id === 'string' ? evidence.id : undefined;
@@ -143,19 +143,19 @@ function toLifecycleTargetPath(finding) {
     }
     return undefined;
 }
-function toQuarantinePath(location) {
+export function toQuarantinePath(location) {
     if (!location)
         return undefined;
     const baseName = path.posix.basename(location);
     return path.posix.join('.sdd', 'quarantine', baseName);
 }
-function toWorkspaceBackupPath(location) {
+export function toWorkspaceBackupPath(location) {
     if (!location)
         return undefined;
     const normalized = location.replace(/\\/g, '/').replace(/^\.sdd\//, '');
     return path.posix.join('.sdd', 'backup', normalized);
 }
-function inferOperation(finding) {
+export function inferOperation(finding) {
     switch (finding.rule_id) {
         case 'SH-RULE-MISSING-DIRECTORY':
             return 'mkdir';
@@ -179,7 +179,7 @@ function inferOperation(finding) {
             return 'manual_review';
     }
 }
-function makeActionFromFinding(finding, index) {
+export function makeActionFromFinding(finding, index) {
     const operation = inferOperation(finding);
     const actionId = `SH-ACTION-${actionToken(finding.finding_id)}-${actionToken(operation)}-${index + 1}`;
     const candidate = {
@@ -216,7 +216,7 @@ function makeActionFromFinding(finding, index) {
         const id = typeof evidence.id === 'string' ? evidence.id : undefined;
         const hasLegacyMarkdown = evidence.has_legacy_markdown === true;
         candidate.notes = hasLegacyMarkdown && id
-            ? `${candidate.notes} Suggested migration: opensdd sdd migrate-workspace --feat ${id}.`
+            ? `${candidate.notes} Suggested migration: codesdd sdd migrate-workspace --feat ${id}.`
             : `${candidate.notes} Suggested repair: manually edit the YAML to satisfy the workspace schema.`;
     }
     if (finding.rule_id === 'SH-RULE-LIFECYCLE-VIOLATION') {
@@ -233,7 +233,7 @@ function makeActionFromFinding(finding, index) {
     }
     return StructuralSanitizerActionSchema.parse(candidate);
 }
-function buildSanitizerDryRunReport(report) {
+export function buildSanitizerDryRunReport(report) {
     const actions = [];
     const blockedActions = [];
     report.findings.forEach((finding, index) => {
@@ -253,7 +253,7 @@ function buildSanitizerDryRunReport(report) {
         blocked_actions: blockedActions,
     });
 }
-function manifestSummary(operations) {
+export function manifestSummary(operations) {
     return {
         applied: operations.filter((item) => item.status === 'applied').length,
         skipped: operations.filter((item) => item.status === 'skipped').length,
@@ -261,7 +261,7 @@ function manifestSummary(operations) {
         rolled_back: operations.filter((item) => item.status === 'rolled_back').length,
     };
 }
-async function writeAuditLog(auditLogPath, lines) {
+export async function writeAuditLog(auditLogPath, lines) {
     await mkdir(path.dirname(auditLogPath), { recursive: true });
     if (lines.length === 0) {
         await writeFile(auditLogPath, '', 'utf-8');
@@ -270,7 +270,7 @@ async function writeAuditLog(auditLogPath, lines) {
     const payload = `${lines.map((line) => JSON.stringify(line)).join('\n')}\n`;
     await writeFile(auditLogPath, payload, 'utf-8');
 }
-async function rollbackOperation(projectRoot, memoryRoot, rollback) {
+export async function rollbackOperation(projectRoot, memoryRoot, rollback) {
     const operation = StructuralSanitizerRollbackOperationSchema.parse(rollback);
     if (operation.operation === 'noop')
         return;
@@ -302,7 +302,7 @@ async function rollbackOperation(projectRoot, memoryRoot, rollback) {
         await cp(backup, target, { recursive: true });
     }
 }
-async function applySanitizerPlan(projectRoot, source, diagnosticReport, dryRunReport) {
+export async function applySanitizerPlan(projectRoot, source, diagnosticReport, dryRunReport) {
     const config = await loadProjectSddConfig(projectRoot);
     const paths = resolveSddPaths(path.resolve(projectRoot), config);
     const transactionId = createTransactionId(dryRunReport.source_report_id);
@@ -581,7 +581,7 @@ async function applySanitizerPlan(projectRoot, source, diagnosticReport, dryRunR
         transaction: manifest,
     };
 }
-async function loadDiagnosticReportFromFile(projectRoot, reportPath) {
+export async function loadDiagnosticReportFromFile(projectRoot, reportPath) {
     const absolutePath = path.resolve(projectRoot, reportPath);
     let raw;
     try {

package/dist/core/sdd/services/agent-run.service.d.ts

@@ -0,0 +1,65 @@
+import { type DeepAgentsRuntimeAdapterEnvelope } from '../deepagents/runtime-factory.js';
+import { type DeepAgentRunEvidence, type DeepAgentRunPlan } from '../deepagents/evidence-mapper.js';
+import { type DeepAgentsOperationalPreflight } from '../deepagents/policy.js';
+import type { DeepAgentsRuntimeImporter } from '../deepagents/runtime-loader.js';
+import type { SddStores } from '../store/sdd-stores.js';
+declare const DEEPAGENTS_RUN_MODES: readonly ["read-only", "plan", "validate", "apply-sandbox", "apply-approved"];
+export type DeepAgentsRunMode = (typeof DEEPAGENTS_RUN_MODES)[number];
+export type DeepAgentsRunStatus = 'allowed' | 'blocked';
+export interface DeepAgentsRunRequest {
+    provider: string;
+    mode?: string;
+    plugin_execution_path?: string;
+    plugin_flow?: string[];
+    operations?: string[];
+    write_scope?: string[];
+    planned_writes?: string[];
+    requested_env?: string[];
+    network_domains?: string[];
+    approval_grants?: string[];
+}
+export interface DeepAgentsRunResult {
+    schema_version: 1;
+    feature_id: string;
+    provider: 'deepagents';
+    requested_provider: string;
+    mode_requested: string;
+    mode: DeepAgentsRunMode;
+    status: DeepAgentsRunStatus;
+    fail_closed: true;
+    reasons: string[];
+    evidence: {
+        run_id: string;
+        generated_at: string;
+        policy: 'deepagents-run-governance/v1';
+        direct_state_write_allowed: false;
+        plugin_execution: {
+            broker_only: true;
+            requested_path: string;
+            required_flow: string[];
+            completed_flow: string[];
+            missing_flow: string[];
+        };
+        runtime?: {
+            preflight: DeepAgentsOperationalPreflight;
+            adapter: DeepAgentsRuntimeAdapterEnvelope;
+            plan: DeepAgentRunPlan;
+            run: DeepAgentRunEvidence;
+            agent_result?: unknown;
+            fake_result?: unknown;
+            error?: string;
+        };
+    };
+}
+export declare class DeepAgentsRunService {
+    execute(featureId: string, request: DeepAgentsRunRequest, options?: {
+        projectRoot?: string;
+        env?: NodeJS.ProcessEnv;
+        stores?: SddStores;
+        importer?: DeepAgentsRuntimeImporter;
+    }): Promise<DeepAgentsRunResult>;
+    private executeRuntimePath;
+    private invokeReadyRuntime;
+}
+export {};
+//# sourceMappingURL=agent-run.service.d.ts.map