@tea-agent/loop-agent 0.16.25 → 0.17.0

package/dist/task/contract/adopt.js

@@ -0,0 +1,166 @@
+import { CANONICALIZER_VERSION, PROJECTION_VERSION, TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
+import { ContractMutationError } from "./apply.js";
+import { computeCanonicalHash, computeSourceHashes, computeTaskConfigSha256, } from "./hash.js";
+import { acquireTaskContractLock, assertLockHeld } from "./lock.js";
+import { loadObservedTaskBytes, logicalRevisionForState, observeTaskContractState, readStoredContractRef, } from "./observe.js";
+import { serializeTaskConfigForDisk } from "./project.js";
+import { appendRequestLedgerEntry, findRequestLedgerEntry, } from "./request-ledger.js";
+import { finalizeTransaction, runJournaledContractCommit, } from "./transaction.js";
+import { getTaskPaths, parseTaskConfigForRuntime } from "../runtime.js";
+/**
+ * Adopt current on-disk 需求.md / 执行约束.md / task.json as next managed revision.
+ * Does not rewrite reference bytes. Requires deterministic readable facts.
+ */
+export async function adoptTaskContract(input) {
+    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`);
+        }
+        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-adopt",
+    });
+    try {
+        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");
+        }
+        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 bytes = await loadObservedTaskBytes(input.repoRoot, input.taskId);
+        if (bytes.requirementBytes === null ||
+            bytes.constraintsBytes === null ||
+            bytes.taskConfigRaw === null ||
+            bytes.taskConfigSha256 === null) {
+            throw new ContractMutationError("INVALID_INPUT", "adopt requires existing 需求.md, 执行约束.md, and task.json");
+        }
+        const observedHash = state.observedCanonicalHash;
+        if (!observedHash) {
+            throw new ContractMutationError("OBSERVED_HASH_CONFLICT", "unable to observe current canonical hash for adopt");
+        }
+        if (input.expectedObservedHash !== observedHash) {
+            throw new ContractMutationError("OBSERVED_HASH_CONFLICT", "expectedObservedHash does not match current observed hash", {
+                expectedObservedHash: input.expectedObservedHash,
+                observedCanonicalHash: observedHash,
+            });
+        }
+        const fullConfig = parseTaskConfigForRuntime(bytes.taskConfigRaw);
+        const taskConfigContent = serializeTaskConfigForDisk(fullConfig);
+        const sourceHashes = computeSourceHashes({
+            requirementBytes: bytes.requirementBytes,
+            constraintsBytes: bytes.constraintsBytes,
+            referenceManifestBytes: bytes.referenceManifestBytes,
+        });
+        const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
+        const canonicalHash = computeCanonicalHash({
+            sourceHashes,
+            taskConfigSha256,
+        });
+        // Sanity: observed should equal recomputed
+        if (canonicalHash !== observedHash) {
+            throw new ContractMutationError("OBSERVED_HASH_CONFLICT", "recomputed canonical hash diverged during adopt");
+        }
+        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,
+        };
+        // Adopt rewrites contract.json and re-writes same source/config bytes
+        // (stable content) so journal protocol is uniform.
+        await assertLockHeld(lock);
+        const { txId, ref } = await runJournaledContractCommit({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            operation: "adopt",
+            requestId: input.requestId,
+            requestPayloadSha256: input.requestPayloadSha256,
+            expectedRevision: input.expectedRevision,
+            expectedObservedCanonicalHash: input.expectedObservedHash,
+            nextRevision,
+            fencingToken: lock.record.fencingToken,
+            targets: {
+                requirementContent: bytes.requirementBytes,
+                constraintsContent: bytes.constraintsBytes,
+                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: "adopt" },
+            },
+        });
+        await finalizeTransaction({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            txId,
+        });
+        return {
+            ref,
+            changedFiles: ["contract.json"],
+            idempotentReplay: false,
+            txId,
+        };
+    }
+    finally {
+        await lock.release();
+    }
+}

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";