reverseport 0.0.0-stage → 1.2.0

package/dist/domain/evidenceBundle.js

@@ -0,0 +1,413 @@
+import { z } from "zod";
+import canonicalize from "canonicalize";
+import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
+import { evidenceSchema, immutableEvidence, parseEvidence, providerSchema, } from "./evidence.js";
+import { residualUnknownSchema, } from "./residualUnknown.js";
+import { freezeJsonSnapshot } from "./immutableJson.js";
+const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
+    digest: true,
+    format: true,
+    architecture: true,
+});
+const providerManifestSchema = providerSchema;
+const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
+const scenarioManifestSchema = z.object({
+    evidence_id: evidenceSchema.shape.evidence_id,
+    operation: z.string().min(1),
+    authority: z.literal("controlled-replay"),
+});
+const captureManifestSchema = z.object({
+    evidence_id: evidenceSchema.shape.evidence_id,
+    predicate_type: z.string().min(1),
+});
+export const evidenceBundleSchema = z.object({
+    artifacts: z.array(artifactManifestSchema),
+    providers: z.array(providerManifestSchema),
+    environments: z.array(environmentManifestSchema),
+    scenarios: z.array(scenarioManifestSchema),
+    captures: z.array(captureManifestSchema),
+    unknowns: z.array(residualUnknownSchema),
+    records: z.array(evidenceSchema),
+});
+const immutableBundles = new WeakMap();
+/** Build and authenticate a sealed bundle while reusing immutable Evidence records. */
+export const createImmutableEvidenceBundle = (records, unknowns = []) => {
+    const checkedRecords = records.map(immutableEvidence);
+    if (new Set(checkedRecords.map(({ evidence_id }) => evidence_id)).size !==
+        checkedRecords.length)
+        throw new TypeError("Evidence bundle contains duplicate record IDs");
+    const checkedUnknowns = unknowns.map((unknown) => residualUnknownSchema.parse(unknown));
+    validateUnknownGraph(checkedUnknowns, checkedRecords);
+    const bundle = freezeJsonSnapshot(createEvidenceBundle(checkedRecords, checkedUnknowns));
+    immutableBundles.set(bundle, bundle);
+    return bundle;
+};
+/** Project records into a deterministic bundle whose order has no semantics. */
+export const createEvidenceBundle = (records, unknowns = []) => {
+    const sortedRecords = [...records].sort((left, right) => compareUnicodeCodePoints(left.evidence_id, right.evidence_id));
+    return {
+        artifacts: uniqueSorted(sortedRecords.flatMap(({ subject }) => subject === null
+            ? []
+            : [
+                {
+                    digest: subject.digest,
+                    format: subject.format,
+                    architecture: subject.architecture,
+                },
+            ])),
+        providers: uniqueSorted(sortedRecords.map(({ provider }) => provider)),
+        environments: uniqueSorted(sortedRecords.flatMap(({ environment }) => environment === null ? [] : [environment])),
+        scenarios: sortedRecords.flatMap((evidence) => evidence.authority === "controlled-replay"
+            ? [
+                {
+                    evidence_id: evidence.evidence_id,
+                    operation: evidence.operation,
+                    authority: evidence.authority,
+                },
+            ]
+            : []),
+        captures: sortedRecords.flatMap((evidence) => evidence.predicate_type === "rea.process-capture"
+            ? [
+                {
+                    evidence_id: evidence.evidence_id,
+                    predicate_type: evidence.predicate_type,
+                },
+            ]
+            : []),
+        unknowns: [...unknowns].sort((left, right) => compareUnicodeCodePoints(left.unknown_id, right.unknown_id) ||
+            left.revision - right.revision),
+        records: sortedRecords,
+    };
+};
+/** Retain target records and eligible complete unknown histories with their mutation evidence. */
+export const evidenceBundleForTarget = (bundle, sha256) => {
+    const recordsById = new Map(bundle.records.map((record) => [record.evidence_id, record]));
+    const histories = new Map();
+    for (const unknown of bundle.unknowns) {
+        const history = histories.get(unknown.unknown_id) ?? [];
+        history.push(unknown);
+        histories.set(unknown.unknown_id, history);
+    }
+    const retained = new Set();
+    const dependents = new Map();
+    const relationships = new Map();
+    for (const [id, history] of histories) {
+        const eligible = history.every((unknown) => {
+            if (unknown.scope_digest !== sha256)
+                return false;
+            const mutationEvidenceIds = new Set(unknown.mutation_evidence_ids);
+            return referencedEvidenceIds(unknown).every((evidenceId) => {
+                const record = recordsById.get(evidenceId);
+                // Mutation subjects record the target active at the time of an edit,
+                // which need not be the question's immutable investigation scope.
+                return (record?.subject?.digest.sha256 === sha256 ||
+                    (mutationEvidenceIds.has(evidenceId) &&
+                        record?.predicate_type === "rea.residual-unknown-mutation"));
+            });
+        });
+        if (!eligible)
+            continue;
+        retained.add(id);
+        const relatedIds = new Set(history.flatMap((unknown) => unknown.relationships.map(({ unknown_id }) => unknown_id)));
+        relationships.set(id, relatedIds);
+        for (const relatedId of relatedIds) {
+            const references = dependents.get(relatedId) ?? new Set();
+            references.add(id);
+            dependents.set(relatedId, references);
+        }
+    }
+    const pending = [];
+    for (const [id, relatedIds] of relationships)
+        if ([...relatedIds].some((relatedId) => !retained.has(relatedId)))
+            pending.push(id);
+    for (let index = 0; index < pending.length; index += 1) {
+        const id = pending[index];
+        if (id === undefined || !retained.delete(id))
+            continue;
+        for (const dependent of dependents.get(id) ?? [])
+            pending.push(dependent);
+    }
+    const unknowns = bundle.unknowns.filter((unknown) => retained.has(unknown.unknown_id));
+    const mutationIds = new Set(unknowns.flatMap(({ mutation_evidence_ids: ids }) => ids));
+    return createEvidenceBundle(bundle.records.filter((record) => record.subject?.digest.sha256 === sha256 ||
+        mutationIds.has(record.evidence_id)), unknowns);
+};
+const referencedEvidenceIds = (unknown) => [
+    ...unknown.supporting_evidence_ids,
+    ...unknown.contradicting_evidence_ids,
+    ...unknown.mutation_evidence_ids,
+    ...(unknown.resolution?.evidence_ids ?? []),
+];
+export const describeEvidenceBundleFailure = (input, cause) => {
+    try {
+        const record = parseEvidence(input);
+        return {
+            kind: "single-record",
+            message: `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`,
+        };
+    }
+    catch {
+        return {
+            kind: "invalid-bundle",
+            message: cause instanceof z.ZodError
+                ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
+                : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`,
+        };
+    }
+};
+/** Locate the first schema issue, or keep a thrown constraint message. */
+export const describeValidationFailure = (cause) => {
+    if (!(cause instanceof z.ZodError))
+        return cause instanceof Error ? cause.message : String(cause);
+    const [first, ...rest] = cause.issues;
+    const location = first === undefined || first.path.length === 0
+        ? "the document root"
+        : first.path.map(String).join(".");
+    return `at ${location}: ${first?.message ?? "invalid value"}${rest.length === 0 ? "" : ` (${String(rest.length)} more issues)`}`;
+};
+/** Parse records, verify semantic IDs, and reject inconsistent manifests. */
+export const parseEvidenceBundle = (input) => {
+    return parseBundle(input, false);
+};
+/** Authenticate and seal file-owned payloads once for downstream zero-copy reuse. */
+export const parseImmutableEvidenceBundle = (input) => {
+    return parseBundle(input, true);
+};
+const parseBundle = (input, seal) => {
+    if (typeof input === "object" && input !== null) {
+        const owned = immutableBundles.get(input);
+        if (owned !== undefined)
+            return owned;
+    }
+    return authenticateBundle(evidenceBundleSchema.parse(input), seal);
+};
+/** Authenticate evidence and bundle invariants after the bundle shape is parsed. */
+export const authenticateParsedEvidenceBundle = (parsed) => authenticateBundle(parsed, false);
+const authenticateBundle = (parsed, seal) => {
+    const recordIds = parsed.records.map(({ evidence_id: id }) => id);
+    if (new Set(recordIds).size !== recordIds.length)
+        throw new TypeError("Evidence bundle contains duplicate record IDs");
+    validateUnknownGraph(parsed.unknowns, parsed.records);
+    const canonical = createEvidenceBundle(parsed.records.map((record, index) => {
+        try {
+            if (!seal)
+                return parseEvidence(record);
+            // Schema parsing gave this boundary exclusive ownership. Register only
+            // validated payloads before authenticating the complete record envelope.
+            record.normalized_result = freezeJsonSnapshot(record.normalized_result);
+            record.raw_result = freezeJsonSnapshot(record.raw_result);
+            return immutableEvidence(record);
+        }
+        catch (cause) {
+            if (cause instanceof z.ZodError)
+                throw new z.ZodError(cause.issues.map((issue) => ({
+                    ...issue,
+                    path: ["records", index, ...issue.path],
+                })));
+            throw cause;
+        }
+    }), parsed.unknowns);
+    if (JSON.stringify(parsed) !== JSON.stringify(canonical))
+        throw new TypeError("Evidence bundle manifests are not canonical");
+    if (seal) {
+        freezeJsonSnapshot(canonical);
+        immutableBundles.set(canonical, canonical);
+    }
+    return canonical;
+};
+const validateUnknownGraph = (unknowns, records) => {
+    const evidenceById = new Map(records.map((record) => [record.evidence_id, record]));
+    const histories = new Map();
+    for (const unknown of unknowns) {
+        const history = histories.get(unknown.unknown_id) ?? [];
+        history.push(unknown);
+        histories.set(unknown.unknown_id, history);
+    }
+    const unknownById = new Map();
+    for (const [id, unordered] of histories) {
+        const history = [...unordered].sort((left, right) => left.revision - right.revision);
+        for (const [index, revision] of history.entries()) {
+            if (revision.revision !== index + 1)
+                throw new TypeError(`Residual unknown ${id} revision history has a gap`);
+            if (index > 0 &&
+                revision.previous_revision_digest !==
+                    history[index - 1]?.revision_digest)
+                throw new TypeError(`Residual unknown ${id} revision chain is broken`);
+        }
+        const head = history.at(-1);
+        if (head === undefined)
+            throw new TypeError("Residual unknown revision history is empty");
+        unknownById.set(id, head);
+    }
+    for (const unknown of unknowns) {
+        const referencedEvidence = [
+            ...unknown.supporting_evidence_ids,
+            ...unknown.contradicting_evidence_ids,
+            ...unknown.mutation_evidence_ids,
+            ...(unknown.resolution?.evidence_ids ?? []),
+        ];
+        for (const evidenceId of referencedEvidence)
+            if (!evidenceById.has(evidenceId))
+                throw new TypeError(`Residual unknown references missing evidence ${evidenceId}`);
+        for (const relationship of unknown.relationships)
+            if (!unknownById.has(relationship.unknown_id))
+                throw new TypeError(`Residual unknown references missing unknown ${relationship.unknown_id}`);
+        if (unknown.resolution?.disposition === "verified")
+            validateVerifiedResolution(unknown, evidenceById);
+    }
+    rejectDependencyCycles(unknownById);
+};
+const validateVerifiedResolution = (unknown, evidenceById) => {
+    if (unknown.contradicting_evidence_ids.length > 0)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} retains contradicting evidence`);
+    const qualifies = unknown.resolution?.evidence_ids.some((evidenceId) => {
+        const evidence = evidenceById.get(evidenceId);
+        return (unknown.supporting_evidence_ids.includes(evidenceId) &&
+            evidence !== undefined &&
+            evidence.predicate_type !== "rea.residual-unknown-mutation" &&
+            evidenceQualifies(unknown, evidence));
+    });
+    if (qualifies !== true)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} has no qualifying resolution evidence`);
+};
+/**
+ * Validate one new residual-unknown revision against an already valid ledger.
+ * This keeps ordinary mutations proportional to the affected revision while
+ * full bundle imports continue to validate the complete graph.
+ */
+export const validateResidualUnknownAddition = (unknown, evidenceById, currentHeads) => {
+    const current = currentHeads.get(unknown.unknown_id);
+    if (current === undefined
+        ? unknown.revision !== 1 || unknown.previous_revision_digest !== null
+        : unknown.revision !== current.revision + 1 ||
+            unknown.previous_revision_digest !== current.revision_digest)
+        throw new TypeError(`Residual unknown ${unknown.unknown_id} revision chain is broken`);
+    for (const evidenceId of referencedEvidenceIds(unknown))
+        if (!evidenceById.has(evidenceId))
+            throw new TypeError(`Residual unknown references missing evidence ${evidenceId}`);
+    for (const relationship of unknown.relationships)
+        if (relationship.unknown_id !== unknown.unknown_id &&
+            !currentHeads.has(relationship.unknown_id))
+            throw new TypeError(`Residual unknown references missing unknown ${relationship.unknown_id}`);
+    if (unknown.resolution?.disposition === "verified")
+        validateVerifiedResolution(unknown, evidenceById);
+    // In a valid graph, no existing node can point to an absent ID. Since the
+    // schema rejects self-relations, a new node's outgoing edges cannot close a
+    // cycle; keep graph traversal for revisions of existing nodes only.
+    if (current !== undefined) {
+        const dependencies = unknown.relationships
+            .filter((relationship) => relationship.type === "depends-on")
+            .map(({ unknown_id }) => unknown_id);
+        if (dependencies.length > 0 &&
+            reachesUnknown(dependencies, unknown.unknown_id, currentHeads, unknown))
+            throw new TypeError("Residual unknown dependency graph contains a cycle");
+    }
+};
+const reachesUnknown = (starts, goal, currentHeads, candidate) => {
+    const pending = [...starts];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const id = pending.pop();
+        if (id === undefined)
+            break;
+        if (id === goal)
+            return true;
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const unknown = id === candidate.unknown_id ? candidate : currentHeads.get(id);
+        if (unknown === undefined)
+            continue;
+        for (const relationship of unknown.relationships)
+            if (relationship.type === "depends-on")
+                pending.push(relationship.unknown_id);
+    }
+    return false;
+};
+const evidenceQualifies = (unknown, evidence) => {
+    if (unknown.required_authority !== null &&
+        evidence.authority !== unknown.required_authority)
+        return false;
+    const confidenceRank = { inferred: 1, derived: 2, observed: 3 };
+    if (confidenceRank[evidence.confidence] <
+        confidenceRank[unknown.required_confidence])
+        return false;
+    const requirement = unknown.required_environment;
+    if (requirement === null)
+        return true;
+    if (evidence.environment === null)
+        return false;
+    return ((requirement.id === null || requirement.id === evidence.environment.id) &&
+        (requirement.platform === null ||
+            requirement.platform === evidence.environment.platform) &&
+        (requirement.architecture === null ||
+            requirement.architecture === evidence.environment.architecture) &&
+        (requirement.isolation === null ||
+            requirement.isolation === evidence.environment.isolation));
+};
+const rejectDependencyCycles = (unknownById) => {
+    const visited = new Set();
+    const active = new Set();
+    const pending = [];
+    for (const root of unknownById.keys()) {
+        if (visited.has(root))
+            continue;
+        const rootUnknown = unknownById.get(root);
+        if (rootUnknown === undefined)
+            throw new TypeError("Residual unknown dependency graph is inconsistent");
+        active.add(root);
+        pending.push({
+            id: root,
+            relationships: rootUnknown.relationships,
+            nextRelationship: 0,
+        });
+        while (pending.length > 0) {
+            const frame = pending[pending.length - 1];
+            if (frame === undefined)
+                break;
+            let descended = false;
+            while (frame.nextRelationship < frame.relationships.length) {
+                const relationship = frame.relationships[frame.nextRelationship];
+                frame.nextRelationship += 1;
+                if (relationship?.type !== "depends-on")
+                    continue;
+                const dependency = relationship.unknown_id;
+                if (active.has(dependency))
+                    throw new TypeError("Residual unknown dependency graph contains a cycle");
+                if (visited.has(dependency))
+                    continue;
+                const unknown = unknownById.get(dependency);
+                if (unknown === undefined)
+                    throw new TypeError("Residual unknown dependency graph is inconsistent");
+                active.add(dependency);
+                pending.push({
+                    id: dependency,
+                    relationships: unknown.relationships,
+                    nextRelationship: 0,
+                });
+                descended = true;
+                break;
+            }
+            if (descended)
+                continue;
+            pending.pop();
+            active.delete(frame.id);
+            visited.add(frame.id);
+        }
+    }
+};
+/** Encode a validated bundle as byte-stable RFC 8785 canonical JSON. */
+export const serializeEvidenceBundle = (bundle) => {
+    const serialized = canonicalize(parseEvidenceBundle(bundle));
+    if (serialized === undefined)
+        throw new TypeError("Evidence bundle canonicalization failed");
+    return serialized;
+};
+const uniqueSorted = (values) => {
+    const unique = new Map();
+    for (const value of values)
+        unique.set(JSON.stringify(value), value);
+    return [...unique.entries()]
+        .sort(([left], [right]) => compareUnicodeCodePoints(left, right))
+        .map(([, value]) => value);
+};

package/dist/domain/evidenceCompletionLedger.js

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { IDENTIFIER_PATTERN } from "./stringPatterns.js";
+import { prefixedDigestSchema } from "./../domain/digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+const claimIdSchema = z.string().regex(IDENTIFIER_PATTERN);
+/** Terminal outcome recorded for one verifier claim. */
+export const evidenceCompletionStatusSchema = z.enum([
+    "pass",
+    "fail",
+    "unsupported",
+    "truncated",
+    "unknown",
+]);
+/** Strict evidence-linked result for one verifier claim. */
+export const evidenceCompletionRecordSchema = z.strictObject({
+    claim_id: claimIdSchema,
+    status: evidenceCompletionStatusSchema,
+    evidence_ids: z.array(evidenceIdSchema).min(1),
+});
+const completionSummarySchema = z.strictObject({
+    total: z.number().int().min(1),
+    pass: z.number().int().nonnegative(),
+    fail: z.number().int().nonnegative(),
+    unsupported: z.number().int().nonnegative(),
+    truncated: z.number().int().nonnegative(),
+    unknown: z.number().int().nonnegative(),
+    complete: z.boolean(),
+});
+const completionLedgerObjectSchema = z.strictObject({
+    ledger_id: prefixedDigestSchema("ecl"),
+    records: z.array(evidenceCompletionRecordSchema).min(1),
+    summary: completionSummarySchema,
+});
+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 summarize = (records) => {
+    const counts = {
+        pass: 0,
+        fail: 0,
+        unsupported: 0,
+        truncated: 0,
+        unknown: 0,
+    };
+    for (const record of records)
+        counts[record.status] += 1;
+    return {
+        total: records.length,
+        ...counts,
+        complete: counts.pass === records.length,
+    };
+};
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("RFC 8785 canonicalization rejected the completion ledger");
+    return serialized;
+};
+const computeLedgerId = (records) => `ecl_${createHash("sha256")
+    .update(canonicalJson({ records }))
+    .digest("hex")}`;
+const ledgerIssues = (ledger, context) => {
+    if (!isSortedUnique(ledger.records.map((record) => record.claim_id)))
+        context.addIssue({
+            code: "custom",
+            path: ["records"],
+            message: "Completion records must be sorted by unique claim ID",
+        });
+    for (const [index, record] of ledger.records.entries())
+        if (!isSortedUnique(record.evidence_ids))
+            context.addIssue({
+                code: "custom",
+                path: ["records", index, "evidence_ids"],
+                message: "Evidence IDs must be sorted and unique",
+            });
+    if (JSON.stringify(summarize(ledger.records)) !== JSON.stringify(ledger.summary))
+        context.addIssue({
+            code: "custom",
+            path: ["summary"],
+            message: "Completion summary does not match its records",
+        });
+    if (computeLedgerId(ledger.records) !== ledger.ledger_id)
+        context.addIssue({
+            code: "custom",
+            path: ["ledger_id"],
+            message: "Completion ledger identifier does not match its records",
+        });
+};
+/** Strict path-free Evidence completion ledger. */
+export const evidenceCompletionLedgerSchema = completionLedgerObjectSchema.superRefine(ledgerIssues);
+/** Build a canonical path-independent ledger from verifier claim outcomes. */
+export const createEvidenceCompletionLedger = (input) => {
+    const records = input
+        .map((record) => evidenceCompletionRecordSchema.parse(record))
+        .map((record) => ({
+        ...record,
+        evidence_ids: [...record.evidence_ids].sort(compareIdentifiers),
+    }))
+        .sort((left, right) => compareIdentifiers(left.claim_id, right.claim_id));
+    if (!isSortedUnique(records.map((record) => record.claim_id)))
+        throw new TypeError("Completion claim IDs must be unique");
+    for (const record of records)
+        if (!isSortedUnique(record.evidence_ids))
+            throw new TypeError("Completion Evidence IDs must be unique per claim");
+    return evidenceCompletionLedgerSchema.parse({
+        ledger_id: computeLedgerId(records),
+        records,
+        summary: summarize(records),
+    });
+};
+/** Parse a completion ledger and reject non-canonical or tampered content. */
+export const parseEvidenceCompletionLedger = (input) => evidenceCompletionLedgerSchema.parse(input);

package/dist/domain/evidenceErrors.js

@@ -0,0 +1,46 @@
+import { AnalysisError, } from "./analysisErrorBase.js";
+/** Evidence identity, schema, or bundle manifests failed integrity checks. */
+export class EvidenceIntegrityError extends AnalysisError {
+    _tag = "EvidenceIntegrityError";
+    userMessage;
+    constructor(message, options) {
+        super(message, options);
+        this.userMessage = options?.userMessage;
+    }
+}
+/** A valid snapshot belongs to a different target, provider, or analysis profile. */
+export class AnalysisSnapshotMismatchError extends EvidenceIntegrityError {
+}
+/** A session Evidence reference is missing or has the wrong semantic identity. */
+export class EvidenceReferenceError extends EvidenceIntegrityError {
+    evidenceId;
+    reason;
+    expected;
+    actual;
+    constructor(evidenceId, reason, expected, actual) {
+        super(`Evidence reference ${reason}: ${evidenceId}`);
+        this.evidenceId = evidenceId;
+        this.reason = reason;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+/** Evidence bundle filesystem access failed within the configured policy. */
+export class EvidenceFileError extends AnalysisError {
+    operation;
+    reason;
+    _tag = "EvidenceFileError";
+    userMessage;
+    /** Caller-selected path that failed, resolved against the working directory. */
+    path;
+    /** Present only when a write committed before cleanup failed. */
+    published;
+    constructor(operation, reason, options) {
+        super(`Evidence bundle ${operation} failed: ${reason}`, options);
+        this.operation = operation;
+        this.reason = reason;
+        this.path = options?.path;
+        this.published = options?.published;
+        this.userMessage = options?.userMessage;
+    }
+}