rea-agents 0.3.0 → 0.5.0

package/dist/domain/artifactComparison.js

@@ -0,0 +1,273 @@
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import {} from "./artifactGraph.js";
+import { evidenceSchema } from "./evidence.js";
+import { parseArtifactInventoryEvidence, } from "./artifactInventoryEvidence.js";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const comparisonStatusSchema = z.enum([
+    "unchanged",
+    "added",
+    "removed",
+    "changed",
+    "truncated",
+    "unknown",
+]);
+const changeKindSchema = z.enum(["added", "removed", "changed", "unknown"]);
+const comparisonDimensionSchema = z.enum([
+    "content",
+    "kind",
+    "format",
+    "size",
+    "executable",
+    "relations",
+    "metadata",
+    "availability",
+]);
+/** Strict Evidence-backed input for deterministic artifact comparison. */
+export const artifactComparisonInputSchema = z.object({
+    left: z.union([evidenceSchema, z.array(evidenceSchema).min(1).max(100)]),
+    right: z.union([evidenceSchema, z.array(evidenceSchema).min(1).max(100)]),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(500).default(100),
+    unknown_registry_approved: z
+        .literal(true)
+        .optional()
+        .describe("Explicit approval to record incomplete or differing evidence"),
+});
+/** One path-classified artifact change with citations to both observations. */
+const artifactChangeSchema = z.object({
+    classification: changeKindSchema,
+    logical_path: z.string().min(1).max(4_096),
+    dimensions: z.array(comparisonDimensionSchema).min(1).max(8),
+    left_occurrence_id: z
+        .string()
+        .regex(/^occ_[a-f0-9]{64}$/u)
+        .nullable(),
+    right_occurrence_id: z
+        .string()
+        .regex(/^occ_[a-f0-9]{64}$/u)
+        .nullable(),
+    left_artifact_id: z
+        .string()
+        .regex(/^art_[a-f0-9]{64}$/u)
+        .nullable(),
+    right_artifact_id: z
+        .string()
+        .regex(/^art_[a-f0-9]{64}$/u)
+        .nullable(),
+    evidence_links: z.array(evidenceIdSchema).min(2).max(200),
+});
+/** Bounded deterministic artifact comparison with an independently paged delta. */
+export const artifactComparisonResultSchema = z.object({
+    status: comparisonStatusSchema,
+    left_manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
+    right_manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
+    summary: z.object({
+        unchanged: z.number().int().min(0),
+        added: z.number().int().min(0),
+        removed: z.number().int().min(0),
+        changed: z.number().int().min(0),
+        unknown: z.number().int().min(0),
+    }),
+    changes: z.object({
+        items: z.array(artifactChangeSchema).max(500),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(500),
+        total: z.number().int().min(0),
+        next_offset: z.number().int().min(0).nullable(),
+    }),
+    limitations: z.array(z.string()),
+});
+/** Compare complete inventory pages without treating missing evidence as equality. */
+export const compareArtifacts = (leftEvidence, rightEvidence, offset, limit) => {
+    const left = parseArtifactInventoryEvidence(leftEvidence);
+    const right = parseArtifactInventoryEvidence(rightEvidence);
+    const leftComplete = left.inventory.complete;
+    const rightComplete = right.inventory.complete;
+    const leftCovered = leftComplete && left.inventory.limitations.length === 0;
+    const rightCovered = rightComplete && right.inventory.limitations.length === 0;
+    const limitations = [
+        ...left.inventory.limitations.map((item) => `Left: ${item}`),
+        ...right.inventory.limitations.map((item) => `Right: ${item}`),
+        ...(leftComplete ? [] : ["Left artifact inventory is incomplete."]),
+        ...(rightComplete ? [] : ["Right artifact inventory is incomplete."]),
+    ];
+    const changes = compareOccurrences(left.inventory, right.inventory, [
+        ...left.evidence.map(({ evidence_id: id }) => id),
+        ...right.evidence.map(({ evidence_id: id }) => id),
+    ], leftCovered && rightCovered);
+    const summary = summarize(left.inventory, right.inventory, changes, leftCovered && rightCovered);
+    const page = changes.slice(offset, offset + limit);
+    return artifactComparisonResultSchema.parse({
+        status: !leftComplete || !rightComplete
+            ? "truncated"
+            : !leftCovered || !rightCovered
+                ? "unknown"
+                : changes.some(({ classification }) => classification === "unknown")
+                    ? "unknown"
+                    : changes.length === 0
+                        ? "unchanged"
+                        : "changed",
+        left_manifest_id: left.inventory.manifest.manifest_id,
+        right_manifest_id: right.inventory.manifest.manifest_id,
+        summary,
+        changes: {
+            items: page,
+            offset,
+            limit,
+            total: changes.length,
+            next_offset: offset + page.length < changes.length ? offset + page.length : null,
+        },
+        limitations: [...new Set(limitations)].sort((a, b) => a.localeCompare(b)),
+    });
+};
+const compareOccurrences = (left, right, evidenceLinks, complete) => {
+    const leftByPath = new Map(left.occurrences.map((item) => [item.logical_path, item]));
+    const rightByPath = new Map(right.occurrences.map((item) => [item.logical_path, item]));
+    const leftNodes = new Map(left.nodes.map((item) => [item.artifact_id, item]));
+    const rightNodes = new Map(right.nodes.map((item) => [item.artifact_id, item]));
+    const leftRelations = relationsByPath(left);
+    const rightRelations = relationsByPath(right);
+    const paths = [
+        ...new Set([...leftByPath.keys(), ...rightByPath.keys()]),
+    ].sort((a, b) => a.localeCompare(b, "en"));
+    const output = [];
+    for (const path of paths) {
+        const leftOccurrence = leftByPath.get(path);
+        const rightOccurrence = rightByPath.get(path);
+        const change = classifyPath({
+            path,
+            leftOccurrence,
+            rightOccurrence,
+            leftNode: nodeFor(leftOccurrence, leftNodes),
+            rightNode: nodeFor(rightOccurrence, rightNodes),
+            leftRelations: leftRelations.get(path) ?? [],
+            rightRelations: rightRelations.get(path) ?? [],
+            complete,
+            evidenceLinks,
+        });
+        if (change !== null)
+            output.push(change);
+    }
+    return output;
+};
+const classifyPath = (input) => {
+    const base = {
+        logical_path: input.path,
+        left_occurrence_id: input.leftOccurrence?.occurrence_id ?? null,
+        right_occurrence_id: input.rightOccurrence?.occurrence_id ?? null,
+        left_artifact_id: input.leftOccurrence?.artifact_id ?? null,
+        right_artifact_id: input.rightOccurrence?.artifact_id ?? null,
+        evidence_links: [...input.evidenceLinks],
+    };
+    if (input.leftOccurrence === undefined)
+        return {
+            ...base,
+            classification: input.complete ? "added" : "unknown",
+            dimensions: [input.complete ? "content" : "availability"],
+        };
+    if (input.rightOccurrence === undefined)
+        return {
+            ...base,
+            classification: input.complete ? "removed" : "unknown",
+            dimensions: [input.complete ? "content" : "availability"],
+        };
+    if (input.leftOccurrence.hash_status !== "verified" ||
+        input.rightOccurrence.hash_status !== "verified" ||
+        input.leftNode === undefined ||
+        input.rightNode === undefined)
+        return { ...base, classification: "unknown", dimensions: ["availability"] };
+    const dimensions = changedDimensions(input);
+    return dimensions.length === 0
+        ? null
+        : { ...base, classification: "changed", dimensions };
+};
+const changedDimensions = (input) => {
+    const left = input.leftNode;
+    const right = input.rightNode;
+    if (left === undefined || right === undefined)
+        return ["availability"];
+    const checks = [
+        ["content", left.sha256 !== right.sha256],
+        ["kind", left.kind !== right.kind],
+        ["format", left.format !== right.format],
+        ["size", left.size !== right.size],
+        [
+            "executable",
+            input.leftOccurrence?.executable !== input.rightOccurrence?.executable,
+        ],
+        [
+            "relations",
+            JSON.stringify(input.leftRelations) !==
+                JSON.stringify(input.rightRelations),
+        ],
+        ["metadata", metadataChanged(input, left, right)],
+    ];
+    return checks
+        .filter(([, changed]) => changed)
+        .map(([dimension]) => dimension);
+};
+const metadataChanged = (input, left, right) => left.media_type !== right.media_type ||
+    left.architecture !== right.architecture ||
+    left.executable !== right.executable ||
+    left.content_state !== right.content_state ||
+    input.leftOccurrence?.entry_kind !== input.rightOccurrence?.entry_kind ||
+    input.leftOccurrence?.encrypted !== input.rightOccurrence?.encrypted ||
+    JSON.stringify(left.limitations) !== JSON.stringify(right.limitations) ||
+    JSON.stringify(input.leftOccurrence?.limitations) !==
+        JSON.stringify(input.rightOccurrence?.limitations);
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Artifact comparison could not canonicalize graph data");
+    return encoded;
+};
+const nodeFor = (occurrence, nodes) => occurrence?.artifact_id === null || occurrence?.artifact_id === undefined
+    ? undefined
+    : nodes.get(occurrence.artifact_id);
+const relationsByPath = (inventory) => {
+    const output = new Map();
+    const occurrences = new Map(inventory.occurrences.map((item) => [item.occurrence_id, item]));
+    for (const edge of inventory.edges) {
+        const path = edge.logical_path ?? ".";
+        const values = output.get(path);
+        const occurrence = occurrences.get(edge.occurrence_id);
+        const projection = {
+            parent_logical_path: occurrence?.parent_occurrence_id === null ||
+                occurrence?.parent_occurrence_id === undefined
+                ? null
+                : (occurrences.get(occurrence.parent_occurrence_id)?.logical_path ??
+                    null),
+            child_artifact_id: edge.child_artifact_id,
+            relation: edge.relation,
+            logical_path: edge.logical_path,
+            producer: edge.producer,
+        };
+        if (values === undefined)
+            output.set(path, [projection]);
+        else
+            values.push(projection);
+    }
+    for (const values of output.values())
+        values.sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)));
+    return output;
+};
+const summarize = (left, right, changes, covered) => {
+    const counts = { added: 0, removed: 0, changed: 0, unknown: 0 };
+    for (const change of changes)
+        counts[change.classification] += 1;
+    return {
+        unchanged: covered
+            ? Math.max(0, Math.min(left.occurrences.length, right.occurrences.length) -
+                counts.changed -
+                counts.unknown)
+            : 0,
+        ...counts,
+        unknown: covered
+            ? counts.unknown
+            : Math.max(counts.unknown, Math.max(left.manifest.occurrence_count, right.manifest.occurrence_count) -
+                counts.added -
+                counts.removed -
+                counts.changed),
+    };
+};

