looply-cli 0.0.0-stage → 0.2.0

package/dist/governed-run.js

@@ -0,0 +1,406 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVIDENCE_MAX_CHARS = exports.EVIDENCE_MAX_LINES = void 0;
+exports.governedServerOf = governedServerOf;
+exports.runGovernedAction = runGovernedAction;
+exports.evidenceLines = evidenceLines;
+exports.describeGovernedResult = describeGovernedResult;
+const governed_approvals_1 = require("./governed-approvals");
+const governed_broker_1 = require("./governed-broker");
+const core_1 = require("@looply/core");
+const config_1 = require("./config");
+/**
+ * The governed surface, narrowed out of the full client.
+ *
+ * BUILT HERE RATHER THAN AT THE CALL SITE, and that is not tidiness. The
+ * composition root is on a list of files asserted to contain no claim
+ * vocabulary at all, and writing these six lines there would put the words back
+ * into exactly the file the guard exists to keep clean. It also keeps the
+ * narrowing discipline `openGoalServer` already follows: the client itself
+ * never leaves the function that made it.
+ */
+function governedServerOf(client) {
+    return {
+        projectApproval: (p, id) => client.projectApproval(p, id),
+        claimApproval: (p, id, input) => client.claimApproval(p, id, input),
+        beginExecution: (p, id, input) => client.beginExecution(p, id, input),
+        settleExecution: (p, id, input) => client.settleExecution(p, id, input),
+        assignExecutionResult: (p, id, runId) => client.assignExecutionResult(p, id, runId),
+        acknowledgeExecutionResult: (p, id, runId) => client.acknowledgeExecutionResult(p, id, runId),
+    };
+}
+async function runGovernedAction(deps, input) {
+    const say = deps.log ?? (() => { });
+    const refused = (because) => ({ kind: 'refused', because });
+    // ── the durable chain, before anything is read from the server ────────────
+    if (input.commandId === undefined || input.commandId.length === 0) {
+        // No Start spawned this. A direct `looply run` lands here and stops, which
+        // is the whole of C5 in one branch.
+        return refused('a governed action needs the Start that authorised it');
+    }
+    let reservation;
+    try {
+        reservation = await deps.reservations.reservationOf(input.approvalId);
+    }
+    catch (e) {
+        return refused(`the reservation for that action could not be read (${e.message})`);
+    }
+    if (reservation === null) {
+        return refused('no Start has reserved that action on this machine');
+    }
+    if (reservation.requestId !== input.commandId) {
+        return refused('that action was reserved by a different Start');
+    }
+    // ── the approval, as the server holds it NOW ──────────────────────────────
+    let row;
+    try {
+        // Reading ONE approval settles a window that has closed, so a claim can
+        // never be taken a moment after the authority ran out.
+        row = await deps.server.projectApproval(input.projectId, input.approvalId);
+    }
+    catch (e) {
+        // NO CONSEQUENTIAL EFFECT WITHOUT AN AUTHORITATIVE READ.
+        return refused(`the approval could not be read (${e.message})`);
+    }
+    if (row === null || typeof row !== 'object' || row.id !== input.approvalId) {
+        return refused('the server answered with something that is not that approval');
+    }
+    if (row.projectId !== input.projectId)
+        return refused('that approval belongs to another project');
+    if (row.goalId !== input.goalId || row.goalVersion !== input.goalVersion) {
+        return refused('that approval was raised for a different pursuit');
+    }
+    if (typeof row.actionFingerprint !== 'string' || row.actionFingerprint.length === 0) {
+        return refused('the server returned an approval this build cannot read');
+    }
+    // ── may this project publish at all? ─────────────────────────────────────
+    //
+    // ASKED HERE, BEFORE THE CLAIM, and never again afterwards. The action type
+    // comes from the row rather than from anything local, and `actionPublishes`
+    // fails closed for a type this build does not know.
+    if (row.state !== 'claimed' &&
+        (0, core_1.actionPublishes)(row.actionType) &&
+        !(0, config_1.mayPublish)(input.publishPolicy ?? 'never')) {
+        return refused(`${String(row.actionType)} would leave this machine, and this project's publish policy is ${input.publishPolicy ?? 'never'}`);
+    }
+    // ── the claim ─────────────────────────────────────────────────────────────
+    const claimRef = (0, governed_approvals_1.claimRefFor)(reservation);
+    let claimId;
+    if (row.state === 'claimed') {
+        // ALREADY OURS, or nobody's business. A machine that claimed and died
+        // leaves exactly this, and the reservation is what lets a later process
+        // present the identical key rather than ask for a second authority.
+        if (typeof row.claimId !== 'string' || row.claimId.length === 0) {
+            return refused('that approval is claimed and the server did not say by what');
+        }
+        claimId = row.claimId;
+    }
+    else if (row.state === 'approved') {
+        if (typeof row.version !== 'number') {
+            return refused('the server returned an approval with no version to claim against');
+        }
+        let taken;
+        try {
+            taken = await deps.server.claimApproval(input.projectId, input.approvalId, {
+                claimRef,
+                expectedFingerprint: row.actionFingerprint,
+                expectedVersion: row.version,
+            });
+        }
+        catch (e) {
+            // Denied, revoked, expired or context-stale between the read and the
+            // write, or another machine got there first. Nothing was attempted.
+            return refused(`that action could not be claimed (${e.message})`);
+        }
+        if (typeof taken.claimId !== 'string' || taken.claimId.length === 0) {
+            return refused('the claim was accepted and the server named no claim');
+        }
+        claimId = taken.claimId;
+    }
+    else {
+        // requested, denied, revoked, expired. A person has not answered, or has
+        // answered no — either way this is not a governed execution, and the
+        // ordinary resume path is what carries a refusal to a model.
+        return refused(`that approval is ${String(row.state)}, which is not something to carry out`);
+    }
+    // ── one execution identity, from the server ───────────────────────────────
+    let envelope;
+    try {
+        envelope = await deps.server.beginExecution(input.projectId, input.approvalId, {
+            claimId,
+            expectedFingerprint: row.actionFingerprint,
+        });
+    }
+    catch (e) {
+        return refused(`the attempt could not be recorded (${e.message})`);
+    }
+    const brokerEnvelope = brokerEnvelopeOf(envelope);
+    if (typeof brokerEnvelope === 'string')
+        return refused(brokerEnvelope);
+    /**
+     * IS THIS ATTEMPT STILL OURS TO MAKE?
+     *
+     * `begin` is idempotent, so an execution that already SETTLED comes back here
+     * looking exactly like one that has just been created. Without this the run
+     * went straight from the envelope to `reconcile`, and from
+     * `observed-not-executed` to EXECUTE — against an attempt that was already
+     * over.
+     *
+     * The daemon's Start gate refuses a Start while an attempt is ambiguous, so
+     * in ordinary running this was unreachable. But that is ONE guard, in another
+     * process, and "terminal for automation" has to be true in the module that
+     * ACTS, not only in the one that admits Starts. `takeClaim` carries four
+     * independent predicates for the same reason.
+     *
+     * The classification is `classifyGovernedRecovery`'s, so the rule about what
+     * may be done with an unfinished attempt is written once, purely, and not
+     * restated here where it could drift.
+     */
+    const recovery = (0, core_1.classifyGovernedRecovery)({
+        executionId: envelope.executionId,
+        approvalId: envelope.approvalId,
+        state: envelope.executionState,
+        // Neither field bears on whether this run may ACT, and the envelope does
+        // not carry them. Delivery is decided by the server when it is asked for,
+        // and asking here would be a second opinion about somebody else's row.
+        resultAssignedRunId: null,
+        acknowledged: false,
+    });
+    if (recovery.kind === 'blocked') {
+        return { kind: 'stop', because: recovery.because };
+    }
+    if (recovery.kind === 'deliver') {
+        // Settled, and the answer belongs to whoever the server gives it to. This
+        // run may ask for it, but it may not attempt the action again.
+        say('that action already finished — picking the answer up rather than repeating it');
+    }
+    // ── LOOK BEFORE ACTING, ALWAYS ────────────────────────────────────────────
+    //
+    // Not "after a crash": a process cannot know whether it is the one that
+    // crashed. The only observation that permits acting is the one that says
+    // nothing happened, and everything else is settled from what was seen.
+    let outcome;
+    let evidence = {};
+    let reason;
+    if (recovery.kind === 'deliver') {
+        /**
+         * ALREADY SETTLED. The attempt is over and nobody has been told, so this
+         * run may ask for the answer and may NOT make the attempt again.
+         *
+         * It falls through to the ordinary tail rather than taking a path of its
+         * own: settling with the outcome the row already holds is idempotent by
+         * design — the server hands the row back, writes nothing and emits no
+         * second event — so the assign-and-acknowledge that follows is reached with
+         * no duplicated logic and no second place for delivery to be decided.
+         */
+        outcome = envelope.executionState === 'succeeded' ? 'success' : 'failure';
+    }
+    else {
+        const looked = await deps.broker.reconcile(brokerEnvelope);
+        const decided = (0, core_1.decideFromObservation)((0, governed_broker_1.observationOf)(looked));
+        if (decided.kind === 'settle') {
+            outcome = decided.outcome;
+            if (looked.kind === 'observed-success')
+                evidence = looked.evidence;
+            if (looked.kind === 'observed-failure' || looked.kind === 'ambiguous')
+                reason = looked.safeReason;
+            say(`already done — recording what was found rather than doing it again`);
+        }
+        else {
+            const result = await deps.broker.execute(brokerEnvelope);
+            outcome = (0, governed_broker_1.outcomeOf)(result);
+            evidence = result.evidence;
+            if (result.kind !== 'success')
+                reason = result.safeReason;
+        }
+    }
+    // ── record it ─────────────────────────────────────────────────────────────
+    let settled;
+    try {
+        settled = await deps.server.settleExecution(input.projectId, envelope.executionId, {
+            claimId,
+            expectedVersion: envelope.executionVersion,
+            expectedFingerprint: envelope.actionFingerprint,
+            outcome,
+            ...(reason === undefined ? {} : { reason }),
+            evidence,
+        });
+    }
+    catch (e) {
+        // The effect may be in the world and the record may not be. NOT a refusal
+        // that lets the run carry on: the next Start reconciles this same execution
+        // and finds out, which is the only safe way to learn.
+        return {
+            kind: 'stop',
+            because: `that action was attempted and the result could not be recorded (${e.message})`,
+        };
+    }
+    if (settled.state === 'ambiguous') {
+        // TERMINAL FOR AUTOMATION. No retry, no new claim, no new execution, and
+        // nothing to tell a model — the plan it would produce from "it may or may
+        // not have happened" is to try again.
+        return {
+            kind: 'stop',
+            because: 'nobody can tell whether that action happened — this one needs you',
+        };
+    }
+    if (settled.state !== 'succeeded' && settled.state !== 'failed') {
+        return { kind: 'stop', because: `that attempt is ${String(settled.state)}` };
+    }
+    // ── one run owns the answer ───────────────────────────────────────────────
+    try {
+        await deps.server.assignExecutionResult(input.projectId, envelope.executionId, input.runId);
+    }
+    catch (e) {
+        // Another run already took it, and it is never reassigned. Telling a model
+        // twice that a consequential act succeeded reads as permission to build on
+        // work already done.
+        return { kind: 'stop', because: `that answer belongs to another run (${e.message})` };
+    }
+    const result = {
+        approvalId: input.approvalId,
+        executionId: envelope.executionId,
+        actionType: envelope.actionType,
+        actionFingerprint: envelope.actionFingerprint,
+        outcome: settled.state,
+        display: envelope.display,
+        safeEvidence: evidence,
+    };
+    try {
+        await deps.server.acknowledgeExecutionResult(input.projectId, envelope.executionId, input.runId);
+    }
+    catch (e) {
+        // The answer is in hand but nothing durably says so. Stopping is the safe
+        // direction: carrying on would leave a pursuit that can never be told the
+        // result again, because the assignment is never given to a second run.
+        return { kind: 'stop', because: `that answer could not be taken up (${e.message})` };
+    }
+    say(`${result.outcome === 'succeeded' ? 'done' : 'not done'} — ${result.display}`);
+    return { kind: 'done', result };
+}
+/**
+ * The server's envelope, checked into the shape the broker will only accept.
+ *
+ * The action is REBUILT through 7B1's parser rather than cast. A 200 is not an
+ * answer, and this is the last point at which what a broker is about to act on
+ * can still be told apart from what somebody sent.
+ */
+function brokerEnvelopeOf(env) {
+    if (env === null || typeof env !== 'object')
+        return 'the server answered with no execution';
+    if (typeof env.executionId !== 'string' || env.executionId.length === 0) {
+        return 'the server returned an execution with no id';
+    }
+    const parsed = (0, core_1.parseActionRequest)(env.actionRequest);
+    if (!parsed.ok)
+        return `the server returned an action this build cannot read — ${parsed.because}`;
+    if (parsed.request.fingerprint !== env.actionFingerprint) {
+        return 'the action the server returned is not the one this execution is for';
+    }
+    return {
+        executionId: env.executionId,
+        approvalId: env.approvalId,
+        claimId: env.claimId,
+        projectId: env.projectId,
+        machineId: env.machineId,
+        actionFingerprint: env.actionFingerprint,
+        actionRequest: parsed.request,
+        actionType: parsed.request.type,
+        display: env.display,
+        executionVersion: env.executionVersion,
+        executionState: env.executionState,
+    };
+}
+/**
+ * What a resumed model is told, as plain lines.
+ *
+ * PROSE, AND DELIBERATELY NOT JSON, for the reason `describeResolution` gives:
+ * the implementer's transcript is scanned for a structured declaration and the
+ * scan takes the FIRST one it finds, so a prompt containing something shaped
+ * like a request is a decoy an echoing model files for real.
+ */
+/**
+ * WHAT A GUARANTEE RESTS ON, SAID BESIDE THE GUARANTEE (the audit’s H-06).
+ *
+ * 🔴 THE TWO ARMS OF THIS SENTENCE DISAGREED ABOUT SCOPE. The failure arm says
+ * "nothing was changed outside this machine" and scopes itself; the success arm
+ * said "it happened exactly once" and named nothing — and the success arm is the
+ * one a model acts on, because it ends "do not ask for it a second time".
+ *
+ * ⚠️ AND WHAT MAKES IT TRUE IS NOT THIS MACHINE. The audit reads the fixture
+ * executor's `createExclusive` and calls exactly-once local, which invites the
+ * conclusion that two machines could each do it once. They cannot: a claim by a
+ * second machine is refused by the server with `already_claimed`, behind a
+ * unique index, and its idempotent arm is reached only by the same machine under
+ * its own key. Two fences at two layers — the server stops a second MACHINE, the
+ * executor's own record stops the same machine doing it twice.
+ *
+ * ⚠️ IT CLAIMS NO MORE THAN THAT. It does not say the effect was verified against
+ * a remote — only `git.push` can say that, and it says it in its own evidence —
+ * and it promises nothing about a machine that never claimed.
+ */
+exports.EVIDENCE_MAX_LINES = 6;
+/** Bound on one value, for the reason every free field on a prompt has one. */
+exports.EVIDENCE_MAX_CHARS = 120;
+/**
+ * The broker's own evidence, as lines in the shape this block already uses.
+ *
+ * 🔴 CARRIED HERE SINCE IT WAS WRITTEN AND READ BY NOTHING. `safeEvidence` is
+ * declared on the context, populated where the result is taken up, and shown by
+ * nobody — while for `git.push` it holds `remote`, `ref`, `sha` and the
+ * `observedSha` the executor actually read back: the observation that makes
+ * "exactly once" checkable rather than believable. Its own type calls it
+ * "bounded, deterministic where possible, and never secret".
+ *
+ * ⚠️ LINES, NEVER JSON. The block's own rule: the transcript is scanned for a
+ * structured declaration and the scan takes the first one it finds, so anything
+ * here shaped like a request is a decoy an echoing model files for real. This
+ * uses the same `  key : value` shape as the two lines above it and no other.
+ */
+function evidenceLines(e) {
+    const keys = Object.keys(e).sort();
+    const shown = keys.slice(0, exports.EVIDENCE_MAX_LINES);
+    const width = Math.max(0, ...shown.map((k) => k.length));
+    const lines = shown.map((k) => {
+        const raw = String(e[k]).replace(/\s+/g, ' ').trim();
+        const value = raw.length <= exports.EVIDENCE_MAX_CHARS
+            ? raw
+            : `${raw.slice(0, Math.max(0, exports.EVIDENCE_MAX_CHARS - 1)).trimEnd()}…`;
+        return `  ${k.padEnd(width)} : ${value}`;
+    });
+    // A cut list says so, for the same reason a cut sentence does.
+    if (keys.length > shown.length)
+        lines.push(`  … and ${keys.length - shown.length} more`);
+    return lines;
+}
+function describeGovernedResult(r) {
+    const head = r.outcome === 'succeeded'
+        ? 'A PERSON APPROVED SOMETHING AND IT HAS NOW BEEN DONE.'
+        : 'A PERSON APPROVED SOMETHING AND IT DID NOT HAPPEN.';
+    const tail = r.outcome === 'succeeded'
+        ? [
+            'It happened exactly once, and it will not happen again on its own.',
+            'That rests on the server rather than on this run: one claim was issued for',
+            'this approval and a second is refused. What the executor observed is above,',
+            'so you can check it rather than take it on trust.',
+            'Carry on from there. Do not ask for it a second time.',
+        ]
+        : [
+            'Nothing was changed outside this machine, and the authority for it is spent.',
+            'Plan around it. Asking for the same thing again needs a new approval, so',
+            'only do that if it is genuinely the way forward.',
+        ];
+    const seen = evidenceLines(r.safeEvidence);
+    return [
+        head,
+        '',
+        `  what was approved : ${r.display}`,
+        `  what happened     : ${r.outcome}`,
+        // Nothing at all when the executor recorded nothing — an empty heading would
+        // be an invitation to wonder what was withheld.
+        ...(seen.length === 0 ? [] : ['', 'what the executor saw:', ...seen]),
+        '',
+        ...tail,
+    ].join('\n');
+}
+//# sourceMappingURL=governed-run.js.map

