@tea-agent/loop-agent 0.16.26 → 0.17.1

package/dist/task/contract/apply.js

@@ -0,0 +1,326 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { CANONICALIZER_VERSION, PROJECTION_VERSION, TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
+import { diffDraftAgainstCurrent } from "./diff.js";
+import { computeCanonicalHash, computeSourceHashes, computeTaskConfigSha256, sha256Utf8, } from "./hash.js";
+import { acquireTaskContractLock, assertLockHeld } from "./lock.js";
+import { loadObservedTaskBytes, logicalRevisionForState, observeTaskContractState, readStoredContractRef, } from "./observe.js";
+import { mergeManagedTaskConfigFields, projectConstraintsMarkdown, projectRequirementMarkdown, serializeTaskConfigForDisk, } from "./project.js";
+import { appendRequestLedgerEntry, findRequestLedgerEntry, } from "./request-ledger.js";
+import { parseTaskContractDraft, validateDraftBusinessRules, } from "./schema.js";
+import { finalizeTransaction, runJournaledContractCommit, } from "./transaction.js";
+import { getTaskPaths, parseTaskConfigForRuntime } from "../runtime.js";
+import { getSourceManifestPath, readSourceManifest, } from "../source-references.js";
+export class ContractMutationError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ContractMutationError";
+        this.code = code;
+        this.details = details;
+    }
+}
+export async function loadDraftFromPath(inputPath, repoRoot) {
+    const absolute = path.isAbsolute(inputPath)
+        ? inputPath
+        : path.resolve(repoRoot, inputPath);
+    let rawText;
+    try {
+        rawText = await readFile(absolute, "utf-8");
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new ContractMutationError("NOT_FOUND", `draft input not found: ${absolute}`);
+        }
+        throw error;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(rawText);
+    }
+    catch (error) {
+        throw new ContractMutationError("INVALID_INPUT", `draft is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let draft;
+    try {
+        draft = parseTaskContractDraft(raw);
+    }
+    catch (error) {
+        throw new ContractMutationError("INVALID_INPUT", `draft schema validation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const businessErrors = validateDraftBusinessRules(draft);
+    if (businessErrors.length > 0) {
+        throw new ContractMutationError("INVALID_INPUT", businessErrors.join("; "));
+    }
+    return {
+        draft,
+        payloadSha256: sha256Utf8(rawText),
+        rawText,
+    };
+}
+export async function validateDraftForTask(input) {
+    const errors = [];
+    const warnings = [];
+    if (input.draft.taskId !== input.taskId) {
+        errors.push(`draft.taskId "${input.draft.taskId}" does not match --task "${input.taskId}"`);
+    }
+    const paths = getTaskPaths(input.repoRoot, input.taskId);
+    try {
+        await readFile(paths.taskConfigPath, "utf-8");
+    }
+    catch {
+        errors.push(`task not found: ${input.taskId}`);
+    }
+    // apply must not rewrite reference bytes; only verify manifest if present.
+    const manifest = await readSourceManifest(paths.sourceDir);
+    if (manifest && input.draft.references) {
+        for (const ref of input.draft.references) {
+            const found = manifest.documents.some((doc) => doc.materializedPath === ref.ref ||
+                doc.materializedPath.endsWith(ref.ref) ||
+                ref.ref.endsWith(doc.materializedPath));
+            if (!found && ref.ref.includes("references/")) {
+                warnings.push(`draft reference "${ref.ref}" not found in source-manifest.json (apply will not create it)`);
+            }
+        }
+    }
+    const business = validateDraftBusinessRules(input.draft);
+    errors.push(...business);
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, warnings };
+}
+export async function diffTaskContract(input) {
+    const state = await observeTaskContractState(input.repoRoot, input.taskId);
+    const bytes = await loadObservedTaskBytes(input.repoRoot, input.taskId);
+    let currentConfig = null;
+    if (bytes.taskConfigRaw) {
+        currentConfig = parseTaskConfigForRuntime(bytes.taskConfigRaw);
+    }
+    const projectedReq = projectRequirementMarkdown(input.draft);
+    const projectedConstraints = projectConstraintsMarkdown(input.draft);
+    return diffDraftAgainstCurrent({
+        taskId: input.taskId,
+        draft: input.draft,
+        currentConfig,
+        currentStatus: state.effectiveStatus,
+        currentRevision: logicalRevisionForState(state),
+        requirementChanged: projectedReq !== (bytes.requirementBytes ?? ""),
+        constraintsChanged: projectedConstraints !== (bytes.constraintsBytes ?? ""),
+    });
+}
+function emptyObservedHashPlaceholder() {
+    // For legacy revision 0 with incomplete files, clients may pass a sentinel.
+    // Empty string is invalid; we accept "0".repeat(64) as "no observed content".
+    return "0".repeat(64);
+}
+export async function applyTaskContract(input) {
+    const validation = await validateDraftForTask({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+        draft: input.draft,
+    });
+    if (!validation.ok) {
+        throw new ContractMutationError("INVALID_INPUT", validation.errors.join("; "));
+    }
+    // Idempotency pre-check (before lock is fine for read; re-check under lock).
+    const existing = await findRequestLedgerEntry({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+        requestId: input.requestId,
+    });
+    if (existing) {
+        if (existing.requestPayloadSha256 !== input.requestPayloadSha256) {
+            throw new ContractMutationError("REQUEST_ID_REUSE_CONFLICT", `requestId ${input.requestId} was used with a different payload hash`, {
+                previousPayloadSha256: existing.requestPayloadSha256,
+                newPayloadSha256: input.requestPayloadSha256,
+            });
+        }
+        const ref = await readStoredContractRef(getTaskPaths(input.repoRoot, input.taskId).contractPath);
+        if (!ref) {
+            throw new ContractMutationError("OPERATION_NEEDS_RECONCILE", "request ledger hit but contract.json missing");
+        }
+        return {
+            ref,
+            changedFiles: [],
+            idempotentReplay: true,
+            txId: existing.txId,
+        };
+    }
+    const lock = await acquireTaskContractLock({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+        requestId: input.requestId,
+        operation: "contract-apply",
+    });
+    try {
+        // Re-check ledger under lock
+        const existingUnderLock = await findRequestLedgerEntry({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            requestId: input.requestId,
+        });
+        if (existingUnderLock) {
+            if (existingUnderLock.requestPayloadSha256 !== input.requestPayloadSha256) {
+                throw new ContractMutationError("REQUEST_ID_REUSE_CONFLICT", `requestId ${input.requestId} was used with a different payload hash`);
+            }
+            const ref = await readStoredContractRef(getTaskPaths(input.repoRoot, input.taskId).contractPath);
+            if (!ref) {
+                throw new ContractMutationError("OPERATION_NEEDS_RECONCILE", "request ledger hit but contract.json missing");
+            }
+            return {
+                ref,
+                changedFiles: [],
+                idempotentReplay: true,
+                txId: existingUnderLock.txId,
+            };
+        }
+        const state = await observeTaskContractState(input.repoRoot, input.taskId);
+        if (state.effectiveStatus === "transaction-incomplete") {
+            throw new ContractMutationError("TRANSACTION_INCOMPLETE", "unfinished transaction; run task contract recover first", { errors: state.observationErrors });
+        }
+        const currentRevision = logicalRevisionForState(state);
+        if (input.expectedRevision !== currentRevision) {
+            throw new ContractMutationError("REVISION_CONFLICT", `expectedRevision ${input.expectedRevision} does not match current ${currentRevision}`, { currentRevision, expectedRevision: input.expectedRevision });
+        }
+        const observedHash = state.observedCanonicalHash ??
+            (currentRevision === 0 ? emptyObservedHashPlaceholder() : null);
+        if (!observedHash) {
+            throw new ContractMutationError("OBSERVED_HASH_CONFLICT", "unable to observe current canonical hash");
+        }
+        // Allow all-zero hash only for revision 0 incomplete observe
+        const expected = input.expectedObservedHash;
+        if (expected !== observedHash) {
+            // If client passes zero hash at rev0 and we also have no hash, accept when both zero
+            if (!(currentRevision === 0 &&
+                expected === emptyObservedHashPlaceholder() &&
+                (observedHash === emptyObservedHashPlaceholder() ||
+                    !state.observedCanonicalHash))) {
+                // For rev0 when files exist, observedHash is real — must match.
+                if (state.observedCanonicalHash) {
+                    throw new ContractMutationError("OBSERVED_HASH_CONFLICT", `expectedObservedHash does not match current observed hash`, {
+                        expectedObservedHash: expected,
+                        observedCanonicalHash: state.observedCanonicalHash,
+                    });
+                }
+                if (expected !== emptyObservedHashPlaceholder()) {
+                    throw new ContractMutationError("OBSERVED_HASH_CONFLICT", `expectedObservedHash does not match current observed hash`, {
+                        expectedObservedHash: expected,
+                        observedCanonicalHash: observedHash,
+                    });
+                }
+            }
+        }
+        if (state.effectiveStatus === "externally-modified" &&
+            state.ref &&
+            input.expectedRevision === state.ref.revision) {
+            // Caller must pass the *observed* hash (drift) and matching revision to repair via apply.
+            // If they pass the stale ref.canonicalHash, reject.
+            if (expected === state.ref.canonicalHash) {
+                throw new ContractMutationError("EXTERNALLY_MODIFIED", "task is externally-modified; pass expectedObservedHash of current on-disk facts (not stale contract hash), or use adopt");
+            }
+        }
+        const bytes = await loadObservedTaskBytes(input.repoRoot, input.taskId);
+        if (!bytes.taskConfigRaw) {
+            throw new ContractMutationError("NOT_FOUND", `task.json missing for ${input.taskId}`);
+        }
+        const currentConfig = parseTaskConfigForRuntime(bytes.taskConfigRaw);
+        const mergedConfig = mergeManagedTaskConfigFields(currentConfig, input.draft);
+        // Re-parse through schema to ensure full TaskConfig shape for hash stability
+        const fullConfig = parseTaskConfigForRuntime(mergedConfig);
+        const taskConfigContent = serializeTaskConfigForDisk(fullConfig);
+        const requirementContent = projectRequirementMarkdown(input.draft);
+        const constraintsContent = projectConstraintsMarkdown(input.draft);
+        // Validate references manifest hash if present (do not modify)
+        const paths = getTaskPaths(input.repoRoot, input.taskId);
+        const manifestText = await readFile(getSourceManifestPath(paths.sourceDir), "utf-8").catch(() => null);
+        const sourceHashes = computeSourceHashes({
+            requirementBytes: requirementContent,
+            constraintsBytes: constraintsContent,
+            referenceManifestBytes: manifestText,
+        });
+        const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
+        const canonicalHash = computeCanonicalHash({
+            sourceHashes,
+            taskConfigSha256,
+        });
+        const nextRevision = currentRevision + 1;
+        const nextRef = {
+            schemaVersion: TASK_CONTRACT_REF_SCHEMA_VERSION,
+            taskId: input.taskId,
+            revision: nextRevision,
+            projectionVersion: PROJECTION_VERSION,
+            canonicalizerVersion: CANONICALIZER_VERSION,
+            taskConfigSchemaVersion: TASK_CONFIG_SCHEMA_VERSION,
+            sourceHashes,
+            taskConfigSha256,
+            canonicalHash,
+            updatedAt: new Date().toISOString(),
+            lastRequestId: input.requestId,
+        };
+        await assertLockHeld(lock);
+        const { txId, ref } = await runJournaledContractCommit({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            operation: "apply",
+            requestId: input.requestId,
+            requestPayloadSha256: input.requestPayloadSha256,
+            expectedRevision: input.expectedRevision,
+            expectedObservedCanonicalHash: expected,
+            nextRevision,
+            fencingToken: lock.record.fencingToken,
+            targets: {
+                requirementContent,
+                constraintsContent,
+                taskConfigContent,
+                contractRef: nextRef,
+            },
+        });
+        await appendRequestLedgerEntry({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            entry: {
+                schemaVersion: 1,
+                requestId: input.requestId,
+                requestPayloadSha256: input.requestPayloadSha256,
+                txId,
+                revision: ref.revision,
+                canonicalHash: ref.canonicalHash,
+                recordedAt: new Date().toISOString(),
+                resultSummary: { ok: true, operation: "apply" },
+            },
+        });
+        await finalizeTransaction({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            txId,
+        });
+        const diff = await diffDraftAgainstCurrent({
+            taskId: input.taskId,
+            draft: input.draft,
+            currentConfig,
+            currentStatus: state.effectiveStatus,
+            currentRevision,
+            requirementChanged: true,
+            constraintsChanged: true,
+        });
+        return {
+            ref,
+            changedFiles: [
+                "source/需求.md",
+                "source/执行约束.md",
+                "task.json",
+                "contract.json",
+            ],
+            idempotentReplay: false,
+            txId,
+            risks: diff.risks,
+        };
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/task/contract/canonicalize.js

@@ -0,0 +1,60 @@
+/**
+ * Deterministic canonicalization rules (design §5.3.2):
+ * - UTF-8, LF line endings, single trailing newline for text projections
+ * - TaskConfig full canonical JSON: sorted object keys, preserve arrays,
+ *   paths with `/`, no Unicode normalization, unknown fields rejected by schema
+ */
+export function normalizeNewlinesToLf(text) {
+    return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+/**
+ * Canonical text projection: LF only + exactly one trailing newline.
+ * Empty string becomes a single newline.
+ */
+export function canonicalizeTextProjection(text) {
+    const lf = normalizeNewlinesToLf(text);
+    const withoutTrailing = lf.replace(/\n+$/u, "");
+    return `${withoutTrailing}\n`;
+}
+/**
+ * Detect whether external bytes differ from LF-canonical form.
+ * External CRLF is NOT silently normalized for hash observation.
+ */
+export function isExternallyNonCanonicalText(rawUtf8) {
+    return rawUtf8 !== canonicalizeTextProjection(rawUtf8);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Deep-sort object keys by Unicode code point; arrays keep order.
+ * Used for TaskConfig and hash material.
+ */
+export function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortKeysDeep(item));
+    }
+    if (isPlainObject(value)) {
+        const keys = Object.keys(value).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+        const out = {};
+        for (const key of keys) {
+            out[key] = sortKeysDeep(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Canonical JSON string: sorted keys, no whitespace, UTF-8 safe.
+ * null is distinct from missing (caller must not drop keys).
+ */
+export function canonicalizeJsonValue(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+/** Path separators forced to `/` without Unicode normalization. */
+export function canonicalizePath(pathValue) {
+    return pathValue.replace(/\\/g, "/");
+}
+export function canonicalizePathArray(paths) {
+    return paths.map(canonicalizePath);
+}

package/dist/task/contract/constants.js

@@ -0,0 +1,29 @@
+/** Fixed version constants for Task Contract projection/hashing. */
+export const TASK_CONTRACT_REF_SCHEMA_VERSION = 1;
+export const TASK_CONTRACT_DRAFT_SCHEMA_VERSION = 1;
+export const PROJECTION_VERSION = 1;
+export const CANONICALIZER_VERSION = 1;
+export const TASK_CONFIG_SCHEMA_VERSION = 1;
+/** Aliases used by schema / hash modules */
+export const TASK_CONTRACT_PROJECTION_VERSION = PROJECTION_VERSION;
+export const TASK_CONTRACT_CANONICALIZER_VERSION = CANONICALIZER_VERSION;
+/** Managed task.json fields that Draft apply may patch/merge. */
+export const MANAGED_TASK_CONFIG_FIELDS = [
+    "title",
+    "taskKind",
+    "featureId",
+    "allowedPaths",
+    "forbiddenPaths",
+    "hardConstraints",
+    "verifyCommands",
+];
+export const CONTRACT_FILE_NAME = "contract.json";
+export const TRANSACTIONS_DIR_NAME = ".transactions";
+export const REQUEST_LEDGER_FILE_NAME = "request-ledger.jsonl";
+export const TASK_LOCK_FILE_NAME = ".contract.lock";
+/** Aliases used by paths.ts helpers */
+export const CONTRACT_JSON_BASENAME = CONTRACT_FILE_NAME;
+export const TRANSACTIONS_DIRNAME = TRANSACTIONS_DIR_NAME;
+export const REQUEST_LEDGER_BASENAME = REQUEST_LEDGER_FILE_NAME;
+export const REQUIREMENT_FILE_NAME = "需求.md";
+export const CONSTRAINTS_FILE_NAME = "执行约束.md";

package/dist/task/contract/diff.js

@@ -0,0 +1,177 @@
+import { MANAGED_TASK_CONFIG_FIELDS } from "./constants.js";
+function maxRisk(a, b) {
+    const order = ["routine", "elevated", "blocking"];
+    return order[Math.max(order.indexOf(a), order.indexOf(b))];
+}
+function setDiff(before, after) {
+    const b = new Set(before);
+    const a = new Set(after);
+    return {
+        added: after.filter((x) => !b.has(x)),
+        removed: before.filter((x) => !a.has(x)),
+    };
+}
+/**
+ * Classify Draft vs current facts (design §5.3.6 risk table).
+ */
+export function diffDraftAgainstCurrent(input) {
+    const risks = [];
+    const changedManagedFields = [];
+    const cfg = input.currentConfig;
+    if (input.requirementChanged) {
+        risks.push({
+            code: "REQUIREMENT_CHANGED",
+            level: "routine",
+            message: "requirement markdown projection changes",
+            path: "source/需求.md",
+        });
+    }
+    if (input.constraintsChanged) {
+        risks.push({
+            code: "CONSTRAINTS_CHANGED",
+            level: "routine",
+            message: "constraints markdown projection changes",
+            path: "source/执行约束.md",
+        });
+    }
+    if (cfg) {
+        if (input.draft.title !== cfg.title) {
+            changedManagedFields.push("title");
+            risks.push({
+                code: "TITLE_CHANGED",
+                level: "routine",
+                message: "title change",
+                path: "task.json#title",
+            });
+        }
+        if (input.draft.taskKind !== cfg.taskKind) {
+            changedManagedFields.push("taskKind");
+            risks.push({
+                code: "TASK_KIND_CHANGED",
+                level: "elevated",
+                message: `taskKind ${cfg.taskKind} → ${input.draft.taskKind}`,
+                path: "task.json#taskKind",
+            });
+        }
+        const allowed = setDiff(cfg.allowedPaths, input.draft.constraints.allowedPaths);
+        if (allowed.added.length > 0) {
+            changedManagedFields.push("allowedPaths");
+            risks.push({
+                code: "ALLOWED_PATHS_EXPANDED",
+                level: "elevated",
+                message: `expand allowedPaths: ${allowed.added.join(", ")}`,
+                path: "task.json#allowedPaths",
+            });
+        }
+        if (allowed.removed.length > 0) {
+            if (!changedManagedFields.includes("allowedPaths")) {
+                changedManagedFields.push("allowedPaths");
+            }
+            risks.push({
+                code: "ALLOWED_PATHS_NARROWED",
+                level: "routine",
+                message: `narrow allowedPaths: ${allowed.removed.join(", ")}`,
+                path: "task.json#allowedPaths",
+            });
+        }
+        const forbidden = setDiff(cfg.forbiddenPaths, input.draft.constraints.forbiddenPaths);
+        if (forbidden.removed.length > 0) {
+            changedManagedFields.push("forbiddenPaths");
+            risks.push({
+                code: "FORBIDDEN_PATHS_REMOVED",
+                level: "elevated",
+                message: `remove forbiddenPaths: ${forbidden.removed.join(", ")}`,
+                path: "task.json#forbiddenPaths",
+            });
+        }
+        if (forbidden.added.length > 0) {
+            if (!changedManagedFields.includes("forbiddenPaths")) {
+                changedManagedFields.push("forbiddenPaths");
+            }
+            risks.push({
+                code: "FORBIDDEN_PATHS_EXPANDED",
+                level: "routine",
+                message: `expand forbiddenPaths: ${forbidden.added.join(", ")}`,
+                path: "task.json#forbiddenPaths",
+            });
+        }
+        const beforeVerify = new Set(cfg.verifyCommands.map((c) => `${c.label}|${c.command}`));
+        const afterVerify = input.draft.verification.commands.map((c) => `${c.label}|${c.command}`);
+        const verifyRemoved = [...beforeVerify].filter((v) => !afterVerify.includes(v));
+        const verifyAdded = afterVerify.filter((v) => !beforeVerify.has(v));
+        if (verifyRemoved.length > 0) {
+            changedManagedFields.push("verifyCommands");
+            risks.push({
+                code: "VERIFY_WEAKENED",
+                level: "elevated",
+                message: `remove/weaken verification: ${verifyRemoved.join("; ")}`,
+                path: "task.json#verifyCommands",
+            });
+        }
+        if (verifyAdded.length > 0) {
+            if (!changedManagedFields.includes("verifyCommands")) {
+                changedManagedFields.push("verifyCommands");
+            }
+            risks.push({
+                code: "VERIFY_ADDED",
+                level: "routine",
+                message: `add verification: ${verifyAdded.join("; ")}`,
+                path: "task.json#verifyCommands",
+            });
+        }
+        const draftHard = input.draft.hardConstraints ?? input.draft.constraints.invariants ?? [];
+        if (JSON.stringify(draftHard) !== JSON.stringify(cfg.hardConstraints ?? [])) {
+            changedManagedFields.push("hardConstraints");
+            risks.push({
+                code: "HARD_CONSTRAINTS_CHANGED",
+                level: "routine",
+                message: "hardConstraints changed",
+                path: "task.json#hardConstraints",
+            });
+        }
+        if (input.draft.featureId !== undefined &&
+            input.draft.featureId !== cfg.featureId) {
+            changedManagedFields.push("featureId");
+            risks.push({
+                code: "FEATURE_ID_CHANGED",
+                level: "routine",
+                message: "featureId changed",
+                path: "task.json#featureId",
+            });
+        }
+    }
+    else {
+        for (const field of MANAGED_TASK_CONFIG_FIELDS) {
+            changedManagedFields.push(field);
+        }
+        risks.push({
+            code: "NO_CURRENT_CONFIG",
+            level: "elevated",
+            message: "no current task.json to diff against",
+        });
+    }
+    if (input.currentStatus === "externally-modified" ||
+        input.currentStatus === "transaction-incomplete") {
+        risks.push({
+            code: "STATUS_BLOCKS_ROUTINE_APPLY",
+            level: "blocking",
+            message: `current effectiveStatus=${input.currentStatus}`,
+        });
+    }
+    let highest = "routine";
+    for (const risk of risks) {
+        highest = maxRisk(highest, risk.level);
+    }
+    void highest;
+    return {
+        taskId: input.taskId,
+        currentRevision: input.currentRevision,
+        currentStatus: input.currentStatus,
+        risks,
+        changedManagedFields: [...new Set(changedManagedFields)],
+        requirementChanged: input.requirementChanged,
+        constraintsChanged: input.constraintsChanged,
+    };
+}
+/** Compatibility alias */
+export const diffTaskContractLegacy = diffDraftAgainstCurrent;

package/dist/task/contract/hash.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { CANONICALIZER_VERSION, PROJECTION_VERSION, TASK_CONFIG_SCHEMA_VERSION, } from "./constants.js";
+import { canonicalizeJsonValue } from "./canonicalize.js";
+export function sha256Utf8(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function sha256OfCanonicalJson(value) {
+    return sha256Utf8(canonicalizeJsonValue(value));
+}
+export function computeTaskConfigSha256(taskConfig) {
+    return sha256OfCanonicalJson(taskConfig);
+}
+export function buildCanonicalHashMaterial(input) {
+    return {
+        projectionVersion: input.projectionVersion ?? PROJECTION_VERSION,
+        canonicalizerVersion: input.canonicalizerVersion ?? CANONICALIZER_VERSION,
+        taskConfigSchemaVersion: input.taskConfigSchemaVersion ?? TASK_CONFIG_SCHEMA_VERSION,
+        sourceHashes: input.sourceHashes,
+        taskConfigSha256: input.taskConfigSha256,
+    };
+}
+/**
+ * canonicalHash over { projectionVersion, canonicalizerVersion,
+ * taskConfigSchemaVersion, sourceHashes, taskConfigSha256 }.
+ * contract.json itself is never part of this hash.
+ */
+export function computeCanonicalHash(input) {
+    return sha256OfCanonicalJson(buildCanonicalHashMaterial(input));
+}
+export function computeSourceHashes(input) {
+    const sourceHashes = {
+        requirementSha256: sha256Utf8(input.requirementBytes),
+        constraintsSha256: sha256Utf8(input.constraintsBytes),
+    };
+    if (input.referenceManifestBytes) {
+        sourceHashes.referenceManifestSha256 = sha256Utf8(input.referenceManifestBytes);
+    }
+    return sourceHashes;
+}
+export function refMatchesObserved(ref, observedCanonicalHash) {
+    return ref.canonicalHash === observedCanonicalHash;
+}