reverseport 0.0.0-stage → 1.2.0

package/dist/domain/completionLedgerGeneration.js

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { IDENTIFIER_PATTERN } from "./stringPatterns.js";
+import { createEvidenceCompletionLedger, evidenceCompletionRecordSchema, } from "./evidenceCompletionLedger.js";
+import { digestSchema } from "./../domain/digests.js";
+import { prefixedDigestSchema } from "./../domain/digests.js";
+const identifierSchema = z.string().regex(IDENTIFIER_PATTERN);
+const identitySchema = z.strictObject({
+    id: identifierSchema,
+    version: z.string().min(1),
+});
+const environmentSchema = z.strictObject({
+    platform: identifierSchema,
+    architecture: identifierSchema,
+    runtime: identifierSchema,
+    runtime_version: z.string().min(1),
+});
+const scenarioSchema = z.strictObject({
+    id: identifierSchema,
+    version: z.number().int().positive(),
+});
+const skillDigestSchema = z.strictObject({
+    skill_id: identifierSchema,
+    sha256: digestSchema,
+});
+const verifierRunSchema = z
+    .strictObject({
+    run_id: z.string().uuid(),
+    verifier_pid: z.number().int().positive(),
+    parent_pid: z.number().int().nonnegative(),
+    process_lineage: z.discriminatedUnion("status", [
+        z.strictObject({
+            status: z.literal("verified"),
+            observed_at: z.iso.datetime(),
+            launcher_pid: z.number().int().positive(),
+            launcher_parent_pid: z.number().int().nonnegative(),
+            process_group_id: z.number().int().positive(),
+            descendants: z.array(z.strictObject({
+                pid: z.number().int().positive(),
+                parent_pid: z.number().int().nonnegative(),
+                process_group_id: z.number().int().positive(),
+            })),
+        }),
+        z.strictObject({
+            status: z.literal("unavailable"),
+            observed_at: z.iso.datetime(),
+            launcher_pid: z.number().int().positive(),
+            launcher_parent_pid: z.number().int().nonnegative(),
+            process_group_id: z.number().int().positive().nullable(),
+            reason: z.string().min(1),
+        }),
+    ]),
+})
+    .superRefine((run, context) => {
+    if (run.process_lineage.launcher_pid !== run.verifier_pid)
+        context.addIssue({
+            code: "custom",
+            path: ["process_lineage", "launcher_pid"],
+            message: "Lineage launcher PID must identify the verifier process",
+        });
+    if (run.process_lineage.launcher_parent_pid !== run.parent_pid)
+        context.addIssue({
+            code: "custom",
+            path: ["process_lineage", "launcher_parent_pid"],
+            message: "Lineage parent PID must identify the verifier parent",
+        });
+});
+const reportClaimSchema = z.strictObject({
+    claim_id: identifierSchema,
+    scenario: scenarioSchema,
+    artifact_sha256s: z.array(digestSchema),
+    provider: identitySchema,
+    status: evidenceCompletionRecordSchema.shape.status,
+    evidence_ids: evidenceCompletionRecordSchema.shape.evidence_ids,
+});
+const completionVerifierReportObjectSchema = z.strictObject({
+    verifier: identitySchema,
+    verifier_run: verifierRunSchema,
+    environment: environmentSchema,
+    claims: z.array(reportClaimSchema).min(1),
+});
+/** Strict output contract implemented by completion-aware verifiers. */
+export const completionVerifierReportSchema = completionVerifierReportObjectSchema.superRefine((report, context) => {
+    for (const [index, claim] of report.claims.entries())
+        if (claim.status === "pass" && claim.artifact_sha256s.length === 0)
+            context.addIssue({
+                code: "custom",
+                path: ["claims", index, "artifact_sha256s"],
+                message: "Passing claims must commit at least one artifact digest",
+            });
+});
+const manifestClaimSchema = reportClaimSchema.omit({
+    status: true,
+    evidence_ids: true,
+});
+const completionManifestObjectSchema = z.strictObject({
+    manifest_id: prefixedDigestSchema("ecm"),
+    verifier: identitySchema,
+    environment: environmentSchema,
+    skill_digests: z.array(skillDigestSchema).min(1),
+    claims: z.array(manifestClaimSchema).min(1),
+});
+const compareIdentifiers = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const isSortedUnique = (values) => values.every((value, index) => index === 0 || compareIdentifiers(values[index - 1] ?? "", value) < 0);
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("RFC 8785 canonicalization rejected completion metadata");
+    return serialized;
+};
+const computeManifestId = (manifest) => `ecm_${createHash("sha256").update(canonicalJson(manifest)).digest("hex")}`;
+const manifestIssues = (manifest, context) => {
+    if (!isSortedUnique(manifest.claims.map(({ claim_id }) => claim_id)))
+        context.addIssue({
+            code: "custom",
+            path: ["claims"],
+            message: "Manifest claims must be sorted by unique claim ID",
+        });
+    if (!isSortedUnique(manifest.skill_digests.map(({ skill_id }) => skill_id)))
+        context.addIssue({
+            code: "custom",
+            path: ["skill_digests"],
+            message: "Skill digests must be sorted by unique skill ID",
+        });
+    for (const [index, claim] of manifest.claims.entries())
+        if (!isSortedUnique(claim.artifact_sha256s))
+            context.addIssue({
+                code: "custom",
+                path: ["claims", index, "artifact_sha256s"],
+                message: "Artifact digests must be sorted and unique",
+            });
+    const { manifest_id: manifestId, ...projection } = manifest;
+    if (computeManifestId(projection) !== manifestId)
+        context.addIssue({
+            code: "custom",
+            path: ["manifest_id"],
+            message: "Completion manifest identifier does not match its content",
+        });
+};
+/** Canonical immutable commitments for one verifier run. */
+export const completionManifestSchema = completionManifestObjectSchema.superRefine(manifestIssues);
+const canonicalClaims = (claims) => claims
+    .map((claim) => ({
+    ...claim,
+    artifact_sha256s: [...claim.artifact_sha256s].sort(compareIdentifiers),
+    evidence_ids: [...claim.evidence_ids].sort(compareIdentifiers),
+}))
+    .sort((left, right) => compareIdentifiers(left.claim_id, right.claim_id));
+/** Generate canonical manifest and ledger artifacts from live verifier output. */
+export const createCompletionLedgerArtifacts = (input, skillDigests) => {
+    const report = completionVerifierReportSchema.parse(input);
+    const claims = canonicalClaims(report.claims);
+    if (!isSortedUnique(claims.map(({ claim_id }) => claim_id)))
+        throw new TypeError("Completion verifier claim IDs must be unique");
+    for (const claim of claims) {
+        if (!isSortedUnique(claim.artifact_sha256s))
+            throw new TypeError("Artifact digests must be unique per claim");
+        if (!isSortedUnique(claim.evidence_ids))
+            throw new TypeError("Evidence IDs must be unique per claim");
+    }
+    const skills = skillDigests
+        .map((skill) => skillDigestSchema.parse(skill))
+        .sort((left, right) => compareIdentifiers(left.skill_id, right.skill_id));
+    if (!isSortedUnique(skills.map(({ skill_id }) => skill_id)))
+        throw new TypeError("Completion skill IDs must be unique");
+    const projection = {
+        verifier: report.verifier,
+        environment: report.environment,
+        skill_digests: skills,
+        claims: claims.map(({ status: _status, evidence_ids: _evidenceIds, ...claim }) => claim),
+    };
+    return {
+        manifest: completionManifestSchema.parse({
+            ...projection,
+            manifest_id: computeManifestId(projection),
+        }),
+        ledger: createEvidenceCompletionLedger(claims.map(({ claim_id, status, evidence_ids }) => ({
+            claim_id,
+            status,
+            evidence_ids,
+        }))),
+    };
+};
+/** Parse generated completion commitments and reject manual tampering. */
+export const parseCompletionManifest = (input) => completionManifestSchema.parse(input);

