reverseport 0.0.0-stage → 1.2.0

package/dist/domain/canonicalDigest.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+/**
+ * Streaming SHA-256 over canonical JSON. Hashing owner (avoids assembling
+ * aggregate strings); `comparisonSemantics.canonicalJson` (canonicalize lib)
+ * is the string-comparison owner. JSON object keys follow RFC 8785's UTF-16
+ * code-unit order in both; entity-list ordering is a separate concern.
+ */
+export const digestCanonicalValue = (value, context = "Comparison") => {
+    const hash = createHash("sha256");
+    // Batch small emitted parts to cut hash.update crossings.
+    // Flush cuts only at part boundaries, so the hashed byte stream is unchanged.
+    let buffered = "";
+    const emit = (part) => {
+        buffered += part;
+        if (buffered.length >= 8192) {
+            hash.update(buffered);
+            buffered = "";
+        }
+    };
+    const encoded = emitCanonical(value, emit, new Set());
+    if (!encoded)
+        throw new TypeError(`${context} could not canonicalize data`);
+    if (buffered)
+        hash.update(buffered);
+    return hash.digest("hex");
+};
+const emitCanonical = (value, emit, ancestors) => {
+    if (typeof value === "number" && !Number.isFinite(value))
+        throw new Error(Number.isNaN(value) ? "NaN is not allowed" : "Infinity is not allowed");
+    if (value === null || typeof value !== "object") {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined)
+            return false;
+        emit(encoded);
+        return true;
+    }
+    if (ancestors.has(value))
+        throw new Error("Circular reference detected");
+    ancestors.add(value);
+    try {
+        if ("toJSON" in value && typeof value.toJSON === "function") {
+            const normalized = value.toJSON();
+            return emitCanonical(normalized, emit, ancestors);
+        }
+        if (Array.isArray(value)) {
+            emit("[");
+            const length = value.length;
+            for (let index = 0; index < length; index += 1) {
+                if (index > 0)
+                    emit(",");
+                // Preserve canonicalize's sparse-array and unsupported-value behavior.
+                if (!(index in value))
+                    continue;
+                const item = value[index];
+                emitCanonical(item === undefined || typeof item === "symbol" ? null : item, emit, ancestors);
+            }
+            emit("]");
+        }
+        else {
+            emit("{");
+            let first = true;
+            // Match canonicalize/RFC 8785, including supplementary-plane keys.
+            for (const key of Object.keys(value).sort()) {
+                if (Reflect.get(value, key) === undefined ||
+                    typeof Reflect.get(value, key) === "symbol")
+                    continue;
+                const item = Reflect.get(value, key);
+                if (!first)
+                    emit(",");
+                first = false;
+                emit(JSON.stringify(key));
+                emit(":");
+                if (!emitCanonical(item, emit, ancestors))
+                    emit("undefined");
+            }
+            emit("}");
+        }
+        return true;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+};

