rea-agents 0.2.1 → 0.4.0

package/dist/domain/residualUnknown.js

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const unknownIdSchema = z.string().regex(/^unk_[a-f0-9]{64}$/u);
+const boundedText = z.string().trim().min(1).max(1_000);
+const environmentRequirementSchema = z.object({
+    id: z.string().min(1).max(200).nullable(),
+    platform: z.string().min(1).max(100).nullable(),
+    architecture: z.string().min(1).max(100).nullable(),
+    isolation: z
+        .enum(["none", "process", "container", "virtual-machine"])
+        .nullable(),
+});
+const probeSchema = z.object({
+    operation: z.string().min(1).max(200),
+    rationale: boundedText,
+});
+const relationshipSchema = z.object({
+    type: z.enum(["depends-on", "related-to", "contradicts"]),
+    unknown_id: unknownIdSchema,
+});
+const resolutionSchema = z.discriminatedUnion("disposition", [
+    z.object({
+        disposition: z.literal("verified"),
+        rationale: boundedText,
+        evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    }),
+    z.object({
+        disposition: z.enum(["withdrawn", "out-of-scope"]),
+        rationale: boundedText,
+        evidence_ids: z.array(evidenceIdSchema).max(100),
+    }),
+]);
+/** Strict durable record for one unresolved or evidence-qualified question. */
+const residualUnknownObjectSchema = z.object({
+    registry_version: z.literal(1),
+    unknown_id: unknownIdSchema,
+    revision: z.number().int().min(1),
+    previous_revision_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    revision_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+    scope_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    question: boundedText,
+    status: z.enum([
+        "open",
+        "investigating",
+        "blocked",
+        "contradicted",
+        "resolved",
+    ]),
+    severity: z.enum(["low", "medium", "high", "critical"]),
+    domain: z.string().trim().min(1).max(100),
+    supporting_evidence_ids: z.array(evidenceIdSchema).max(100),
+    contradicting_evidence_ids: z.array(evidenceIdSchema).max(100),
+    required_authority: z
+        .enum([
+        "shipped-artifact",
+        "controlled-replay",
+        "historical-reference",
+        "external-service",
+        "analyst-inference",
+    ])
+        .nullable(),
+    required_confidence: z.enum(["observed", "derived", "inferred"]),
+    required_environment: environmentRequirementSchema.nullable(),
+    recommended_probes: z.array(probeSchema).max(20),
+    relationships: z.array(relationshipSchema).max(100),
+    resolution: resolutionSchema.nullable(),
+    mutation_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+});
+export const residualUnknownSchema = residualUnknownObjectSchema.superRefine((value, context) => {
+    if (computeRevisionDigest(value) !== value.revision_digest)
+        context.addIssue({
+            code: "custom",
+            message: "Residual unknown revision digest does not match",
+            path: ["revision_digest"],
+        });
+    if ((value.revision === 1) !== (value.previous_revision_digest === null))
+        context.addIssue({
+            code: "custom",
+            message: "Only the first revision has no predecessor",
+            path: ["previous_revision_digest"],
+        });
+    if ((value.status === "resolved") !== (value.resolution !== null))
+        context.addIssue({
+            code: "custom",
+            message: "Only resolved unknowns carry a resolution",
+            path: ["resolution"],
+        });
+    if (value.status === "contradicted" &&
+        value.contradicting_evidence_ids.length === 0)
+        context.addIssue({
+            code: "custom",
+            message: "Contradicted status requires contradicting evidence",
+            path: ["contradicting_evidence_ids"],
+        });
+    if (value.relationships.some((relationship) => relationship.unknown_id === value.unknown_id))
+        context.addIssue({
+            code: "custom",
+            message: "An unknown cannot relate to itself",
+            path: ["relationships"],
+        });
+    for (const ids of [
+        value.supporting_evidence_ids,
+        value.contradicting_evidence_ids,
+        value.mutation_evidence_ids,
+    ])
+        if (new Set(ids).size !== ids.length)
+            context.addIssue({
+                code: "custom",
+                message: "Evidence IDs must be unique",
+            });
+    if (value.supporting_evidence_ids.some((id) => value.contradicting_evidence_ids.includes(id)))
+        context.addIssue({
+            code: "custom",
+            message: "Evidence cannot simultaneously support and contradict",
+        });
+    const relationships = value.relationships.map((relationship) => `${relationship.type}:${relationship.unknown_id}`);
+    if (new Set(relationships).size !== relationships.length)
+        context.addIssue({
+            code: "custom",
+            message: "Relationships must be unique",
+            path: ["relationships"],
+        });
+});
+/** Input for deterministic creation of one residual unknown. */
+export const recordUnknownInputSchema = residualUnknownObjectSchema
+    .omit({
+    registry_version: true,
+    unknown_id: true,
+    revision: true,
+    previous_revision_digest: true,
+    revision_digest: true,
+    scope_digest: true,
+    status: true,
+    supporting_evidence_ids: true,
+    contradicting_evidence_ids: true,
+    resolution: true,
+    mutation_evidence_ids: true,
+})
+    .extend({
+    supporting_evidence_ids: z.array(evidenceIdSchema).max(100).default([]),
+    contradicting_evidence_ids: z.array(evidenceIdSchema).max(100).default([]),
+    approved: z.literal(true),
+});
+/** Explicit optimistic-concurrency update command for one unknown. */
+export const updateUnknownInputSchema = z.object({
+    unknown_id: unknownIdSchema,
+    expected_revision: z.number().int().min(1),
+    approved: z.literal(true),
+    status: residualUnknownObjectSchema.shape.status,
+    severity: residualUnknownObjectSchema.shape.severity,
+    supporting_evidence_ids: z.array(evidenceIdSchema).max(100),
+    contradicting_evidence_ids: z.array(evidenceIdSchema).max(100),
+    required_authority: residualUnknownObjectSchema.shape.required_authority,
+    required_confidence: residualUnknownObjectSchema.shape.required_confidence,
+    required_environment: environmentRequirementSchema.nullable(),
+    recommended_probes: z.array(probeSchema).max(20),
+    relationships: z.array(relationshipSchema).max(100),
+    resolution: resolutionSchema.nullable(),
+});
+/** Create stable identity from immutable question and domain fields. */
+export const createResidualUnknown = (input, mutationEvidenceId, scopeDigest) => {
+    const question = input.question.replace(/\s+/gu, " ");
+    const identity = canonicalJson({
+        domain: input.domain,
+        question,
+        scope_digest: scopeDigest,
+    });
+    const revision = {
+        registry_version: 1,
+        unknown_id: `unk_${createHash("sha256").update(identity).digest("hex")}`,
+        revision: 1,
+        previous_revision_digest: null,
+        scope_digest: scopeDigest,
+        question,
+        status: input.contradicting_evidence_ids.length > 0 ? "contradicted" : "open",
+        domain: input.domain,
+        ...projectRevisionDetails(input),
+        resolution: null,
+        mutation_evidence_ids: [mutationEvidenceId],
+    };
+    return residualUnknownSchema.parse({
+        ...revision,
+        revision_digest: computeRevisionDigest(revision),
+    });
+};
+/** Apply a complete, revision-guarded replacement while preserving identity. */
+export const updateResidualUnknown = (current, input, mutationEvidenceId) => {
+    const revision = {
+        registry_version: 1,
+        unknown_id: current.unknown_id,
+        revision: current.revision + 1,
+        previous_revision_digest: current.revision_digest,
+        scope_digest: current.scope_digest,
+        question: current.question,
+        status: input.status,
+        domain: current.domain,
+        ...projectRevisionDetails(input),
+        resolution: input.resolution,
+        mutation_evidence_ids: sortedUnique([
+            ...current.mutation_evidence_ids,
+            mutationEvidenceId,
+        ]),
+    };
+    return residualUnknownSchema.parse({
+        ...revision,
+        revision_digest: computeRevisionDigest(revision),
+    });
+};
+const projectRevisionDetails = (input) => ({
+    severity: input.severity,
+    supporting_evidence_ids: sortedUnique(input.supporting_evidence_ids),
+    contradicting_evidence_ids: sortedUnique(input.contradicting_evidence_ids),
+    required_authority: input.required_authority,
+    required_confidence: input.required_confidence,
+    required_environment: input.required_environment,
+    recommended_probes: [...input.recommended_probes],
+    relationships: sortedRelationships(input.relationships),
+});
+const computeRevisionDigest = (value) => {
+    const { revision_digest: _revisionDigest, ...semantic } = "revision_digest" in value ? value : { ...value, revision_digest: "" };
+    void _revisionDigest;
+    return createHash("sha256").update(canonicalJson(semantic)).digest("hex");
+};
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Unknown identity failed");
+    return serialized;
+};
+const sortedUnique = (values) => [...new Set(values)].sort((left, right) => left.localeCompare(right));
+const sortedRelationships = (values) => [...values].sort((left, right) => `${left.type}:${left.unknown_id}`.localeCompare(`${right.type}:${right.unknown_id}`));