package/dist/domain/configurationErrors.js

@@ -0,0 +1,37 @@
+import { AnalysisError, } from "./analysisErrorBase.js";
+/** Runtime configuration could not be parsed safely. */
+export class ConfigurationError extends AnalysisError {
+    _tag = "ConfigurationError";
+    settings;
+    constructor(message, options) {
+        super(message, options);
+        this.settings = (options?.settings ?? []).map(({ setting, constraint }) => ({ setting, constraint }));
+    }
+}
+/** No app or binary session exists for an analysis request. */
+export class NoBinaryOpenError extends AnalysisError {
+    _tag = "NoBinaryOpenError";
+    constructor() {
+        super("No app is open. Ask the user which app to investigate, then call open_binary with its local path.");
+    }
+}
+/** A supplied target path could not be safely opened as a supported app or binary. */
+export class BinaryTargetError extends AnalysisError {
+    path;
+    reason;
+    _tag = "BinaryTargetError";
+    constraint;
+    /** The OS read-permission code of the cause, when the host denied access. */
+    systemCode;
+    constructor(path, reason, options) {
+        super(`Cannot open artifact: ${reason}`, options);
+        this.path = path;
+        this.reason = reason;
+        this.constraint = options?.constraint;
+        this.systemCode = readPermissionCode(options?.cause);
+    }
+}
+const readPermissionCode = (cause) => {
+    const code = cause instanceof Error ? Reflect.get(cause, "code") : undefined;
+    return code === "EACCES" || code === "EPERM" ? code : undefined;
+};

