looply-cli 0.0.0-stage → 0.2.0

package/dist/governed-approvals.d.ts

@@ -0,0 +1,152 @@
+import type { AttemptFs } from './start-attempts';
+/**
+ * ONE START CARRIES ONE APPROVED ACTION, AND THE KEY IT USES SURVIVES A CRASH.
+ *
+ * When an owner approves a consequential action, the pursuit does not resume by
+ * itself — a person's next Start picks it up, claims the authority on the
+ * server, and drives the one execution it buys. Two Starts could arrive for the
+ * same approval, so one of them has to win, and this is where.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE SAME MECHANISM AS `ApprovalResumes`, AND THE OPPOSITE ANSWER FOR THE LOSER
+ *
+ * A resume claim that loses is not a refusal: the other Start has the answer, so
+ * this one carries on as an ordinary Start. That is right for a DENIAL, where
+ * carrying on means planning around something.
+ *
+ * It is wrong here. A Start that lost the reservation for an APPROVED action and
+ * carried on as ordinary would be a run doing everything except the one thing
+ * the person authorised, while another run does that thing — two runs, one of
+ * them pointless, both holding budget. So the loser is REFUSED, and told why.
+ *
+ * The server's claim is still what makes a second EFFECT impossible; this only
+ * decides which Start is worth spending. Security below, liveness here, and
+ * neither pretending to be the other.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THE FILE IS READ BY THE LOSER RATHER THAN JUST REFUSING IT
+ *
+ * A machine can claim an approval and then die before recording an attempt, and
+ * the claim is not a lease — nothing takes it back. The only way that authority
+ * ever completes is if a later process can present the SAME claim key and reach
+ * the idempotent arm of the server's claim rules, which match on machine AND
+ * key. So the key can never be derived from anything belonging to the process
+ * that happened to go first.
+ *
+ * That rules out the run id: a recovering run is a new run, would present a new
+ * key, and would be told `already_claimed` — a dead claim, which is the one
+ * outcome the claim design exists to avoid. It rules out randomness and memory
+ * for the same reason.
+ *
+ * So the key derives from the RESERVATION: the Start that first reserved this
+ * approval, written down durably at the moment it reserved. A recovery Start
+ * reads the record, re-derives a byte-identical key, and continues the same
+ * authority instead of asking for a second one.
+ *
+ * NOTE THE CONTRAST WITH `approvalClientRef`, which is deliberately run-scoped
+ * so that the same action asked for on Monday and on Thursday is two questions.
+ * Asking for authority and taking it are different operations, and the schema
+ * keeps their keys apart for exactly this reason: they need opposite properties.
+ */
+export declare const GOVERNED_APPROVALS_SCHEMA = 1;
+export interface GovernedReservation {
+    /** The approval this Start took responsibility for. */
+    approvalId: string;
+    /** The Start that took it. The claim key derives from this, for ever. */
+    requestId: string;
+    /** ISO, from the reserving process's own clock. */
+    reservedAt: string;
+}
+export type ReserveOutcome = 
+/** This Start holds it. Use `claimRefFor(reservation)`. */
+{
+    readonly ok: true;
+    readonly reservation: GovernedReservation;
+    readonly fresh: boolean;
+}
+/**
+ * Somebody else holds it.
+ *
+ * The record comes back anyway, because whether this is a race or a recovery
+ * is not a question this file can answer — it depends on what the SERVER says
+ * about the approval, which only the caller can ask. What is guaranteed is
+ * that the key in hand is the one the original Start used.
+ */
+ | {
+    readonly ok: false;
+    readonly held: GovernedReservation;
+    readonly because: string;
+}
+/** The record exists and cannot be read. Never treated as absent. */
+ | {
+    readonly ok: false;
+    readonly held: null;
+    readonly because: string;
+};
+/**
+ * THE CLAIM KEY, DERIVED AND NEVER CHOSEN.
+ *
+ * Two durable values and nothing else. Both are written down before any claim
+ * is attempted, so any later process holding the reservation computes the same
+ * string — which is precisely what the server's idempotent claim arm needs.
+ *
+ * The model reaches neither half.
+ */
+export declare function claimRefFor(reservation: GovernedReservation): string;
+export declare class GovernedApprovals {
+    private readonly stateDir;
+    private readonly fs;
+    private readonly deps;
+    /** Distinguishes two temp files written by one process. See `takeOver`. */
+    private static writes;
+    constructor(stateDir: string, fs: AttemptFs, deps?: {
+        now?: () => number;
+    });
+    private get dir();
+    private path;
+    /**
+     * Take responsibility for carrying this approved action out, if nobody has.
+     *
+     * `createExclusive` is the whole mechanism: the operating system hands the
+     * file to exactly one caller, and the loser finds out from the filesystem
+     * rather than from a read it took a moment earlier. An in-process guard would
+     * not survive two daemons, or one daemon and a person at a terminal.
+     */
+    reserve(approvalId: string, requestId: string): Promise<ReserveOutcome>;
+    /**
+     * TAKE A RESERVATION OVER FOR A LATER START, WHEN THE SERVER SAYS THE FIRST
+     * ONE IS GONE.
+     *
+     * `reserve` is one-shot on purpose: a second Start finding a record is
+     * normally a RACE, and letting it win would mean two runs carrying one
+     * authority. But the same one-shot record also wedged every recovery. A Start
+     * that reserved an approval and died left a record no later Start could
+     * satisfy, `runGovernedAction` refuses a reservation naming a different Start,
+     * and the approval stayed `claimed` for ever — so nothing could ever go and
+     * look at an attempt nobody finished.
+     *
+     * 🔴 THE CALLER MUST HAVE ASKED THE SERVER FIRST. This is only correct where
+     * the gate says `claimed`, `executing` or `result-pending` — i.e. where the
+     * server has ALREADY recorded that authority was taken. That is not a
+     * courtesy; it is what makes the rewrite harmless:
+     *
+     *   - the claim key derives from the reservation, and it MUST stay
+     *     byte-identical for the server's idempotent claim arm;
+     *   - but `runGovernedAction` only ever computes that key on the `approved`
+     *     branch. Where the approval is already `claimed` it takes `claimId` from
+     *     the SERVER and never looks at the derived one.
+     *
+     * So on exactly the arms this is allowed for, the key it changes is a key
+     * nothing reads. On the arm where the key matters, `reserve` still refuses.
+     *
+     * ⚠️ AND IT DOES NOT WEAKEN THE C5 CHAIN. The chain is "the DAEMON wrote a
+     * reservation naming the Start it is about to spawn"; argv still proves
+     * nothing, and the boundary being defended — the MODEL, which cannot reach
+     * `.looply/state`, cannot spawn a run and cannot see this file — is untouched.
+     * What changes is only that the daemon may write that record twice.
+     */
+    takeOver(approvalId: string, requestId: string): Promise<ReserveOutcome>;
+    /** What was reserved for this approval, or null. Unreadable is null, not a throw. */
+    reservationOf(approvalId: string): Promise<GovernedReservation | null>;
+}
+//# sourceMappingURL=governed-approvals.d.ts.map

