looply-cli 0.0.0-stage → 0.2.0

package/dist/goal-depends-executor.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.goalDependsExecutor = goalDependsExecutor;
+exports.describeEdgeEffect = describeEdgeEffect;
+/**
+ * The approved action, re-read from the envelope.
+ *
+ * ⚠️ CHECKED AGAIN HERE EVEN THOUGH THE PARSER ALREADY REFUSED THESE. This is
+ * the last code before an effect, and `git-push-executor.ts` makes the same
+ * argument about a forced push: a shape the parser rejects should still not be
+ * carried out if it somehow arrives.
+ */
+function actionOf(env) {
+    const a = env.actionRequest.action;
+    if (typeof a?.goalId !== 'string' || a.goalId === '')
+        return 'no goal';
+    if (typeof a?.dependsOnId !== 'string' || a.dependsOnId === '')
+        return 'no dependency';
+    if (a.goalId === a.dependsOnId)
+        return 'a goal cannot be made to wait for itself';
+    if (typeof a?.goalVersion !== 'number' || !Number.isInteger(a.goalVersion) || a.goalVersion < 0) {
+        return 'the approved goal version is not a whole number';
+    }
+    if (typeof a?.dependsOnVersion !== 'number' || !Number.isInteger(a.dependsOnVersion) || a.dependsOnVersion < 0) {
+        return 'the approved dependency version is not a whole number';
+    }
+    return {
+        goalId: a.goalId,
+        dependsOnId: a.dependsOnId,
+        goalVersion: a.goalVersion,
+        dependsOnVersion: a.dependsOnVersion,
+        sourceId: typeof a.sourceId === 'string' ? a.sourceId : '',
+        sourceSha: typeof a.sourceSha === 'string' ? a.sourceSha : '',
+    };
+}
+/**
+ * What is kept as evidence.
+ *
+ * ⚠️ EVERY FIELD IS ALREADY INSIDE THE FINGERPRINT A PERSON APPROVED, so none
+ * of it is new information and none of it is a secret. The observed list is
+ * summarised as a COUNT rather than enumerated: how many edges that goal has is
+ * the fact worth recording, and the other goals' ids are nobody's business
+ * here.
+ */
+function evidenceOf(a, observedEdges) {
+    return {
+        goal: a.goalId,
+        dependsOn: a.dependsOnId,
+        goalVersion: String(a.goalVersion),
+        ...(observedEdges === null ? {} : { edgesAfter: String(observedEdges) }),
+    };
+}
+function goalDependsExecutor(projectId, goals) {
+    const look = async (a) => {
+        try {
+            return await goals.read(projectId, a.goalId);
+        }
+        catch (e) {
+            /**
+             * 🔴 COULD NOT LOOK IS NOT "NOT THERE". The same distinction
+             * `git-push-executor.ts` keeps about a remote: reading a failure to read
+             * as an absence is how an effect gets applied twice.
+             */
+            return { because: `the goal could not be read (${e.message})` };
+        }
+    };
+    return {
+        type: 'goal.depends',
+        async execute(env) {
+            const a = actionOf(env);
+            if (typeof a === 'string')
+                return { kind: 'failure', safeReason: a, evidence: {} };
+            const seen = await look(a);
+            if (seen !== null && 'because' in seen) {
+                return { kind: 'ambiguous', safeReason: seen.because, evidence: evidenceOf(a, null) };
+            }
+            if (seen === null) {
+                return { kind: 'failure', safeReason: `${a.goalId} is not a goal in this project`, evidence: evidenceOf(a, null) };
+            }
+            /**
+             * 🔴 THE APPROVAL WAS FOR ONE VERSION OF THIS GOAL. If it has moved,
+             * nothing is written: the edge may still be right, and it is not the same
+             * decision any more, so it goes back to a person rather than through.
+             */
+            if (seen.version !== a.goalVersion) {
+                return {
+                    kind: 'failure',
+                    safeReason: `this was approved for ${a.goalId}@${a.goalVersion} and it is now at ${seen.version}`,
+                    evidence: evidenceOf(a, seen.dependsOn.length),
+                };
+            }
+            if (seen.dependsOn.includes(a.dependsOnId)) {
+                // The approved effect is present. `git.push` answers the same way when
+                // the remote already holds the commit.
+                return { kind: 'success', evidence: evidenceOf(a, seen.dependsOn.length) };
+            }
+            /**
+             * 🔴 AND THE GOAL IT WILL WAIT FOR IS STILL THE ONE THAT WAS APPROVED. The
+             * person read "wait for R2@2"; an R2 rewritten or abandoned since is not
+             * what they said yes to. `dependsOnVersion` was parsed here and compared
+             * with nothing until the governed write became reachable (F11 review).
+             */
+            const prerequisite = await look({ ...a, goalId: a.dependsOnId });
+            if (prerequisite !== null && 'because' in prerequisite) {
+                return { kind: 'ambiguous', safeReason: prerequisite.because, evidence: evidenceOf(a, null) };
+            }
+            if (prerequisite === null) {
+                return { kind: 'failure', safeReason: `${a.dependsOnId} is not a goal in this project`, evidence: evidenceOf(a, null) };
+            }
+            if (prerequisite.version !== a.dependsOnVersion) {
+                return {
+                    kind: 'failure',
+                    safeReason: `this was approved to wait for ${a.dependsOnId}@${a.dependsOnVersion} and it is now at ${prerequisite.version}`,
+                    evidence: evidenceOf(a, seen.dependsOn.length),
+                };
+            }
+            /**
+             * 🔴 THE UNION, NEVER THE ONE EDGE. `PATCH dependsOn` REPLACES the list,
+             * so sending `[dependsOnId]` alone would delete every other edge on this
+             * goal as a side effect of adding one.
+             */
+            const next = [...seen.dependsOn, a.dependsOnId];
+            try {
+                // 🔴 NAMING THE EXECUTION IS WHAT LETS THE MACHINE WRITE THIS AT ALL.
+                // Changing a goal is a person's route; the server admits this one write
+                // only as the effect of THIS execution of an approved `goal.depends`,
+                // and checks the list against the action it holds (see the server's
+                // `GovernedGoalEdgeService`). Without it every approved edge was a 403.
+                await goals.setDependsOn(projectId, a.goalId, a.goalVersion, next, env.executionId);
+            }
+            catch (e) {
+                /**
+                 * IT THREW, AND THAT IS NOT THE SAME AS IT NOT HAPPENING. A request
+                 * that timed out after the server applied it looks identical from here,
+                 * so this does not decide — it goes and LOOKS.
+                 */
+                const after = await look(a);
+                if (after === null || 'because' in after) {
+                    return {
+                        kind: 'ambiguous',
+                        safeReason: `the edge was not confirmed and ${after === null ? 'the goal is no longer there' : after.because}`,
+                        evidence: evidenceOf(a, null),
+                    };
+                }
+                if (after.dependsOn.includes(a.dependsOnId)) {
+                    return { kind: 'success', evidence: evidenceOf(a, after.dependsOn.length) };
+                }
+                return {
+                    kind: 'failure',
+                    safeReason: `the edge was refused (${e.message})`,
+                    evidence: evidenceOf(a, after.dependsOn.length),
+                };
+            }
+            /**
+             * ⚠️ IT RETURNED CLEANLY AND IT IS STILL CONFIRMED. One read, and the
+             * success recorded is one somebody could go and verify.
+             */
+            const after = await look(a);
+            if (after === null || 'because' in after) {
+                return {
+                    kind: 'ambiguous',
+                    safeReason: `the edge was written and ${after === null ? 'the goal is no longer there' : after.because}`,
+                    evidence: evidenceOf(a, null),
+                };
+            }
+            if (!after.dependsOn.includes(a.dependsOnId)) {
+                return {
+                    kind: 'ambiguous',
+                    safeReason: 'the edge was written and the goal does not have it',
+                    evidence: evidenceOf(a, after.dependsOn.length),
+                };
+            }
+            return { kind: 'success', evidence: evidenceOf(a, after.dependsOn.length) };
+        },
+        async reconcile(env) {
+            const a = actionOf(env);
+            // An action this executor cannot read is not one it can have performed.
+            if (typeof a === 'string')
+                return { kind: 'observed-not-executed' };
+            const seen = await look(a);
+            if (seen !== null && 'because' in seen)
+                return { kind: 'ambiguous', safeReason: seen.because };
+            /**
+             * ⚠️ A GOAL THAT IS GONE IS AMBIGUOUS, NOT "NOT EXECUTED". The edge may
+             * have been written and the goal deleted afterwards; answering
+             * `observed-not-executed` would permit a retry against something that is
+             * not there, and that arm is the ONLY one that permits one.
+             */
+            if (seen === null)
+                return { kind: 'ambiguous', safeReason: `${a.goalId} is no longer a goal in this project` };
+            if (seen.dependsOn.includes(a.dependsOnId)) {
+                return { kind: 'observed-success', evidence: evidenceOf(a, seen.dependsOn.length) };
+            }
+            return { kind: 'observed-not-executed' };
+        },
+    };
+}
+/** One line for a person, for a result that already carries its own evidence. */
+function describeEdgeEffect(a) {
+    return `${a.goalId} waits for ${a.dependsOnId}`;
+}
+//# sourceMappingURL=goal-depends-executor.js.map

