loopforge 2.11.0 → 3.2.1

package/dist/cognitive-governance.js

@@ -0,0 +1,126 @@
+/** v2.12: User/Agent gate classification and governance helpers.
+ *
+ *  Ported from the 3.x line with the V2 flat-contract adaptation: the MCP
+ *  surface works with a flat gate text (the agent's blocker description),
+ *  while the structured GateActionDescriptor stays an internal type for
+ *  audit display. Only decisions are persisted — gate state is always
+ *  re-derivable via deriveGate, so the vault never holds a second truth.
+ */
+import { createHash } from "node:crypto";
+import { computeGoalTextHash } from "./loop-compiler.js";
+import { entryRound as sharedEntryRound } from "./token-utils.js";
+export function entryRound(entry) {
+    return sharedEntryRound(entry);
+}
+/** Effects that always require human authorization. */
+const USER_EFFECTS = new Set([
+    "production", "credentials", "data_migration", "public_api", "publish",
+    "payment", "external_communication",
+]);
+/** High-risk markers, English + Chinese. */
+const USER_RISK = /production|prod\b|credential|secret|permission|publish|release|database migration|schema migration|public api break|rm\s+-rf|reset\s+--hard|send email|payment|生产|上线|凭据|密钥|权限|发布|数据迁移|破坏性/i;
+/** Stable gate ID from canonicalized gate text (gate- + sha256 slice 12). */
+export function deriveGateId(text) {
+    return "gate-" + computeGoalTextHash(text).slice(0, 12);
+}
+/** Stable todo item ID (todo- + sha256 slice 8) for the LoopProjection. */
+export function deriveTodoId(text) {
+    return "todo-" + computeGoalTextHash(text).slice(0, 8);
+}
+/** Canonical serialization — sorted scope/effects make the hash stable
+ *  across field-order and whitespace differences. */
+export function canonicalizeGateAction(action) {
+    return JSON.stringify({
+        description: action.description.trim(),
+        scope: [...action.scope].map((value) => value.trim()).filter(Boolean).sort(),
+        effects: [...action.effects].sort(),
+        reversibility: action.reversibility,
+        authorization: action.authorization,
+    });
+}
+/** 16-hex hash binding an approval to the exact action text — an edited
+ *  action produces a different hash, so old approvals expire automatically. */
+export function gateActionHash(action) {
+    return createHash("sha256").update(canonicalizeGateAction(action)).digest("hex").slice(0, 16);
+}
+/** Classify a structured action descriptor (internal use; audit display). */
+export function deriveStructuredGate(action) {
+    const actionHash = gateActionHash(action);
+    const highRisk = action.authorization === "user_required" ||
+        action.reversibility === "irreversible" ||
+        action.reversibility === "unknown" ||
+        action.effects.some((effect) => USER_EFFECTS.has(effect));
+    const userGate = highRisk || action.authorization === "unknown" || action.effects.length === 0;
+    return {
+        id: `gate-${actionHash}`,
+        actionHash,
+        gate: userGate
+            ? {
+                kind: "user",
+                question: `Authorize this action: ${action.description}`,
+                blockedScope: action.scope.length ? action.scope : [action.description],
+                allowedWork: ["Read-only investigation", "Local dry-run", "Prepare verification and rollback evidence"],
+            }
+            : {
+                kind: "agent",
+                problem: action.description,
+                requiredEvidence: action.scope,
+                suggestedResolution: "Resolve the technical blocker and submit concrete evidence in RoundReport.",
+            },
+    };
+}
+/** Classify a flat gate text (MCP surface). The id embeds the canonicalized
+ *  text hash, so a changed blocker text yields a different gate id and any
+ *  previously recorded approval no longer matches. */
+export function deriveGate(action, scope = []) {
+    if (typeof action !== "string")
+        return deriveStructuredGate(action);
+    const normalized = [action, ...scope].join("\n").trim();
+    const id = deriveGateId(normalized);
+    const gate = USER_RISK.test(normalized)
+        ? {
+            kind: "user",
+            question: `Authorize this high-risk action: ${action}`,
+            blockedScope: scope.length ? scope : [action],
+            allowedWork: ["Read-only investigation", "Local dry-run", "Prepare verification and rollback evidence"],
+        }
+        : {
+            kind: "agent",
+            problem: action,
+            requiredEvidence: scope,
+            suggestedResolution: "Resolve the technical blocker and submit concrete evidence in RoundReport.",
+        };
+    return { id, gate };
+}
+/** Deterministic replay order for audit — backends may return entries in
+ *  different physical orders, so insertion order can never decide which
+ *  gate decision or verification result wins. */
+export function auditOrder(entries) {
+    return entries
+        .map((entry, index) => ({ entry, index }))
+        .sort((left, right) => {
+        // v2.14: the event_sequence sort layer was removed — no entry in the
+        // codebase ever writes that field, so the branch was unreachable.
+        const roundDiff = entryRound(left.entry) - entryRound(right.entry);
+        if (roundDiff !== 0)
+            return roundDiff;
+        const timeLeft = Date.parse(left.entry.timestamp ?? "");
+        const timeRight = Date.parse(right.entry.timestamp ?? "");
+        const validLeft = Number.isFinite(timeLeft);
+        const validRight = Number.isFinite(timeRight);
+        if (validLeft && validRight && timeLeft !== timeRight)
+            return timeLeft - timeRight;
+        if (validLeft !== validRight)
+            return validLeft ? -1 : 1;
+        const key = (entry) => [
+            entry.task_type ?? "",
+            entry.task_id ?? entry.id ?? "",
+            entry.gate_id ?? "",
+            entry.approved === true ? "1" : entry.approved === false ? "0" : "",
+        ].join("\0");
+        const keyDiff = key(left.entry).localeCompare(key(right.entry));
+        return keyDiff !== 0 ? keyDiff : left.index - right.index;
+    })
+        .map(({ entry }) => entry);
+}
+//# sourceMappingURL=cognitive-governance.js.map