package/dist/domain/conformancePackage.js

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { IDENTIFIER_PATTERN } from "./stringPatterns.js";
+import { evidenceSchema } from "./evidence.js";
+import { evidenceBundleSchema } from "./evidenceBundle.js";
+import { err, ok } from "./result.js";
+import { prefixedDigestSchema } from "./../domain/digests.js";
+const conformancePackageIdSchema = prefixedDigestSchema("cp");
+const scenarioIdSchema = z.string().regex(IDENTIFIER_PATTERN);
+const scenarioManifestSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    name: z.string().min(1),
+    description: z.string().min(1),
+    /** Source-owned fixture path relative to the repository root. */
+    fixture_path: z.string().min(1),
+    /** Expected exit code or null if unspecified. */
+    expected_exit_code: z.number().int().nullable(),
+    /** Expected output patterns that must appear in the capture. */
+    expected_patterns: z.array(z.string()).default([]),
+});
+const replayPlanSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Ordered steps to execute during replay. */
+    steps: z
+        .array(z.strictObject({
+        step_id: z.string().min(1),
+        action: z.string().min(1),
+        arguments: z.array(z.string()).default([]),
+        timeout_ms: z.number().int().positive(),
+    }))
+        .min(1),
+    /** Environment variables to set (never inherit host paths). */
+    environment: z.record(z.string(), z.string()).default({}),
+});
+const shimPlanSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Shims to install, each intercepting a named effect. */
+    shims: z.array(z.strictObject({
+        shim_id: z.string().min(1),
+        kind: z.enum(["filesystem", "network", "process", "signal"]),
+        target: z.string().min(1),
+        policy: z.enum(["observe", "allow", "block", "emulate"]),
+    })),
+});
+const expectedEvidenceSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Expected evidence envelopes. */
+    envelopes: z.array(evidenceSchema),
+    /** Expected evidence bundle. */
+    bundle: evidenceBundleSchema.nullable(),
+    /** Required dimensions that must be present in the evidence. */
+    required_dimensions: z.array(z.string().min(1)).default([]),
+});
+const verifierContractSchema = z.strictObject({
+    scenario_id: scenarioIdSchema,
+    /** Dimensions to verify. */
+    dimensions: z
+        .array(z.strictObject({
+        name: z.string().min(1),
+        required: z.boolean().default(true),
+        comparison: z.enum(["exact", "semantic", "fuzzy"]),
+    }))
+        .min(1),
+    /** Tolerance for timing differences in milliseconds. */
+    timing_tolerance_ms: z.number().int().nonnegative().default(0),
+});
+const conformancePackageContentsSchema = z.strictObject({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    created_at: z.string().datetime(),
+    /** Scenario manifests. */
+    scenarios: z.array(scenarioManifestSchema).min(1),
+    /** Exactly one replay plan for each scenario. */
+    replay_plans: z.array(replayPlanSchema).min(1),
+    /** At most one optional shim plan for each scenario. */
+    shim_plans: z.array(shimPlanSchema).default([]),
+    /** Exactly one expected-evidence record for each scenario. */
+    expected_evidence: z.array(expectedEvidenceSchema).min(1),
+    /** Exactly one verifier contract for each scenario. */
+    verifier_contracts: z.array(verifierContractSchema).min(1),
+});
+const conformancePackageRecordSchema = conformancePackageContentsSchema.extend({
+    package_id: conformancePackageIdSchema,
+});
+const conformancePackageSchema = conformancePackageRecordSchema.brand();
+/** Parse unknown input once into a package whose aggregate invariants hold. */
+export function parseConformancePackage(input) {
+    const parsed = conformancePackageSchema.safeParse(input);
+    if (!parsed.success)
+        return err({
+            kind: "invalid_package",
+            message: parsed.error.issues[0]?.message ?? "Invalid package",
+        });
+    const relationError = parseScenarioRelations(parsed.data);
+    if (relationError !== undefined)
+        return err(relationError);
+    const expectedPackageId = computePackageId(packageContents(parsed.data));
+    if (parsed.data.package_id !== expectedPackageId)
+        return err({
+            kind: "package_id_mismatch",
+            actual: parsed.data.package_id,
+            expected: expectedPackageId,
+            message: "Package identifier does not match its canonical contents",
+        });
+    return ok(parsed.data);
+}
+/** Create a content-addressed package from source-owned typed fields. */
+export function createConformancePackage(input) {
+    const contents = conformancePackageContentsSchema.safeParse(input);
+    if (!contents.success)
+        throw new TypeError(`Invalid conformance package source: ${contents.error.issues[0]?.message ?? "unknown parse failure"}`);
+    const parsed = parseConformancePackage({
+        ...contents.data,
+        package_id: computePackageId(contents.data),
+    });
+    if (!parsed.ok)
+        throw new TypeError(`Invalid conformance package source: ${parsed.error.message}`);
+    return parsed.value;
+}
+const parseScenarioRelations = (pkg) => {
+    const scenarioIds = new Set();
+    for (const scenario of pkg.scenarios) {
+        if (scenarioIds.has(scenario.scenario_id))
+            return {
+                kind: "duplicate_scenario",
+                scenario_id: scenario.scenario_id,
+                message: `Duplicate scenario ${scenario.scenario_id}`,
+            };
+        scenarioIds.add(scenario.scenario_id);
+    }
+    const sections = [
+        { name: "replay_plans", entries: pkg.replay_plans, required: true },
+        { name: "shim_plans", entries: pkg.shim_plans, required: false },
+        {
+            name: "expected_evidence",
+            entries: pkg.expected_evidence,
+            required: true,
+        },
+        {
+            name: "verifier_contracts",
+            entries: pkg.verifier_contracts,
+            required: true,
+        },
+    ];
+    for (const section of sections) {
+        const error = parseScenarioSection(scenarioIds, section);
+        if (error !== undefined)
+            return error;
+    }
+    return undefined;
+};
+const parseScenarioSection = (scenarioIds, section) => {
+    const referenced = new Set();
+    for (const entry of section.entries) {
+        if (!scenarioIds.has(entry.scenario_id))
+            return {
+                kind: "unknown_scenario_reference",
+                section: section.name,
+                scenario_id: entry.scenario_id,
+                message: `${section.name} references unknown scenario ${entry.scenario_id}`,
+            };
+        if (referenced.has(entry.scenario_id))
+            return {
+                kind: "duplicate_scenario_reference",
+                section: section.name,
+                scenario_id: entry.scenario_id,
+                message: `${section.name} contains duplicate scenario ${entry.scenario_id}`,
+            };
+        referenced.add(entry.scenario_id);
+    }
+    if (!section.required)
+        return undefined;
+    for (const scenarioId of scenarioIds) {
+        if (!referenced.has(scenarioId))
+            return {
+                kind: "missing_scenario_reference",
+                section: section.name,
+                scenario_id: scenarioId,
+                message: `${section.name} is missing scenario ${scenarioId}`,
+            };
+    }
+    return undefined;
+};
+const packageContents = (pkg) => ({
+    name: pkg.name,
+    description: pkg.description,
+    created_at: pkg.created_at,
+    scenarios: pkg.scenarios,
+    replay_plans: pkg.replay_plans,
+    shim_plans: pkg.shim_plans,
+    expected_evidence: pkg.expected_evidence,
+    verifier_contracts: pkg.verifier_contracts,
+});
+const computePackageId = (contents) => {
+    const json = canonicalize(contents);
+    if (json === undefined)
+        throw new TypeError("Could not canonicalize parsed conformance package");
+    return `cp_${createHash("sha256").update(json).digest("hex")}`;
+};