package/dist/goal-depends-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-depends-executor.js","sourceRoot":"","sources":["../src/goal-depends-executor.ts"],"names":[],"mappings":";;AAwGA,kDAsJC;AAGD,gDAEC;AA1MD;;;;;;;GAOG;AACH,SAAS,QAAQ,CAAC,GAA8B;IAC9C,MAAM,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC,MAAyC,CAAC;IACtE,IAAI,OAAO,CAAC,EAAE,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACvE,IAAI,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,KAAK,EAAE;QAAE,OAAO,eAAe,CAAC;IACvF,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,WAAW;QAAE,OAAO,0CAA0C,CAAC;IAClF,IAAI,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;QAChG,OAAO,iDAAiD,CAAC;IAC3D,CAAC;IACD,IAAI,OAAO,CAAC,EAAE,gBAAgB,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,gBAAgB,GAAG,CAAC,EAAE,CAAC;QAC/G,OAAO,uDAAuD,CAAC;IACjE,CAAC;IACD,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;QACpC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;QAC1D,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,CAAa,EAAE,aAA4B;IAC7D,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,MAAM;QACd,SAAS,EAAE,CAAC,CAAC,WAAW;QACxB,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;QAClC,GAAG,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;KACzE,CAAC;AACJ,CAAC;AAED,SAAgB,mBAAmB,CAAC,SAAiB,EAAE,KAAyB;IAC9E,MAAM,IAAI,GAAG,KAAK,EAChB,CAAa,EAC4E,EAAE;QAC3F,IAAI,CAAC;YACH,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX;;;;eAIG;YACH,OAAO,EAAE,OAAO,EAAE,+BAAgC,CAAW,CAAC,OAAO,GAAG,EAAE,CAAC;QAC7E,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,cAAc;QAEpB,KAAK,CAAC,OAAO,CAAC,GAAG;YACf,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YAEnF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;YAC3B,IAAI,IAAI,KAAK,IAAI,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;gBACvC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;YACxF,CAAC;YACD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,MAAM,gCAAgC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;YACrH,CAAC;YAED;;;;eAIG;YACH,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;gBACnC,OAAO;oBACL,IAAI,EAAE,SAAS;oBACf,UAAU,EAAE,yBAAyB,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,WAAW,qBAAqB,IAAI,CAAC,OAAO,EAAE;oBACjG,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;iBAC/C,CAAC;YACJ,CAAC;YAED,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC3C,uEAAuE;gBACvE,uCAAuC;gBACvC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7E,CAAC;YAED;;;;;eAKG;YACH,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YACjE,IAAI,YAAY,KAAK,IAAI,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;gBACvD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;YAChG,CAAC;YACD,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;gBAC1B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,WAAW,gCAAgC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;YAC1H,CAAC;YACD,IAAI,YAAY,CAAC,OAAO,KAAK,CAAC,CAAC,gBAAgB,EAAE,CAAC;gBAChD,OAAO;oBACL,IAAI,EAAE,SAAS;oBACf,UAAU,EAAE,iCAAiC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,gBAAgB,qBAAqB,YAAY,CAAC,OAAO,EAAE;oBAC3H,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;iBAC/C,CAAC;YACJ,CAAC;YACD;;;;eAIG;YACH,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;YAChD,IAAI,CAAC;gBACH,sEAAsE;gBACtE,wEAAwE;gBACxE,sEAAsE;gBACtE,oEAAoE;gBACpE,wEAAwE;gBACxE,MAAM,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;YACtF,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX;;;;mBAIG;gBACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;gBAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;oBACzC,OAAO;wBACL,IAAI,EAAE,WAAW;wBACjB,UAAU,EAAE,kCAAkC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE;wBAC9G,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC;qBAC9B,CAAC;gBACJ,CAAC;gBACD,IAAI,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC5C,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC9E,CAAC;gBACD,OAAO;oBACL,IAAI,EAAE,SAAS;oBACf,UAAU,EAAE,yBAA0B,CAAW,CAAC,OAAO,GAAG;oBAC5D,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;iBAChD,CAAC;YACJ,CAAC;YAED;;;eAGG;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;gBACzC,OAAO;oBACL,IAAI,EAAE,WAAW;oBACjB,UAAU,EAAE,4BAA4B,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE;oBACxG,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC;iBAC9B,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC7C,OAAO;oBACL,IAAI,EAAE,WAAW;oBACjB,UAAU,EAAE,oDAAoD;oBAChE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;iBAChD,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9E,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,GAAG;YACjB,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YACxB,wEAAwE;YACxE,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;YAEpE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;YAC3B,IAAI,IAAI,KAAK,IAAI,IAAI,SAAS,IAAI,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/F;;;;;eAKG;YACH,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,MAAM,sCAAsC,EAAE,CAAC;YAE/G,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC3C,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtF,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;QAC3C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,SAAgB,kBAAkB,CAAC,CAA0C;IAC3E,OAAO,GAAG,CAAC,CAAC,MAAM,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC;AAClD,CAAC"}