package/dist/domain/artifactGraph.js

@@ -0,0 +1,194 @@
+import { z } from "zod";
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
+const artifactIdSchema = z.string().regex(/^art_[a-f0-9]{64}$/u);
+const occurrenceIdSchema = z.string().regex(/^occ_[a-f0-9]{64}$/u);
+const edgeIdSchema = z.string().regex(/^edge_[a-f0-9]{64}$/u);
+const manifestIdSchema = z.string().regex(/^agm_[a-f0-9]{64}$/u);
+const extractionIdSchema = z.string().regex(/^aex_[a-f0-9]{64}$/u);
+const boundedRelativePathSchema = z
+    .string()
+    .min(1)
+    .max(4_096)
+    .refine((path) => !path.startsWith("/") &&
+    !path.includes("\\") &&
+    path.split("/").every((part) => part !== "" && part !== ".."), "Expected a normalized relative POSIX path without traversal");
+/** Closed artifact categories used to traverse application containers. */
+const artifactKindSchema = z.enum([
+    "container",
+    "executable",
+    "dynamic-library",
+    "framework",
+    "native-addon",
+    "javascript",
+    "source-map",
+    "plist",
+    "entitlements",
+    "resource",
+    "universal-slice",
+    "package-metadata",
+    "unknown",
+]);
+/** Recognized storage or application formats; unknown bytes remain explicit. */
+const artifactFormatSchema = z.enum([
+    "dmg",
+    "zip",
+    "pkg",
+    "asar",
+    "javascript-bundle",
+    "source-map",
+    "mach-o-universal",
+    "mach-o",
+    "elf",
+    "pe",
+    "hopper",
+    "ipa",
+    "apk",
+    "plist",
+    "entitlements",
+    "directory",
+    "file",
+    "unknown",
+]);
+/** Exact bounded policy applied while discovering or extracting artifacts. */
+const artifactTraversalLimitsSchema = z.object({
+    max_entries: z.number().int().min(1).max(1_000_000),
+    max_total_bytes: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+    max_entry_bytes: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+    max_compression_ratio: z.number().min(1).max(100_000),
+    max_depth: z.number().int().min(0).max(100),
+    max_path_bytes: z.number().int().min(1).max(65_535),
+});
+/** File byte interval for an artifact derived without writing it to disk. */
+const artifactByteRangeSchema = z.object({
+    offset: z.number().int().min(0),
+    length: z.number().int().min(0),
+});
+/** Bounded external command provenance, including observable side effects. */
+const artifactCommandSchema = z.object({
+    tool: z.string().min(1),
+    arguments: z.array(z.string().max(4_096)).max(1_024),
+    tool_version: z.string().nullable(),
+    executable_sha256: sha256Schema.nullable(),
+    exit_code: z.number().int().nullable(),
+    effects: z.array(z.enum(["read", "write", "mount"])).max(3),
+});
+/** One content-addressed application artifact in deterministic manifest order. */
+const artifactNodeSchema = z.object({
+    artifact_id: artifactIdSchema,
+    kind: artifactKindSchema,
+    format: artifactFormatSchema,
+    sha256: sha256Schema,
+    size: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    media_type: z.string().min(1).nullable(),
+    architecture: z.string().min(1).nullable(),
+    executable: z.boolean(),
+    content_state: z.enum(["materialized", "embedded", "virtual"]),
+    limitations: z.array(z.string()),
+});
+/** One path or virtual location where an artifact occurs in its parent. */
+const artifactOccurrenceSchema = z.object({
+    occurrence_id: occurrenceIdSchema,
+    artifact_id: artifactIdSchema.nullable(),
+    parent_occurrence_id: occurrenceIdSchema.nullable(),
+    logical_path: boundedRelativePathSchema,
+    entry_kind: z.enum(["file", "directory", "symlink", "slice"]),
+    declared_size: z
+        .number()
+        .int()
+        .min(0)
+        .max(Number.MAX_SAFE_INTEGER)
+        .nullable(),
+    compressed_size: z
+        .number()
+        .int()
+        .min(0)
+        .max(Number.MAX_SAFE_INTEGER)
+        .nullable(),
+    executable: z.boolean(),
+    encrypted: z.boolean(),
+    hash_status: z.enum(["verified", "not-hashed-limit", "unavailable"]),
+    source_location: artifactByteRangeSchema.nullable(),
+    limitations: z.array(z.string()),
+});
+/** Parent-child derivation relation between two content-addressed artifacts. */
+const artifactEdgeSchema = z.object({
+    edge_id: edgeIdSchema,
+    ordinal: z.number().int().min(0),
+    parent_artifact_id: artifactIdSchema,
+    child_artifact_id: artifactIdSchema,
+    relation: z.enum([
+        "contains",
+        "extracts",
+        "slice-of",
+        "embeds",
+        "loads",
+        "maps-source",
+        "derived-from",
+    ]),
+    occurrence_id: occurrenceIdSchema,
+    logical_path: boundedRelativePathSchema.nullable(),
+    producer: artifactCommandSchema.nullable(),
+});
+/** Stable cryptographic commitment and counts for a complete artifact graph. */
+const artifactGraphManifestSchema = z.object({
+    schema_version: z.literal(1),
+    manifest_id: manifestIdSchema,
+    root_artifact_id: artifactIdSchema,
+    root_sha256: sha256Schema,
+    root_format: artifactFormatSchema,
+    graph_sha256: sha256Schema,
+    node_count: z.number().int().min(1),
+    occurrence_count: z.number().int().min(1),
+    edge_count: z.number().int().min(0),
+});
+/** Independently bounded offset page used for deterministic graph traversal. */
+const artifactPageSchema = (item) => z.object({
+    items: z.array(item).max(500),
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(500),
+    total: z.number().int().min(0),
+    next_offset: z.number().int().min(0).nullable(),
+});
+/** Inventory observation containing stable manifest identity and bounded pages. */
+export const artifactInventoryResultSchema = z.object({
+    manifest: artifactGraphManifestSchema,
+    nodes: artifactPageSchema(artifactNodeSchema),
+    occurrences: artifactPageSchema(artifactOccurrenceSchema),
+    edges: artifactPageSchema(artifactEdgeSchema),
+    limits: artifactTraversalLimitsSchema,
+    provenance: z.array(artifactCommandSchema).max(256),
+    limitations: z.array(z.string()),
+});
+/** One safely materialized artifact beneath caller-approved output root. */
+const extractedArtifactSchema = z.object({
+    artifact_id: artifactIdSchema,
+    relative_path: boundedRelativePathSchema,
+    sha256: sha256Schema,
+    bytes_written: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    created: z.boolean(),
+});
+/** Path-independent commitment to one selected extraction operation. */
+const artifactExtractionManifestSchema = z.object({
+    schema_version: z.literal(1),
+    extraction_id: extractionIdSchema,
+    source_manifest_id: manifestIdSchema,
+    selected_occurrence_ids: z.array(occurrenceIdSchema).min(1).max(500),
+    files_sha256: sha256Schema,
+    output_root_alias: z.literal("$OUTPUT_ROOT"),
+});
+/** Safe extraction observation with containment and cleanup verification. */
+export const artifactExtractionResultSchema = z.object({
+    manifest: artifactGraphManifestSchema,
+    extraction_manifest: artifactExtractionManifestSchema,
+    output_root: z.string().min(1),
+    artifacts: artifactPageSchema(extractedArtifactSchema),
+    containment_verified: z.boolean(),
+    cleanup: z.object({
+        attempted: z.boolean(),
+        verified: z.boolean(),
+        residual_paths: z.array(boundedRelativePathSchema).max(500),
+    }),
+    limits: artifactTraversalLimitsSchema,
+    provenance: z.array(artifactCommandSchema).max(256),
+    limitations: z.array(z.string()),
+});