package/dist/domain/conformanceReplay.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { parseConformancePackage } from "./conformancePackage.js";
+import { evaluatePackageTrustGates, trustGateResultSchema, } from "./conformanceTrustGate.js";
+/** Result of a single scenario replay. */
+export const scenarioReplayResultSchema = z.strictObject({
+    scenario_id: z.string().min(1),
+    status: z.enum(["pass", "fail", "error", "skipped"]),
+    exit_code: z.number().int().nullable(),
+    duration_ms: z.number().int().nonnegative(),
+    output: z.string().default(""),
+    error: z.string().nullable(),
+});
+/** Result of replaying an entire conformance package. */
+export const packageReplayResultSchema = z
+    .strictObject({
+    package_id: z.string().min(1),
+    total_scenarios: z.number().int().positive(),
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    errored: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    scenario_results: z.array(scenarioReplayResultSchema),
+    trust_gate_results: z.array(trustGateResultSchema),
+    drift_detected: z.boolean(),
+    first_drift: z
+        .strictObject({
+        scenario_id: z.string().min(1),
+        dimension: z.string().min(1),
+        evidence_id: z.string().min(1),
+        message: z.string(),
+    })
+        .nullable(),
+})
+    .superRefine((result, context) => {
+    const count = (status) => result.scenario_results.filter((item) => item.status === status).length;
+    const countMismatch = result.passed !== count("pass") ||
+        result.failed !== count("fail") ||
+        result.errored !== count("error") ||
+        result.skipped !== count("skipped");
+    const driftDetected = result.trust_gate_results.some(({ verdict }) => verdict === "fail");
+    if (result.total_scenarios !== result.scenario_results.length ||
+        countMismatch)
+        context.addIssue({
+            code: "custom",
+            message: "Scenario totals must summarize scenario results",
+            path: ["total_scenarios"],
+        });
+    if (result.drift_detected !== driftDetected)
+        context.addIssue({
+            code: "custom",
+            message: "Drift status must summarize trust-gate failures",
+            path: ["drift_detected"],
+        });
+    if (!driftDetected && result.first_drift !== null)
+        context.addIssue({
+            code: "custom",
+            message: "A drift witness requires a failed trust gate",
+            path: ["first_drift"],
+        });
+});
+/**
+ * Default no-op scenario runner that skips all scenarios.
+ * Real CI replays inject an actual runner.
+ */
+async function defaultRunner() {
+    return {
+        scenario_id: "unknown",
+        status: "skipped",
+        exit_code: null,
+        duration_ms: 0,
+        output: "",
+        error: "no runner provided",
+    };
+}
+/**
+ * Replay a conformance package from a clean checkout.
+ * Runs each scenario, evaluates trust gates, and detects drift
+ * between the captured run and the committed package.
+ */
+export async function replayConformancePackage(packageInput, actualEvidence, runner = defaultRunner, options = {}) {
+    const parsed = parseConformancePackage(packageInput);
+    if (!parsed.ok)
+        throw new TypeError(`invalid conformance package: ${parsed.error.message}`);
+    const pkg = parsed.value;
+    const scenarioResults = [];
+    let passed = 0;
+    let failed = 0;
+    let errored = 0;
+    let skipped = 0;
+    for (const scenario of pkg.scenarios) {
+        const result = await runner(scenario.scenario_id, scenario.fixture_path);
+        scenarioResults.push(result);
+        switch (result.status) {
+            case "pass":
+                passed++;
+                break;
+            case "fail":
+                failed++;
+                break;
+            case "error":
+                errored++;
+                break;
+            case "skipped":
+                skipped++;
+                break;
+        }
+    }
+    const trustGateResults = evaluatePackageTrustGates(pkg, actualEvidence, options);
+    const driftGates = trustGateResults.filter((r) => r.verdict === "fail");
+    const drift_detected = driftGates.length > 0;
+    const first_drift_gate = driftGates[0];
+    const first_drift = first_drift_gate?.first_divergence
+        ? {
+            scenario_id: first_drift_gate.scenario_id,
+            dimension: first_drift_gate.first_divergence.dimension,
+            evidence_id: first_drift_gate.first_divergence.evidence_id,
+            message: first_drift_gate.first_divergence.message,
+        }
+        : null;
+    return packageReplayResultSchema.parse({
+        package_id: pkg.package_id,
+        total_scenarios: pkg.scenarios.length,
+        passed,
+        failed,
+        errored,
+        skipped,
+        scenario_results: scenarioResults,
+        trust_gate_results: trustGateResults,
+        drift_detected,
+        first_drift,
+    });
+}