package/dist/governed-run.js.map

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

package/dist/grant-reconcile.d.ts

@@ -0,0 +1,63 @@
+import type { GoalAutonomyState, GoalState, MachineSettlableState } from '@looply/core';
+import type { Reconciliation } from './autonomy-controller';
+import type { AutonomyProgress } from './autonomy-store';
+import type { ServerAutonomy } from './server-client';
+/**
+ * WHETHER THE SERVER STILL AUTHORIZES THIS GRANT.
+ *
+ * Pure, and shared by production and every test — there is one answer to "may
+ * this machine spend another of a person's Starts", and a second derivation
+ * living somewhere else is how two halves of a system come to disagree about
+ * somebody's permission.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * IDENTITY BEFORE STATE
+ *
+ * It is not enough that the server says `authorized`. Every immutable field of
+ * a grant is stamped at authorization and never moves again, so a response
+ * whose goal, version, generation, ceiling or expiry differs from the one this
+ * machine adopted is not a newer answer about the same grant — it is a
+ * different grant, or a build that disagrees about what a grant is. Either way
+ * the two records contradict each other, and this is not the place to pick a
+ * side.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * A NETWORK FAILURE IS NOT AN ENDING
+ *
+ * `unreachable` never becomes `cancelled`, `expired` or anything else terminal.
+ * Not reaching the server means this machine does not currently know whether it
+ * may spend — which is a reason to wait, and never a statement about a person's
+ * goal.
+ */
+/**
+ * The goal as the server holds it right now.
+ *
+ * Not optional. A machine cannot decide whether to spend another of a person's
+ * Starts without knowing whether the wording it was authorized for is still the
+ * wording — and an absent answer must not read as "unchanged".
+ */
+export interface CurrentGoal {
+    version: number;
+    state: GoalState;
+}
+/** What the machine holds locally, narrowed to what reconciliation compares. */
+export type LocalGrant = Pick<AutonomyProgress, 'controllerId' | 'goalId' | 'goalVersion' | 'maxStarts' | 'expiresAt'>;
+/** The immutable fields, named once so the comparison and its test agree. */
+export declare const IMMUTABLE_GRANT_FIELDS: readonly ["controllerId", "goalId", "goalVersion", "maxStarts", "expiresAt"];
+/**
+ * Compare what the server says with what this machine adopted.
+ *
+ * `remote` is null when the server could be reached but has no such grant —
+ * which is a contradiction rather than an absence, since the machine only holds
+ * grants the server minted.
+ */
+export declare function reconcileGrant(local: LocalGrant, remote: ServerAutonomy | null, goal: CurrentGoal | null, now: number): Reconciliation;
+/**
+ * The states a machine may report about itself, as the controller's vocabulary.
+ *
+ * The controller can conclude things the machine may not SAY — `cancelled` is
+ * the one that matters, because a person owns it. Mapping happens here so the
+ * refusal that produced it is not quietly rewritten somewhere further out.
+ */
+export declare function settlableState(state: GoalAutonomyState): MachineSettlableState | null;
+//# sourceMappingURL=grant-reconcile.d.ts.map

