@tacuchi/agent-workflow-cli 22.4.1 → 23.0.0

package/dist/application/claims-ledger.js

@@ -0,0 +1,330 @@
+/**
+ * The durable trace of a reservation's whole life — and the only place it lives.
+ *
+ * A claim used to leave exactly one artifact: the marker file itself. That made
+ * the reservation visible while it existed and completely unaccountable once it
+ * did not. Nothing recorded who had claimed a correlative, why it went away, or
+ * whether it had ever been published — so a released number was
+ * indistinguishable from one that never existed, and a recovery had no evidence
+ * to stand on.
+ *
+ * This ledger is append-only and lives under `.workflow/`, deliberately OUTSIDE
+ * `docs/`: the corpus is for documents somebody published, and a reservation's
+ * history is not one. Putting it in `docs/` would make the trace itself look like
+ * a spec or a plan, which is the confusion the whole change exists to end.
+ *
+ * It answers three different questions with one file, which is why there is one
+ * file and not three:
+ *   - **what happened** — the audit trail, still readable after the session's
+ *     folder is gone, because a session is deleted and its history should not be;
+ *   - **which correlatives came back** — a number released and never published is
+ *     eligible again, and only this record knows the difference;
+ *   - **what may no longer be published** — a revocation is a durable fence, and
+ *     a fence that lives in memory is not one.
+ *
+ * Append-only is load-bearing for the third: a record that can be rewritten is a
+ * fence somebody can lift, and the revocation has to be irrevocable to be worth
+ * anything.
+ */
+import { join } from "node:path";
+import { compareCorrelatives, isCorrelative } from "../domain/correlative.js";
+/** Lives next to HISTORY.md: workspace state, never workspace corpus. */
+const LEDGER_FILE = "claims.jsonl";
+const LEDGER_VERSION = 1;
+/** The identity as one comparable string. Order is fixed so it is stable. */
+export function claimKey(claim) {
+    return `${claim.category}/${claim.correlative}-${claim.name}@${claim.owner}`;
+}
+export function ledgerPath(paths) {
+    return join(paths.cwdRoot(), LEDGER_FILE);
+}
+/**
+ * Add one record. Append-only by construction: there is no update and no delete.
+ *
+ * Two callers, two different guarantees, and the difference is worth stating
+ * rather than glossing:
+ *
+ * - the **claim** appends inside the workspace lock that mints the slot, so the
+ *   reservation and its record cannot separate;
+ * - the **release** at session close does NOT hold that lock — the close's
+ *   reservation sweep is deliberately outside it and non-fatal — so its record
+ *   is ordered by `O_APPEND` alone.
+ *
+ * That is sufficient here only because a record is one short line: `O_APPEND`
+ * makes a single small write atomic, so two processes appending cannot interleave
+ * halves of a record. It would stop being sufficient the day a record grew past a
+ * pipe buffer, which is the reason a record is one line and not a pretty-printed
+ * object.
+ */
+export async function appendClaimEvent(fs, paths, event) {
+    const record = { version: LEDGER_VERSION, ...event };
+    await fs.appendText(ledgerPath(paths), `${JSON.stringify(record)}\n`);
+}
+/** Every record, oldest first. A missing ledger reads as empty, never as an error. */
+export async function readClaimEvents(fs, paths) {
+    const path = ledgerPath(paths);
+    if (!(await fs.exists(path)))
+        return { events: [], unreadable: 0 };
+    const raw = await fs.readText(path);
+    const events = [];
+    let unreadable = 0;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const parsed = parseEvent(trimmed);
+        if (parsed === null)
+            unreadable += 1;
+        else
+            events.push(parsed);
+    }
+    return { events, unreadable };
+}
+function parseEvent(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const candidate = value;
+    const claim = candidate.claim;
+    if (typeof candidate.at !== "string" ||
+        typeof candidate.event !== "string" ||
+        typeof claim !== "object" ||
+        claim === null ||
+        typeof claim.category !== "string" ||
+        typeof claim.correlative !== "string" ||
+        typeof claim.name !== "string" ||
+        typeof claim.owner !== "string") {
+        return null;
+    }
+    return value;
+}
+/**
+ * The claims this owner still holds: a `claimed` with no terminal record after it.
+ *
+ * Derived rather than stored, because the ledger is append-only and a "still
+ * open" flag would be exactly the kind of mutable state that makes an
+ * append-only log pointless. `published`, `released` and `revoked` are all
+ * terminal — the first spends the number, the other two end the owner's hold on
+ * it — so any of them closes the claim for this reading.
+ */
+export function openClaimsOf(events, owner) {
+    const open = new Map();
+    for (const event of events) {
+        if (event.claim.owner !== owner)
+            continue;
+        const key = claimKey(event.claim);
+        if (event.event === "claimed")
+            open.set(key, event.claim);
+        else
+            open.delete(key);
+    }
+    return [...open.values()];
+}
+/**
+ * The claim a workspace-relative `docs/<category>/<NNN>-<name>` path would be.
+ *
+ * `null` for anything that is not a numbered document inside a category, which
+ * is what keeps this from reading a claim out of an unrelated destination.
+ *
+ * Exported because it is the ONE place that decides how a path splits into a
+ * claim identity: the publication reads it to credit a completion and the
+ * retirement reads it to name what it is giving back, and two spellings of that
+ * split would join to two different histories for the same slot.
+ */
+export function claimOfDocsPath(path, owner) {
+    const parts = path.split("/").filter((segment) => segment.length > 0);
+    const docsAt = parts.indexOf("docs");
+    if (docsAt === -1 || parts.length - docsAt !== 3)
+        return null;
+    const category = parts[docsAt + 1];
+    const file = parts[docsAt + 2];
+    if (category === undefined || file === undefined)
+        return null;
+    const match = /^(\d{3,})-(.+)$/.exec(file);
+    if (match?.[1] === undefined || match[2] === undefined)
+        return null;
+    return { category, correlative: match[1], name: match[2], owner };
+}
+/**
+ * Which claims of this owner a publication just completed.
+ *
+ * The whole decision of "did this write finish a reservation of mine?" lives
+ * here rather than at the publication site, and getting it wrong is durable in
+ * both directions:
+ *
+ * - **Under-crediting** leaves a claim open about a correlative that is holding a
+ *   published document, which invites a later recovery to release live bytes.
+ *   That is why `already_applied` is handled here: the re-entry that finds the
+ *   document already on disk reports `written: []`, and crediting only `written`
+ *   left the claim open FOREVER — every retry answers the same way, so nothing
+ *   could ever correct it. When the apply says already-applied, every destination
+ *   holds exactly the proposed bytes, so the destinations are the candidates.
+ * - **Over-crediting** writes a permanent "spent forever" fence on a correlative
+ *   the session never reserved. So a candidate only counts when it closes one of
+ *   THIS owner's open claims, read from the ledger — not from the shape of
+ *   whatever proposal happened to carry the write. Every flow's publication goes
+ *   through this same path, not only the one whose single artifact is its own slot.
+ *
+ * Both directions had a surviving mutant when this logic sat inlined at the call
+ * site, which is the other reason it is here: it is testable in isolation.
+ */
+export function completedClaimsIn(events, owner, publication) {
+    const candidates = publication.already_applied ? publication.destinations : publication.written;
+    if (candidates.length === 0)
+        return [];
+    const open = new Set(openClaimsOf(events, owner).map((claim) => claimKey(claim)));
+    if (open.size === 0)
+        return [];
+    const completed = [];
+    for (const path of candidates) {
+        const claim = claimOfDocsPath(path, owner);
+        if (claim === null || !open.has(claimKey(claim)))
+            continue;
+        completed.push(claim);
+    }
+    return completed;
+}
+/**
+ * Every claim this ledger has ever revoked.
+ *
+ * Membership is permanent by construction: one `revoked` record fences the claim
+ * forever, and no later record lifts it. That is what "irrevocable" has to mean
+ * to be worth anything — a fence somebody can reopen is not a fence, and the
+ * whole reason a recovery may free a correlative is that no late publication can
+ * still land on it.
+ */
+function revokedKeys(events) {
+    const revoked = new Set();
+    for (const event of events) {
+        if (event.event === "revoked")
+            revoked.add(claimKey(event.claim));
+    }
+    return revoked;
+}
+/** Whether this exact claim is fenced. */
+export function isRevoked(events, claim) {
+    return revokedKeys(events).has(claimKey(claim));
+}
+/**
+ * The destinations of a publication that a revocation forbids.
+ *
+ * Checked at the publication point rather than at the release: once a recovery
+ * has freed a correlative, the slot no longer exists on disk, so a late sealed
+ * proposal would read its destination as a plain creation and land a document on
+ * a number that may already belong to somebody else. The fence is the only thing
+ * standing between "the reservation was recovered" and "two documents share a
+ * correlative".
+ */
+export function revokedAmong(events, owner, destinations) {
+    const revoked = revokedKeys(events);
+    if (revoked.size === 0)
+        return [];
+    const blocked = [];
+    for (const path of destinations) {
+        const claim = claimOfDocsPath(path, owner);
+        if (claim === null || !revoked.has(claimKey(claim)))
+            continue;
+        blocked.push(claim);
+    }
+    return blocked;
+}
+/**
+ * Destinations that look like a numbered document of this owner's category space.
+ *
+ * Used only to scope the fail-closed: a ledger with unreadable lines cannot prove
+ * the ABSENCE of a revocation, so a publication that could be completing a
+ * reservation must refuse rather than guess. A write that is not a numbered
+ * document in a category cannot be a reservation, so it is never held up by a
+ * ledger it does not depend on.
+ */
+export function claimShapedAmong(owner, destinations) {
+    const shaped = [];
+    for (const path of destinations) {
+        const claim = claimOfDocsPath(path, owner);
+        if (claim !== null)
+            shaped.push(claim);
+    }
+    return shaped;
+}
+function sameSlot(claim, slot) {
+    return (claim.category === slot.category &&
+        claim.correlative === slot.correlative &&
+        claim.name === slot.name);
+}
+/**
+ * Whether this slot was ever published, by anyone.
+ *
+ * Asked BEFORE the bytes are interpreted, because bytes lie in one direction that
+ * matters: a published document whose content happens to be empty looks exactly
+ * like the legacy placeholder a recovery is allowed to delete. The record knows
+ * the difference and the file does not, so the record decides.
+ */
+export function wasPublished(events, slot) {
+    return events.some((event) => event.event === "published" && sameSlot(event.claim, slot));
+}
+/**
+ * The owner whose claim on this slot is still open, or `null`.
+ *
+ * Lets a file that is no longer its own intact marker — emptied by an editor, a
+ * `> file`, a checkout — still be attributed to the session that reserved it.
+ * Without this the same file reads as ownerless, and freeing it would give the
+ * correlative back with no fence for the owner that is still holding it.
+ */
+export function openOwnerOfSlot(events, slot) {
+    let open = null;
+    for (const event of events) {
+        if (!sameSlot(event.claim, slot))
+            continue;
+        open = event.event === "claimed" ? event.claim : null;
+    }
+    return open;
+}
+/**
+ * Correlatives of this category that were released and never published, ascending.
+ *
+ * The second reason this ledger exists. Minting used to compute `max + 1` and
+ * probe forward only, so a correlative given back in the middle of the range was
+ * lost forever — this workspace's own `docs/plans` has a permanent hole at `033`
+ * from exactly that. Only the record can tell a number that came back from one
+ * that never existed, because the disk looks identical either way.
+ *
+ * Judged per (category, correlative) and by the LAST terminal record, not by the
+ * presence of any: a number can be released, re-claimed and then published, and
+ * after that it is spent. `published` is the one state that never becomes eligible
+ * again — a correlative holding a document is not a free number, whatever else
+ * the history says about it.
+ *
+ * Ascending because the rule has to be deterministic and reproducible, and
+ * lowest-first also fills the holes rather than growing the range. The caller is
+ * still responsible for skipping anything taken on disk: this answers "did the
+ * record give it back", never "is the name free right now".
+ */
+export function eligibleCorrelatives(events, category) {
+    const state = new Map();
+    for (const event of events) {
+        if (event.claim.category !== category)
+            continue;
+        if (event.event === "claimed")
+            continue;
+        state.set(event.claim.correlative, event.event);
+    }
+    const eligible = [];
+    for (const [correlative, last] of state) {
+        // Validated before it can be handed out. A single semi-valid ledger line
+        // would otherwise put a non-correlative into the mint, where it becomes an
+        // unrecognizable filename or a throw on the comparator.
+        if (last === "released" && isCorrelative(correlative))
+            eligible.push(correlative);
+    }
+    // `compareCorrelatives` and not a hand-rolled numeric sort: it is bigint-based,
+    // so it stays correct past the width where `parseInt` loses precision — and a
+    // second ordering rule for the same domain type is a second thing to keep true.
+    return eligible.sort(compareCorrelatives);
+}
+//# sourceMappingURL=claims-ledger.js.map