package/dist/domain/canonicalJsonDigestSteps.js

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+/** Hash owned, validated JSON in bounded steps without a document-sized string. */
+export function* canonicalJsonDigestSteps(value) {
+    const hash = createHash("sha256");
+    const ancestors = new Set();
+    const stack = [{ kind: "value", value }];
+    const encodedKeys = new Map();
+    // Keep reusable key encodings within one existing digest-buffer quantum.
+    let remainingKeyCodeUnits = 8192;
+    let buffered = "";
+    let flushed = false;
+    const emit = (part) => {
+        buffered += part;
+        if (buffered.length >= 8192) {
+            hash.update(buffered);
+            buffered = "";
+            flushed = true;
+        }
+    };
+    try {
+        while (stack.length > 0) {
+            if (flushed) {
+                flushed = false;
+                yield;
+            }
+            const frame = stack.pop();
+            if (frame === undefined)
+                break;
+            if (frame.kind === "separator") {
+                emit(":");
+                continue;
+            }
+            if (frame.kind === "string") {
+                if (frame.index === frame.value.length) {
+                    emit('"');
+                    continue;
+                }
+                let end = Math.min(frame.index + 8192, frame.value.length);
+                const last = frame.value.charCodeAt(end - 1);
+                const next = frame.value.charCodeAt(end);
+                if (end < frame.value.length &&
+                    last >= 0xd800 &&
+                    last <= 0xdbff &&
+                    next >= 0xdc00 &&
+                    next <= 0xdfff)
+                    end -= 1;
+                emit(JSON.stringify(frame.value.slice(frame.index, end)).slice(1, -1));
+                frame.index = end;
+                stack.push(frame);
+                continue;
+            }
+            let item;
+            if (frame.kind === "array") {
+                if (frame.index === frame.length) {
+                    emit("]");
+                    ancestors.delete(frame.value);
+                    continue;
+                }
+                const element = frame.value[frame.index];
+                if (element === undefined)
+                    throw new TypeError("Canonical JSON digest requires dense JSON arrays");
+                if (frame.index++ > 0)
+                    emit(",");
+                stack.push(frame);
+                item = element;
+            }
+            else if (frame.kind === "object") {
+                if (frame.index === frame.keys.length) {
+                    emit("}");
+                    ancestors.delete(frame.value);
+                    continue;
+                }
+                const key = frame.keys[frame.index++];
+                if (key === undefined)
+                    throw new TypeError("Canonical JSON object changed during hashing");
+                const property = frame.value[key];
+                if (property === undefined) {
+                    stack.push(frame);
+                    continue;
+                }
+                if (frame.written++ > 0)
+                    emit(",");
+                if (key.length > 8192) {
+                    emit('"');
+                    stack.push(frame, { kind: "value", value: property }, { kind: "separator" }, { kind: "string", value: key, index: 0 });
+                    continue;
+                }
+                let encodedKey = encodedKeys.get(key);
+                if (encodedKey === undefined) {
+                    encodedKey = JSON.stringify(key);
+                    if (encodedKey.length <= remainingKeyCodeUnits) {
+                        encodedKeys.set(key, encodedKey);
+                        remainingKeyCodeUnits -= encodedKey.length;
+                    }
+                }
+                emit(encodedKey);
+                emit(":");
+                stack.push(frame);
+                item = property;
+            }
+            else {
+                item = frame.value;
+            }
+            // Resume containers directly; scalar members need no temporary value frame.
+            if (flushed) {
+                flushed = false;
+                yield;
+            }
+            if (typeof item === "string" && item.length > 8192) {
+                emit('"');
+                stack.push({ kind: "string", value: item, index: 0 });
+            }
+            else if (item === null || typeof item !== "object") {
+                if (typeof item === "number" && !Number.isFinite(item))
+                    throw new Error(Number.isNaN(item)
+                        ? "NaN is not allowed"
+                        : "Infinity is not allowed");
+                emit(JSON.stringify(item));
+            }
+            else {
+                if (ancestors.has(item))
+                    throw new Error("Circular reference detected");
+                ancestors.add(item);
+                if (Array.isArray(item)) {
+                    emit("[");
+                    stack.push({
+                        kind: "array",
+                        value: item,
+                        length: item.length,
+                        index: 0,
+                    });
+                }
+                else {
+                    emit("{");
+                    stack.push({
+                        kind: "object",
+                        value: item,
+                        keys: Object.keys(item).sort(),
+                        index: 0,
+                        written: 0,
+                    });
+                }
+            }
+        }
+        if (buffered !== "")
+            hash.update(buffered);
+        return hash.digest("hex");
+    }
+    finally {
+        stack.length = 0;
+        ancestors.clear();
+        encodedKeys.clear();
+        buffered = "";
+    }
+}

package/dist/domain/canonicalOrdering.js

@@ -0,0 +1,3 @@
+import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
+/** Deduplicate and sort strings with canonical code-point ordering. */
+export const uniqueSorted = (values) => [...new Set(values)].sort(compareUnicodeCodePoints);

package/dist/domain/changedBehavior.js