package/dist/governed-approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governed-approvals.d.ts","sourceRoot":"","sources":["../src/governed-approvals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAK3C,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;CACpB;AAOD,MAAM,MAAM,cAAc;AACxB,2DAA2D;AACzD;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AAC3F;;;;;;;GAOG;GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACtF,qEAAqE;GACnE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM,CAEpE;AAED,qBAAa,iBAAiB;IAK1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;gBAGP,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,SAAS,EACb,IAAI,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAGpD,OAAO,KAAK,GAAG,GAEd;IAED,OAAO,CAAC,IAAI;IAIZ;;;;;;;OAOG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA6C7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAmC9E,qFAAqF;IAC/E,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;CAK7E"}

package/dist/governed-approvals.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovernedApprovals = exports.GOVERNED_APPROVALS_SCHEMA = void 0;
+exports.claimRefFor = claimRefFor;
+/**
+ * ONE START CARRIES ONE APPROVED ACTION, AND THE KEY IT USES SURVIVES A CRASH.
+ *
+ * When an owner approves a consequential action, the pursuit does not resume by
+ * itself — a person's next Start picks it up, claims the authority on the
+ * server, and drives the one execution it buys. Two Starts could arrive for the
+ * same approval, so one of them has to win, and this is where.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE SAME MECHANISM AS `ApprovalResumes`, AND THE OPPOSITE ANSWER FOR THE LOSER
+ *
+ * A resume claim that loses is not a refusal: the other Start has the answer, so
+ * this one carries on as an ordinary Start. That is right for a DENIAL, where
+ * carrying on means planning around something.
+ *
+ * It is wrong here. A Start that lost the reservation for an APPROVED action and
+ * carried on as ordinary would be a run doing everything except the one thing
+ * the person authorised, while another run does that thing — two runs, one of
+ * them pointless, both holding budget. So the loser is REFUSED, and told why.
+ *
+ * The server's claim is still what makes a second EFFECT impossible; this only
+ * decides which Start is worth spending. Security below, liveness here, and
+ * neither pretending to be the other.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THE FILE IS READ BY THE LOSER RATHER THAN JUST REFUSING IT
+ *
+ * A machine can claim an approval and then die before recording an attempt, and
+ * the claim is not a lease — nothing takes it back. The only way that authority
+ * ever completes is if a later process can present the SAME claim key and reach
+ * the idempotent arm of the server's claim rules, which match on machine AND
+ * key. So the key can never be derived from anything belonging to the process
+ * that happened to go first.
+ *
+ * That rules out the run id: a recovering run is a new run, would present a new
+ * key, and would be told `already_claimed` — a dead claim, which is the one
+ * outcome the claim design exists to avoid. It rules out randomness and memory
+ * for the same reason.
+ *
+ * So the key derives from the RESERVATION: the Start that first reserved this
+ * approval, written down durably at the moment it reserved. A recovery Start
+ * reads the record, re-derives a byte-identical key, and continues the same
+ * authority instead of asking for a second one.
+ *
+ * NOTE THE CONTRAST WITH `approvalClientRef`, which is deliberately run-scoped
+ * so that the same action asked for on Monday and on Thursday is two questions.
+ * Asking for authority and taking it are different operations, and the schema
+ * keeps their keys apart for exactly this reason: they need opposite properties.
+ */
+exports.GOVERNED_APPROVALS_SCHEMA = 1;
+/** One trailing newline, spelled once so no template mangles the escape. */
+const NEWLINE = String.fromCharCode(10);
+/**
+ * THE CLAIM KEY, DERIVED AND NEVER CHOSEN.
+ *
+ * Two durable values and nothing else. Both are written down before any claim
+ * is attempted, so any later process holding the reservation computes the same
+ * string — which is precisely what the server's idempotent claim arm needs.
+ *
+ * The model reaches neither half.
+ */
+function claimRefFor(reservation) {
+    return `govern:${reservation.requestId}:${reservation.approvalId}`;
+}
+class GovernedApprovals {
+    stateDir;
+    fs;
+    deps;
+    /** Distinguishes two temp files written by one process. See `takeOver`. */
+    static writes = 0;
+    constructor(stateDir, fs, deps = {}) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+        this.deps = deps;
+    }
+    get dir() {
+        return `${this.stateDir}/governed-approvals`;
+    }
+    path(approvalId) {
+        return `${this.dir}/${approvalId}.json`;
+    }
+    /**
+     * Take responsibility for carrying this approved action out, if nobody has.
+     *
+     * `createExclusive` is the whole mechanism: the operating system hands the
+     * file to exactly one caller, and the loser finds out from the filesystem
+     * rather than from a read it took a moment earlier. An in-process guard would
+     * not survive two daemons, or one daemon and a person at a terminal.
+     */
+    async reserve(approvalId, requestId) {
+        if (approvalId.length === 0)
+            return { ok: false, held: null, because: 'no approval was named' };
+        // Path safety, not validation theatre: the id becomes a filename, and an id
+        // carrying a separator would write outside the directory this owns.
+        if (/[^A-Za-z0-9_-]/.test(approvalId)) {
+            return { ok: false, held: null, because: `${approvalId} is not a usable approval id` };
+        }
+        if (requestId.length === 0) {
+            return { ok: false, held: null, because: 'no Start was named' };
+        }
+        const reservation = {
+            approvalId,
+            requestId,
+            reservedAt: new Date(this.deps.now?.() ?? Date.now()).toISOString(),
+        };
+        const body = { schema: exports.GOVERNED_APPROVALS_SCHEMA, reservation };
+        await this.fs.mkdir(this.dir);
+        try {
+            await this.fs.createExclusive(this.path(approvalId), JSON.stringify(body, null, 2) + '\n');
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            const held = await this.reservationOf(approvalId);
+            if (held === null) {
+                // Present and unreadable. NOT treated as absent, and not overwritten:
+                // the file may name the key an in-flight claim is using, and inventing
+                // a new one would ask the server for a second authority.
+                return {
+                    ok: false,
+                    held: null,
+                    because: 'another Start holds this action and its record cannot be read',
+                };
+            }
+            if (held.requestId === requestId) {
+                // This very Start, asking again. A dropped response, not a race.
+                return { ok: true, reservation: held, fresh: false };
+            }
+            return {
+                ok: false,
+                held,
+                because: 'another Start is already carrying this action out',
+            };
+        }
+        return { ok: true, reservation, fresh: true };
+    }
+    /**
+     * TAKE A RESERVATION OVER FOR A LATER START, WHEN THE SERVER SAYS THE FIRST
+     * ONE IS GONE.
+     *
+     * `reserve` is one-shot on purpose: a second Start finding a record is
+     * normally a RACE, and letting it win would mean two runs carrying one
+     * authority. But the same one-shot record also wedged every recovery. A Start
+     * that reserved an approval and died left a record no later Start could
+     * satisfy, `runGovernedAction` refuses a reservation naming a different Start,
+     * and the approval stayed `claimed` for ever — so nothing could ever go and
+     * look at an attempt nobody finished.
+     *
+     * 🔴 THE CALLER MUST HAVE ASKED THE SERVER FIRST. This is only correct where
+     * the gate says `claimed`, `executing` or `result-pending` — i.e. where the
+     * server has ALREADY recorded that authority was taken. That is not a
+     * courtesy; it is what makes the rewrite harmless:
+     *
+     *   - the claim key derives from the reservation, and it MUST stay
+     *     byte-identical for the server's idempotent claim arm;
+     *   - but `runGovernedAction` only ever computes that key on the `approved`
+     *     branch. Where the approval is already `claimed` it takes `claimId` from
+     *     the SERVER and never looks at the derived one.
+     *
+     * So on exactly the arms this is allowed for, the key it changes is a key
+     * nothing reads. On the arm where the key matters, `reserve` still refuses.
+     *
+     * ⚠️ AND IT DOES NOT WEAKEN THE C5 CHAIN. The chain is "the DAEMON wrote a
+     * reservation naming the Start it is about to spawn"; argv still proves
+     * nothing, and the boundary being defended — the MODEL, which cannot reach
+     * `.looply/state`, cannot spawn a run and cannot see this file — is untouched.
+     * What changes is only that the daemon may write that record twice.
+     */
+    async takeOver(approvalId, requestId) {
+        const first = await this.reserve(approvalId, requestId);
+        // Free, or already ours. Nothing to take over, and no rewrite.
+        if (first.ok)
+            return first;
+        // Present and UNREADABLE is not taken over. It may name the key an
+        // in-flight claim is using, and this cannot tell that from a corrupt file.
+        if (first.held === null)
+            return first;
+        if (first.held.requestId === requestId)
+            return { ok: true, reservation: first.held, fresh: false };
+        const reservation = {
+            approvalId,
+            requestId,
+            reservedAt: new Date(this.deps.now?.() ?? Date.now()).toISOString(),
+        };
+        const body = { schema: exports.GOVERNED_APPROVALS_SCHEMA, reservation };
+        /**
+         * WRITTEN ASIDE AND RENAMED, NEVER IN PLACE.
+         *
+         * `writeFile` onto the live path truncates first, so a crash, a full disk or
+         * a killed daemon mid-write leaves a TORN reservation — and a torn one is
+         * unreadable, which both `reserve` and `takeOver` refuse for ever. The one
+         * operation added to recover a wedged approval would otherwise have been
+         * able to create a worse wedge than the one it fixes.
+         *
+         * The temp name is PRIVATE TO THIS WRITER, for the same reason
+         * `LedgerStore` makes its own: a shared `.tmp` is some other writer's
+         * half-written file, and renaming that over the real one is precisely the
+         * failure this exists to prevent.
+         */
+        const tmp = `${this.path(approvalId)}.${process.pid}.${(GovernedApprovals.writes += 1)}.tmp`;
+        await this.fs.writeFile(tmp, JSON.stringify(body, null, 2) + NEWLINE);
+        await this.fs.rename(tmp, this.path(approvalId));
+        return { ok: true, reservation, fresh: true };
+    }
+    /** What was reserved for this approval, or null. Unreadable is null, not a throw. */
+    async reservationOf(approvalId) {
+        const text = await this.fs.readFile(this.path(approvalId));
+        if (text === null)
+            return null;
+        return readReservation(text);
+    }
+}
+exports.GovernedApprovals = GovernedApprovals;
+function readReservation(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const file = parsed;
+    if (typeof file !== 'object' || file === null)
+        return null;
+    if (file.schema !== exports.GOVERNED_APPROVALS_SCHEMA)
+        return null;
+    const r = file.reservation;
+    if (typeof r !== 'object' || r === null)
+        return null;
+    if (typeof r['approvalId'] !== 'string' || r['approvalId'] === '')
+        return null;
+    if (typeof r['requestId'] !== 'string' || r['requestId'] === '')
+        return null;
+    if (typeof r['reservedAt'] !== 'string')
+        return null;
+    return {
+        approvalId: r['approvalId'],
+        requestId: r['requestId'],
+        reservedAt: r['reservedAt'],
+    };
+}
+//# sourceMappingURL=governed-approvals.js.map