package/dist/domain/artifactInventoryEvidence.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { artifactInventoryResultSchema, } from "./artifactGraph.js";
+import { parseEvidence } from "./evidence.js";
+/** Parse, merge, and verify a bounded set of inventory Evidence pages. */
+export const parseArtifactInventoryEvidence = (input) => assembleInventorySet((Array.isArray(input) ? input : [input]).map((value) => {
+    const evidence = parseEvidence(value);
+    if (evidence.operation !== "inventory_artifact")
+        throw new TypeError("Artifact comparison requires inventory_artifact Evidence");
+    const inventory = artifactInventoryResultSchema.parse(evidence.normalized_result);
+    if (evidence.subject === null ||
+        evidence.subject.digest.sha256 !== inventory.manifest.root_sha256 ||
+        evidence.subject.format !== inventory.manifest.root_format)
+        throw new TypeError("Artifact inventory Evidence subject does not match its root digest");
+    validateInventoryPage(inventory);
+    return { evidence, inventory };
+}));
+const validateInventoryPage = (inventory) => {
+    assertUnique(inventory.nodes.items.map(({ artifact_id: id }) => id), "node ID");
+    assertUnique(inventory.occurrences.items.map(({ occurrence_id: id }) => id), "occurrence ID");
+    assertUnique(inventory.occurrences.items.map(({ logical_path: path }) => path), "logical path");
+    assertUnique(inventory.edges.items.map(({ edge_id: id }) => id), "edge ID");
+    for (const node of inventory.nodes.items)
+        if (node.artifact_id !==
+            `art_${digestCanonical({ schema_version: 1, sha256: node.sha256 })}`)
+            throw new TypeError("Artifact node ID is not content-addressed");
+};
+const assembleInventorySet = (pages) => {
+    if (pages.length === 0 || pages.length > 100)
+        throw new TypeError("Artifact comparison requires 1 to 100 Evidence pages");
+    const first = pages[0];
+    if (first === undefined)
+        throw new TypeError("Artifact comparison requires Evidence pages");
+    const manifestJson = canonicalJson(first.inventory.manifest);
+    const nodes = new Map();
+    const occurrences = new Map();
+    const paths = new Map();
+    const edges = new Map();
+    for (const page of pages) {
+        if (canonicalJson(page.inventory.manifest) !== manifestJson)
+            throw new TypeError("Artifact inventory pages do not share one manifest");
+        for (const node of page.inventory.nodes.items)
+            mergeExact(nodes, node.artifact_id, node, "node");
+        for (const occurrence of page.inventory.occurrences.items) {
+            mergeExact(occurrences, occurrence.occurrence_id, occurrence, "occurrence");
+            mergeExact(paths, occurrence.logical_path, occurrence, "logical path");
+        }
+        for (const edge of page.inventory.edges.items)
+            mergeExact(edges, edge.edge_id, edge, "edge");
+    }
+    const inventory = orderedInventory(first.inventory, pages, {
+        nodes,
+        occurrences,
+        edges,
+    });
+    if (inventory.complete)
+        validateCompleteInventory(inventory);
+    return { evidence: pages.map(({ evidence }) => evidence), inventory };
+};
+const orderedInventory = (first, pages, values) => {
+    const nodes = [...values.nodes.values()].sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
+    const occurrences = [...values.occurrences.values()].sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
+    const edges = [...values.edges.values()].sort((left, right) => left.edge_id.localeCompare(right.edge_id));
+    return {
+        manifest: first.manifest,
+        nodes,
+        occurrences,
+        edges,
+        limitations: [
+            ...new Set(pages.flatMap(({ inventory }) => inventory.limitations)),
+        ].sort((left, right) => left.localeCompare(right)),
+        complete: nodes.length === first.manifest.node_count &&
+            occurrences.length === first.manifest.occurrence_count &&
+            edges.length === first.manifest.edge_count,
+    };
+};
+const validateCompleteInventory = (inventory) => {
+    const nodeIds = new Set(inventory.nodes.map(({ artifact_id: id }) => id));
+    const occurrenceIds = new Set(inventory.occurrences.map(({ occurrence_id: id }) => id));
+    const rootNode = inventory.nodes.find(({ artifact_id: id }) => id === inventory.manifest.root_artifact_id);
+    if (rootNode?.sha256 !== inventory.manifest.root_sha256)
+        throw new TypeError("Artifact root node does not match its manifest digest");
+    for (const occurrence of inventory.occurrences)
+        validateOccurrence(occurrence, inventory, nodeIds, occurrenceIds);
+    for (const edge of inventory.edges)
+        validateEdge(edge, nodeIds, occurrenceIds);
+    const graphSha256 = digestCanonical({
+        nodes: inventory.nodes,
+        occurrences: inventory.occurrences,
+        edges: inventory.edges,
+    });
+    if (graphSha256 !== inventory.manifest.graph_sha256)
+        throw new TypeError("Artifact graph commitment does not match its members");
+    const manifestId = `agm_${digestCanonical({
+        schema_version: 1,
+        root_artifact_id: inventory.manifest.root_artifact_id,
+        graph_sha256: graphSha256,
+    })}`;
+    if (manifestId !== inventory.manifest.manifest_id)
+        throw new TypeError("Artifact manifest ID does not match its commitment");
+};
+const validateOccurrence = (occurrence, inventory, nodeIds, occurrenceIds) => {
+    if (occurrence.artifact_id !== null && !nodeIds.has(occurrence.artifact_id))
+        throw new TypeError("Artifact occurrence references a missing node");
+    if (occurrence.parent_occurrence_id !== null &&
+        !occurrenceIds.has(occurrence.parent_occurrence_id))
+        throw new TypeError("Artifact occurrence references a missing parent");
+    const expectedId = occurrence.logical_path === "."
+        ? `occ_${digestCanonical({ root: inventory.manifest.root_artifact_id })}`
+        : `occ_${digestCanonical({
+            root_artifact_id: inventory.manifest.root_artifact_id,
+            logical_path: occurrence.logical_path,
+            entry_kind: occurrence.entry_kind,
+        })}`;
+    if (occurrence.occurrence_id !== expectedId)
+        throw new TypeError("Artifact occurrence ID does not match its identity");
+};
+const validateEdge = (edge, nodeIds, occurrenceIds) => {
+    if (!nodeIds.has(edge.parent_artifact_id) ||
+        !nodeIds.has(edge.child_artifact_id) ||
+        !occurrenceIds.has(edge.occurrence_id))
+        throw new TypeError("Artifact edge references a missing graph member");
+    const semantic = {
+        parent_artifact_id: edge.parent_artifact_id,
+        child_artifact_id: edge.child_artifact_id,
+        relation: edge.relation,
+        occurrence_id: edge.occurrence_id,
+        logical_path: edge.logical_path,
+    };
+    if (edge.edge_id !== `edge_${digestCanonical(semantic)}`)
+        throw new TypeError("Artifact edge ID does not match its identity");
+};
+const mergeExact = (output, key, value, label) => {
+    const previous = output.get(key);
+    if (previous !== undefined &&
+        canonicalJson(previous) !== canonicalJson(value))
+        throw new TypeError(`Artifact inventory has conflicting ${label} pages`);
+    output.set(key, value);
+};
+const assertUnique = (values, label) => {
+    if (new Set(values).size !== values.length)
+        throw new TypeError(`Artifact inventory contains a duplicate ${label}`);
+};
+const digestCanonical = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Artifact inventory could not canonicalize graph data");
+    return encoded;
+};