@@ -0,0 +1,282 @@
+import { z } from "zod";
+import { artifactComparisonResultSchema } from "./artifactComparison.js";
+import { uniqueSorted } from "./canonicalOrdering.js";
+import { compositeKey, compareUnicodeCodePoints, } from "./unicodeCodePointOrder.js";
+import { comparisonSourceEvidenceIds } from "./comparisonSourceEvidence.js";
+import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { functionComparisonResultSchema } from "./functionComparisonSchemas.js";
+import { PROCESS_PROVIDER, isProcessEvidenceProvider, } from "./process/processEvidenceProvider.js";
+import { comparisonStatusSchema, deriveProcessComparisonStatus, PROCESS_COMPARISON_DIMENSIONS, processCaptureComparisonSchema, } from "./process/processComparison.js";
+import { prefixedDigestSchema } from "./../domain/digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+/** Input for aggregating existing comparison Evidence. */
+export const changedBehaviorInputSchema = z.strictObject({
+    comparisons: z.array(evidenceSchema).min(1),
+});
+const findingSchema = z.object({
+    scope: z.enum(["runtime", "protocol", "resource", "static_candidate"]),
+    dimension: z.string().min(1),
+    classification: z.enum([
+        "observed_change",
+        "derived_relationship",
+        "contradiction",
+        "unresolved_branch",
+    ]),
+    status: comparisonStatusSchema,
+    source_comparison_id: evidenceIdSchema,
+    evidence_links: z.array(evidenceIdSchema).min(2),
+    limitations: z.array(z.string()),
+});
+/** Truthful aggregate: runtime observations remain separate from static candidates. */
+export const changedBehaviorResultSchema = z
+    .object({
+    behavior_status: z.enum([
+        "observed_changed",
+        "observed_unchanged",
+        "unknown",
+        "truncated",
+    ]),
+    summary: z.object({
+        observed_changes: z.number().int().min(0),
+        static_candidates: z.number().int().min(0),
+        contradictions: z.number().int().min(0),
+        unresolved: z.number().int().min(0),
+    }),
+    findings: z.object({
+        items: z.array(findingSchema),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(2),
+    limitations: z.array(z.string()),
+})
+    .superRefine((result, context) => {
+    const summaryTotal = Object.values(result.summary).reduce((total, count) => total + count, 0);
+    if (summaryTotal !== result.findings.items.length)
+        context.addIssue({
+            code: "custom",
+            message: "Finding classification counts must equal the finding total",
+            path: ["summary"],
+        });
+    if ((result.behavior_status === "observed_changed" &&
+        result.summary.observed_changes === 0) ||
+        (result.behavior_status === "observed_unchanged" &&
+            result.summary.observed_changes > 0))
+        context.addIssue({
+            code: "custom",
+            message: "Observed-change status must agree with runtime findings",
+            path: ["behavior_status"],
+        });
+});
+const EXPECTED_PROVIDERS = {
+    compare_process_captures: {
+        predicates: ["rea.process-comparison"],
+        ...PROCESS_PROVIDER,
+    },
+    compare_artifacts: {
+        predicates: ["rea.artifact-comparison"],
+        id: "rea-artifact-comparison",
+        name: "REA artifact comparison",
+        version: "1",
+    },
+    compare_functions: {
+        predicates: ["rea.function-comparison"],
+        id: "rea-function-comparison",
+        name: "REA function comparison",
+        version: "1",
+    },
+};
+const acceptsPredicate = (expected, actual) => expected.some((predicate) => predicate === actual);
+/** Find observed runtime changes and separately report static change candidates. */
+export const findChangedBehavior = (comparisonsInput) => {
+    const parsedInput = changedBehaviorInputSchema.parse({
+        comparisons: comparisonsInput,
+    });
+    const comparisons = parsedInput.comparisons;
+    const evidence = comparisons.map(parseComparisonEvidence);
+    assertUnique(evidence.map(({ evidence_id: id }) => id), "comparison Evidence");
+    const findings = evidence.flatMap(findingsFor).sort(compareFindings);
+    const runtimeStatuses = evidence.flatMap(runtimeStatus);
+    const links = uniqueSorted(evidence.flatMap((item) => [item.evidence_id, ...item.evidence_links]));
+    return changedBehaviorResultSchema.parse({
+        behavior_status: behaviorStatus(runtimeStatuses),
+        summary: {
+            observed_changes: count(findings, "observed_change"),
+            static_candidates: count(findings, "derived_relationship"),
+            contradictions: count(findings, "contradiction"),
+            unresolved: count(findings, "unresolved_branch"),
+        },
+        findings: {
+            items: findings,
+        },
+        evidence_links: links,
+        limitations: uniqueSorted([
+            ...evidence.flatMap(({ limitations }) => limitations),
+            ...(evidence.some(({ operation }) => operation !== "compare_process_captures")
+                ? [
+                    "Static differences are behavior candidates, not runtime observations.",
+                ]
+                : []),
+            ...(runtimeStatuses.length === 0
+                ? ["No process comparison Evidence was supplied."]
+                : []),
+        ]),
+    });
+};
+const parseComparisonEvidence = (input) => {
+    const evidence = parseEvidence(input);
+    if (!(evidence.operation in EXPECTED_PROVIDERS))
+        throw new TypeError("Changed-behavior analysis requires process, artifact, or function comparison Evidence");
+    const operation = z
+        .enum([
+        "compare_process_captures",
+        "compare_artifacts",
+        "compare_functions",
+    ])
+        .parse(evidence.operation);
+    const expected = EXPECTED_PROVIDERS[operation];
+    if (!acceptsPredicate(expected.predicates, evidence.predicate_type) ||
+        (operation === "compare_process_captures"
+            ? !isProcessEvidenceProvider(evidence.provider)
+            : evidence.provider.id !== expected.id ||
+                evidence.provider.name !== expected.name ||
+                evidence.provider.version !== expected.version) ||
+        evidence.confidence !== "derived" ||
+        evidence.authority !== "analyst-inference" ||
+        evidence.subject !== null)
+        throw new TypeError("Comparison Evidence operation, predicate, and provider disagree");
+    if (!comparisonSourceEvidenceIds(evidence).every((id) => evidence.evidence_links.includes(id)))
+        throw new TypeError("Comparison Evidence must cite both selected source observations");
+    parseResult(evidence);
+    return evidence;
+};
+const parseResult = (evidence) => {
+    if (evidence.operation === "compare_process_captures") {
+        const result = processCaptureComparisonSchema.parse(evidence.normalized_result);
+        const expected = deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => result[dimension]));
+        if (result.status !== expected)
+            throw new TypeError("Process comparison status contradicts its dimensions");
+        return;
+    }
+    if (evidence.operation === "compare_functions") {
+        const result = functionComparisonResultSchema.parse(evidence.normalized_result);
+        assertNestedLinks(evidence, result.dimensions.flatMap(({ evidence_links: links }) => links));
+        return;
+    }
+    const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+    assertNestedLinks(evidence, result.changes.flatMap(({ evidence_links: links }) => links));
+};
+const assertNestedLinks = (evidence, nestedLinks) => {
+    const topLevel = new Set(evidence.evidence_links);
+    if (nestedLinks.some((evidenceId) => !topLevel.has(evidenceId)))
+        throw new TypeError("Comparison finding cites Evidence outside its top-level closure");
+};
+const findingsFor = (evidence) => {
+    if (evidence.operation === "compare_process_captures")
+        return processFindings(evidence);
+    if (evidence.operation === "compare_functions")
+        return functionFindings(evidence);
+    return artifactFindings(evidence);
+};
+const processFindings = (evidence) => {
+    const result = processCaptureComparisonSchema.parse(evidence.normalized_result);
+    const dimensions = [
+        ["terminal", result.terminal, "runtime"],
+        ["interaction", result.interaction, "runtime"],
+        ["exit", result.exit, "runtime"],
+        ["filesystem", result.filesystem, "resource"],
+        ["process", result.process, "runtime"],
+    ];
+    return dimensions.flatMap(([dimension, status, scope]) => status === "unchanged"
+        ? []
+        : [
+            makeFinding({
+                evidence,
+                dimension,
+                scope,
+                status,
+                classification: isChange(status)
+                    ? "observed_change"
+                    : "unresolved_branch",
+                limitations: result.limitations,
+            }),
+        ]);
+};
+const functionFindings = (evidence) => {
+    const result = functionComparisonResultSchema.parse(evidence.normalized_result);
+    return result.dimensions.flatMap((dimension) => dimension.status === "unchanged"
+        ? []
+        : [
+            makeFinding({
+                evidence,
+                dimension: dimension.dimension,
+                scope: "static_candidate",
+                status: dimension.status,
+                classification: dimension.status === "unknown"
+                    ? "unresolved_branch"
+                    : dimension.conclusion_kind,
+                limitations: dimension.limitations,
+                links: dimension.evidence_links,
+            }),
+        ]);
+};
+const artifactFindings = (evidence) => {
+    const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+    const changes = result.changes.map((change) => makeFinding({
+        evidence,
+        dimension: `artifact:${change.logical_path}`,
+        scope: "static_candidate",
+        status: change.classification,
+        classification: change.classification === "contradiction"
+            ? "contradiction"
+            : change.classification === "unknown"
+                ? "unresolved_branch"
+                : "derived_relationship",
+        limitations: result.limitations,
+        links: change.evidence_links,
+    }));
+    return (result.status === "unknown" || result.status === "truncated") &&
+        !changes.some(({ classification }) => classification === "unresolved_branch")
+        ? [
+            ...changes,
+            makeFinding({
+                evidence,
+                dimension: "artifact:coverage",
+                scope: "static_candidate",
+                status: result.status,
+                classification: "unresolved_branch",
+                limitations: result.limitations,
+            }),
+        ]
+        : changes;
+};
+const makeFinding = (input) => findingSchema.parse({
+    scope: input.scope,
+    dimension: input.dimension,
+    classification: input.classification,
+    status: input.status,
+    source_comparison_id: input.evidence.evidence_id,
+    evidence_links: uniqueSorted([
+        input.evidence.evidence_id,
+        ...(input.links ?? input.evidence.evidence_links),
+    ]),
+    limitations: uniqueSorted(input.limitations),
+});
+const runtimeStatus = (evidence) => evidence.operation === "compare_process_captures"
+    ? [processCaptureComparisonSchema.parse(evidence.normalized_result).status]
+    : [];
+const behaviorStatus = (statuses) => {
+    if (statuses.length === 0)
+        return "unknown";
+    if (statuses.includes("truncated"))
+        return "truncated";
+    if (statuses.includes("unknown"))
+        return "unknown";
+    return statuses.some(isChange) ? "observed_changed" : "observed_unchanged";
+};
+const isChange = (status) => status === "added" || status === "removed" || status === "changed";
+const count = (findings, classification) => findings.filter((finding) => finding.classification === classification)
+    .length;
+const compareFindings = (left, right) => compareUnicodeCodePoints(compositeKey([left.scope, left.dimension, left.source_comparison_id]), compositeKey([right.scope, right.dimension, right.source_comparison_id]));
+const assertUnique = (values, label) => {
+    if (new Set(values).size !== values.length)
+        throw new TypeError(`Changed-behavior analysis rejects duplicate ${label}`);
+};