package/dist/goal-execution-evidence.d.ts

@@ -0,0 +1,135 @@
+import { type Item, type RunScope } from '@looply/core';
+import type { RoundRecord } from './round-records';
+/**
+ * KEY 2 — THE HALF OF "THIS GOAL IS MET" THAT CANNOT BE TALKED INTO AN ANSWER.
+ *
+ * The evaluator is the same write-capable machinery that produced the work it
+ * is judging, so its `satisfied` is necessary and never sufficient. This is the
+ * other key, and it asks the only question the machine can answer for itself:
+ * did Looply actually deliver this plan, and is what it delivered what the
+ * repository is standing on right now?
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS REPLACED AN EVIDENCE-FRESHNESS CHECK
+ *
+ * The first version of KEY 2 asked whether every delivered item had a verifier
+ * evidence entry recorded at the current HEAD. An adversarial review proved
+ * that could never be true, and the proof is short:
+ *
+ *   the evidence cache is keyed by (item, head) and written by the VERIFY pass,
+ *   which reads HEAD before the work happens (verify-pass.ts) — then the round
+ *   implements the item and COMMITS, which moves HEAD, and only then marks it
+ *   `done` (round-runner.ts). Nothing writes evidence in between.
+ *
+ * So a genuinely delivered item's evidence is always pinned to an ancestor of
+ * its own commit; `lookup` answers `moved`; KEY 2 refused. Every goal, for
+ * ever, at the cost of an eight-minute evaluation each time. The end-to-end
+ * test passed only because its simulated run recorded evidence at a HEAD that
+ * never moved — a commit that changes nothing, which the real runner cannot
+ * produce.
+ *
+ * The mistake was asking pre-commit evidence to vouch for a post-commit tree.
+ * It was never checked against that tree and pretending otherwise would be the
+ * kind of lie this codebase refuses elsewhere.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT IT ASKS INSTEAD
+ *
+ * There must exist a real delivered round for the CURRENT goal, version and
+ * plan revision such that:
+ *
+ *   1. the round COMMITTED — `round.ended.outcome === 'committed'`
+ *   2. its commit is what the repository is on NOW — `sha === current HEAD`
+ *   3. its own gate record proves every CURRENTLY-required step passed
+ *
+ * (2) is what makes this honest without pretending: rather than asking stale
+ * evidence about a new tree, it asks whether the tree is still the one the
+ * round produced. If anything has moved HEAD since — another run, a person, a
+ * merge — KEY 2 fails closed, because nothing here has checked that.
+ *
+ * (3) is re-derived from the CURRENT config every time, not from what was
+ * required when the round ran. A step added to `config.gates` since is a step
+ * this delivery never passed, and the answer to "is the goal met" must be
+ * about the standard in force now.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT IT REFUSES TO REST ON
+ *
+ *   - `proof.reason` — agent prose.
+ *   - `proof.confidence` — an agent's self-report.
+ *   - the mere existence of a commit. `mayCommit` runs with `proofEnabled`
+ *     taken from config, and the audit established it is commonly false, so a
+ *     commit alone says only that something was written down.
+ *   - evidence-cache freshness, for the reason above.
+ *   - the plan's revision MARKER, which is a receipt that a plan happened and
+ *     is not work. A revision that delivered nothing cannot meet a goal.
+ *
+ * PURE. No agent, no git, no queue write, no compiler. Everything it needs is
+ * an argument, which is what lets production and the tests run the same code
+ * rather than two descriptions of it.
+ */
+export interface GoalExecutionInput {
+    /**
+     * The goal, version AND revision being asked about.
+     *
+     * `planRevision` is required, not optional. Production once passed a scope
+     * whose revision had not been assigned yet, which made `classifyForScope`
+     * revision-blind and let revision 1's delivery answer for revision 2 — a
+     * defect no unit test could see, because the unit tests supplied a revision
+     * the composition root did not. Failing closed on a missing one is the fix
+     * that cannot be forgotten again.
+     */
+    scope: RunScope;
+    items: readonly Item[];
+    rounds: readonly RoundRecord[];
+    currentHead: string;
+    /** Re-derived from the CURRENT config, via `requiredSteps(cfg.gates)`. */
+    requiredSteps: readonly string[];
+    /**
+     * Whether work a PERSON adopted into the goal may provide the delivery.
+     *
+     * Default true, and the reasoning is that `source` records where an item came
+     * from, not how much it is trusted: an item somebody adopted, which Looply
+     * then implemented, gated and committed, is delivered by exactly the same
+     * machinery as a compiled one. What is excluded either way is a commit
+     * Looply did not make — this only ever looks at rounds in its own ledger, so
+     * a person's own `git commit` can never qualify.
+     */
+    countManualWork?: boolean;
+}
+export type GoalExecutionOutcome = {
+    ok: true;
+    round: RoundRecord;
+    /**
+     * The items this plan actually delivered, and the gate steps the
+     * confirming round recorded.
+     *
+     * 🔴 REPORTED BY THE FUNCTION THAT ESTABLISHED KEY 2, not re-derived by
+     * the caller. Per-requirement coverage asks two further questions — was
+     * the item claiming a requirement in this delivery, and did the check it
+     * names pass at this tree — and both are things this function has
+     * already looked at. A second derivation elsewhere is a second answer
+     * that can disagree with the one the completion claim rests on.
+     *
+     * ⚠️ THE STEPS ARE THE CONFIRMING ROUND'S, which is the round whose
+     * commit IS the current HEAD. That is the tree being judged, so its own
+     * gate record is the only one that can speak for it.
+     */
+    delivered: readonly string[];
+} | {
+    ok: false;
+    because: string;
+};
+export declare function confirmGoalExecutionEvidence(input: GoalExecutionInput): GoalExecutionOutcome;
+/** A committed round, as a goal-met Start locates it: its commit and the run that made it. */
+export interface DeliveredTip {
+    readonly sha: string;
+    readonly runId: string;
+}
+/**
+ * The plan's NEWEST committed round — the delivered tree a goal-met Start judges while the
+ * lane has not moved it (F27). Null wherever KEY 2 would find nothing to confirm, and when
+ * the revision is unknown, for the reason KEY 2 fails closed on it.
+ */
+export declare function deliveredTipOf(input: Pick<GoalExecutionInput, 'scope' | 'items' | 'rounds' | 'countManualWork'>): DeliveredTip | null;
+//# sourceMappingURL=goal-execution-evidence.d.ts.map