package/dist/cognitive-governance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cognitive-governance.js","sourceRoot":"","sources":["../src/cognitive-governance.ts"],"names":[],"mappings":"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"}

package/dist/enforcement-gate.d.ts

@@ -16,7 +16,7 @@
  * - terminate: loop has reached an unrecoverable state; stop immediately
  *              with stopReason "enforcement_terminated".
  */
-import type { VaultEntry } from "./backends/interface.js";
+import type { VaultEntry } from "./loop-store.js";
 import type { EnforcementResult, SelfEvaluation, VerificationFlag, VerificationResult } from "./protocol.js";
 /** Scan backwards from currentRound to find the most recent clean round.
  *  Collects discovered_constraints from skipped rounds along the way.
@@ -25,6 +25,11 @@ export declare function findSafeRestorePoint(currentRound: number, vaultEntries:
     round: number;
     skippedDiscoveries: string[];
 } | null;
+/** v2.12: Git HEAD commit hash at the restore point. Read from the restore
+ *  round's committed transaction snapshot (after evidence preferred, before
+ *  evidence as fallback). Returns null when the round has no git snapshot
+ *  or no committed feedback entry. */
+export declare function findBacktrackTargetGitHead(restoreRound: number, vaultEntries: VaultEntry[]): string | null;
 /** Build the backtrack prompt injected at the top of the restored round.
  *
  *  v2.13: Includes concrete workspace restore instructions with affected
@@ -34,9 +39,9 @@ export declare function buildBacktrackPrompt(fromRound: number, toRound: number,
 /** v2.13: Files changed in the skipped rounds (from evidence snapshots).
  *  Used to show the agent exactly what needs to be reverted. */
 skippedFiles?: string[], 
-/** v2.13: Git HEAD commit hash at the backtrack point (current HEAD).
+/** v2.12: Git HEAD commit hash at the backtrack point (current HEAD).
  *  The agent must discard work back to the clean round's state. */
-_gitHead?: string): string;
+gitHead?: string): string;
 /** Enforce round-boundary rules based on the verification gate's findings
  *  and the agent's self-evaluation integrity.
  *

package/dist/enforcement-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enforcement-gate.d.ts","sourceRoot":"","sources":["../src/enforcement-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AA6DvB;;iEAEiE;AACjE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,UAAU,EAAE,EAC1B,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAsCxD;AAED;;;;oDAIoD;AACpD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAAE;AAC5B;gEACgE;AAChE,YAAY,GAAE,MAAM,EAAO;AAC3B;mEACmE;AACnE,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CA0HR;AA4kBD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,kBAAkB,EAChC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,UAAU,EAAE,EAC1B,qBAAqB,GAAE,MAAU,EACjC,iBAAiB,UAAQ;AACzB,6DAA6D;AAC7D,wBAAwB,GAAE,MAAU,GACnC,iBAAiB,CA0BnB;AAED;;;;;;;;;;;;;;sEAcsE;AACtE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,iBAAiB,EAChC,iBAAiB,GAAE,gBAAgB,EAAO,GACzC,MAAM,CA6CR"}
+{"version":3,"file":"enforcement-gate.d.ts","sourceRoot":"","sources":["../src/enforcement-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAyHvB;;iEAEiE;AACjE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,UAAU,EAAE,EAC1B,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CA6CxD;AAED;;;sCAGsC;AACtC,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,UAAU,EAAE,GACzB,MAAM,GAAG,IAAI,CAwBf;AAED;;;;oDAIoD;AACpD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAAE;AAC5B;gEACgE;AAChE,YAAY,GAAE,MAAM,EAAO;AAC3B;mEACmE;AACnE,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CA6IR;AAy0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,kBAAkB,EAChC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,UAAU,EAAE,EAC1B,qBAAqB,GAAE,MAAU,EACjC,iBAAiB,UAAQ;AACzB,6DAA6D;AAC7D,wBAAwB,GAAE,MAAU,GACnC,iBAAiB,CAiCnB;AAED;;;;;;;;;;;;;;sEAcsE;AACtE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,iBAAiB,EAChC,iBAAiB,GAAE,gBAAgB,EAAO,GACzC,MAAM,CA6CR"}