package/dist/grant-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-reconcile.d.ts","sourceRoot":"","sources":["../src/grant-reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,IAAI,CAC3B,gBAAgB,EAChB,cAAc,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CACtE,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,8EAMzB,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,cAAc,GAAG,IAAI,EAC7B,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,GAAG,EAAE,MAAM,GACV,cAAc,CAgEhB;AAcD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,IAAI,CAoBrF"}

package/dist/grant-reconcile.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMMUTABLE_GRANT_FIELDS = void 0;
+exports.reconcileGrant = reconcileGrant;
+exports.settlableState = settlableState;
+/** The immutable fields, named once so the comparison and its test agree. */
+exports.IMMUTABLE_GRANT_FIELDS = [
+    'controllerId',
+    'goalId',
+    'goalVersion',
+    'maxStarts',
+    'expiresAt',
+];
+/**
+ * Compare what the server says with what this machine adopted.
+ *
+ * `remote` is null when the server could be reached but has no such grant —
+ * which is a contradiction rather than an absence, since the machine only holds
+ * grants the server minted.
+ */
+function reconcileGrant(local, remote, goal, now) {
+    if (remote === null) {
+        return {
+            kind: 'mismatch',
+            because: `the server has no record of grant ${local.controllerId}`,
+        };
+    }
+    if (goal === null) {
+        // A grant for a goal the server does not have. Not an ending — a
+        // contradiction, and not something to pick a side of.
+        return { kind: 'mismatch', because: `the server has no goal ${local.goalId}` };
+    }
+    // IDENTITY FIRST. A grant that disagrees about what it is for cannot be
+    // reasoned about, whatever state it claims.
+    const differs = describeDrift(local, remote);
+    if (differs !== null)
+        return { kind: 'mismatch', because: differs };
+    // THE GOAL AS IT STANDS NOW, and this is REQUIRED rather than optional.
+    //
+    // It was optional and production supplied nothing, which meant "assume the
+    // wording has not changed" — a default that is wrong exactly when it matters.
+    // Nothing on the server writes `superseded`, so a grant for G@8 goes on
+    // reading `authorized` after somebody edits the goal to G@9, and the machine
+    // would spend a whole Start of their budget discovering, inside the bounded
+    // run, something the server already knew.
+    //
+    // Checked BEFORE the grant's own state: a grant that is live for wording that
+    // no longer exists is superseded whatever its row says.
+    if (goal.state === 'abandoned') {
+        return { kind: 'ended', state: 'abandoned', because: 'the goal was given up on' };
+    }
+    if (goal.version !== remote.goalVersion) {
+        return {
+            kind: 'ended',
+            state: 'superseded',
+            because: `the goal has moved to version ${goal.version}`,
+        };
+    }
+    if (remote.state !== 'authorized') {
+        return {
+            kind: 'ended',
+            state: remote.state,
+            because: remote.reason ?? `the pursuit is ${remote.state}`,
+        };
+    }
+    // The clock, checked against the SERVER's copy. A machine whose clock ran
+    // fast must not be able to extend an authorization, and one whose clock ran
+    // slow must not keep spending past the end.
+    const expires = Date.parse(remote.expiresAt);
+    if (Number.isNaN(expires)) {
+        return { kind: 'mismatch', because: 'the expiry on this grant cannot be read' };
+    }
+    if (expires <= now) {
+        return {
+            kind: 'ended',
+            state: 'budget_exhausted',
+            because: 'the time this grant was given has run out',
+        };
+    }
+    return { kind: 'active', maxStarts: remote.maxStarts };
+}
+/** The first immutable field the two records disagree about, in words. */
+function describeDrift(local, remote) {
+    for (const field of exports.IMMUTABLE_GRANT_FIELDS) {
+        const mine = local[field];
+        const theirs = remote[field];
+        if (mine !== theirs) {
+            return `this grant's ${field} is ${String(mine)} here and ${String(theirs)} on the server`;
+        }
+    }
+    return null;
+}
+/**
+ * The states a machine may report about itself, as the controller's vocabulary.
+ *
+ * The controller can conclude things the machine may not SAY — `cancelled` is
+ * the one that matters, because a person owns it. Mapping happens here so the
+ * refusal that produced it is not quietly rewritten somewhere further out.
+ */
+function settlableState(state) {
+    switch (state) {
+        case 'satisfied':
+        case 'human_required':
+        case 'budget_exhausted':
+        case 'superseded':
+        case 'abandoned':
+            return state;
+        case 'cancelled':
+            // A person's word. The machine may observe it and stop; it may not write
+            // it, so there is nothing to project.
+            return null;
+        case 'authorized':
+            // Not an ending at all.
+            return null;
+        default: {
+            const never = state;
+            throw new Error(`no settlable mapping for ${String(never)}`);
+        }
+    }
+}
+//# sourceMappingURL=grant-reconcile.js.map

package/dist/grant-reconcile.js.map

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