package/dist/domain/staticRuntimeCorrelation.js

@@ -0,0 +1,375 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { artifactComparisonResultSchema } from "./artifactComparison.js";
+import { evidenceSchema, parseEvidence } from "./evidence.js";
+import { functionComparisonResultSchema } from "./functionComparison.js";
+import { comparisonStatusSchema, processCaptureComparisonSchema, } from "./processCapture.js";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const functionDimensionSchema = z.enum([
+    "identity",
+    "pseudocode",
+    "assembly",
+    "comments",
+    "calls",
+    "references",
+    "strings_names",
+    "cfg",
+]);
+const runtimeDimensionSchema = z.enum([
+    "terminal",
+    "exit",
+    "filesystem",
+    "protocol",
+    "process",
+]);
+const expectedPatternSchema = z.enum([
+    "cochanged",
+    "static_only",
+    "runtime_only",
+    "both_unchanged",
+]);
+const observedPatternSchema = z.enum([
+    ...expectedPatternSchema.options,
+    "unknown",
+    "truncated",
+]);
+const artifactSelectorSchema = z
+    .object({
+    kind: z.literal("artifact"),
+    logical_path: z.string().min(1).max(4_096),
+})
+    .strict();
+const functionSelectorSchema = z
+    .object({ kind: z.literal("function"), dimension: functionDimensionSchema })
+    .strict();
+const staticSelectorSchema = z.discriminatedUnion("kind", [
+    artifactSelectorSchema,
+    functionSelectorSchema,
+]);
+const mappingSchema = z
+    .object({
+    static: z
+        .object({
+        comparison_evidence_id: evidenceIdSchema,
+        selector: staticSelectorSchema,
+    })
+        .strict(),
+    runtime: z
+        .object({
+        comparison_evidence_id: evidenceIdSchema,
+        dimension: runtimeDimensionSchema,
+    })
+        .strict(),
+    side_alignment: z.enum(["left_to_left", "left_to_right"]),
+    hypothesis: z
+        .object({
+        statement: z.string().trim().min(1).max(500),
+        expected_pattern: expectedPatternSchema,
+    })
+        .strict(),
+})
+    .strict();
+/** Strict bounded input for explicit static/runtime hypothesis correlation. */
+export const staticRuntimeCorrelationInputSchema = z
+    .object({
+    static_comparisons: z.array(evidenceSchema).min(1).max(100),
+    runtime_comparisons: z.array(evidenceSchema).min(1).max(100),
+    mappings: z.array(mappingSchema).min(1).max(500),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(100).default(100),
+    unknown_registry_approved: z.literal(true).optional(),
+})
+    .strict();
+const correlationItemSchema = z.object({
+    correlation_id: z.string().regex(/^cor_[a-f0-9]{64}$/u),
+    static: z.object({
+        comparison_evidence_id: evidenceIdSchema,
+        selector: staticSelectorSchema,
+        status: comparisonStatusSchema,
+        conclusion_kind: z.enum([
+            "derived_relationship",
+            "contradiction",
+            "unresolved_branch",
+        ]),
+    }),
+    runtime: z.object({
+        comparison_evidence_id: evidenceIdSchema,
+        dimension: runtimeDimensionSchema,
+        status: comparisonStatusSchema,
+    }),
+    side_alignment: z.enum(["left_to_left", "left_to_right"]),
+    hypothesis: z.object({
+        statement: z.string().min(1).max(500),
+        expected_pattern: expectedPatternSchema,
+    }),
+    observed_pattern: observedPatternSchema,
+    classification: z.enum(["hypothesis", "contradiction", "unresolved_branch"]),
+    evidence_links: z.array(evidenceIdSchema).min(2).max(20_100),
+    limitations: z.array(z.string()),
+});
+/** Deterministic, paginated static/runtime correlation payload. */
+export const staticRuntimeCorrelationResultSchema = z.object({
+    status: z.enum(["correlated", "contradicted", "unknown", "truncated"]),
+    summary: z.object({
+        hypotheses: z.number().int().min(0),
+        contradictions: z.number().int().min(0),
+        unresolved: z.number().int().min(0),
+    }),
+    correlations: z.object({
+        items: z.array(correlationItemSchema).max(100),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(100),
+        total: z.number().int().min(0),
+        next_offset: z.number().int().min(0).nullable(),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(2).max(20_100),
+    limitations: z.array(z.string()),
+});
+const EXPECTED = {
+    compare_artifacts: [
+        "rea.artifact-comparison/v1",
+        "rea-artifact-comparison",
+        "REA artifact comparison",
+    ],
+    compare_functions: [
+        "rea.function-comparison/v1",
+        "rea-function-comparison",
+        "REA function comparison",
+    ],
+    compare_process_captures: [
+        "rea.process-comparison/v1",
+        "rea-process",
+        "REA deterministic process harness",
+    ],
+};
+/** Correlate only caller-declared static/runtime hypotheses. */
+export const correlateStaticAndRuntime = (input) => {
+    const parsed = staticRuntimeCorrelationInputSchema.parse(input);
+    const staticEvidence = parsed.static_comparisons.map(parseStatic);
+    const runtimeEvidence = parsed.runtime_comparisons.map(parseRuntime);
+    assertUnique(staticEvidence, "static comparison Evidence");
+    assertUnique(runtimeEvidence, "runtime comparison Evidence");
+    const staticById = byId(staticEvidence);
+    const runtimeById = byId(runtimeEvidence);
+    const correlations = parsed.mappings
+        .map((mapping) => correlate(mapping, staticById, runtimeById))
+        .sort((left, right) => left.correlation_id.localeCompare(right.correlation_id, "en"));
+    if (new Set(correlations.map(({ correlation_id: id }) => id)).size !==
+        correlations.length)
+        throw new TypeError("Static/runtime correlation rejects duplicate mappings");
+    const page = correlations.slice(parsed.offset, parsed.offset + parsed.limit);
+    const links = uniqueSorted(correlations.flatMap(({ evidence_links: evidenceLinks }) => evidenceLinks));
+    if (links.length > 20_100)
+        throw new TypeError("Static/runtime Evidence closure exceeds limit");
+    const unresolved = correlations.filter(({ classification }) => classification === "unresolved_branch");
+    const contradictions = correlations.filter(({ classification }) => classification === "contradiction");
+    return staticRuntimeCorrelationResultSchema.parse({
+        status: correlations.some(({ observed_pattern: pattern }) => pattern === "truncated")
+            ? "truncated"
+            : unresolved.length > 0
+                ? "unknown"
+                : contradictions.length > 0
+                    ? "contradicted"
+                    : "correlated",
+        summary: {
+            hypotheses: correlations.length - contradictions.length - unresolved.length,
+            contradictions: contradictions.length,
+            unresolved: unresolved.length,
+        },
+        correlations: {
+            items: page,
+            offset: parsed.offset,
+            limit: parsed.limit,
+            total: correlations.length,
+            next_offset: parsed.offset + page.length < correlations.length
+                ? parsed.offset + page.length
+                : null,
+        },
+        evidence_links: links,
+        limitations: [
+            "Mappings are caller-declared hypotheses; consistency does not establish causality.",
+            "Only explicit mappings were evaluated; similar unmapped observations were not correlated.",
+        ],
+    });
+};
+const correlate = (mapping, staticById, runtimeById) => {
+    const staticEvidence = required(staticById, mapping.static.comparison_evidence_id, "static comparison");
+    const runtimeEvidence = required(runtimeById, mapping.runtime.comparison_evidence_id, "runtime comparison");
+    const selectedStatic = selectStatic(staticEvidence, mapping.static.selector);
+    const process = processCaptureComparisonSchema.parse(runtimeEvidence.normalized_result);
+    const runtimeStatus = process[mapping.runtime.dimension];
+    const pattern = observedPattern(selectedStatic.status, runtimeStatus);
+    const classification = pattern === "unknown" || pattern === "truncated"
+        ? "unresolved_branch"
+        : pattern === mapping.hypothesis.expected_pattern
+            ? "hypothesis"
+            : "contradiction";
+    const projection = {
+        static: mapping.static,
+        runtime: mapping.runtime,
+        side_alignment: mapping.side_alignment,
+        hypothesis: mapping.hypothesis,
+    };
+    return correlationItemSchema.parse({
+        correlation_id: `cor_${sha256(canonicalJson(projection))}`,
+        static: { ...mapping.static, ...selectedStatic },
+        runtime: { ...mapping.runtime, status: runtimeStatus },
+        side_alignment: mapping.side_alignment,
+        hypothesis: mapping.hypothesis,
+        observed_pattern: pattern,
+        classification,
+        evidence_links: uniqueSorted([
+            staticEvidence.evidence_id,
+            ...staticEvidence.evidence_links,
+            runtimeEvidence.evidence_id,
+            ...runtimeEvidence.evidence_links,
+        ]),
+        limitations: uniqueSorted([
+            ...staticEvidence.limitations,
+            ...runtimeEvidence.limitations,
+            ...process.limitations,
+            "This correlation tests an explicit hypothesis and does not establish causality.",
+            "Side alignment is caller-declared and was not independently validated against source subjects or environments.",
+        ]),
+    });
+};
+const selectStatic = (evidence, selector) => {
+    if (selector.kind === "function") {
+        if (evidence.operation !== "compare_functions")
+            throw new TypeError("Function selector requires function comparison Evidence");
+        const result = functionComparisonResultSchema.parse(evidence.normalized_result);
+        const matches = result.dimensions.filter(({ dimension }) => dimension === selector.dimension);
+        if (matches.length !== 1)
+            throw new TypeError("Function selector must resolve exactly once");
+        return {
+            status: matches[0].status,
+            conclusion_kind: matches[0].conclusion_kind,
+        };
+    }
+    if (evidence.operation !== "compare_artifacts")
+        throw new TypeError("Artifact selector requires artifact comparison Evidence");
+    const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+    if (result.changes.offset !== 0 ||
+        result.changes.next_offset !== null ||
+        result.changes.items.length !== result.changes.total)
+        throw new TypeError("Static/runtime correlation requires complete artifact comparison pagination");
+    const matches = result.changes.items.filter(({ logical_path: path }) => path === selector.logical_path);
+    if (matches.length !== 1)
+        throw new TypeError("Artifact selector must resolve exactly one reported delta");
+    const status = matches[0].classification;
+    return {
+        status,
+        conclusion_kind: status === "unknown" ? "unresolved_branch" : "derived_relationship",
+    };
+};
+const parseStatic = (input) => {
+    const evidence = parseEvidence(input);
+    if (evidence.operation !== "compare_artifacts" &&
+        evidence.operation !== "compare_functions")
+        throw new TypeError("Static/runtime correlation requires artifact or function comparison Evidence");
+    assertComparisonIdentity(evidence);
+    if (evidence.operation === "compare_artifacts") {
+        const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+        assertCompleteArtifactResult(result);
+        assertNestedLinks(evidence, result.changes.items.flatMap(({ evidence_links: links }) => links));
+    }
+    else {
+        const result = functionComparisonResultSchema.parse(evidence.normalized_result);
+        assertNestedLinks(evidence, result.dimensions.flatMap(({ evidence_links: links }) => links));
+    }
+    return evidence;
+};
+const assertNestedLinks = (evidence, nestedLinks) => {
+    const closure = new Set(evidence.evidence_links);
+    if (nestedLinks.some((evidenceId) => !closure.has(evidenceId)))
+        throw new TypeError("Comparison finding cites Evidence outside its top-level closure");
+};
+const parseRuntime = (input) => {
+    const evidence = parseEvidence(input);
+    if (evidence.operation !== "compare_process_captures")
+        throw new TypeError("Static/runtime correlation requires process comparison Evidence");
+    assertComparisonIdentity(evidence);
+    processCaptureComparisonSchema.parse(evidence.normalized_result);
+    return evidence;
+};
+const assertComparisonIdentity = (evidence) => {
+    const expected = EXPECTED[evidence.operation];
+    if (expected === undefined ||
+        evidence.predicate_type !== expected[0] ||
+        evidence.provider.id !== expected[1] ||
+        evidence.provider.name !== expected[2] ||
+        evidence.provider.version !== "1" ||
+        evidence.confidence !== "derived" ||
+        evidence.authority !== "analyst-inference" ||
+        evidence.subject !== null ||
+        evidence.evidence_links.length < 2 ||
+        new Set(evidence.evidence_links).size !== evidence.evidence_links.length)
+        throw new TypeError("Comparison Evidence operation, predicate, provider, or citations disagree");
+    const parameterLinks = comparisonParameterLinks(evidence);
+    if (!sameSet(parameterLinks, evidence.evidence_links))
+        throw new TypeError("Comparison Evidence closure disagrees with its source parameters");
+};
+const comparisonParameterLinks = (evidence) => {
+    if (evidence.operation === "compare_process_captures") {
+        const parameters = z
+            .object({
+            left_evidence_id: evidenceIdSchema,
+            right_evidence_id: evidenceIdSchema,
+        })
+            .passthrough()
+            .parse(evidence.parameters);
+        return [parameters.left_evidence_id, parameters.right_evidence_id];
+    }
+    const parameters = z
+        .object({
+        left_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+        right_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    })
+        .passthrough()
+        .parse(evidence.parameters);
+    return [...parameters.left_evidence_ids, ...parameters.right_evidence_ids];
+};
+const sameSet = (left, right) => left.length === right.length &&
+    new Set(left).size === left.length &&
+    left.every((item) => right.includes(item));
+const assertCompleteArtifactResult = (result) => {
+    if (result.changes.offset !== 0 ||
+        result.changes.next_offset !== null ||
+        result.changes.items.length !== result.changes.total)
+        throw new TypeError("Static/runtime correlation requires complete artifact comparison pagination");
+};
+const observedPattern = (staticStatus, runtimeStatus) => {
+    if (staticStatus === "truncated" || runtimeStatus === "truncated")
+        return "truncated";
+    if (staticStatus === "unknown" || runtimeStatus === "unknown")
+        return "unknown";
+    const staticChanged = staticStatus !== "unchanged";
+    const runtimeChanged = runtimeStatus !== "unchanged";
+    if (staticChanged && runtimeChanged)
+        return "cochanged";
+    if (staticChanged)
+        return "static_only";
+    if (runtimeChanged)
+        return "runtime_only";
+    return "both_unchanged";
+};
+const required = (values, id, label) => {
+    const value = values.get(id);
+    if (value === undefined)
+        throw new TypeError(`Mapping references absent ${label} Evidence`);
+    return value;
+};
+const byId = (evidence) => new Map(evidence.map((item) => [item.evidence_id, item]));
+const assertUnique = (evidence, label) => {
+    if (new Set(evidence.map(({ evidence_id: id }) => id)).size !== evidence.length)
+        throw new TypeError(`Static/runtime correlation rejects duplicate ${label}`);
+};
+const uniqueSorted = (values) => [...new Set(values)].sort((left, right) => left.localeCompare(right, "en"));
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("RFC 8785 canonicalization rejected correlation mapping");
+    return serialized;
+};

package/dist/hopper/BridgeLauncher.js

@@ -5,6 +5,8 @@ import { basename, dirname, extname, join } from "node:path";
 import { promisify } from "node:util";
 import { HopperCancelledError, HopperStartError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
+import { cleanupOwnedProcessGroup, } from "../application/ProcessOwnership.js";
+import writeFileAtomic from "write-file-atomic";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
 /**
@@ -17,8 +19,9 @@ const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
  * supported launcher; callers must treat possible foreground UI as an upstream
  * Hopper constraint, not as evidence that analysis failed.
  *
- * The returned process is the short-lived launcher helper, not the Hopper app,
- * so REA does not claim ownership of the application's lifetime.
+ * REA owns only the short-lived launcher helper's run-token-authenticated
+ * process group. It does not claim ownership of the Hopper GUI process that
+ * macOS LaunchServices may create or reuse.
  */
 export class HopperApplicationLauncher {
     options;
@@ -30,6 +33,7 @@ export class HopperApplicationLauncher {
         const source = [
             `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
             `REA_TOKEN = ${JSON.stringify(session.token)}`,
+            `REA_RUN_ID = ${JSON.stringify(session.runId)}`,
             `exec(compile(open(${JSON.stringify(this.options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(this.options.bridgeScriptPath)}, 'exec'))`,
             "",
         ].join("\n");
@@ -57,6 +61,8 @@ export class HopperApplicationLauncher {
                 return err(new HopperCancelledError());
             const child = spawn(this.options.launcherPath, args, {
                 stdio: ["ignore", "ignore", "pipe"],
+                detached: process.platform !== "win32",
+                env: { ...process.env, REA_PROCESS_RUN_ID: session.runId },
             });
             const started = await new Promise((resolve) => {
                 const onSpawn = () => {
@@ -72,7 +78,38 @@ export class HopperApplicationLauncher {
             });
             if (!started.ok)
                 return started;
-            return ok({ process: child, ownsProcessLifetime: false });
+            const pid = child.pid;
+            if (pid === undefined)
+                return err(new HopperStartError({ cause: new Error("missing launcher PID") }));
+            const ownership = {
+                schema_version: 1,
+                run_id: session.runId,
+                pid,
+                process_group_id: pid,
+                parent_pid: process.pid,
+                launcher: this.options.launcherPath,
+                created_at: new Date().toISOString(),
+            };
+            try {
+                await writeFileAtomic(join(session.directory, "ownership.json"), `${JSON.stringify(ownership)}\n`, { encoding: "utf8", mode: 0o600 });
+            }
+            catch (cause) {
+                await cleanupOwnedProcessGroup({
+                    runId: session.runId,
+                    leaderPid: pid,
+                    processGroupId: pid,
+                });
+                return err(new HopperStartError({ cause }));
+            }
+            return ok({
+                process: child,
+                ownsProcessLifetime: true,
+                cleanup: () => cleanupOwnedProcessGroup({
+                    runId: session.runId,
+                    leaderPid: pid,
+                    processGroupId: pid,
+                }),
+            });
         }
         catch (cause) {
             return err(new HopperStartError({ cause }));