package/dist/goal-execution-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-execution-evidence.d.ts","sourceRoot":"","sources":["../src/goal-execution-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAErF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IACvB,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,oBAAoB,GAC5B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,WAAW,CAAC;IACnB;;;;;;;;;;;;;;OAcG;IACH,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,kBAAkB,GAAG,oBAAoB,CAuG5F;AA8CD,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,iBAAiB,CAAC,GAChF,YAAY,GAAG,IAAI,CAOrB"}

package/dist/goal-execution-evidence.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmGoalExecutionEvidence = confirmGoalExecutionEvidence;
+exports.deliveredTipOf = deliveredTipOf;
+const core_1 = require("@looply/core");
+const goal_compile_1 = require("./goal-compile");
+function confirmGoalExecutionEvidence(input) {
+    const { scope, currentHead } = input;
+    if (scope === null)
+        return { ok: false, because: 'this run is not bound to a goal' };
+    if (scope.planRevision === undefined) {
+        // Fails closed rather than defaulting. A caller that has not worked out
+        // which plan it is asking about is a caller whose answer would be about
+        // every plan the version ever had.
+        return { ok: false, because: 'the plan revision is unknown, so there is nothing definite to confirm' };
+    }
+    if (currentHead === '')
+        return { ok: false, because: 'the current commit could not be read' };
+    /**
+     * COMPLETION AUTHORITY IS STRICTER THAN COMMIT AUTHORITY.
+     *
+     * `mayCommit` with an empty `requiredSteps` only rejects a step that ran and
+     * FAILED. Executed, it returns ok for a round whose single gate step was
+     * skipped, and for a round with no steps at all. That is a defensible commit
+     * policy — a project may choose to gate nothing — but it means the gate half
+     * of this check degenerates to "nothing actively failed", i.e. "something
+     * committed at HEAD".
+     *
+     * Under one explicit Start a person reads the answer and judges it. Under an
+     * autonomous controller it is a FALSE TERMINATION: the machine would declare
+     * a goal met because a commit exists, and stop.
+     *
+     * So automatic satisfaction requires at least one required step to exist.
+     * This does not change `mayCommit` for anybody else; it says that finishing a
+     * goal by itself needs a standard, and a project with no required gate has
+     * not given the machine one.
+     */
+    if (input.requiredSteps.length === 0) {
+        return {
+            ok: false,
+            because: 'no gate step is marked required, so nothing here can prove a goal is met — ' +
+                'mark at least one required step, or finish this goal yourself',
+        };
+    }
+    const plan = committedOfPlan(input, scope);
+    if (!plan.ok)
+        return plan;
+    const { committed, deliveredIds, mineById } = plan;
+    const atHead = committed.filter((r) => r.sha === currentHead);
+    if (atHead.length === 0) {
+        // Deliberately not "close enough". Something has moved the repository since
+        // this plan landed, and nothing here has checked that the goal survived it.
+        return {
+            ok: false,
+            because: 'the code has moved on since this plan was delivered, so what is here now was never checked',
+        };
+    }
+    // An EXISTS, not a FOR-ALL, and that is the whole reachability argument: a
+    // plan of five steps produces five commits and only the last is HEAD, so
+    // requiring all of them to be at HEAD would be the same unreachable demand
+    // the evidence-cache version made.
+    let lastReason = 'the gate that permitted this plan’s commit was never recorded';
+    for (const round of atHead) {
+        const item = mineById.get(round.itemId);
+        /**
+         * Belt and braces on the marker — STRUCTURALLY, by the id a receipt for
+         * these exact fields would have.
+         *
+         * This line first read `item.tag === 'goal'`, and that was a live defect of
+         * exactly the kind the whole repair exists to remove. `'goal'` is not a
+         * marker signature: it is the COMPILER'S DEFAULT TAG for any step the agent
+         * left untagged, which `normalizeStep` blesses as legitimate. So a
+         * genuinely delivered, gated, committed step whose tag the model happened
+         * to omit was skipped here, KEY 2 fell through to "the gate was never
+         * recorded" — about a gate that was in the ledger — and completion became
+         * unreachable again, for one line of redundant caution.
+         *
+         * A receipt cannot claim its exemption by holding a value; it can only be
+         * one by ALREADY having the id a receipt for its own fields would have.
+         *
+         * Deliberately NOT `goal-ownership`'s `isPlanReceipt`, which also requires
+         * `state === 'closed'`. That condition is right where it lives — it guards
+         * the rule that rows are born `draft`, and a receipt is the one exception —
+         * but it is exactly wrong here. The question here is whether a row may
+         * count as DELIVERY, and a receipt somehow carrying another state is more
+         * suspect than one behaving itself, not less. So the state is not part of
+         * the test: a row holding a marker's id is never delivery, whatever state
+         * it is in.
+         */
+        if (item === undefined || (0, goal_compile_1.isPlanMarker)(item))
+            continue;
+        if (round.gate === undefined)
+            continue;
+        // The SAME authority that permitted the commit, asked again with the
+        // requirements in force now. `proofEnabled: false` on purpose: the proof
+        // key is a separate question with a separate answer, and this one is about
+        // gates. Reused rather than reimplemented so the two cannot disagree about
+        // what "every required step passed" means.
+        const permitted = (0, core_1.mayCommit)({
+            steps: round.gate.steps,
+            requiredSteps: input.requiredSteps,
+            proofEnabled: false,
+        });
+        if (permitted.ok)
+            return { ok: true, round, delivered: [...deliveredIds] };
+        lastReason = permitted.reason ?? 'the gate did not pass';
+    }
+    return { ok: false, because: lastReason };
+}
+/**
+ * The committed rounds of this plan's delivered work — KEY 2's own selection, shared so
+ * `deliveredTipOf` can never pick a round KEY 2 would not (F27).
+ */
+function committedOfPlan(input, scope) {
+    const countManual = input.countManualWork ?? true;
+    // The rows this revision may claim. `classifyForScope` is the one authority
+    // on that and is asked directly, rather than re-deriving its rules here.
+    const mine = input.items.filter((item) => {
+        const verdict = (0, core_1.classifyForScope)(item, scope);
+        if (verdict === 'current-plan')
+            return true;
+        return countManual && verdict === 'manual';
+    });
+    // Delivery means `done`. A marker is born `closed` and can never be `done`,
+    // so it is excluded by this alone — but it is the single most important thing
+    // this function must not accept, so it is also excluded by name in the caller.
+    const delivered = mine.filter((i) => i.state === 'done');
+    if (delivered.length === 0) {
+        return { ok: false, because: 'nothing in this plan was actually delivered' };
+    }
+    const deliveredIds = new Set(delivered.map((i) => i.id));
+    const mineById = new Map(mine.map((i) => [i.id, i]));
+    // Every round this plan's own delivered work produced.
+    const ours = input.rounds.filter((r) => deliveredIds.has(r.itemId));
+    if (ours.length === 0) {
+        return { ok: false, because: 'no round in this machine’s ledger delivered any of this plan' };
+    }
+    const committed = ours.filter((r) => r.outcome === 'committed');
+    if (committed.length === 0) {
+        return { ok: false, because: 'nothing in this plan reached a commit' };
+    }
+    return { ok: true, committed, deliveredIds, mineById };
+}
+/**
+ * The plan's NEWEST committed round — the delivered tree a goal-met Start judges while the
+ * lane has not moved it (F27). Null wherever KEY 2 would find nothing to confirm, and when
+ * the revision is unknown, for the reason KEY 2 fails closed on it.
+ */
+function deliveredTipOf(input) {
+    const { scope } = input;
+    if (scope === null || scope.planRevision === undefined)
+        return null;
+    const plan = committedOfPlan(input, scope);
+    if (!plan.ok)
+        return null;
+    const newest = [...plan.committed].reverse().find((r) => r.sha !== undefined);
+    return newest?.sha === undefined ? null : { sha: newest.sha, runId: newest.runId };
+}
+//# sourceMappingURL=goal-execution-evidence.js.map

