@mortice/mapwright 0.8.0

package/dist/comparison/store.js

@@ -0,0 +1,462 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync, statSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { stableStringify } from "../catalogue/deterministic.js";
+import { COMPARISON_SCHEMA_VERSION, CHANGE_CONTRACT_VERSION, COMPATIBILITY_RULE_VERSION, COMPARISON_IDENTITY_SCHEME, COMPARISON_PROJECTION_VERSION, CANDIDATE_DETECTION_POLICY_VERSION } from "./version.js";
+import { isCanonicalWithinWorkspace, isWithinWorkspace } from "../security/pathPolicy.js";
+import { validateArtefactSemantics } from "./artefactValidate.js";
+export const COMPARISON_OUTPUT_FILES = {
+    comparison: "comparison.json",
+    changes: "changes.json",
+    compatibility: "compatibility.json",
+    impactSummary: "impact-summary.json",
+    graphIndex: "graph-index.json",
+    lock: "comparison.lock.json"
+};
+export const ALLOWED_ARTEFACT_FILENAMES = new Set([
+    COMPARISON_OUTPUT_FILES.comparison,
+    COMPARISON_OUTPUT_FILES.changes,
+    COMPARISON_OUTPUT_FILES.compatibility,
+    COMPARISON_OUTPUT_FILES.impactSummary,
+    COMPARISON_OUTPUT_FILES.graphIndex
+]);
+export const MAX_ARTEFACT_FILE_BYTES = 32 * 1024 * 1024;
+export const MAX_ARTEFACT_TOTAL_BYTES = 96 * 1024 * 1024;
+export const MAX_CHANGE_RECORDS = 500_000;
+export const MAX_COMPAT_FINDINGS = 200_000;
+export const MAX_CANDIDATES = 100_000;
+export const MAX_GRAPH_EDGES = 1_000_000;
+export const defaultArtefactFs = {
+    mkdirSync,
+    writeFileSync: (filePath, content) => writeFileSync(filePath, content, "utf8"),
+    existsSync,
+    renameSync,
+    rmSync
+};
+function sha256Bytes(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function isSafeLockFilename(name) {
+    if (!name || typeof name !== "string")
+        return false;
+    if (name !== path.basename(name))
+        return false;
+    if (name.includes("..") || name.includes("/") || name.includes("\\"))
+        return false;
+    if (/^[a-zA-Z]:/.test(name))
+        return false;
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(name))
+        return false;
+    return ALLOWED_ARTEFACT_FILENAMES.has(name);
+}
+export function assertComparisonPathContained(workspaceRoot, relativeOrAbsolute) {
+    const resolvedWorkspace = path.resolve(workspaceRoot);
+    const resolved = path.isAbsolute(relativeOrAbsolute)
+        ? path.resolve(relativeOrAbsolute)
+        : path.resolve(resolvedWorkspace, relativeOrAbsolute);
+    if (!isWithinWorkspace(resolvedWorkspace, resolved)) {
+        return {
+            code: "comparison_path_rejected",
+            message: "Comparison path escapes declared workspace root."
+        };
+    }
+    if (existsSync(resolved) && !isCanonicalWithinWorkspace(resolvedWorkspace, resolved)) {
+        return {
+            code: "comparison_path_rejected",
+            message: "Comparison path is not canonically within workspace root."
+        };
+    }
+    return null;
+}
+function uniqueSibling(outputRoot, label) {
+    return `${outputRoot}.${label}-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+}
+/**
+ * Transactional / rollback-safe directory replacement.
+ * Not claimed as single-syscall filesystem-atomic across platforms.
+ */
+export function replaceDirectoryTransactionally(outputRoot, tmpRoot, fsImpl = defaultArtefactFs) {
+    const backupRoot = uniqueSibling(outputRoot, "bak");
+    let backedUp = false;
+    try {
+        if (!fsImpl.existsSync(outputRoot)) {
+            fsImpl.renameSync(tmpRoot, outputRoot);
+            return { ok: true };
+        }
+        fsImpl.renameSync(outputRoot, backupRoot);
+        backedUp = true;
+        try {
+            fsImpl.renameSync(tmpRoot, outputRoot);
+        }
+        catch (error) {
+            // Rollback: restore backup
+            try {
+                if (fsImpl.existsSync(outputRoot)) {
+                    fsImpl.rmSync(outputRoot, { recursive: true, force: true });
+                }
+                fsImpl.renameSync(backupRoot, outputRoot);
+                backedUp = false;
+            }
+            catch (rollbackError) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "comparison_artifact_invalid",
+                        message: `Failed to install comparison artefact and rollback failed: ${String(error)}; rollback: ${String(rollbackError)}`
+                    }
+                };
+            }
+            if (fsImpl.existsSync(tmpRoot)) {
+                try {
+                    fsImpl.rmSync(tmpRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            return {
+                ok: false,
+                error: {
+                    code: "comparison_artifact_invalid",
+                    message: `Failed to install comparison artefact; previous artefact restored. ${String(error)}`
+                }
+            };
+        }
+        let cleanupWarning;
+        try {
+            fsImpl.rmSync(backupRoot, { recursive: true, force: true });
+        }
+        catch (cleanupError) {
+            cleanupWarning = `Backup cleanup failed after successful replacement: ${String(cleanupError)}`;
+        }
+        return cleanupWarning ? { ok: true, cleanupWarning } : { ok: true };
+    }
+    catch (error) {
+        if (fsImpl.existsSync(tmpRoot)) {
+            try {
+                fsImpl.rmSync(tmpRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        if (backedUp && fsImpl.existsSync(backupRoot) && !fsImpl.existsSync(outputRoot)) {
+            try {
+                fsImpl.renameSync(backupRoot, outputRoot);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        return {
+            ok: false,
+            error: {
+                code: "comparison_artifact_invalid",
+                message: `Failed transactional artefact replacement: ${String(error)}`
+            }
+        };
+    }
+}
+export function writeComparisonArtefact(outputRoot, comparison, pretty = true, fsImpl = defaultArtefactFs) {
+    const tmpRoot = uniqueSibling(outputRoot, "tmp");
+    try {
+        if (comparison.changes.length > MAX_CHANGE_RECORDS) {
+            return {
+                ok: false,
+                error: {
+                    code: "comparison_artifact_too_large",
+                    message: `Change record count ${comparison.changes.length} exceeds limit.`
+                }
+            };
+        }
+        if (comparison.compatibilityFindings.length > MAX_COMPAT_FINDINGS) {
+            return {
+                ok: false,
+                error: {
+                    code: "comparison_artifact_too_large",
+                    message: `Compatibility finding count exceeds limit.`
+                }
+            };
+        }
+        if (comparison.candidates.length > MAX_CANDIDATES) {
+            return {
+                ok: false,
+                error: {
+                    code: "comparison_artifact_too_large",
+                    message: `Candidate count exceeds limit.`
+                }
+            };
+        }
+        const edgeCount = comparison.graphIndex.base.length + comparison.graphIndex.head.length;
+        if (edgeCount > MAX_GRAPH_EDGES) {
+            return {
+                ok: false,
+                error: {
+                    code: "comparison_artifact_too_large",
+                    message: `Graph edge count ${edgeCount} exceeds limit.`
+                }
+            };
+        }
+        fsImpl.mkdirSync(tmpRoot, { recursive: true });
+        const comparisonJson = stableStringify(comparison.manifest, pretty);
+        const changesJson = stableStringify({ items: comparison.changes }, pretty);
+        const compatibilityJson = stableStringify({
+            aggregate: comparison.manifest.aggregateCompatibility,
+            findings: comparison.compatibilityFindings,
+            candidates: comparison.candidates
+        }, pretty);
+        const impactSummaryJson = stableStringify({
+            note: "Impact is computed from graph-index at query time (Model A).",
+            changeIds: comparison.changes.filter((c) => c.status !== "unchanged").map((c) => c.id)
+        }, pretty);
+        const graphIndexJson = stableStringify(comparison.graphIndex, pretty);
+        const files = {
+            [COMPARISON_OUTPUT_FILES.comparison]: comparisonJson,
+            [COMPARISON_OUTPUT_FILES.changes]: changesJson,
+            [COMPARISON_OUTPUT_FILES.compatibility]: compatibilityJson,
+            [COMPARISON_OUTPUT_FILES.impactSummary]: impactSummaryJson,
+            [COMPARISON_OUTPUT_FILES.graphIndex]: graphIndexJson
+        };
+        let totalBytes = 0;
+        for (const [name, content] of Object.entries(files)) {
+            const bytes = Buffer.byteLength(content, "utf8");
+            totalBytes += bytes;
+            if (bytes > MAX_ARTEFACT_FILE_BYTES) {
+                throw Object.assign(new Error(`Artefact file ${name} too large`), { code: "comparison_artifact_too_large" });
+            }
+            fsImpl.writeFileSync(path.join(tmpRoot, name), content);
+        }
+        if (totalBytes > MAX_ARTEFACT_TOTAL_BYTES) {
+            throw Object.assign(new Error("Total artefact size too large"), { code: "comparison_artifact_too_large" });
+        }
+        const lock = {
+            comparisonSchemaVersion: comparison.manifest.comparisonSchemaVersion,
+            comparisonId: comparison.manifest.comparisonId,
+            baseCatalogueId: comparison.manifest.baseCatalogueId,
+            headCatalogueId: comparison.manifest.headCatalogueId,
+            fileHashes: Object.fromEntries(Object.entries(files).map(([name, content]) => [name, sha256Bytes(content)]))
+        };
+        fsImpl.writeFileSync(path.join(tmpRoot, COMPARISON_OUTPUT_FILES.lock), stableStringify(lock, pretty));
+        return replaceDirectoryTransactionally(outputRoot, tmpRoot, fsImpl);
+    }
+    catch (error) {
+        if (fsImpl.existsSync(tmpRoot)) {
+            try {
+                fsImpl.rmSync(tmpRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "comparison_artifact_invalid";
+        return {
+            ok: false,
+            error: {
+                code: (code === "comparison_artifact_too_large"
+                    ? "comparison_artifact_too_large"
+                    : "comparison_artifact_invalid"),
+                message: `Failed to write comparison artefact: ${String(error)}`
+            }
+        };
+    }
+}
+function validateLoadedComparison(comparison, lockMeta) {
+    const m = comparison.manifest;
+    if (m.comparisonSchemaVersion !== COMPARISON_SCHEMA_VERSION) {
+        return {
+            code: "comparison_schema_unsupported",
+            message: `Unsupported comparisonSchemaVersion ${String(m.comparisonSchemaVersion)}.`
+        };
+    }
+    if (m.changeContractVersion !== CHANGE_CONTRACT_VERSION) {
+        return {
+            code: "comparison_artifact_invalid",
+            message: `Unsupported changeContractVersion ${String(m.changeContractVersion)}.`
+        };
+    }
+    if (m.compatibilityRuleVersion !== COMPATIBILITY_RULE_VERSION) {
+        return {
+            code: "comparison_artifact_invalid",
+            message: `Unsupported compatibilityRuleVersion ${String(m.compatibilityRuleVersion)}.`
+        };
+    }
+    if (m.comparisonIdentityScheme !== COMPARISON_IDENTITY_SCHEME) {
+        return {
+            code: "comparison_identity_scheme_unsupported",
+            message: `Unsupported comparisonIdentityScheme ${String(m.comparisonIdentityScheme)}.`
+        };
+    }
+    if (m.comparisonProjectionVersion !== COMPARISON_PROJECTION_VERSION) {
+        return {
+            code: "comparison_artifact_invalid",
+            message: `Unsupported comparisonProjectionVersion ${String(m.comparisonProjectionVersion)}.`
+        };
+    }
+    if (m.candidateDetectionPolicyVersion !== CANDIDATE_DETECTION_POLICY_VERSION) {
+        return {
+            code: "comparison_artifact_invalid",
+            message: `Unsupported candidateDetectionPolicyVersion ${String(m.candidateDetectionPolicyVersion)}.`
+        };
+    }
+    if (!m.comparisonId || !m.baseCatalogueId || !m.headCatalogueId) {
+        return {
+            code: "comparison_artifact_invalid",
+            message: "Manifest missing comparisonId or catalogue IDs."
+        };
+    }
+    if (!Array.isArray(comparison.changes) || !Array.isArray(comparison.compatibilityFindings)) {
+        return { code: "comparison_artifact_invalid", message: "Changes/findings must be arrays." };
+    }
+    if (!Array.isArray(comparison.candidates)) {
+        return { code: "comparison_artifact_invalid", message: "Candidates must be an array." };
+    }
+    if (!comparison.graphIndex || !Array.isArray(comparison.graphIndex.base) || !Array.isArray(comparison.graphIndex.head)) {
+        return { code: "comparison_artifact_invalid", message: "Malformed graph index." };
+    }
+    const added = comparison.changes.filter((c) => c.status === "added").length;
+    const removed = comparison.changes.filter((c) => c.status === "removed").length;
+    const modified = comparison.changes.filter((c) => c.status === "modified").length;
+    if (m.counts.added !== added ||
+        m.counts.removed !== removed ||
+        m.counts.modified !== modified ||
+        m.counts.compatibilityFindings !== comparison.compatibilityFindings.length ||
+        m.counts.candidates !== comparison.candidates.length) {
+        return {
+            code: "comparison_artifact_invalid",
+            message: "Manifest counts do not match artefact contents."
+        };
+    }
+    return validateArtefactSemantics(comparison, lockMeta);
+}
+export function loadComparisonArtefact(outputRoot) {
+    const requiredContent = [
+        COMPARISON_OUTPUT_FILES.comparison,
+        COMPARISON_OUTPUT_FILES.changes,
+        COMPARISON_OUTPUT_FILES.compatibility,
+        COMPARISON_OUTPUT_FILES.graphIndex,
+        COMPARISON_OUTPUT_FILES.lock
+    ];
+    for (const file of requiredContent) {
+        if (!existsSync(path.join(outputRoot, file))) {
+            return {
+                ok: false,
+                error: {
+                    code: "comparison_artifact_invalid",
+                    message: `Missing required comparison artefact file: ${file}`
+                }
+            };
+        }
+    }
+    try {
+        const lockRaw = readFileSync(path.join(outputRoot, COMPARISON_OUTPUT_FILES.lock), "utf8");
+        if (Buffer.byteLength(lockRaw, "utf8") > MAX_ARTEFACT_FILE_BYTES) {
+            return {
+                ok: false,
+                error: { code: "comparison_artifact_too_large", message: "Lock file exceeds size limit." }
+            };
+        }
+        const lock = JSON.parse(lockRaw);
+        const hashes = lock.fileHashes ?? {};
+        const hashKeys = Object.keys(hashes);
+        for (const key of hashKeys) {
+            if (!isSafeLockFilename(key)) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "comparison_path_rejected",
+                        message: `Lock filename rejected: ${key}`
+                    }
+                };
+            }
+        }
+        for (const required of ALLOWED_ARTEFACT_FILENAMES) {
+            if (!(required in hashes)) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "comparison_artifact_invalid",
+                        message: `Missing required lock hash for ${required}`
+                    }
+                };
+            }
+        }
+        if (hashKeys.length !== ALLOWED_ARTEFACT_FILENAMES.size) {
+            return {
+                ok: false,
+                error: {
+                    code: "comparison_artifact_invalid",
+                    message: "Lock fileHashes must contain exactly the required artefact filenames."
+                }
+            };
+        }
+        let total = 0;
+        for (const file of hashKeys) {
+            const full = path.join(outputRoot, file);
+            const st = statSync(full);
+            total += st.size;
+            if (st.size > MAX_ARTEFACT_FILE_BYTES) {
+                return {
+                    ok: false,
+                    error: { code: "comparison_artifact_too_large", message: `Artefact file ${file} too large.` }
+                };
+            }
+            const actual = sha256Bytes(readFileSync(full, "utf8"));
+            if (actual !== hashes[file]) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "comparison_lock_mismatch",
+                        message: `Hash mismatch for ${file}.`
+                    }
+                };
+            }
+        }
+        if (total > MAX_ARTEFACT_TOTAL_BYTES) {
+            return {
+                ok: false,
+                error: { code: "comparison_artifact_too_large", message: "Total artefact size too large." }
+            };
+        }
+        const manifest = JSON.parse(readFileSync(path.join(outputRoot, COMPARISON_OUTPUT_FILES.comparison), "utf8"));
+        const changes = JSON.parse(readFileSync(path.join(outputRoot, COMPARISON_OUTPUT_FILES.changes), "utf8"));
+        const compatibility = JSON.parse(readFileSync(path.join(outputRoot, COMPARISON_OUTPUT_FILES.compatibility), "utf8"));
+        const graphIndex = JSON.parse(readFileSync(path.join(outputRoot, COMPARISON_OUTPUT_FILES.graphIndex), "utf8"));
+        const comparison = {
+            manifest,
+            changes: changes.items ?? [],
+            compatibilityFindings: compatibility.findings ?? [],
+            candidates: compatibility.candidates ?? [],
+            graphIndex
+        };
+        const validated = validateLoadedComparison(comparison, {
+            comparisonSchemaVersion: lock.comparisonSchemaVersion,
+            comparisonId: lock.comparisonId,
+            baseCatalogueId: lock.baseCatalogueId,
+            headCatalogueId: lock.headCatalogueId
+        });
+        if (validated)
+            return { ok: false, error: validated };
+        return { ok: true, comparison };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_artifact_invalid",
+                message: `Failed to load comparison artefact: ${String(error)}`
+            }
+        };
+    }
+}
+export function removeComparisonArtefact(outputRoot) {
+    if (existsSync(outputRoot)) {
+        rmSync(outputRoot, { recursive: true, force: true });
+    }
+}
+export function listArtefactFiles(outputRoot) {
+    if (!existsSync(outputRoot))
+        return [];
+    return readdirSync(outputRoot);
+}

package/dist/comparison/validate.d.ts

@@ -0,0 +1,23 @@
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+import type { ComparisonError } from "./schema.js";
+export type CataloguePairResult = {
+    ok: true;
+    base: CatalogueSnapshot;
+    head: CatalogueSnapshot;
+    warnings: string[];
+} | {
+    ok: false;
+    error: ComparisonError;
+};
+/**
+ * Load and validate a base/head catalogue pair from committed directories.
+ * Does not index source.
+ */
+export declare function loadCataloguePair(input: {
+    baseWorkspaceRoot: string;
+    baseCatalogueDir: string;
+    headWorkspaceRoot: string;
+    headCatalogueDir: string;
+}): CataloguePairResult;
+/** Validate an in-memory catalogue pair (already loaded snapshots). */
+export declare function validateCataloguePair(base: CatalogueSnapshot, head: CatalogueSnapshot): CataloguePairResult;

package/dist/comparison/validate.js

@@ -0,0 +1,137 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { loadCommittedCatalogue } from "../catalogue/store.js";
+import { isCanonicalWithinWorkspace, isWithinWorkspace } from "../security/pathPolicy.js";
+function mapLoadError(side, result) {
+    const code = result.error.code;
+    if (code === "committed_catalogue_not_found") {
+        return {
+            code: side === "base" ? "comparison_base_not_found" : "comparison_head_not_found",
+            message: result.error.message
+        };
+    }
+    if (code === "catalogue_upgrade_required" || code === "catalogue_schema_unsupported") {
+        return { code: "comparison_schema_unsupported", message: result.error.message };
+    }
+    if (code === "catalogue_identity_scheme_unsupported") {
+        return { code: "comparison_identity_scheme_unsupported", message: result.error.message };
+    }
+    if (code === "catalogue_lock_mismatch") {
+        return { code: "comparison_lock_mismatch", message: result.error.message };
+    }
+    return { code: "comparison_catalogue_invalid", message: result.error.message };
+}
+function assertCatalogueRootContained(workspaceRoot, catalogueDir, side) {
+    const resolvedWorkspace = path.resolve(workspaceRoot);
+    const resolvedCatalogue = path.resolve(resolvedWorkspace, catalogueDir);
+    if (!isWithinWorkspace(resolvedWorkspace, resolvedCatalogue)) {
+        return {
+            code: "comparison_path_rejected",
+            message: `${side} catalogue path escapes workspace root.`
+        };
+    }
+    if (existsSync(resolvedCatalogue) && !isCanonicalWithinWorkspace(resolvedWorkspace, resolvedCatalogue)) {
+        return {
+            code: "comparison_path_rejected",
+            message: `${side} catalogue path is not canonically within workspace root.`
+        };
+    }
+    return null;
+}
+/**
+ * Load and validate a base/head catalogue pair from committed directories.
+ * Does not index source.
+ */
+export function loadCataloguePair(input) {
+    const baseContainment = assertCatalogueRootContained(input.baseWorkspaceRoot, input.baseCatalogueDir, "base");
+    if (baseContainment) {
+        return { ok: false, error: baseContainment };
+    }
+    const headContainment = assertCatalogueRootContained(input.headWorkspaceRoot, input.headCatalogueDir, "head");
+    if (headContainment) {
+        return { ok: false, error: headContainment };
+    }
+    const baseRoot = path.resolve(input.baseWorkspaceRoot, input.baseCatalogueDir);
+    const headRoot = path.resolve(input.headWorkspaceRoot, input.headCatalogueDir);
+    if (!existsSync(baseRoot)) {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_base_not_found",
+                message: `Base catalogue directory not found: ${input.baseCatalogueDir}`
+            }
+        };
+    }
+    if (!existsSync(headRoot)) {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_head_not_found",
+                message: `Head catalogue directory not found: ${input.headCatalogueDir}`
+            }
+        };
+    }
+    const baseLoaded = loadCommittedCatalogue(input.baseWorkspaceRoot, input.baseCatalogueDir);
+    if (!baseLoaded.ok) {
+        return { ok: false, error: mapLoadError("base", baseLoaded) };
+    }
+    const headLoaded = loadCommittedCatalogue(input.headWorkspaceRoot, input.headCatalogueDir);
+    if (!headLoaded.ok) {
+        return { ok: false, error: mapLoadError("head", headLoaded) };
+    }
+    if (baseLoaded.snapshot.identityScheme !== headLoaded.snapshot.identityScheme) {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_identity_scheme_mismatch",
+                message: `Base identityScheme ${baseLoaded.snapshot.identityScheme} does not match head ${headLoaded.snapshot.identityScheme}.`
+            }
+        };
+    }
+    return {
+        ok: true,
+        base: baseLoaded.snapshot,
+        head: headLoaded.snapshot,
+        warnings: [...baseLoaded.warnings, ...headLoaded.warnings]
+    };
+}
+/** Validate an in-memory catalogue pair (already loaded snapshots). */
+export function validateCataloguePair(base, head) {
+    if (base.schemaVersion !== 2 || head.schemaVersion !== 2) {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_schema_unsupported",
+                message: `Unsupported catalogue schemaVersion (base=${base.schemaVersion}, head=${head.schemaVersion}).`
+            }
+        };
+    }
+    if (!base.identityScheme || !head.identityScheme) {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_identity_scheme_unsupported",
+                message: "Catalogue identityScheme is missing."
+            }
+        };
+    }
+    if (base.identityScheme !== head.identityScheme) {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_identity_scheme_mismatch",
+                message: `Base identityScheme ${base.identityScheme} does not match head ${head.identityScheme}.`
+            }
+        };
+    }
+    if (base.identityScheme !== "stable-sha256-v1") {
+        return {
+            ok: false,
+            error: {
+                code: "comparison_identity_scheme_unsupported",
+                message: `Unsupported identityScheme ${base.identityScheme}.`
+            }
+        };
+    }
+    return { ok: true, base, head, warnings: [] };
+}

package/dist/comparison/version.d.ts

@@ -0,0 +1,9 @@
+/** Comparison contract versions for Mortice Mapwright v0.8. */
+export declare const COMPARISON_SCHEMA_VERSION: 1;
+export declare const CHANGE_CONTRACT_VERSION: "1";
+export declare const COMPATIBILITY_RULE_VERSION: "1";
+export declare const COMPARISON_IDENTITY_SCHEME: "comparison-sha256-v1";
+export declare const COMPARISON_PROJECTION_VERSION: "1";
+export declare const CANDIDATE_DETECTION_POLICY_VERSION: "1";
+export declare const COMPARISON_NAMESPACE = "code-atlas-comparison";
+export declare const CHANGE_NAMESPACE = "code-atlas-change";

package/dist/comparison/version.js

@@ -0,0 +1,11 @@
+/** Comparison contract versions for Mortice Mapwright v0.8. */
+export const COMPARISON_SCHEMA_VERSION = 1;
+export const CHANGE_CONTRACT_VERSION = "1";
+export const COMPATIBILITY_RULE_VERSION = "1";
+export const COMPARISON_IDENTITY_SCHEME = "comparison-sha256-v1";
+export const COMPARISON_PROJECTION_VERSION = "1";
+export const CANDIDATE_DETECTION_POLICY_VERSION = "1";
+// FROZEN: namespace strings inherited from the pre-release Code Atlas era.
+// Do not rename — changing them would change every stable comparison/change ID for existing comparisons.
+export const COMPARISON_NAMESPACE = "code-atlas-comparison";
+export const CHANGE_NAMESPACE = "code-atlas-change";

package/dist/extractors/docTags.d.ts

@@ -0,0 +1,9 @@
+import type { CatalogueDocTag, DiagnosticRecord } from "../catalogue/schema.js";
+export interface ParsedDoc {
+    summary: string;
+    tags: CatalogueDocTag[];
+    diagnostics: DiagnosticRecord[];
+}
+export declare function parseDocTags(text: string, filePath: string): ParsedDoc;
+export declare function firstTag(tags: CatalogueDocTag[], name: string): string | undefined;
+export declare function manyTags(tags: CatalogueDocTag[], name: string): string[];