package/dist/domain/compactStringIdentity.js

@@ -0,0 +1,9 @@
+import { digestCanonicalValue } from "./canonicalDigest.js";
+/** Retain short exact string keys or commit their value in a reserved digest namespace. */
+export const compactStringIdentityKey = (value) => {
+    const prefix = "value-sha256:";
+    const digestKey = `${prefix}${digestCanonicalValue(value, "String identity")}`;
+    return value.length <= digestKey.length && !value.startsWith(prefix)
+        ? value
+        : digestKey;
+};

package/dist/domain/comparisonSemantics.js

@@ -0,0 +1,12 @@
+import canonicalize from "canonicalize";
+/** Whether an inventory can support a claim that an item is absent. */
+export const absenceClaimable = (coverage) => coverage.status === "complete" &&
+    coverage.truncated !== true &&
+    (coverage.omitted_count === undefined || coverage.omitted_count === 0);
+/** Canonical JSON used for deterministic tie breaking and stable digests. */
+export const canonicalJson = (value, context = "Comparison") => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError(`${context} could not canonicalize data`);
+    return encoded;
+};

package/dist/domain/comparisonSourceEvidence.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { uniqueSorted } from "./canonicalOrdering.js";
+import { prefixedDigestSchema } from "./digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+const sideParametersSchema = z.object({
+    left_evidence_id: evidenceIdSchema.optional(),
+    right_evidence_id: evidenceIdSchema.optional(),
+    left_evidence_ids: z.array(evidenceIdSchema).min(1).optional(),
+    right_evidence_ids: z.array(evidenceIdSchema).min(1).optional(),
+});
+/** Resolve each selected side and validate aliases and duplicates within that role. */
+export const comparisonSourceEvidenceSides = (evidence) => {
+    const parameters = sideParametersSchema.parse(evidence.parameters);
+    if ((parameters.left_evidence_id === undefined) !==
+        (parameters.right_evidence_id === undefined) ||
+        (parameters.left_evidence_ids === undefined) !==
+            (parameters.right_evidence_ids === undefined))
+        throw new TypeError("Comparison Evidence source representation omitted one side");
+    const side = (single, multiple) => {
+        if (single !== undefined &&
+            multiple !== undefined &&
+            (multiple.length !== 1 || multiple[0] !== single))
+            throw new TypeError("Comparison Evidence source representations disagree");
+        const selected = single === undefined ? (multiple ?? []) : [single];
+        if (selected.length === 0)
+            throw new TypeError("Comparison Evidence omitted its source parameters");
+        if (new Set(selected).size !== selected.length)
+            throw new TypeError("Comparison Evidence repeats a source within one side");
+        return selected;
+    };
+    return {
+        left: side(parameters.left_evidence_id, parameters.left_evidence_ids),
+        right: side(parameters.right_evidence_id, parameters.right_evidence_ids),
+    };
+};
+/** Resolve the source closure without counting observations shared by both roles twice. */
+export const comparisonSourceEvidenceIds = (evidence) => {
+    const sides = comparisonSourceEvidenceSides(evidence);
+    return uniqueSorted([...sides.left, ...sides.right]);
+};

package/dist/domain/comparisonStatus.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/**
+ * Canonical top-level comparison outcome shared by every comparison
+ * pipeline. Pipeline-native detail enums keep their wire schemas, while
+ * shared result contracts use this canonical triple.
+ */
+export const comparisonStatusSchema = z.enum([
+    "unchanged",
+    "changed",
+    "unknown",
+]);