package/dist/governed-approvals.js.map

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

package/dist/governed-broker.d.ts

@@ -0,0 +1,169 @@
+import { type ActionRequest, type BrokerOutcome, type ReconcileObservation } from '@looply/core';
+import type { AttemptFs } from './start-attempts';
+/**
+ * THE ONE THING IN LOOPLY THAT MAY CAUSE A CONSEQUENTIAL EFFECT.
+ *
+ * Everything before this point is about deciding: a model proposed an exact
+ * action, a person authorised it, one machine took the right to try, and the
+ * server minted one execution identity for that try. This is the try.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * IT TAKES AN ENVELOPE, AND AN ENVELOPE IS NOT AN ACTION
+ *
+ * The only input is what the SERVER returned when the execution was created:
+ * the action it holds, re-parsed and re-verified against the fingerprint a
+ * person approved. There is deliberately no overload that accepts an
+ * `ActionRequest`, a `PendingActionSignal`, or anything a run assembled — the
+ * signature is the boundary. A broker that could be handed an action by its
+ * caller is a broker that can be handed one action wearing the fingerprint of
+ * another, and every check upstream would still have passed.
+ *
+ * IT IS NOT MODEL-CALLABLE. There is no MCP tool for it, no tool name, and no
+ * path from `tool-bridge` to here. The model's entire surface is read, glob,
+ * grep, edit and write, inside a container, and none of those can reach this
+ * module or the place it writes.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THREE ANSWERS, AND THE THIRD IS THE IMPORTANT ONE
+ *
+ * `success` means the effect is proven to exist. `failure` means it is proven
+ * NOT to exist. `ambiguous` means nobody can tell, and it is the honest answer
+ * to a timeout, a killed process, a connection that died mid-response, and any
+ * result this build does not recognise.
+ *
+ * Recording an ambiguous outcome as a failure is the single most dangerous lie
+ * available here, because a failure invites a retry and a retry of something
+ * that already happened is the duplicate effect this whole phase exists to
+ * prevent. No code path below produces `failure` from the absence of evidence.
+ */
+/** What the server said this execution is. Never assembled locally. */
+export interface GovernedExecutionEnvelope {
+    executionId: string;
+    approvalId: string;
+    claimId: string;
+    projectId: string;
+    machineId: string;
+    actionFingerprint: string;
+    actionRequest: ActionRequest;
+    actionType: string;
+    display: string;
+    executionVersion: number;
+    executionState: string;
+}
+/** Bounded, deterministic where possible, and never secret. */
+export interface BrokerEvidence {
+    readonly [key: string]: string | number | boolean;
+}
+export type BrokerResult = {
+    readonly kind: 'success';
+    readonly evidence: BrokerEvidence;
+}
+/** PROVEN not to have happened. Never inferred from silence. */
+ | {
+    readonly kind: 'failure';
+    readonly safeReason: string;
+    readonly evidence: BrokerEvidence;
+} | {
+    readonly kind: 'ambiguous';
+    readonly safeReason: string;
+    readonly evidence: BrokerEvidence;
+};
+export type ReconcileResult = {
+    readonly kind: 'observed-success';
+    readonly evidence: BrokerEvidence;
+}
+/** The executor's own evidence shows no effect. The ONLY arm that permits a retry. */
+ | {
+    readonly kind: 'observed-not-executed';
+} | {
+    readonly kind: 'observed-failure';
+    readonly safeReason: string;
+} | {
+    readonly kind: 'ambiguous';
+    readonly safeReason: string;
+};
+export declare function outcomeOf(result: BrokerResult): BrokerOutcome;
+export declare function observationOf(result: ReconcileResult): ReconcileObservation;
+/**
+ * One kind of consequential action, and how to do it.
+ *
+ * `reconcile` is not optional and is not a courtesy. A broker call that does not
+ * come back leaves exactly one question — did it happen — and an executor with
+ * no way to answer it can only ever produce `ambiguous`, which holds the pursuit
+ * for a person for ever. Any action type added here must be able to look.
+ */
+export interface ActionExecutor {
+    readonly type: string;
+    execute(env: GovernedExecutionEnvelope): Promise<BrokerResult>;
+    reconcile(env: GovernedExecutionEnvelope): Promise<ReconcileResult>;
+}
+export interface GovernedActionBroker {
+    execute(env: GovernedExecutionEnvelope): Promise<BrokerResult>;
+    reconcile(env: GovernedExecutionEnvelope): Promise<ReconcileResult>;
+}
+/**
+ * WHERE A BROKER-OWNED EFFECT LIVES.
+ *
+ * Under the machine's own Looply home, which is outside every project worktree
+ * and is one of the roots contained execution may never be granted. The
+ * contained tool worker confines every path to the project root — lexically and
+ * physically, resolving reparse points — so a model cannot read this, write it,
+ * or delete it, whatever it asks for.
+ *
+ * That is what makes the tests worth anything. A fixture effect written inside
+ * the repository would be an effect the thing under test can forge, and
+ * "exactly one effect happened" would be a claim about a file the model could
+ * have produced itself.
+ */
+export declare function fixtureEffectDir(home?: string): string;
+/**
+ * ONE FILE PER EXECUTION, CREATED IF ABSENT, NEVER APPENDED TO.
+ *
+ * The idempotency primitive is `createExclusive`, the same one the Start
+ * reservation and the resume claim use, and the reason is the same: the
+ * operating system hands the file to exactly one caller.
+ *
+ * A SHARED LEDGER WOULD NOT DO. Two processes appending to one file both
+ * succeed, and the duplicate is discovered afterwards by reading it back —
+ * which is a check, not a constraint, and it is exactly the check a crashed
+ * process never runs. Here the second attempt is refused by the filesystem
+ * before it writes a byte.
+ */
+export interface FixtureEffectRecord {
+    executionId: string;
+    approvalId: string;
+    claimId: string;
+    actionFingerprint: string;
+    /** Deterministic from the action, so a reconciliation can recognise its own work. */
+    effect: string;
+    at: string;
+}
+/**
+ * The fixture executor for `fixture.publish`.
+ *
+ * Inert in the world and real on this machine: it produces a durable artifact
+ * outside the model's reach, which is exactly the property a real executor will
+ * need and the only one the tests can check independently.
+ */
+export declare function fixturePublishExecutor(deps: {
+    fs: AttemptFs;
+    home?: string;
+    now?: () => number;
+    /** Injected so a test can make the effect fail or hang without faking the result. */
+    attempt?: (record: FixtureEffectRecord) => Promise<void>;
+}): ActionExecutor;
+/**
+ * Route an envelope to the executor for its action, or refuse it.
+ *
+ * FAILS CLOSED THREE TIMES OVER. The action type must be one Looply has
+ * registered, it must classify as consequential, and the stored request must
+ * still verify against its own fingerprint. An unregistered type is refused
+ * rather than assumed harmless — that is the branch that stops a tool added
+ * next year from executing simply because nothing has classified it yet.
+ *
+ * A refusal here is `failure`, not `ambiguous`, and that is correct rather than
+ * convenient: nothing was attempted, so no effect can exist, and saying so
+ * definitely is what lets the pursuit plan around it instead of holding.
+ */
+export declare function createGovernedBroker(executors: readonly ActionExecutor[]): GovernedActionBroker;
+//# sourceMappingURL=governed-broker.d.ts.map

package/dist/governed-broker.d.ts.map

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