@voce-engine/cli 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1 @@
+Apache License 2.0

package/README.md

@@ -0,0 +1,9 @@
+# @voce-engine/cli
+
+The `voce` command is the offline-first, explicit-path CLI for VOCE v0.1. It does not load lifecycle scripts, discover global packages, inspect credentials, or call a Provider unless the command explicitly selects the built-in `mock` provider.
+
+> `0.1.0-rc.1` is a release candidate, not production-ready. CLI behavior may change before `0.1.0`.
+
+```bash
+npm install --global @voce-engine/cli@0.1.0-rc.1
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from './index.js';
+const exitCode = await runCli();
+process.exitCode = exitCode;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare const CLI_VERSION = "0.1.0-rc.1";
+export declare function runCli(argv?: string[]): Promise<number>;

package/dist/index.js

@@ -0,0 +1,730 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, realpath, rename, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import * as process from 'node:process';
+import { MOCK_IMAGE_PROFILE, MOCK_JPEG_PROFILE, MOCK_LIMITED_REFERENCE_PROFILE, compileEvaluationReport, computeExecutionRunHash, computeCompilationContextHash, computeOntologyInstanceHash, computeSemanticReviewRequestHash, createConstraintWaiver, createHumanAcceptanceDecision, compileConstraints, createScenarioPackRegistry, executeOffline, executeSemanticReview, FixtureReferenceInterpreter, FixtureSemanticReviewer, guardPromptCandidate, renderStaticTraceReport, sha256, traceModelFromExecution, validateStructuralImage, canonicalize, } from '@voce-engine/core';
+import { FIXTURE_M6_OPAQUE_PNG, fixtureChangeIntent, fixtureM4ConstraintInput, fixtureM5Candidate, fixtureM5ExecutionInput, fixtureM5GuardInput, fixtureM5PromptIR, fixtureM6Artifact, fixtureM6Authorization, fixtureScopePlan, } from '@voce-engine/testkit';
+import { BUNDLE_MANIFEST_SCHEMA_VERSION } from '@voce-engine/contracts';
+export const CLI_VERSION = '0.1.0-rc.1';
+const TOOL_ID = '@voce-engine/cli';
+const CONTRACTS_VERSION = '0.1.0-rc.1';
+const CORE_VERSION = '0.1.0-rc.1';
+const SOURCE_SCHEMA = 'voce.scenario-pack-source/v1alpha1';
+const PACK_SCHEMA = 'voce.scenario-pack/v1alpha1';
+const HASH = /^sha256:[0-9a-f]{64}$/;
+const EXIT = { ok: 0, usage: 2, input: 3, contract: 4, offline: 5, output: 6, internal: 7 };
+class CliError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = EXIT.input) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+function compare(a, b) { return a < b ? -1 : a > b ? 1 : 0; }
+function json(value) { return canonicalize(value); }
+function bytesHash(bytes) { return `sha256:${createHash('sha256').update(bytes).digest('hex')}`; }
+function textBytes(value) { return new TextEncoder().encode(json(value)); }
+function clone(value) { return JSON.parse(JSON.stringify(value)); }
+function isObject(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+function record(value, code) {
+    if (!isObject(value))
+        throw new CliError(code, 'Expected a JSON object.');
+    return value;
+}
+function assertKnown(object, fields, code) { const allowed = new Set(fields); for (const key of Object.keys(object))
+    if (!allowed.has(key))
+        throw new CliError(code, `Unknown field ${key}.`, EXIT.contract); }
+function stringField(object, field, code = 'INPUT_FIELD_INVALID') {
+    if (typeof object[field] !== 'string' || object[field].length === 0)
+        throw new CliError(code, `Field ${field} is required.`);
+    return object[field];
+}
+function safeRelative(value) {
+    return value.length > 0 && !value.includes('\\') && !value.startsWith('/') && !/^[A-Za-z]:/.test(value) && !value.split('/').some((part) => part === '' || part === '.' || part === '..');
+}
+function safeDisplayPath(value) { return path.basename(value).replaceAll('\\', '/'); }
+function assertHash(value, code = 'HASH_INVALID') { if (typeof value !== 'string' || !HASH.test(value))
+    throw new CliError(code, 'A content hash is invalid.', EXIT.contract); }
+function assertNoUnsafe(value, location = 'document') {
+    if (typeof value === 'string') {
+        if (/^(?:https?:|data:|file:|\\\\|[A-Za-z]:[\\/])/.test(value))
+            throw new CliError('PUBLIC_PATH_OR_URL_FORBIDDEN', `Unsafe path or URL in ${location}.`, EXIT.contract);
+        if (value.length > 128 && /^[A-Za-z0-9+/=_-]+$/.test(value))
+            throw new CliError('PUBLIC_BASE64_FORBIDDEN', `Encoded payload in ${location}.`, EXIT.contract);
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertNoUnsafe(item, `${location}[${index}]`));
+        return;
+    }
+    if (isObject(value)) {
+        for (const [key, item] of Object.entries(value)) {
+            if (/(?:password|secret|token|api[_-]?key|credential|signed[_-]?url|base64)/i.test(key) && key !== 'leftTokens' && key !== 'rightTokens')
+                throw new CliError('PUBLIC_SECRET_FIELD_FORBIDDEN', `Sensitive field ${key} is not allowed.`, EXIT.contract);
+            assertNoUnsafe(item, `${location}.${key}`);
+        }
+    }
+}
+function omit(value, field) { const copy = clone(value); delete copy[field]; return copy; }
+function contributionBody(category, raw, packId) {
+    const body = { ...raw };
+    delete body.contentDigest;
+    body.id = typeof body.id === 'string' ? body.id : `${packId}.${category}.default`;
+    body.schemaVersion = typeof body.schemaVersion === 'string' ? body.schemaVersion : `voce.${category}/v1alpha1`;
+    if (category === 'rulePacks') {
+        body.namespace = typeof body.namespace === 'string' ? body.namespace : `${packId}.rules`;
+        body.rules = Array.isArray(body.rules) ? body.rules : [];
+    }
+    const digest = sha256(body);
+    return { ...body, contentDigest: digest };
+}
+function fixtureSuite(raw) {
+    const base = { id: raw.id, schemaVersion: 'voce.fixture-suite/v1alpha1', cases: raw.cases };
+    return { ...base, cases: raw.cases, contentDigest: sha256(base) };
+}
+function distributionFiles(bodies) {
+    return bodies.map((item) => ({ path: item.path, bytes: textBytes(item.content) }));
+}
+function makeManifest(doc, contributions, files, suiteList) {
+    const indexes = Object.keys(contributions).reduce((result, category) => {
+        if (category === 'fixtureSuites')
+            return result;
+        const values = contributions[category];
+        result[category] = values.map((body) => ({ id: String(body.id), schemaVersion: String(body.schemaVersion), contentDigest: String(body.contentDigest) }));
+        return result;
+    }, {});
+    return {
+        schemaVersion: PACK_SCHEMA, packId: doc.packId, version: doc.version, kind: doc.kind ?? 'root',
+        supportedInteractionModes: ['text_only', 'reference_guided', 'edit_existing'],
+        inputExpectations: [{ id: 'intent', inputKind: 'text_intent', dataType: 'text', requiredIn: ['text_only', 'reference_guided', 'edit_existing'], cardinality: { min: 1, max: 1 }, sensitivity: 'none' }],
+        outputExpectations: [{ id: 'image', artifactKind: 'image', dataType: 'image', producedIn: ['text_only', 'reference_guided', 'edit_existing'], cardinality: { min: 1, max: 1 }, mediaTypes: ['image/png', 'image/jpeg'] }],
+        license: 'Apache-2.0', provenance: { publisher: 'VOCE fixture authors', sourceRepository: 'https://github.com/windforce19820520-ai/visual-ontology-constraint-engine' },
+        coreRange: '>=0.1.0', contractRanges: { 'voce.scenario-pack': '>=0.1.0' }, ui: { defaultLocale: 'en', locales: { en: { displayName: doc.packId, description: 'Redistributable offline VOCE fixture pack.', messages: {} } }, disclosures: [], accessibility: { textAlternativesRequired: true, keyboardOperableReferenceUI: true, doesNotRelyOnColorAlone: true } },
+        dependencies: [], conflicts: [], composition: { before: [], after: [] }, contributions: indexes, fixtures: suiteList.map((suite) => ({ id: suite.id, schemaVersion: suite.schemaVersion, contentDigest: suite.contentDigest })), migrations: [], capabilityRequirements: [],
+        declarations: { containsExecutableScenarioCode: false, distributionLifecycleScripts: false, containsExecutableFiles: false, fixturesRequireNetwork: false, fixturesRequireRealProvider: false, collectsTelemetry: false, ...doc.declarations },
+        permissions: { network: false, remoteCalls: false, secrets: false, filesystemWrite: false, mutateConfirmedFacts: false, authorizeCalls: false, overrideHostPolicy: false, selectProvider: false, changeBudgets: false },
+        distributionInventory: files.map((file) => ({ path: file.path, role: file.path.includes('/fixtures/') ? 'fixture' : 'contribution', contentDigest: bytesHash(file.bytes) })),
+    };
+}
+function sourceDocument(raw) {
+    const value = record(raw, 'PACK_SOURCE_INVALID');
+    if (value.schemaVersion !== SOURCE_SCHEMA)
+        throw new CliError('PACK_SCHEMA_UNSUPPORTED', 'ScenarioPack source schema is unsupported.', EXIT.contract);
+    const packId = stringField(value, 'packId', 'PACK_SOURCE_INVALID');
+    const version = stringField(value, 'version', 'PACK_SOURCE_INVALID');
+    if (value.kind !== undefined && value.kind !== 'root' && value.kind !== 'extension')
+        throw new CliError('PACK_SOURCE_INVALID', 'Pack kind is invalid.');
+    const declarations = value.declarations === undefined ? { mayHandlePersonImages: false, rightsDisclosureRequired: false } : record(value.declarations, 'PACK_DECLARATIONS_INVALID');
+    assertKnown(declarations, ['mayHandlePersonImages', 'rightsDisclosureRequired'], 'PACK_DECLARATIONS_UNKNOWN_FIELD');
+    if (typeof declarations.mayHandlePersonImages !== 'boolean' || typeof declarations.rightsDisclosureRequired !== 'boolean')
+        throw new CliError('PACK_DECLARATIONS_INVALID', 'ScenarioPack declarations must be booleans.', EXIT.contract);
+    if (value.contribution !== undefined && !isObject(value.contribution))
+        throw new CliError('PACK_SOURCE_INVALID', 'Contribution must be an object.');
+    if (value.contributions !== undefined && !isObject(value.contributions))
+        throw new CliError('PACK_SOURCE_INVALID', 'Contributions must be an object.');
+    if (value.fixtures !== undefined && (!Array.isArray(value.fixtures) || value.fixtures.some((item) => !isObject(item) || typeof item.id !== 'string' || !Array.isArray(item.cases))))
+        throw new CliError('PACK_SOURCE_INVALID', 'Fixture suites are invalid.');
+    const known = new Set(['schemaVersion', 'packId', 'version', 'kind', 'scenarioLabel', 'declarations', 'contribution', 'contributions', 'fixtures']);
+    for (const key of Object.keys(value))
+        if (!known.has(key))
+            throw new CliError('PACK_UNKNOWN_FIELD', `Unknown ScenarioPack source field ${key}.`, EXIT.contract);
+    return { ...value, declarations };
+}
+async function noSymlinkAncestors(filePath, code) {
+    const absolute = path.resolve(filePath);
+    const parsed = path.parse(absolute);
+    let current = parsed.root;
+    for (const part of path.relative(parsed.root, absolute).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        const info = await lstat(current).catch(() => undefined);
+        if (info?.isSymbolicLink())
+            throw new CliError(code, 'Input path contains a symbolic link.', EXIT.contract);
+        if (!info)
+            break;
+    }
+}
+async function regularFile(filePath, unsafeCode) {
+    const absolute = path.resolve(filePath);
+    await noSymlinkAncestors(absolute, unsafeCode);
+    const info = await lstat(absolute).catch(() => undefined);
+    if (!info)
+        throw new CliError('INPUT_READ_FAILED', 'Input file cannot be read.');
+    if (info.isSymbolicLink() || info.nlink > 1 || !info.isFile())
+        throw new CliError(unsafeCode, 'Input must be a regular, single-link file.', EXIT.contract);
+}
+async function existingBoundary(inputPath, unsafeCode) {
+    const absolute = path.resolve(inputPath);
+    await noSymlinkAncestors(absolute, unsafeCode);
+    const info = await lstat(absolute).catch(() => undefined);
+    if (!info)
+        throw new CliError('INPUT_READ_FAILED', 'Input path cannot be read.');
+    if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()) || info.isFile() && info.nlink > 1)
+        throw new CliError(unsafeCode, 'Input path is not a safe explicit file or directory.', EXIT.contract);
+    return realpath(absolute);
+}
+async function outputBoundary(outputPath) {
+    const absolute = path.resolve(outputPath);
+    await noSymlinkAncestors(absolute, 'OUTPUT_PATH_UNSAFE');
+    const info = await lstat(absolute).catch(() => undefined);
+    if (info?.isSymbolicLink() || info && !info.isDirectory() && !info.isFile())
+        throw new CliError('OUTPUT_PATH_UNSAFE', 'Output path is not a regular file or directory.', EXIT.output);
+    if (info)
+        return realpath(absolute);
+    const missing = [];
+    let cursor = absolute;
+    while (!(await lstat(cursor).catch(() => undefined))) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return absolute;
+        missing.unshift(path.basename(cursor));
+        cursor = parent;
+    }
+    return path.join(await realpath(cursor), ...missing);
+}
+function boundaryOverlaps(left, right) {
+    const normalize = (value) => process.platform === 'win32' ? value.toLowerCase() : value;
+    const a = normalize(path.resolve(left));
+    const b = normalize(path.resolve(right));
+    const same = (x, y) => x === y || x.startsWith(`${y}${path.sep}`);
+    return same(a, b) || same(b, a);
+}
+async function assertOutputSeparated(outputPath, inputPaths) {
+    const output = await outputBoundary(outputPath);
+    for (const inputPath of inputPaths) {
+        const input = await existingBoundary(inputPath, 'INPUT_PATH_UNSAFE');
+        if (boundaryOverlaps(output, input))
+            throw new CliError('OUTPUT_INPUT_OVERLAP', 'Output must be independent from every input path.', EXIT.output);
+    }
+}
+async function readJson(filePath, unsafeCode = 'INPUT_FILE_UNSAFE') {
+    await regularFile(filePath, unsafeCode);
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf8');
+    }
+    catch {
+        throw new CliError('INPUT_READ_FAILED', 'Input file cannot be read.');
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CliError('INPUT_JSON_INVALID', 'Input is not valid JSON.');
+    }
+}
+async function loadPack(sourcePath) {
+    const explicit = path.resolve(sourcePath);
+    let inputPath = explicit;
+    const info = await lstat(explicit).catch(() => undefined);
+    if (!info)
+        throw new CliError('PACK_SOURCE_NOT_FOUND', 'Explicit ScenarioPack source was not found.');
+    if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()) || info.isFile() && info.nlink > 1)
+        throw new CliError('PACK_SOURCE_UNSAFE', 'ScenarioPack source must be a regular file or directory.', EXIT.contract);
+    if (info.isDirectory()) {
+        const simple = path.join(explicit, 'pack.json');
+        const standard = path.join(explicit, 'scenario-pack', 'manifest.json');
+        if (await lstat(simple).catch(() => undefined))
+            inputPath = simple;
+        else if (await lstat(standard).catch(() => undefined))
+            return loadStandardDirectory(explicit, standard);
+        else
+            throw new CliError('PACK_SOURCE_INVALID', 'Explicit directory has no pack.json or scenario-pack/manifest.json.');
+    }
+    const doc = sourceDocument(await readJson(inputPath, 'PACK_SOURCE_UNSAFE'));
+    const categories = ['ontologyVocabulary', 'rulePacks', 'interpretationScopes', 'promptSections', 'reviewTemplates', 'defaults', 'overridePoints'];
+    const bodies = {};
+    const files = [];
+    for (const category of categories) {
+        const rawValues = doc.contributions?.[category] ?? (category === 'rulePacks' && doc.contribution ? [doc.contribution] : []);
+        const values = rawValues.map((raw) => contributionBody(category, raw, doc.packId));
+        bodies[category] = values;
+        values.forEach((body) => files.push({ path: `scenario-pack/contributions/${category}/${String(body.id)}.json`, content: body, role: 'contribution' }));
+    }
+    const suites = (doc.fixtures ?? [{ id: `${doc.packId}.offline`, cases: [] }]).map(fixtureSuite);
+    bodies.fixtureSuites = suites;
+    for (const suite of suites)
+        files.push({ path: `scenario-pack/fixtures/${suite.id}.json`, content: suite, role: 'fixture' });
+    const logicalFiles = distributionFiles(files);
+    const manifest = makeManifest(doc, bodies, logicalFiles, suites);
+    const definition = { manifest, contributions: bodies, migrations: [] };
+    const registry = createScenarioPackRegistry();
+    const source = { kind: 'memory', definition, logicalFiles };
+    let descriptor;
+    try {
+        descriptor = registry.register(source);
+    }
+    catch (error) {
+        throw new CliError(error instanceof Error ? error.message : 'PACK_REGISTER_FAILED', 'ScenarioPack validation failed.', EXIT.contract);
+    }
+    return { source, definition, descriptor, fixtures: suites.flatMap((suite) => suite.cases) };
+}
+async function loadStandardDirectory(root, manifestPath) {
+    await existingBoundary(root, 'PACK_SOURCE_UNSAFE');
+    await regularFile(manifestPath, 'PACK_MANIFEST_UNSAFE');
+    const manifest = await readJson(manifestPath, 'PACK_MANIFEST_UNSAFE');
+    if (!isObject(manifest) || manifest.schemaVersion !== PACK_SCHEMA || !Array.isArray(manifest.distributionInventory))
+        throw new CliError('PACK_MANIFEST_INVALID', 'ScenarioPack manifest is invalid.', EXIT.contract);
+    assertKnown(manifest, ['schemaVersion', 'packId', 'version', 'kind', 'supportedInteractionModes', 'inputExpectations', 'outputExpectations', 'extensionOf', 'license', 'provenance', 'coreRange', 'contractRanges', 'configurationSchema', 'ui', 'dependencies', 'conflicts', 'composition', 'contributions', 'fixtures', 'migrations', 'capabilityRequirements', 'declarations', 'permissions', 'distributionInventory'], 'PACK_UNKNOWN_FIELD');
+    if (manifest.distributionInventory.some((item) => !isObject(item) || typeof item.path !== 'string' || !safeRelative(item.path) || typeof item.contentDigest !== 'string' || !HASH.test(item.contentDigest)))
+        throw new CliError('PACK_MANIFEST_INVALID', 'ScenarioPack inventory is invalid.', EXIT.contract);
+    const inventoryPaths = new Set(manifest.distributionInventory.map((item) => item.path));
+    async function enumerate(directory, relative = '') {
+        const names = await readdir(path.join(directory, relative), { withFileTypes: true });
+        const result = [];
+        for (const entry of names) {
+            const child = relative ? `${relative}/${entry.name}` : entry.name;
+            const metadata = await lstat(path.join(directory, ...child.split('/')));
+            if (metadata.isSymbolicLink() || metadata.nlink > 1)
+                throw new CliError('PACK_ENTRY_UNSAFE', 'ScenarioPack contains a symlink or hardlink.', EXIT.contract);
+            if (metadata.isDirectory())
+                result.push(...await enumerate(directory, child));
+            else if (metadata.isFile())
+                result.push(child.replaceAll('\\', '/'));
+            else
+                throw new CliError('PACK_ENTRY_UNSAFE', 'ScenarioPack contains a device or non-file entry.', EXIT.contract);
+        }
+        return result;
+    }
+    const actualPaths = await enumerate(root);
+    const expectedPaths = new Set(['scenario-pack/manifest.json', ...inventoryPaths]);
+    if (actualPaths.some((item) => !expectedPaths.has(item)) || expectedPaths.size !== actualPaths.length)
+        throw new CliError('PACK_INVENTORY_INCOMPLETE', 'ScenarioPack files do not match the explicit inventory.', EXIT.contract);
+    const logicalFiles = [];
+    const contributions = { ontologyVocabulary: [], rulePacks: [], interpretationScopes: [], promptSections: [], reviewTemplates: [], defaults: [], overridePoints: [], fixtureSuites: [] };
+    for (const item of manifest.distributionInventory) {
+        if (!isObject(item) || typeof item.path !== 'string' || !safeRelative(item.path))
+            throw new CliError('PACK_PATH_UNSAFE', 'ScenarioPack inventory path is unsafe.', EXIT.contract);
+        const filePath = path.join(root, ...item.path.split('/'));
+        await regularFile(filePath, 'PACK_ENTRY_UNSAFE');
+        const bytes = await readFile(filePath).catch(() => { throw new CliError('PACK_FILE_MISSING', 'ScenarioPack inventory file is missing.', EXIT.contract); });
+        if (bytesHash(bytes) !== item.contentDigest)
+            throw new CliError('PACK_DIGEST_MISMATCH', 'ScenarioPack inventory digest does not match.', EXIT.contract);
+        logicalFiles.push({ path: item.path, bytes });
+        if (item.path.includes('/contributions/')) {
+            const parts = item.path.split('/');
+            const category = parts[2];
+            const body = await parseBytes(bytes);
+            if (category in contributions && category !== 'fixtureSuites')
+                contributions[category].push(body);
+        }
+        else if (item.path.includes('/fixtures/'))
+            contributions.fixtureSuites.push(await parseBytes(bytes));
+    }
+    const definition = { manifest, contributions, migrations: [] };
+    const source = { kind: 'memory', definition, logicalFiles };
+    const registry = createScenarioPackRegistry();
+    let descriptor;
+    try {
+        descriptor = registry.register(source);
+    }
+    catch (error) {
+        throw new CliError(error instanceof Error ? error.message : 'PACK_REGISTER_FAILED', 'ScenarioPack validation failed.', EXIT.contract);
+    }
+    return { source, definition, descriptor, fixtures: contributions.fixtureSuites.flatMap((suite) => suite.cases) };
+}
+async function parseBytes(bytes) { try {
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+catch {
+    throw new CliError('PACK_JSON_INVALID', 'ScenarioPack data file is not valid JSON.', EXIT.contract);
+} }
+function probeInput(probe, resolution, caseSpec) {
+    const base = fixtureM4ConstraintInput();
+    const contextBase = { ...base.context, caseSpecId: caseSpec.id, caseSpecRevision: caseSpec.revision, caseSpecHash: sha256({ fixtureCase: caseSpec.id, revision: caseSpec.revision }), effectiveScenarioHash: resolution.effectiveScenario.effectiveScenarioHash };
+    const context = { ...contextBase, contextHash: computeCompilationContextHash(contextBase) };
+    const requestedScopePlan = fixtureScopePlan(['person.identity'], 'ref-01', caseSpec.id, caseSpec.revision);
+    const ontologyBase = { ...base.ontologyInstance, id: `ontology-${probe.id}`, caseId: caseSpec.id, caseRevision: caseSpec.revision, contextHash: context.contextHash, requestedScopePlanHash: requestedScopePlan.planHash, unknownPaths: probe.unknownPaths ?? [], unspecifiedPaths: [], facts: [], conflicts: [], unresolvedItems: [], decisionTrace: [] };
+    const ontologyInstance = { ...ontologyBase, instanceHash: computeOntologyInstanceHash({ ...ontologyBase, instanceHash: '' }) };
+    const intents = (probe.intents ?? []).map((intent) => ({ ...fixtureChangeIntent(intent.id, intent.operation, intent.targetPath, intent.requestedValue), importance: intent.importance ?? 'required' }));
+    const waivers = probe.waiverTarget ? [createConstraintWaiver({ schemaVersion: 'voce.constraint-waiver/v1alpha1', id: `waiver-${probe.id}`, caseId: caseSpec.id, caseRevision: caseSpec.revision, contextHash: context.contextHash, targetId: probe.waiverTarget, authority: 'user', decidedBy: 'fixture-reviewer', reasonCode: 'FIXTURE_EXPLICIT_WAIVER', decidedAt: '2026-01-01T00:00:00.000Z' })] : [];
+    return fixtureM4ConstraintInput({ caseId: caseSpec.id, caseRevision: caseSpec.revision, context, contextHash: context.contextHash, requestedScopePlanHash: requestedScopePlan.planHash, ontologyInstance, changeIntents: intents, effectiveScenario: resolution.effectiveScenario, waivers });
+}
+function coreProbeEvidence(probe, resolution, caseSpec) {
+    const ir = compileConstraints(probeInput(probe, resolution, caseSpec));
+    return {
+        status: ir.status, constraintHash: ir.deterministicSignature, blockingConflictCount: ir.conflicts.filter((item) => item.blocking).length,
+        conflictCodes: ir.conflicts.map((item) => item.code).sort(compare), reviewRequirementCount: ir.reviewRequirements.length,
+        reviewReasons: ir.reviewRequirements.map((item) => item.reasonCode).sort(compare), waivedWarnings: ir.warnings.filter((item) => item === 'REQUIRED_CONFLICT_WAIVED' || item === 'HARD_CONFLICT_CANNOT_WAIVE').sort(compare),
+        degradationCount: ir.degradedPreferences.length, personIntentCount: (probe.intents ?? []).filter((item) => item.targetPath.startsWith('person.')).length,
+    };
+}
+function referenceEvidence(fixture, resolution, caseSpec) {
+    const paths = fixture.scopePaths ?? [];
+    const plan = fixtureScopePlan(paths, 'ref-01', caseSpec.id, caseSpec.revision);
+    const result = new FixtureReferenceInterpreter().interpret({ schemaVersion: 'voce.reference-interpreter-input/v1alpha1', caseId: caseSpec.id, caseRevision: caseSpec.revision, contextHash: sha256({ fixture: fixture.id, caseId: caseSpec.id }), assets: caseSpec.assets, requestedScopePlan: plan, effectiveScenario: resolution.effectiveScenario, fixtureId: fixture.id });
+    return { status: result.status, observationCount: result.observations.length, personObservationCount: result.observations.filter((item) => item.ontologyPath.startsWith('person.')).length, observationPaths: result.observations.map((item) => item.ontologyPath).sort(compare), observationAssetIds: result.observations.map((item) => item.assetId).sort(compare), unresolvedCodes: result.unresolvedItems.map((item) => item.code).sort(compare), resultHash: result.resultHash };
+}
+function pathValue(value, target) {
+    let current = value;
+    for (const part of target.split('.')) {
+        if (!isObject(current) && !Array.isArray(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function assertionMatches(actual, assertion) {
+    if (assertion.operator === 'exists')
+        return actual !== undefined;
+    if (assertion.operator === 'sha256')
+        return typeof actual === 'string' && HASH.test(actual);
+    if (assertion.operator === 'gte')
+        return typeof actual === 'number' && typeof assertion.expected === 'number' && actual >= assertion.expected;
+    if (assertion.operator === 'includes')
+        return Array.isArray(actual) ? actual.some((item) => canonicalize(item) === canonicalize(assertion.expected)) : typeof actual === 'string' && typeof assertion.expected === 'string' && actual.includes(assertion.expected);
+    return canonicalize(actual) === canonicalize(assertion.expected);
+}
+function assertFixtureAssertions(fixture, context, phase) {
+    const assertions = fixture.expectedAssertions ?? [];
+    const selected = assertions.filter((assertion) => phase === 'all' || assertion.phase === phase);
+    const seen = new Set();
+    const results = [];
+    for (const assertion of selected) {
+        if (seen.has(assertion.id) || !assertion.id || !assertion.target || !['equals', 'includes', 'gte', 'exists', 'sha256'].includes(assertion.operator))
+            throw new CliError('FIXTURE_ASSERTION_INVALID', 'Fixture assertion contract is invalid.', EXIT.contract);
+        seen.add(assertion.id);
+        const actual = pathValue(context, assertion.target);
+        if (!assertionMatches(actual, assertion))
+            throw new CliError('FIXTURE_ASSERTION_FAILED', `Fixture assertion ${assertion.id} did not match.`, EXIT.contract);
+        results.push({ id: assertion.id, status: 'passed', target: assertion.target, operator: assertion.operator, observedHash: sha256(actual === undefined ? null : actual) });
+    }
+    if (phase === 'all' && results.length !== assertions.length)
+        throw new CliError('FIXTURE_ASSERTION_NOT_EXECUTED', 'A declared fixture assertion was not executed.', EXIT.contract);
+    return results.sort((left, right) => compare(String(left.id), String(right.id)));
+}
+function profileFor(id) {
+    if (id === MOCK_IMAGE_PROFILE.id)
+        return MOCK_IMAGE_PROFILE;
+    if (id === MOCK_JPEG_PROFILE.id)
+        return MOCK_JPEG_PROFILE;
+    if (id === MOCK_LIMITED_REFERENCE_PROFILE.id)
+        return MOCK_LIMITED_REFERENCE_PROFILE;
+    throw new CliError('PROFILE_UNSUPPORTED', 'Only a declared offline Mock capability profile is accepted.', EXIT.contract);
+}
+async function loadProfile(filePath) { const object = record(await readJson(path.resolve(filePath), 'PROFILE_FILE_UNSAFE'), 'PROFILE_JSON_INVALID'); return profileFor(stringField(object, 'id', 'PROFILE_INVALID')); }
+function profilePin(profile) { return { id: profile.id, version: profile.version, digest: profile.profileHash }; }
+function toolPin(id, version) { return { id, version, digest: sha256({ id, version }) }; }
+function defaultCase(doc, packId) {
+    assertKnown(doc, ['schemaVersion', 'id', 'revision', 'fixtureId', 'mode', 'scenario', 'userIntent', 'assets', 'trustedMetadata', 'policies', 'requestedOutput'], 'CASE_UNKNOWN_FIELD');
+    const id = typeof doc.id === 'string' ? doc.id : `${packId}-case`;
+    const revision = typeof doc.revision === 'number' ? doc.revision : 1;
+    const output = isObject(doc.requestedOutput) ? doc.requestedOutput : { artifactKind: 'image', dataType: 'image', mediaTypes: ['image/png'], cardinality: { min: 1, max: 1 }, background: 'opaque', allowAlpha: false };
+    const asset = { id: 'ref-01', storeId: 'fixture-store', contentHash: sha256({ fixture: `${id}:ref-01` }), mediaType: 'image/png', byteLength: 64, role: 'reference', resolverId: 'fixture-resolver', availability: 'available', retentionClass: 'fixture', redactionPolicy: 'hash-only' };
+    return { schemaVersion: 'voce.case-spec/v1alpha1', id, revision, mode: 'manual', scenario: { root: { packId, versionRange: '0.1.0' }, extensions: [] }, userIntent: typeof doc.userIntent === 'string' ? doc.userIntent : 'Offline fixture case.', assets: [asset], trustedMetadata: [], policies: { schemaVersion: 'voce.case-policies/v1alpha1', observationConfirmation: 'explicit', bindingConfirmation: 'explicit', allowDeclaredDefaults: true }, requestedOutput: output };
+}
+async function compileInputs(casePath, scenarioPath, profilePath) {
+    const caseDoc = record(await readJson(path.resolve(casePath), 'CASE_FILE_UNSAFE'), 'CASE_JSON_INVALID');
+    const loaded = await loadPack(scenarioPath);
+    const registry = createScenarioPackRegistry();
+    registry.register(loaded.source);
+    const resolution = registry.resolve({ root: { packId: loaded.descriptor.manifest.packId, versionRange: loaded.descriptor.manifest.version }, extensions: [] });
+    if (resolution.status !== 'resolved')
+        throw new CliError('PACK_RESOLUTION_BLOCKED', 'ScenarioPack resolution is blocked.', EXIT.contract);
+    const caseSpec = defaultCase(caseDoc, loaded.descriptor.manifest.packId);
+    const fixtureId = typeof caseDoc.fixtureId === 'string' ? caseDoc.fixtureId : caseSpec.id;
+    const fixture = loaded.fixtures.find((candidate) => candidate.id === fixtureId) ?? loaded.fixtures[0] ?? { id: fixtureId, profileId: MOCK_IMAGE_PROFILE.id };
+    const profile = await loadProfile(profilePath);
+    const prompt = fixtureM5Candidate(fixtureM5PromptIR(profile));
+    const input = fixtureM5ExecutionInput(profile);
+    const coreProbes = Object.fromEntries((fixture.coreProbes ?? []).sort((left, right) => compare(left.id, right.id)).map((probe) => [probe.id, coreProbeEvidence(probe, resolution, caseSpec)]));
+    const acceptance = { resolution: { status: resolution.status, selectedCount: resolution.report.selected.length, effectiveScenarioHash: resolution.effectiveScenario.effectiveScenarioHash }, reference: referenceEvidence(fixture, resolution, caseSpec), coreProbes, compile: { constraintHash: input.constraintIR.deterministicSignature, referencePlanHash: input.referencePlan.planHash, pipelinePlanHash: input.pipelinePlan.planHash } };
+    return { loaded, resolution, caseSpec, profile, fixture, input, prompt, acceptance };
+}
+function bundlePins(profile, scenario) { return { tool: toolPin(TOOL_ID, CLI_VERSION), core: toolPin('@voce-engine/core', CORE_VERSION), contracts: toolPin('@voce-engine/contracts', CONTRACTS_VERSION), scenario: { id: scenario.descriptor.manifest.packId, version: scenario.descriptor.manifest.version, digest: scenario.descriptor.packageDigest }, profile: profilePin(profile) }; }
+function payloadBytes(payload) { return Object.entries(payload).sort((a, b) => compare(a[0], b[0])).map(([name, value]) => ({ path: `${name}.json`, bytes: textBytes(value) })); }
+function semanticManifestBase(kind, caseInfo, pins, files) { return { schemaVersion: BUNDLE_MANIFEST_SCHEMA_VERSION, kind, case: caseInfo, pins, files, createdBy: 'voce-cli' }; }
+async function prepareOutput(directory, allowed) {
+    const absolute = path.resolve(directory);
+    await mkdir(absolute, { recursive: true });
+    const entries = await readdir(absolute, { withFileTypes: true });
+    for (const entry of entries)
+        if (!allowed.has(entry.name))
+            throw new CliError('OUTPUT_DIRECTORY_NOT_EXCLUSIVE', 'Output directory contains an unrelated entry.', EXIT.output);
+}
+async function atomicWrite(filePath, bytes) { await mkdir(path.dirname(filePath), { recursive: true }); const temporary = path.join(path.dirname(filePath), `.voce-tmp-${randomUUID()}`); await writeFile(temporary, bytes); await rename(temporary, filePath); }
+async function writeBundle(directory, kind, caseInfo, pins, payload) {
+    const files = payloadBytes(payload);
+    const fileEntries = files.map((file) => ({ path: file.path, sha256: bytesHash(file.bytes), byteLength: file.bytes.byteLength })).sort((a, b) => compare(a.path, b.path));
+    const base = semanticManifestBase(kind, caseInfo, pins, fileEntries);
+    const semanticHash = sha256(base);
+    const manifest = { ...base, semanticHash };
+    const allowed = new Set(['manifest.json', ...files.map((file) => file.path)]);
+    await prepareOutput(directory, allowed);
+    for (const file of files)
+        await atomicWrite(path.join(path.resolve(directory), ...file.path.split('/')), file.bytes);
+    await atomicWrite(path.join(path.resolve(directory), 'manifest.json'), textBytes(manifest));
+    return { manifest, semanticHash };
+}
+async function validateBundlePath(bundlePath) {
+    const directory = path.resolve(bundlePath);
+    const info = await lstat(directory).catch(() => undefined);
+    if (!info?.isDirectory() || info.isSymbolicLink())
+        throw new CliError('BUNDLE_NOT_FOUND', 'Bundle directory was not found.', EXIT.contract);
+    await existingBoundary(directory, 'BUNDLE_SOURCE_UNSAFE');
+    const manifestPath = path.join(directory, 'manifest.json');
+    await regularFile(manifestPath, 'BUNDLE_MANIFEST_UNSAFE');
+    const manifest = record(await readJson(manifestPath, 'BUNDLE_MANIFEST_UNSAFE'), 'BUNDLE_MANIFEST_INVALID');
+    assertKnown(manifest, ['schemaVersion', 'kind', 'case', 'pins', 'files', 'semanticHash', 'createdBy'], 'BUNDLE_UNKNOWN_FIELD');
+    if (manifest.schemaVersion !== BUNDLE_MANIFEST_SCHEMA_VERSION || !['compiled', 'run', 'evaluation', 'trace', 'release-candidate'].includes(manifest.kind))
+        throw new CliError('BUNDLE_SCHEMA_UNSUPPORTED', 'Bundle manifest schema or kind is unsupported.', EXIT.contract);
+    assertHash(manifest.semanticHash, 'BUNDLE_SEMANTIC_HASH_INVALID');
+    if (!isObject(manifest.case) || typeof manifest.case.id !== 'string' || typeof manifest.case.revision !== 'number')
+        throw new CliError('BUNDLE_CASE_INVALID', 'Bundle case pin is invalid.', EXIT.contract);
+    assertKnown(manifest.case, ['id', 'revision'], 'BUNDLE_CASE_UNKNOWN_FIELD');
+    if (!isObject(manifest.pins))
+        throw new CliError('BUNDLE_PINS_INVALID', 'Bundle pins are invalid.', EXIT.contract);
+    assertKnown(manifest.pins, ['tool', 'core', 'contracts', 'scenario', 'profile'], 'BUNDLE_PINS_UNKNOWN_FIELD');
+    for (const pin of Object.values(manifest.pins)) {
+        if (pin === undefined)
+            continue;
+        if (!isObject(pin))
+            throw new CliError('BUNDLE_PIN_INVALID', 'Bundle version pin is invalid.', EXIT.contract);
+        assertKnown(pin, ['id', 'version', 'digest'], 'BUNDLE_PIN_UNKNOWN_FIELD');
+        assertHash(pin.digest, 'BUNDLE_PIN_DIGEST_INVALID');
+    }
+    const seen = new Set();
+    const files = Array.isArray(manifest.files) ? manifest.files : [];
+    for (const entry of files) {
+        if (!isObject(entry))
+            throw new CliError('BUNDLE_INVENTORY_INVALID', 'Bundle inventory entry is invalid.', EXIT.contract);
+        assertKnown(entry, ['path', 'sha256', 'byteLength'], 'BUNDLE_FILE_UNKNOWN_FIELD');
+        if (typeof entry.path !== 'string' || !safeRelative(entry.path) || typeof entry.byteLength !== 'number' || !Number.isInteger(entry.byteLength) || entry.byteLength < 0 || seen.has(entry.path) || [...seen].some((item) => item.toLowerCase() === entry.path.toLowerCase()))
+            throw new CliError('BUNDLE_INVENTORY_INVALID', 'Bundle inventory contains an unsafe or duplicate path.', EXIT.contract);
+        seen.add(entry.path);
+        assertHash(entry.sha256, 'BUNDLE_FILE_HASH_INVALID');
+    }
+    const actual = await readdir(directory, { withFileTypes: true });
+    for (const entry of actual) {
+        if (entry.name === 'manifest.json')
+            continue;
+        if (!seen.has(entry.name))
+            throw new CliError('BUNDLE_EXTRA_FILE', 'Bundle has a file outside its manifest.', EXIT.contract);
+        const info = await lstat(path.join(directory, entry.name));
+        if (info.isSymbolicLink() || info.nlink > 1 || !info.isFile())
+            throw new CliError('BUNDLE_ENTRY_UNSAFE', 'Bundle contains a symlink, hardlink, device, or non-file entry.', EXIT.contract);
+    }
+    for (const entry of files) {
+        const filePath = path.join(directory, ...entry.path.split('/'));
+        const present = await lstat(filePath).catch(() => undefined);
+        if (!present)
+            throw new CliError('BUNDLE_FILE_MISSING', 'Bundle inventory file is missing.', EXIT.contract);
+        await regularFile(filePath, 'BUNDLE_ENTRY_UNSAFE');
+        const bytes = await readFile(filePath).catch(() => { throw new CliError('BUNDLE_FILE_MISSING', 'Bundle inventory file is missing.', EXIT.contract); });
+        if (bytes.byteLength !== entry.byteLength || bytesHash(bytes) !== entry.sha256)
+            throw new CliError('BUNDLE_FILE_HASH_MISMATCH', 'Bundle file hash or length does not match its manifest.', EXIT.contract);
+    }
+    const semantic = sha256(semanticManifestBase(manifest.kind, manifest.case, manifest.pins, files));
+    if (semantic !== manifest.semanticHash)
+        throw new CliError('BUNDLE_SEMANTIC_HASH_MISMATCH', 'Bundle semantic hash does not match its manifest.', EXIT.contract);
+    const payload = {};
+    for (const entry of files) {
+        if (!entry.path.endsWith('.json'))
+            continue;
+        payload[entry.path.slice(0, -5)] = await readJson(path.join(directory, ...entry.path.split('/')), 'BUNDLE_ENTRY_UNSAFE');
+    }
+    assertNoUnsafe(payload, 'bundle');
+    return { manifest, payload };
+}
+function outputSummary(manifest, extra = {}) { return { status: 'ok', kind: manifest.kind, caseId: manifest.case.id, revision: manifest.case.revision, semanticHash: manifest.semanticHash, ...extra }; }
+async function compileCommand(args) {
+    const casePath = required(args, 'case');
+    const scenarioPath = required(args, 'scenario');
+    const profilePath = required(args, 'profile');
+    const outputPath = required(args, 'out');
+    await assertOutputSeparated(outputPath, [casePath, scenarioPath, profilePath]);
+    const result = await compileInputs(casePath, scenarioPath, profilePath);
+    const guardInput = fixtureM5GuardInput(fixtureM5PromptIR(result.profile), result.prompt);
+    const guard = guardPromptCandidate(guardInput);
+    const acceptance = clone(result.acceptance);
+    acceptance.compile = { ...acceptance.compile, promptGuard: guard.status };
+    const assertionResults = assertFixtureAssertions(result.fixture, acceptance, 'compile');
+    acceptance.assertions = assertionResults;
+    acceptance.assertionHash = sha256(assertionResults);
+    const payload = { 'case': result.caseSpec, 'scenario': result.resolution, 'profile': { id: result.profile.id, version: result.profile.version, digest: result.profile.profileHash }, 'fixture': result.fixture, 'constraint-ir': result.input.constraintIR, 'reference-plan': result.input.referencePlan, 'pipeline-plan': result.input.pipelinePlan, 'prompt-ir': result.input.promptArtifact, 'prompt-guard': guard, 'execution-input': result.input, acceptance, 'replay-contract': { planReplay: 'available', artifactReplay: 'deferred-until-run', liveRerun: 'requires-new-authorization' } };
+    const written = await writeBundle(outputPath, 'compiled', { id: result.caseSpec.id, revision: result.caseSpec.revision }, bundlePins(result.profile, result.loaded), payload);
+    return outputSummary(written.manifest, { promptGuard: guard.status, scenario: result.loaded.descriptor.manifest.packId });
+}
+async function semanticForRun(run, artifacts, profile) {
+    const reviewer = new FixtureSemanticReviewer();
+    const inputHash = sha256({ runId: run.id, artifacts: artifacts.map((item) => item.contentHash).sort() });
+    const model = reviewer.version;
+    const adapter = { id: 'voce.fixture-semantic-reviewer-adapter', version: '1.0.0', digest: sha256({ id: 'voce.fixture-semantic-reviewer-adapter', version: '1.0.0' }) };
+    const requestBase = { schemaVersion: 'voce.semantic-review-request/v1alpha1', id: `semantic-${run.id}`, caseId: run.caseId, caseRevision: run.caseRevision, contextHash: run.contextHash, inputHash, outputArtifacts: artifacts, criteria: [{ id: 'fixture.semantic', kind: 'semantic_fidelity', importance: 'required', prompt: 'Offline fixture semantic proposal.' }], model, adapter, profile: { id: profile.id, version: profile.version, digest: profile.profileHash }, authorizationId: `semantic-auth-${run.id}`, destination: 'local', allowedEvidenceRegionIds: [], dataCategories: ['image'], budget: { schemaVersion: 'voce.budget/v1alpha1', id: `semantic-budget-${run.id}`, maximumCalls: 1, maximumRetries: 0, timeoutMs: 60_000 } };
+    const request = { ...requestBase, requestHash: computeSemanticReviewRequestHash(requestBase) };
+    const authorization = fixtureM6Authorization({ id: request.authorizationId, caseId: request.caseId, caseRevision: request.caseRevision, contextHash: request.contextHash, stepId: request.id, purpose: 'semantic_review', inputHash, artifactHashes: artifacts.map((item) => item.contentHash), adapter, profileDigest: request.profile.digest, destination: 'local', dataCategories: ['image'], budget: request.budget, modelId: model.id, modelVersion: model.version });
+    const execution = await executeSemanticReview(reviewer, request, authorization);
+    return { report: execution.report, receipt: execution.receipt, remote: execution.remoteCallRun };
+}
+async function runCommand(args) {
+    if (args.provider !== 'mock')
+        throw new CliError('PROVIDER_DISABLED', 'The default provider is disabled; pass --provider mock for offline execution.', EXIT.offline);
+    const bundlePath = required(args, 'bundle');
+    const outputPath = required(args, 'out');
+    await assertOutputSeparated(outputPath, [bundlePath]);
+    const bundle = await validateBundlePath(bundlePath);
+    if (bundle.manifest.kind !== 'compiled')
+        throw new CliError('BUNDLE_KIND_INVALID', 'case run requires a compiled bundle.', EXIT.contract);
+    const input = bundle.payload['execution-input'];
+    if (!input || input.schemaVersion !== 'voce.offline-execution-input/v1alpha1')
+        throw new CliError('EXECUTION_INPUT_INVALID', 'Compiled bundle has no valid offline execution input.', EXIT.contract);
+    const result = executeOffline(input);
+    const run = result.run ?? result.executionRun;
+    if (!run)
+        throw new CliError(result.code || 'EXECUTION_BLOCKED', 'Offline execution did not produce a run.', EXIT.offline);
+    const artifacts = run.outputArtifacts ?? [];
+    const structuralArtifact = fixtureM6Artifact(`structural-${run.id}`, FIXTURE_M6_OPAQUE_PNG, 'image/png', 'generated-image');
+    const outputContract = { artifactKind: 'image', dataType: 'image', mediaTypes: ['image/png'], cardinality: { min: 1, max: 1 }, background: 'opaque', allowAlpha: false };
+    const structural = validateStructuralImage({ schemaVersion: 'voce.structural-validation-input/v1alpha1', id: `structural-${run.id}`, artifacts: [{ artifact: structuralArtifact, bytes: FIXTURE_M6_OPAQUE_PNG }], outputContract, expectedCardinality: { min: 1, max: 1 } });
+    const fixture = bundle.payload.fixture;
+    let semanticProposal;
+    const semanticReceipts = [];
+    const reconciliation = [];
+    if (fixture?.semanticReview) {
+        const semantic = await semanticForRun(run, [structuralArtifact, ...artifacts], profileFor(String(bundle.payload.profile?.id ?? MOCK_IMAGE_PROFILE.id)));
+        semanticProposal = semantic.report;
+        semanticReceipts.push(semantic.receipt);
+        reconciliation.push(semantic.remote);
+    }
+    const human = fixture?.humanPending ? createHumanAcceptanceDecision({ schemaVersion: 'voce.human-acceptance-decision/v1alpha1', id: `human-${run.id}`, runId: run.id, status: 'pending', annotations: [], artifactIds: [structuralArtifact.id, ...artifacts.map((item) => item.id)] }) : undefined;
+    const evaluation = compileEvaluationReport({ run: { id: run.id, technicalOutcome: run.technicalOutcome, state: run.state, contextHash: run.contextHash, pipelinePlanHash: run.pipelinePlanHash, promptArtifactHash: run.promptArtifactHash }, structural, semanticProposal, humanAcceptance: human, cleanup: result.cleanupReceipts, replay: { mode: 'artifact', status: 'available', code: 'REPLAY_AVAILABLE', artifactIds: artifacts.map((item) => item.id) }, artifacts: [structuralArtifact, ...artifacts], sourceHashes: { compiledBundle: bundle.manifest.semanticHash, executionRun: computeExecutionRunHash(run) } });
+    const traceModel = traceModelFromExecution({ run, receipts: [...result.receipts, ...semanticReceipts], cleanup: result.cleanupReceipts, reconciliation: [...result.remoteCallRuns, ...reconciliation], artifacts: [structuralArtifact, ...artifacts], structural, semanticProposal, humanAcceptance: human, budgets: input.pipelinePlan.steps.map((step) => step.budget), destinations: input.pipelinePlan.dataTransfers.map((item) => item.destination), constraintHash: input.constraintIR.deterministicSignature, referencePlanHash: input.referencePlan.planHash, promptHash: input.executionAuthorization.promptArtifactHash, warnings: result.reasons });
+    const acceptance = isObject(bundle.payload.acceptance) ? clone(bundle.payload.acceptance) : {};
+    const runEvidence = { executionStatus: result.status, executionCode: result.code, receiptCount: result.receipts.length + semanticReceipts.length, receiptAdapters: [...result.receipts, ...semanticReceipts].map((item) => item.adapterId).sort(compare), artifactMediaTypes: artifacts.map((item) => item.mediaType).sort(compare), artifactRoles: artifacts.map((item) => item.role).sort(compare), structuralStatus: structural.status, semanticStatus: semanticProposal?.status ?? 'absent', humanStatus: human?.status ?? 'absent', evaluationStatus: evaluation.status, traceModelPresent: true, traceModelHash: traceModel.modelHash };
+    acceptance.run = runEvidence;
+    const runAssertions = fixture ? assertFixtureAssertions(fixture, acceptance, 'run') : [];
+    acceptance.assertions = [...(Array.isArray(acceptance.assertions) ? acceptance.assertions : []), ...runAssertions].sort((left, right) => compare(String(left.id), String(right.id)));
+    acceptance.assertionHash = sha256(acceptance.assertions);
+    const payload = { 'compiled-ref': { semanticHash: bundle.manifest.semanticHash }, 'run': run, 'events': result.events, 'receipts': [...result.receipts, ...semanticReceipts], 'remote-call-runs': [...result.remoteCallRuns, ...reconciliation], 'cleanup': result.cleanupReceipts, 'compensation': result.compensationReceipts, 'evaluation': evaluation, 'trace-model': traceModel, acceptance, 'comparison-snapshot': { constraintIR: input.constraintIR, referencePlan: input.referencePlan, promptIR: input.promptArtifact, pipelinePlan: input.pipelinePlan, receipts: [...result.receipts, ...semanticReceipts], evaluation } };
+    const written = await writeBundle(outputPath, 'run', bundle.manifest.case, bundle.manifest.pins, payload);
+    return outputSummary(written.manifest, { execution: result.status, executionCode: result.code, evaluation: evaluation.status, traceModel: traceModel.modelHash });
+}
+async function traceCommand(args) { const bundlePath = required(args, 'bundle'); const outputPath = required(args, 'out'); await assertOutputSeparated(outputPath, [bundlePath]); const bundle = await validateBundlePath(bundlePath); const model = bundle.payload['trace-model']; if (!model || model.schemaVersion !== 'voce.static-trace-report-model/v1alpha1')
+    throw new CliError('TRACE_MODEL_INVALID', 'Bundle has no valid static trace model.', EXIT.contract); const report = renderStaticTraceReport(model); await atomicWrite(path.resolve(outputPath), report.content); return { status: 'ok', mediaType: report.mediaType, contentHash: report.contentHash, modelHash: report.modelHash }; }
+function comparisonSnapshot(payload) { return { constraintIR: payload['constraint-ir'], referencePlan: payload['reference-plan'], promptIR: payload['prompt-ir'], pipelinePlan: payload['pipeline-plan'], receipts: payload.receipts, evaluation: payload.evaluation }; }
+async function compareCommand(args) { const beforePath = required(args, 'before'); const afterPath = required(args, 'after'); const out = args.out ? path.resolve(args.out) : undefined; if (out)
+    await assertOutputSeparated(out, [beforePath, afterPath]); const before = await validateBundlePath(beforePath); const after = await validateBundlePath(afterPath); const beforeSnapshot = before.payload['comparison-snapshot'] ?? comparisonSnapshot(before.payload); const afterSnapshot = after.payload['comparison-snapshot'] ?? comparisonSnapshot(after.payload); const { compareSnapshots } = await import('@voce-engine/core'); const report = compareSnapshots({ caseId: after.manifest.case.id, beforeRevision: before.manifest.case.revision, afterRevision: after.manifest.case.revision, before: beforeSnapshot, after: afterSnapshot }); if (out)
+    await atomicWrite(out, textBytes(report)); return out ? { status: 'ok', reportHash: report.reportHash, output: safeDisplayPath(out) } : report; }
+async function packInspectCommand(source) { const loaded = await loadPack(source); return { status: 'ok', packId: loaded.descriptor.manifest.packId, version: loaded.descriptor.manifest.version, kind: loaded.descriptor.manifest.kind, declarations: { mayHandlePersonImages: loaded.descriptor.manifest.declarations.mayHandlePersonImages, rightsDisclosureRequired: loaded.descriptor.manifest.declarations.rightsDisclosureRequired }, manifestHash: loaded.descriptor.manifestHash, packageDigest: loaded.descriptor.packageDigest, distributionDigest: loaded.descriptor.distributionDigest, fixtureSuites: loaded.definition.contributions.fixtureSuites.map((suite) => ({ id: suite.id, caseIds: suite.cases.map((item) => isObject(item) && typeof item.id === 'string' ? item.id : 'invalid') })) }; }
+async function packValidateCommand(source) { const loaded = await loadPack(source); return { status: 'ok', valid: true, packId: loaded.descriptor.manifest.packId, version: loaded.descriptor.manifest.version, manifestHash: loaded.descriptor.manifestHash, packageDigest: loaded.descriptor.packageDigest, distributionDigest: loaded.descriptor.distributionDigest, lifecycleScriptsExecuted: false }; }
+async function packTestCommand(source) {
+    const loaded = await loadPack(source);
+    const registry = createScenarioPackRegistry();
+    registry.register(loaded.source);
+    const resolution = registry.resolve({ root: { packId: loaded.descriptor.manifest.packId, versionRange: loaded.descriptor.manifest.version }, extensions: [] });
+    if (resolution.status !== 'resolved')
+        throw new CliError('PACK_RESOLUTION_BLOCKED', 'ScenarioPack resolution is blocked.', EXIT.contract);
+    const results = [];
+    for (const fixture of loaded.fixtures) {
+        const profile = profileFor(fixture.profileId ?? MOCK_IMAGE_PROFILE.id);
+        const caseSpec = defaultCase({ id: fixture.id }, loaded.descriptor.manifest.packId);
+        const input = fixtureM5ExecutionInput(profile);
+        const prompt = fixtureM5Candidate(fixtureM5PromptIR(profile));
+        const guard = guardPromptCandidate(fixtureM5GuardInput(fixtureM5PromptIR(profile), prompt));
+        const coreProbes = Object.fromEntries((fixture.coreProbes ?? []).sort((left, right) => compare(left.id, right.id)).map((probe) => [probe.id, coreProbeEvidence(probe, resolution, caseSpec)]));
+        const acceptance = { resolution: { status: resolution.status, selectedCount: resolution.report.selected.length, effectiveScenarioHash: resolution.effectiveScenario.effectiveScenarioHash }, reference: referenceEvidence(fixture, resolution, caseSpec), coreProbes, compile: { constraintHash: input.constraintIR.deterministicSignature, referencePlanHash: input.referencePlan.planHash, pipelinePlanHash: input.pipelinePlan.planHash, promptGuard: guard.status } };
+        const result = executeOffline(input);
+        const run = result.run ?? result.executionRun;
+        if (!run)
+            throw new CliError(result.code || 'EXECUTION_BLOCKED', 'Offline fixture execution did not produce a run.', EXIT.offline);
+        const artifacts = run.outputArtifacts ?? [];
+        const structuralArtifact = fixtureM6Artifact(`structural-${run.id}`, FIXTURE_M6_OPAQUE_PNG, 'image/png', 'generated-image');
+        const outputContract = { artifactKind: 'image', dataType: 'image', mediaTypes: ['image/png'], cardinality: { min: 1, max: 1 }, background: 'opaque', allowAlpha: false };
+        const structural = validateStructuralImage({ schemaVersion: 'voce.structural-validation-input/v1alpha1', id: `structural-${run.id}`, artifacts: [{ artifact: structuralArtifact, bytes: FIXTURE_M6_OPAQUE_PNG }], outputContract, expectedCardinality: { min: 1, max: 1 } });
+        let semanticProposal;
+        const semanticReceipts = [];
+        const reconciliation = [];
+        if (fixture.semanticReview) {
+            const semantic = await semanticForRun(run, [structuralArtifact, ...artifacts], profile);
+            semanticProposal = semantic.report;
+            semanticReceipts.push(semantic.receipt);
+            reconciliation.push(semantic.remote);
+        }
+        const human = fixture.humanPending ? createHumanAcceptanceDecision({ schemaVersion: 'voce.human-acceptance-decision/v1alpha1', id: `human-${run.id}`, runId: run.id, status: 'pending', annotations: [], artifactIds: [structuralArtifact.id, ...artifacts.map((item) => item.id)] }) : undefined;
+        const compiledHash = sha256({ packId: loaded.descriptor.manifest.packId, fixtureId: fixture.id });
+        const evaluation = compileEvaluationReport({ run: { id: run.id, technicalOutcome: run.technicalOutcome, state: run.state, contextHash: run.contextHash, pipelinePlanHash: run.pipelinePlanHash, promptArtifactHash: run.promptArtifactHash }, structural, semanticProposal, humanAcceptance: human, cleanup: result.cleanupReceipts, replay: { mode: 'artifact', status: 'available', code: 'REPLAY_AVAILABLE', artifactIds: artifacts.map((item) => item.id) }, artifacts: [structuralArtifact, ...artifacts], sourceHashes: { compiledBundle: compiledHash, executionRun: computeExecutionRunHash(run) } });
+        const traceModel = traceModelFromExecution({ run, receipts: [...result.receipts, ...semanticReceipts], cleanup: result.cleanupReceipts, reconciliation: [...result.remoteCallRuns, ...reconciliation], artifacts: [structuralArtifact, ...artifacts], structural, semanticProposal, humanAcceptance: human, budgets: input.pipelinePlan.steps.map((step) => step.budget), destinations: input.pipelinePlan.dataTransfers.map((item) => item.destination), constraintHash: input.constraintIR.deterministicSignature, referencePlanHash: input.referencePlan.planHash, promptHash: input.executionAuthorization.promptArtifactHash, warnings: result.reasons });
+        acceptance.run = { executionStatus: result.status, executionCode: result.code, receiptCount: result.receipts.length + semanticReceipts.length, receiptAdapters: [...result.receipts, ...semanticReceipts].map((item) => item.adapterId).sort(compare), artifactMediaTypes: artifacts.map((item) => item.mediaType).sort(compare), artifactRoles: artifacts.map((item) => item.role).sort(compare), structuralStatus: structural.status, semanticStatus: semanticProposal?.status ?? 'absent', humanStatus: human?.status ?? 'absent', evaluationStatus: evaluation.status, traceModelPresent: true, traceModelHash: traceModel.modelHash };
+        const assertions = assertFixtureAssertions(fixture, acceptance, 'all');
+        const expected = fixture.expectedStatus ?? 'completed';
+        const accepted = result.status === expected || (expected === 'needs_review' && result.status === 'completed');
+        results.push({ id: fixture.id, status: accepted ? 'passed' : 'failed', expectedStatus: expected, observedStatus: result.status, executionCode: result.code, reasons: result.reasons, assertionIds: assertions.map((item) => item.id), assertions, assertionHash: sha256(assertions), observedHashes: { constraint: input.constraintIR.deterministicSignature, trace: traceModel.modelHash, evaluation: evaluation.reportHash } });
+    }
+    const failed = results.some((item) => item.status === 'failed');
+    return { status: failed ? 'failed' : 'passed', packId: loaded.descriptor.manifest.packId, resolutionHash: resolution.report.reportHash, lockHash: resolution.lock.lockHash, effectiveScenarioHash: resolution.effectiveScenario.effectiveScenarioHash, fixtureCount: results.length, results };
+}
+async function doctorCommand() { const major = Number(process.versions.node.split('.')[0]); return { status: major >= 20 ? 'ok' : 'blocked', node: { version: process.versions.node, supported: major >= 20 }, contracts: { schemaVersion: BUNDLE_MANIFEST_SCHEMA_VERSION, packageVersion: CONTRACTS_VERSION }, paths: { explicitOnly: true }, providers: { default: 'disabled', mock: 'offline', networkProbe: false }, authProbe: { inspected: false } }; }
+function required(args, key) { if (!args[key])
+    throw new CliError('ARGUMENT_MISSING', `Missing --${key}.`, EXIT.usage); return args[key]; }
+function help() { return `voce ${CLI_VERSION}\n\nOffline-first explicit-path CLI.\n\nCommands:\n  voce pack inspect --source <path> [--json]\n  voce pack validate --source <path> [--json]\n  voce pack test --source <path> [--json]\n  voce case compile --case <file> --scenario <path> --profile <file> --out <dir> [--json]\n  voce case run --bundle <dir> --provider mock --out <dir> [--json]\n  voce trace render --bundle <dir> --out <html> [--json]\n  voce compare --before <dir> --after <dir> [--out <file>] [--json]\n  voce doctor [--json]\n\nExit codes: 0 success, 2 usage, 3 input, 4 contract/hash, 5 offline/provider, 6 output, 7 internal.`; }
+function parse(argv) { const command = []; const args = {}; let machine = false; for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--json') {
+        machine = true;
+        continue;
+    }
+    if (token === '--help' || token === '-h') {
+        command.push('--help');
+        continue;
+    }
+    if (token === '--version' || token === '-v') {
+        command.push('--version');
+        continue;
+    }
+    if (token.startsWith('--')) {
+        const key = token.slice(2);
+        const value = argv[i + 1];
+        if (!value || value.startsWith('--'))
+            throw new CliError('ARGUMENT_MISSING', `Missing --${key}.`, EXIT.usage);
+        args[key] = value;
+        i += 1;
+    }
+    else
+        command.push(token);
+} return { command, args, machine }; }
+export async function runCli(argv = process.argv.slice(2)) {
+    let machine = argv.includes('--json');
+    try {
+        const parsed = parse(argv);
+        machine = parsed.machine;
+        if (parsed.command.includes('--help') || parsed.command.length === 0) {
+            process.stdout.write(machine ? json({ status: 'ok', version: CLI_VERSION, help: help() }) + '\n' : help() + '\n');
+            return EXIT.ok;
+        }
+        if (parsed.command.includes('--version')) {
+            process.stdout.write(machine ? json({ status: 'ok', version: CLI_VERSION }) + '\n' : CLI_VERSION + '\n');
+            return EXIT.ok;
+        }
+        let result;
+        const [first, second, third] = parsed.command;
+        if (first === 'doctor')
+            result = await doctorCommand();
+        else if (first === 'pack' && second === 'inspect')
+            result = await packInspectCommand(required(parsed.args, 'source'));
+        else if (first === 'pack' && second === 'validate')
+            result = await packValidateCommand(required(parsed.args, 'source'));
+        else if (first === 'pack' && second === 'test')
+            result = await packTestCommand(required(parsed.args, 'source'));
+        else if (first === 'case' && second === 'compile')
+            result = await compileCommand(parsed.args);
+        else if (first === 'case' && second === 'run')
+            result = await runCommand(parsed.args);
+        else if (first === 'trace' && second === 'render')
+            result = await traceCommand(parsed.args);
+        else if (first === 'compare')
+            result = await compareCommand(parsed.args);
+        else
+            throw new CliError('UNKNOWN_COMMAND', 'Unknown command.', EXIT.usage);
+        assertNoUnsafe(result, 'stdout');
+        process.stdout.write(machine ? json(result) + '\n' : `${String(result.status)}${result.semanticHash ? ` ${result.semanticHash}` : ''}\n`);
+        return result.status === 'failed' ? EXIT.offline : EXIT.ok;
+    }
+    catch (error) {
+        const cliError = error instanceof CliError ? error : new CliError('INTERNAL_ERROR', 'The command failed without a public diagnostic.', EXIT.internal);
+        process.stderr.write(`${cliError.code}: ${cliError.message}\n`);
+        if (machine)
+            process.stdout.write(json({ status: 'error', code: cliError.code }) + '\n');
+        return cliError.exitCode;
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@voce-engine/cli",
+  "version": "0.1.0-rc.1",
+  "description": "Offline-first command line tools for the VOCE v0.1 release candidate.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/cli.js",
+    "dist/cli.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "voce": "dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windforce19820520-ai/visual-ontology-constraint-engine.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/windforce19820520-ai/visual-ontology-constraint-engine#readme",
+  "bugs": {
+    "url": "https://github.com/windforce19820520-ai/visual-ontology-constraint-engine/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "dependencies": {
+    "@voce-engine/contracts": "0.1.0-rc.1",
+    "@voce-engine/core": "0.1.0-rc.1",
+    "@voce-engine/testkit": "0.1.0-rc.1"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}