package/dist/goal-execution-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-execution-evidence.js","sourceRoot":"","sources":["../src/goal-execution-evidence.ts"],"names":[],"mappings":";;AA8HA,oEAuGC;AAyDD,wCASC;AAvSD,uCAAqF;AACrF,iDAA8C;AA6H9C,SAAgB,4BAA4B,CAAC,KAAyB;IACpE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IACrC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;IACrF,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,wEAAwE;QACxE,wEAAwE;QACxE,mCAAmC;QACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,uEAAuE,EAAE,CAAC;IACzG,CAAC;IACD,IAAI,WAAW,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC;IAE9F;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,6EAA6E;gBAC7E,+DAA+D;SAClE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAEnD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,WAAW,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,4EAA4E;QAC5E,4EAA4E;QAC5E,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,4FAA4F;SACtG,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,mCAAmC;IACnC,IAAI,UAAU,GAAG,+DAA+D,CAAC;IACjF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxC;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;QACH,IAAI,IAAI,KAAK,SAAS,IAAI,IAAA,2BAAY,EAAC,IAAI,CAAC;YAAE,SAAS;QACvD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QAEvC,qEAAqE;QACrE,yEAAyE;QACzE,2EAA2E;QAC3E,2EAA2E;QAC3E,2CAA2C;QAC3C,MAAM,SAAS,GAAG,IAAA,gBAAS,EAAC;YAC1B,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK;YACvB,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,YAAY,EAAE,KAAK;SACpB,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC;QAC3E,UAAU,GAAG,SAAS,CAAC,MAAM,IAAI,uBAAuB,CAAC;IAC3D,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CACtB,KAAuE,EACvE,KAA4B;IAI5B,MAAM,WAAW,GAAG,KAAK,CAAC,eAAe,IAAI,IAAI,CAAC;IAElD,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QACvC,MAAM,OAAO,GAAG,IAAA,uBAAgB,EAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9C,IAAI,OAAO,KAAK,cAAc;YAAE,OAAO,IAAI,CAAC;QAC5C,OAAO,WAAW,IAAI,OAAO,KAAK,QAAQ,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,8EAA8E;IAC9E,+EAA+E;IAC/E,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC;IACzD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;IAC/E,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAU,CAAC,CAAC,CAAC;IAE9D,uDAAuD;IACvD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACpE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,8DAA8D,EAAE,CAAC;IAChG,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC;IAChE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,uCAAuC,EAAE,CAAC;IACzE,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;AACzD,CAAC;AAQD;;;;GAIG;AACH,SAAgB,cAAc,CAC5B,KAAiF;IAEjF,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACxB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpE,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC;IAC9E,OAAO,MAAM,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AACrF,CAAC"}