package/dist/application/claims-ledger.js.map

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

package/dist/application/claims-recovery.js

@@ -0,0 +1,338 @@
+/**
+ * Recovering a reservation whose owner never came back.
+ *
+ * The normal cycle needs none of this: completing, closing and cancelling all
+ * resolve a reservation through its owner. What is left is the run that simply
+ * died — no publication, no close, nothing terminal — and left a correlative held
+ * by a session that is never going to finish it. There is deliberately NO clock
+ * here: a reservation does not expire, because "it has been a while" is not
+ * evidence that nobody is coming, and a timer that frees a slot somebody is still
+ * writing into would be worse than the stranded number it fixes.
+ *
+ * So the release is explicit, authorized, and ORDERED. The order is the whole
+ * safety argument and it runs one way only:
+ *
+ *   1. the reservation is still exactly its own intact marker — otherwise the
+ *      bytes are somebody's work and this is not a recovery;
+ *   2. a revocation is SEALED, durably and irrevocably, scoped to that one claim;
+ *   3. and only then is the slot released.
+ *
+ * Step 2 before step 3 is not a preference. Once the file is gone the correlative
+ * is eligible again, so a late sealed proposal from the dead owner — one that was
+ * approved before the recovery and lands after it — would write a document onto a
+ * number somebody else may already hold. The fence is what makes that publication
+ * fail instead of collide, and a fence written after the release is a window. If
+ * the seal cannot be written, the recovery FAILS and releases nothing: a released
+ * slot with no fence is the one outcome this must never produce.
+ *
+ * The revocation belongs to the CLAIM, never to the session. The owner may be
+ * alive and working on other things, and revoking its whole session to reclaim
+ * one number would destroy work to tidy up a correlative.
+ */
+import { join } from "node:path";
+import { leadingCorrelative } from "../domain/correlative.js";
+import { reservationOwnerOf } from "../domain/reservation.js";
+import { appendClaimEvent, claimKey, isRevoked, openOwnerOfSlot, readClaimEvents, wasPublished, } from "./claims-ledger.js";
+import { withCwdLock } from "./lock-service.js";
+import { semanticDigest } from "./semantic-operation/protocol.js";
+import { CLOSED_MARKER, listSessionFolders } from "./session-resolver.js";
+/** The identity a reservation's slot maps to, or `null` for an unattributable one. */
+function claimOfSlot(slot) {
+    if (slot.owner === null)
+        return null;
+    return {
+        category: slot.category,
+        correlative: slot.correlative,
+        name: slot.name,
+        owner: slot.owner,
+    };
+}
+/**
+ * The slot a numbered file is, or `null` when it is a document.
+ *
+ * The LEDGER decides before the bytes do, and the order is the fix for a real
+ * defect: classifying from bytes alone made every empty numbered file an
+ * ownerless legacy placeholder — releasable with no fence — including a published
+ * document whose content happens to be empty, and including a reservation whose
+ * marker somebody emptied. In the first case a recovery deleted a published
+ * document; in the second it gave a correlative back while its real owner still
+ * held an open claim on it. Both times the record held the answer and only the
+ * bytes were consulted.
+ */
+function slotOf(category, fileName, text, events, activeOwners) {
+    const correlative = leadingCorrelative(fileName);
+    if (correlative === null)
+        return null;
+    const name = fileName.slice(correlative.length + 1);
+    const slot = { category, correlative, name };
+    // Published is terminal and terminal means "a document lives here": whatever
+    // its bytes look like, it is not a slot anybody may free.
+    if (wasPublished(events, slot))
+        return null;
+    const markerOwner = reservationOwnerOf(text);
+    const base = { path: `docs/${category}/${fileName}`, category, correlative, name };
+    if (markerOwner !== null) {
+        return {
+            ...base,
+            kind: "reservation",
+            owner: markerOwner,
+            ownerActive: activeOwners.has(markerOwner),
+            revoked: false,
+            intact: true,
+        };
+    }
+    // Real content and no marker: a document, by its bytes this time.
+    if (text.trim().length > 0)
+        return null;
+    // Empty. If the ledger still holds an open claim on this slot, it is that
+    // owner's reservation with damaged bytes — not nobody's placeholder.
+    const open = openOwnerOfSlot(events, slot);
+    if (open !== null) {
+        return {
+            ...base,
+            kind: "reservation",
+            owner: open.owner,
+            ownerActive: activeOwners.has(open.owner),
+            revoked: false,
+            intact: false,
+        };
+    }
+    return {
+        ...base,
+        kind: "legacy-placeholder",
+        owner: null,
+        ownerActive: null,
+        revoked: false,
+        intact: false,
+    };
+}
+/**
+ * Walk `docs/` into `into`, throwing on the first unreadable thing.
+ *
+ * The accumulator is the caller's so a failure still reports what it managed to
+ * see: an unreadable category is a different fact from an empty one, and folding
+ * the two would let the board say "no reservations" about a directory nobody
+ * could open.
+ */
+async function walkSlots(fs, docs, events, activeOwners, into) {
+    for (const category of await fs.list(docs)) {
+        if (category.type !== "dir")
+            continue;
+        for (const entry of await fs.list(category.path)) {
+            // The filename decides whether the bytes are worth reading at all. Reading
+            // every file in every docs/ subdirectory to then discard most of them on the
+            // first line of `slotOf` made a scan that runs on EVERY board projection pay
+            // for the whole corpus.
+            if (entry.type !== "file" || leadingCorrelative(entry.name) === null)
+                continue;
+            const slot = slotOf(category.name, entry.name, await fs.readText(entry.path), events, activeOwners);
+            if (slot === null)
+                continue;
+            const claim = claimOfSlot(slot);
+            slot.revoked = claim !== null && isRevoked(events, claim);
+            into.push(slot);
+        }
+    }
+}
+/**
+ * The session folders that are still open.
+ *
+ * Read once per scan, because the sanctioned action for a slot depends on it: a
+ * reservation of a live session is that session's to finish or close, and only a
+ * slot nobody is finishing may be recovered.
+ */
+async function activeSessionFolders(fs, paths) {
+    const active = new Set();
+    try {
+        for (const folder of await listSessionFolders(fs, paths.cwdSessionsDir())) {
+            if (await fs.exists(join(folder.path, CLOSED_MARKER)))
+                continue;
+            active.add(folder.name);
+        }
+    }
+    catch {
+        // An unreadable sessions dir means nobody can be proven alive. The fallback is
+        // the conservative one: with no owner known to be active, no slot is offered
+        // for recovery on the strength of liveness it could not check.
+    }
+    return active;
+}
+/**
+ * Every reservation and legacy placeholder under `docs/`.
+ *
+ * Walks each immediate subdirectory rather than a list of categories, for the
+ * same reason the close's sweep does: the claim mechanism is category-agnostic,
+ * and a hardcoded list is a second place to update the day something else claims
+ * a number.
+ *
+ * A failure comes back WITH its reason and with whatever was already seen. An
+ * unreadable `docs/` is not an empty one, and swallowing the difference would let
+ * the board answer "no reservations" about a directory nobody could open.
+ */
+export async function scanSlots(fs, paths) {
+    const docs = join(paths.workspaceDir(), "docs");
+    const slots = [];
+    const ledger = await readClaimEvents(fs, paths);
+    const activeOwners = await activeSessionFolders(fs, paths);
+    const sorted = () => slots.sort((a, b) => a.path.localeCompare(b.path));
+    if (!(await fs.exists(docs)))
+        return { slots };
+    try {
+        await walkSlots(fs, docs, ledger.events, activeOwners, slots);
+    }
+    catch (error) {
+        return {
+            slots: sorted(),
+            error: `no se pudo revisar docs/ en busca de reservas: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return { slots: sorted() };
+}
+function sealRecovery(body) {
+    return { ...body, digest: semanticDigest(body) };
+}
+/** The proposal for one slot, or why there is none. */
+export async function previewRecovery(fs, paths, target) {
+    const scan = await scanSlots(fs, paths);
+    const slot = scan.slots.find((candidate) => candidate.path === target);
+    if (slot === undefined) {
+        return {
+            error: `'${target}' no es una reserva ni un placeholder legacy de este workspace`,
+            action: scan.error ??
+                "corré 'aw claims' para ver los correlativos recuperables; un documento publicado no se recupera",
+        };
+    }
+    return {
+        proposal: sealRecovery({
+            version: 1,
+            target: slot.path,
+            kind: slot.kind,
+            claim: claimOfSlot(slot),
+            requires_no_producer_confirmation: !slot.intact,
+            resuming: slot.revoked,
+        }),
+    };
+}
+/**
+ * Seal the fence, then release — and never the other way round.
+ *
+ * The whole thing runs under the workspace lock, which is not decoration: the
+ * check that the slot is still what the preview saw, the seal and the removal are
+ * three separate awaits, and without the lock a sanctioned publication could pass
+ * its own fence, take the lock, write its document and have this function delete
+ * it a moment later — leaving the correlative recorded as both spent-forever and
+ * eligible-again, with the published document silently gone. Its two siblings hold
+ * the lock across exactly this span for exactly this reason.
+ *
+ * It also re-derives its own proposal inside the lock instead of trusting the
+ * digest it was handed: the approval proves a person authorized THIS recovery, not
+ * that the world still looks the way it did when they read it.
+ */
+export async function applyRecovery(fs, paths, input) {
+    const outcome = await withCwdLock(fs, paths, () => recoverUnderLock(fs, paths, input));
+    if ("error" in outcome && "action" in outcome)
+        return outcome;
+    if ("error" in outcome) {
+        return {
+            error: `no se pudo tomar el candado del workspace: ${outcome.error}`,
+            action: "esperá a que otro flujo lo libere y volvé a aplicar la recuperación",
+        };
+    }
+    return outcome;
+}
+async function recoverUnderLock(fs, paths, input) {
+    const preview = await previewRecovery(fs, paths, input.target);
+    if ("error" in preview)
+        return preview;
+    const proposal = preview.proposal;
+    if (proposal.digest !== input.approval) {
+        return {
+            error: "la aprobación no corresponde a la recuperación vigente",
+            action: `volvé a mirarla con 'aw claims recover ${input.target}' y aprobá el digest que devuelve`,
+        };
+    }
+    if (proposal.requires_no_producer_confirmation && input.noProducerConfirmed !== true) {
+        return {
+            error: proposal.kind === "legacy-placeholder"
+                ? `'${input.target}' es un placeholder legacy ambiguo: sus bytes no prueban que nadie vaya a escribirlo`
+                : `'${input.target}' ya no tiene el marcador intacto de su dueño: alguien escribió ahí`,
+            action: "confirmá explícitamente que no queda productor capaz de escribir ese destino antes de liberar su correlativo",
+        };
+    }
+    const claim = proposal.claim;
+    if (claim !== null && !proposal.resuming) {
+        // The fence FIRST. If this throws, nothing was released and the slot is
+        // exactly as it was: the recovery failed, which is the correct outcome.
+        // Releasing first would leave a window where the correlative is eligible and
+        // a late sealed publication can still land on it.
+        await appendClaimEvent(fs, paths, {
+            at: new Date().toISOString(),
+            event: "revoked",
+            claim,
+            cause: `aw claims recover: recuperación autorizada de ${proposal.target}`,
+        });
+    }
+    // Recorded before the file goes, same reason as the close's release: a slot
+    // freed with no line saying so is the state this ledger exists to end. The
+    // identity is the SLOT's, so it joins to its own history by claimKey — an
+    // ownerless placeholder still records the category, correlative and name it
+    // gave back, and only its owner field says nobody held it.
+    await appendClaimEvent(fs, paths, {
+        at: new Date().toISOString(),
+        event: "released",
+        claim: claim ?? {
+            category: slotIdentityOf(proposal.target).category,
+            correlative: slotIdentityOf(proposal.target).correlative,
+            name: slotIdentityOf(proposal.target).name,
+            owner: LEGACY_OWNERLESS,
+        },
+        cause: claim === null
+            ? "aw claims recover: placeholder legacy liberado con confirmación explícita de que no queda productor"
+            : `aw claims recover: liberado tras revocar ${claimKey(claim)}`,
+    });
+    await fs.remove(join(paths.workspaceDir(), proposal.target));
+    return {
+        applied: {
+            target: proposal.target,
+            revoked: claim,
+            released: true,
+            resumed: proposal.resuming,
+            digest: proposal.digest,
+        },
+    };
+}
+/** The owner field of a slot that never had one. Never a session folder. */
+const LEGACY_OWNERLESS = "(placeholder legacy sin dueño)";
+/** `docs/<cat>/<NNN>-<name>` split the same way every ledger record splits it. */
+function slotIdentityOf(target) {
+    const parts = target.split("/");
+    const category = parts[1] ?? "";
+    const file = parts[2] ?? "";
+    const correlative = leadingCorrelative(file) ?? "";
+    return {
+        category,
+        correlative,
+        name: correlative.length > 0 ? file.slice(correlative.length + 1) : file,
+    };
+}
+/**
+ * The one action this slot sanctions, named per slot.
+ *
+ * A reservation of a live session is resumed or closed by its owner; only a slot
+ * nobody is finishing gets recovered. And a slot whose bytes are not its own
+ * intact marker carries the confirmation flag in the command itself, so the
+ * operator sees the extra assertion being asked of them before they type it.
+ */
+export function sanctionedActionFor(slot) {
+    // A live owner's reservation is NOT a recovery candidate. Naming the recovery
+    // here was destructive: the board handed the running session the one command
+    // that revokes its own slot irrevocably, and the flow reads this very field as
+    // "the sanctioned next command". Closing the owner releases an intact
+    // reservation as part of closing, which is the action that actually resolves it.
+    if (slot.ownerActive === true && slot.owner !== null) {
+        return `aw session-close --code ${slot.owner}`;
+    }
+    const confirm = slot.intact ? "" : " --confirm-no-producer";
+    return `aw claims recover ${slot.path}${confirm}`;
+}
+//# sourceMappingURL=claims-recovery.js.map