package/dist/goal-gap.d.ts

@@ -0,0 +1,140 @@
+import type { Evidence, Item } from '@looply/core';
+import type { AgentInvoke } from './agent-exec';
+/**
+ * WHAT IS STILL MISSING, if anything.
+ *
+ * A plan finishing is not a goal being met. The compiler is heuristic — it
+ * proposes six steps for a sentence a person wrote — and when all six land, the
+ * only thing that has been established is that six particular pieces of work
+ * were done. "Add secure password reset" can have every planned step delivered
+ * and still be missing expiry, or rate limiting, or the screen.
+ *
+ * So this asks. Once, bounded, at the one moment it can be answered usefully:
+ * the current plan is exhausted and nothing else can move.
+ *
+ * WHAT IT IS NOT. It is not a second key. `AgentInvoke` is the same
+ * write-capable machinery the compiler and the implementer use — there is no
+ * read-only mode in this system, and calling this an independent review would
+ * be a lie of exactly the kind `goal-compile.ts` warns about. A `satisfied`
+ * verdict from here is NECESSARY and never SUFFICIENT: the caller pairs it with
+ * machine-enforced evidence before believing it.
+ *
+ * WHAT IT MAY NOT DO. It describes a gap; it does not produce work. The
+ * compiler turns gaps into steps, and keeping those apart is what stops a
+ * reviewer that can also plan from becoming a second, hidden round runner. It
+ * therefore imports neither the compiler nor anything that touches the
+ * repository, and the architecture guard asserts both.
+ */
+/** One reasoning call about whether a goal is met. Shorter than the compiler's. */
+export declare const GOAL_GAP_TIMEOUT_MS: number;
+/**
+ * How many gaps one evaluation may name.
+ *
+ * The compiler that answers them is capped at ADAPTIVE_MAX_STEPS, so naming
+ * more would be naming work nothing will do. Bounded here as well because this
+ * is untrusted input and the list ends up in a prompt.
+ */
+export declare const MAX_GAPS = 6;
+/** Longest a single gap description may be; the rest is trimmed, not refused. */
+export declare const MAX_GAP_TEXT = 300;
+/**
+ * One thing the goal still needs. DATA ONLY, deliberately.
+ *
+ * No command, no path to write, no item id, no goal version, no revision. A
+ * model that could name any of those could choose what executes, which is the
+ * authority this whole phase keeps in machine hands.
+ */
+export interface Gap {
+    /** Stable-ish handle for logs and prompts. Normalised from the description. */
+    key: string;
+    description: string;
+}
+export type GoalGapVerdict = 
+/** Nothing is missing, as far as reading the code can tell. Never believed alone. */
+{
+    kind: 'satisfied';
+    summary?: string;
+}
+/** Named, bounded things still to do. The compiler decides how. */
+ | {
+    kind: 'incomplete';
+    gaps: Gap[];
+}
+/** Cannot be decided by reading. A person has to say what they meant. */
+ | {
+    kind: 'human-required';
+    reason: string;
+};
+export type GoalGapOutcome = {
+    ok: true;
+    verdict: GoalGapVerdict;
+    transcript: string;
+}
+/**
+ * The evaluation did not happen. RETRYABLE, and deliberately distinct from
+ * every verdict: a timeout, a crashed agent or an unreadable answer must
+ * never be turned into `satisfied` (which would finish a goal that is not
+ * finished) or into `incomplete` (which would spend a plan revision on
+ * nothing). Both directions cost something real, so neither is guessed.
+ */
+ | {
+    ok: false;
+    reason: string;
+    transcript: string;
+};
+export interface GoalGapInput {
+    goalId: string;
+    goalVersion: number;
+    goalText: string;
+    planRevision: number;
+    projectName: string;
+    /** The current plan's rows and how each ended. Titles and states, nothing more. */
+    planItems: readonly Pick<Item, 'title' | 'state' | 'attempts'>[];
+    /** Evidence the verifier recorded for this plan, at the HEAD it was recorded against. */
+    evidence?: readonly Evidence[];
+    /** The commit the answer is about. Carried back so staleness is detectable. */
+    headSha: string;
+    /**
+     * F37: in a programme, what the OTHER goals own (the packet's `ownedElsewhere`). MEASURED LIVE (LIVE-2,
+     * 2026-09-26): the dependency-intent goal ("R2 and R3 … may be implemented concurrently") compiled an empty
+     * plan — F19 told the COMPILER what others own — and then this check, told nothing, called R2's missing fee
+     * calculator a gap; the re-plan built it, and a second checkout implemented R2's capability for the wrong goal.
+     */
+    ownedElsewhere?: readonly {
+        readonly goalId: string;
+        readonly key: string;
+        readonly text: string;
+    }[];
+}
+export interface GoalGapDeps {
+    invoke: AgentInvoke;
+    timeoutMs?: number;
+    maxGaps?: number;
+}
+export declare function gapKey(description: string): string;
+export declare function buildGapPrompt(input: GoalGapInput): string;
+/**
+ * Pull the verdict out of what the agent said.
+ *
+ * Scans from the END, like `extractPlan` and `extractFindings`, and for the
+ * same reason: an agent often echoes the example object from its own prompt
+ * before producing the real one, and taking the first match reads the example
+ * back as an answer. The whole transcript is tried first, because a
+ * pretty-printed object spans many lines.
+ *
+ * Unlike a plan, NOTHING here is dropped and carried on with. A plan is a list
+ * of proposals and a malformed one is simply fewer proposals; a verdict is a
+ * single decision, so a malformed one is no decision at all.
+ */
+export declare function extractVerdict(transcript: string, maxGaps: number): GoalGapVerdict | null;
+/**
+ * Ask, once.
+ *
+ * Every failure direction returns `ok: false` rather than a verdict, because
+ * both verdicts cost something: `satisfied` ends a goal, `incomplete` spends
+ * one of a small number of plan revisions. A truncated run that exits zero is
+ * caught by the envelope, which is the only thing that can tell a finished
+ * answer from a stopped one.
+ */
+export declare function evaluateGoalGap(input: GoalGapInput, deps: GoalGapDeps): Promise<GoalGapOutcome>;
+//# sourceMappingURL=goal-gap.d.ts.map