@telora/daemon 0.22.187 → 0.22.208

package/dist/migrations/migration-claim-lifecycle.js

@@ -0,0 +1,198 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/focus/migration-claim-pass.test.ts,
+//   packages/daemon/src/migrations/migration-claim-lifecycle.test.ts,
+//   packages/daemon/src/queries/focus-unclaimed-migration.test.ts
+// PINNED-BY-END
+/** The empty decision: what an unreadable branch produces. */
+function nothing(readable) {
+    return { confirm: [], release: [], unclaimed: [], clearUnclaimed: false, readable };
+}
+/**
+ * The tag a recorded path implies.
+ *
+ * The record stores the number and the file, not the tag -- one text serves
+ * both the human reading it and the lifecycle reasoning over it, and a second
+ * stored field is a second thing to keep in step. Reading it back off the
+ * filename is exact for every file the declaration's own pattern matched.
+ */
+function tagFromRecordedPath(ordinal, path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const withoutOrdinal = base.startsWith(`${ordinal}_`) ? base.slice(ordinal.length + 1) : base;
+    return withoutOrdinal.replace(/\.[^.]+$/, '');
+}
+/** Confirm every claim whose file is on the branch; release the ended ones. */
+function decideClaims(claims, onBranch, onIntegration, focus, decision) {
+    for (const claim of claims) {
+        const file = onBranch.get(claim.ordinal);
+        if (file) {
+            // The file landed. Confirm with the tag the FILE carries -- a team is
+            // free to rename as it writes, and the file is the reality.
+            //
+            // Re-confirm only when what was RECORDED differs from what is there now.
+            // Comparing against `tag` (frozen intent) instead would differ forever
+            // for any team that renamed as it wrote, rewriting the row every tick.
+            if (claim.confirmedAt === null || claim.confirmedTag !== file.tag) {
+                decision.confirm.push({
+                    migrationClaimId: claim.migrationClaimId,
+                    ordinal: claim.ordinal,
+                    confirmedTag: file.tag,
+                });
+            }
+            continue;
+        }
+        // No file on the branch. Only a focus that has ENDED releases anything: a
+        // live focus simply has not written it yet.
+        if (focus.endedBecause === null)
+            continue;
+        // RELEASE REQUIRES ESTABLISHED ABSENCE FROM BOTH PLACES A FILE CAN BE.
+        // Absence from the branch is established above. Absence from INTEGRATION
+        // has to be established too, and for every claim -- not only confirmed
+        // ones. A claim can be unconfirmed simply because the confirm pass never
+        // ran before the branch merged: its file is on integration, and releasing
+        // it would hand a landed migration's number out a second time, which is
+        // the cleanup re-creating the failure it cleans up after.
+        if (onIntegration === null)
+            continue; // cannot prove it is gone -- hold
+        if (onIntegration.has(claim.ordinal))
+            continue; // it merged; the number stands
+        decision.release.push({
+            migrationClaimId: claim.migrationClaimId,
+            ordinal: claim.ordinal,
+            reason: focus.endedBecause,
+        });
+    }
+}
+/**
+ * Migrations on the branch that no claim accounts for, and whether an existing
+ * record may be cleared.
+ *
+ * DETECTING one is judged against the UNRELEASED claims and only against files
+ * the branch adds beyond integration -- a migration inherited from integration
+ * is someone else's already-landed work, and naming it would put the whole of
+ * history in front of the team on every tick.
+ *
+ * KEEPING one named is a different question, and conflating the two is how the
+ * record used to disappear without anyone resolving it. TWO WAYS IT VANISHED:
+ * the branch MERGES, so the file reads as "inherited" and the detection goes
+ * quiet; or the branch is PRUNED after merging (crash-recovery's merged-orphan
+ * cleanup deletes it), so there is no branch to see the file on at all. In both
+ * the team neither claimed the number nor removed the file, and in both the
+ * file is sitting on integration.
+ *
+ * So resolution is stated positively and is the ONLY thing that clears a
+ * record: a live claim now covers the ordinal, or the file is gone from the
+ * branch AND from integration -- really removed, not merely moved. Where
+ * integration cannot be read, nothing is resolved, because removal cannot be
+ * told from a merge.
+ */
+function decideUnclaimed(claims, onBranch, onIntegration, recorded, decision) {
+    const claimed = new Set(claims.map((c) => c.ordinal));
+    const named = new Set();
+    const alreadyRecorded = new Set(recorded.map((e) => e.ordinal));
+    for (const migration of onBranch.values()) {
+        if (claimed.has(migration.ordinal))
+            continue;
+        if (!alreadyRecorded.has(migration.ordinal)) {
+            // A NEW detection: inherited history is not this team's file.
+            if (onIntegration === null)
+                continue; // cannot tell inherited from new
+            if (onIntegration.has(migration.ordinal))
+                continue;
+        }
+        named.add(migration.ordinal);
+        decision.unclaimed.push({
+            ordinal: migration.ordinal,
+            tag: migration.tag,
+            path: migration.path,
+        });
+    }
+    if (recorded.length === 0)
+        return;
+    // A RECORDED ORDINAL THE BRANCH NO LONGER SHOWS IS NOT AUTOMATICALLY GONE.
+    // The common case is that it MERGED: the file is on integration, reads as
+    // inherited, and drops out of the walk above. If the caller re-renders the
+    // record from `unclaimed` alone, that ordinal is silently dropped from it --
+    // so with [0352, 0353] recorded, 0352 merged and 0353 still on the branch,
+    // re-recording leaves only 0353, and claiming 0353 then clears the record
+    // although 0352 was never claimed or removed. Unresolved state must survive
+    // a re-render, so it is carried here, sourced from integration (which is
+    // where the file now is).
+    for (const entry of recorded) {
+        const { ordinal } = entry;
+        if (claimed.has(ordinal) || named.has(ordinal))
+            continue;
+        const merged = onIntegration?.get(ordinal);
+        if (merged) {
+            // It MERGED. Sourced from integration, which is where the file now is.
+            named.add(ordinal);
+            decision.unclaimed.push({ ordinal: merged.ordinal, tag: merged.tag, path: merged.path });
+            continue;
+        }
+        if (onIntegration === null) {
+            // UNRESOLVABLE, and that is precisely when it must be kept. Integration
+            // could not be read, so "this merged" and "this was removed" are the same
+            // observation from here. `clearUnclaimed` already refuses to clear the
+            // record on this evidence -- but the caller RE-RENDERS the record from
+            // `unclaimed`, so an ordinal missing from that list is dropped from the
+            // record just the same, quietly, and only for the ordinals an outage made
+            // unknowable. Carried forward verbatim instead, from what the record
+            // itself said.
+            named.add(ordinal);
+            decision.unclaimed.push({
+                ordinal,
+                tag: tagFromRecordedPath(ordinal, entry.path),
+                path: entry.path,
+            });
+            continue;
+        }
+        // Integration WAS read and does not have it, and the branch does not
+        // either: really removed. It leaves the record.
+    }
+    decision.clearUnclaimed = recorded.every(({ ordinal }) => {
+        if (claimed.has(ordinal))
+            return true; // the team claimed it
+        if (named.has(ordinal))
+            return false; // still unresolved, still named
+        if (onIntegration === null)
+            return false; // removal cannot be told from a merge
+        return !onIntegration.has(ordinal); // gone from both: really removed
+    });
+}
+/**
+ * Decide what this focus's claims and files call for.
+ *
+ * @param claims       The focus's UNRELEASED claims.
+ * @param branch       What its branch holds (the reader's result).
+ * @param integration  What integration holds. Used to keep a confirmed claim
+ *                     whose file has merged and left the branch, and to tell a
+ *                     removed migration from a merged one.
+ * @param focus        The focus, and whether it has ended.
+ * @param recorded     Ordinals an existing unclaimed record already names.
+ *                     Once named, an ordinal stays named until the team
+ *                     RESOLVES it; see `decideUnclaimed`.
+ */
+export function decideClaimLifecycle(claims, branch, integration, focus, recorded = []) {
+    // A declaration problem is not a branch fact: nothing can be decided at all.
+    if (branch.kind === 'declarationUnreadable')
+        return nothing(false);
+    if (branch.kind === 'undeclared')
+        return nothing(true);
+    // A branch that could not be READ proves nothing about what it holds.
+    if (branch.kind === 'refUnreadable')
+        return nothing(false);
+    // The file is absent from the branch either because the branch was read and
+    // does not have it, or because there IS no branch -- a deleted one, or a
+    // focus that never got one. Both are established absence FROM THE BRANCH;
+    // neither is absence from INTEGRATION, which is asked separately.
+    const onBranch = branch.kind === 'read'
+        ? new Map(branch.inventory.migrations.map((m) => [m.ordinal, m]))
+        : new Map();
+    const onIntegration = integration.kind === 'read'
+        ? new Map(integration.inventory.migrations.map((m) => [m.ordinal, m]))
+        : null;
+    const decision = nothing(true);
+    decideClaims(claims, onBranch, onIntegration, focus, decision);
+    decideUnclaimed(claims, onBranch, onIntegration, recorded, decision);
+    return decision;
+}
+//# sourceMappingURL=migration-claim-lifecycle.js.map

package/dist/migrations/migration-claim-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-claim-lifecycle.js","sourceRoot":"","sources":["../../src/migrations/migration-claim-lifecycle.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,qEAAqE;AACrE,sEAAsE;AACtE,kEAAkE;AAClE,gBAAgB;AAmKhB,8DAA8D;AAC9D,SAAS,OAAO,CAAC,QAAiB;IAChC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACtF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,mBAAmB,CAAC,OAAe,EAAE,IAAY;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9F,OAAO,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC;AAKD,+EAA+E;AAC/E,SAAS,YAAY,CACnB,MAAiC,EACjC,QAA6C,EAC7C,aAAyD,EACzD,KAAqB,EACrB,QAA2B;IAE3B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEzC,IAAI,IAAI,EAAE,CAAC;YACT,sEAAsE;YACtE,4DAA4D;YAC5D,EAAE;YACF,yEAAyE;YACzE,uEAAuE;YACvE,uEAAuE;YACvE,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;gBAClE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;oBACpB,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;oBACxC,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,YAAY,EAAE,IAAI,CAAC,GAAG;iBACvB,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QAED,0EAA0E;QAC1E,4CAA4C;QAC5C,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI;YAAE,SAAS;QAE1C,uEAAuE;QACvE,yEAAyE;QACzE,uEAAuE;QACvE,yEAAyE;QACzE,0EAA0E;QAC1E,wEAAwE;QACxE,0DAA0D;QAC1D,IAAI,aAAa,KAAK,IAAI;YAAE,SAAS,CAAC,kCAAkC;QACxE,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,SAAS,CAAC,+BAA+B;QAE/E,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;YACpB,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,MAAM,EAAE,KAAK,CAAC,YAAY;SAC3B,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAS,eAAe,CACtB,MAAiC,EACjC,QAA6C,EAC7C,aAAyD,EACzD,QAA2B,EAC3B,QAA2B;IAE3B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAEhE,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC;YAAE,SAAS;QAC7C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5C,8DAA8D;YAC9D,IAAI,aAAa,KAAK,IAAI;gBAAE,SAAS,CAAC,iCAAiC;YACvE,IAAI,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC;gBAAE,SAAS;QACrD,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC7B,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC;YACtB,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,GAAG,EAAE,SAAS,CAAC,GAAG;YAClB,IAAI,EAAE,SAAS,CAAC,IAAI;SACrB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAElC,2EAA2E;IAC3E,0EAA0E;IAC1E,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,0EAA0E;IAC1E,4EAA4E;IAC5E,yEAAyE;IACzE,0BAA0B;IAC1B,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QAC1B,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,SAAS;QAEzD,MAAM,MAAM,GAAG,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,MAAM,EAAE,CAAC;YACX,uEAAuE;YACvE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACnB,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACzF,SAAS;QACX,CAAC;QAED,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,wEAAwE;YACxE,0EAA0E;YAC1E,uEAAuE;YACvE,uEAAuE;YACvE,wEAAwE;YACxE,0EAA0E;YAC1E,qEAAqE;YACrE,eAAe;YACf,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACnB,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC;gBACtB,OAAO;gBACP,GAAG,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC;gBAC7C,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,qEAAqE;QACrE,gDAAgD;IAClD,CAAC;IAED,QAAQ,CAAC,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE;QACvD,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,sBAAsB;QAC7D,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,gCAAgC;QACtE,IAAI,aAAa,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,CAAC,sCAAsC;QAChF,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,iCAAiC;IACvE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAiC,EACjC,MAAqB,EACrB,WAAqC,EACrC,KAAqB,EACrB,WAA8B,EAAE;IAEhC,6EAA6E;IAC7E,IAAI,MAAM,CAAC,IAAI,KAAK,uBAAuB;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;IACnE,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,sEAAsE;IACtE,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;IAE3D,4EAA4E;IAC5E,yEAAyE;IACzE,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,KAAK,MAAM;QACrC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QACjE,CAAC,CAAC,IAAI,GAAG,EAA0B,CAAC;IAEtC,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,KAAK,MAAM;QAC/C,CAAC,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;QACtE,CAAC,CAAC,IAAI,CAAC;IAET,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC/D,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACrE,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/migrations/migration-held-set.d.ts

@@ -0,0 +1,171 @@
+/**
+ * What a product's migration numbers are CURRENTLY held by, across every ref
+ * that matters -- integration and every live focus branch.
+ *
+ * WHY THIS LIVES IN THE DAEMON AND THE GRANT DOES NOT
+ * ---------------------------------------------------
+ * The two halves of claiming a number sit on opposite sides of a boundary, and
+ * neither half can move:
+ *
+ *   - Seeing what is held needs the REPO. It is a git-tree read across several
+ *     refs, and only the daemon has the repository on disk. The product-api
+ *     edge function has no git (`sessionStateHandler` says as much: "the server
+ *     has no git access").
+ *   - Granting a number needs the DATABASE, atomically. Two teams claiming at
+ *     once must be separated by a constraint, not by timing, and the constraint
+ *     is the partial unique index on `product_migration_claims`.
+ *
+ * So the held set has to cross the gap. The daemon PUBLISHES it -- per product,
+ * on the heartbeat, the way `metadata.verificationPostures` is published for
+ * the same reason ("posture is workstation-local config the API cannot itself
+ * derive; the daemon is the single source") -- and the edge handler grants
+ * against the published set plus the live claims it can see itself.
+ *
+ * THE OTHER SHAPE, AND WHY NOT IT. Serving the whole claim from the daemon was
+ * the alternative. It collapses: either the daemon reads-then-inserts, which is
+ * the two-worktrees race reborn one altitude up, or it still calls an edge
+ * handler to do the atomic insert -- in which case that handler exists anyway
+ * and the daemon is an extra hop in front of it. The decision is recorded on
+ * the delivery.
+ *
+ * WHY A STALE SNAPSHOT IS SAFE, AND WHERE IT IS NOT
+ * -------------------------------------------------
+ * The published set is only ever an INPUT TO THE CANDIDATE. It never decides
+ * anything: the unique index decides. A snapshot read a minute ago can make the
+ * handler propose a number that a concurrent claim just took -- and the insert
+ * fails, and the handler recomputes. A stale snapshot costs a retry; it cannot
+ * cost a collision.
+ *
+ * What it CAN cost is a number granted against branch tips that have since
+ * moved -- a migration landed on a sibling branch after the snapshot was taken,
+ * and no claim was recorded for it (a team that skipped the rule). That is why
+ * every reading carries `tips`: the exact sha each ref was at when it was read.
+ * The confirm pass re-checks a claim whose snapshot predates the tips its branch
+ * actually had. A snapshot with no recorded staleness is a silent read-then-write
+ * race wearing a different hat, so the tips are not optional decoration.
+ *
+ * WHAT AN UNREADABLE REF DOES
+ * ---------------------------
+ * It makes the whole reading INCOMPLETE, and the reading says so. A ref that
+ * could not be read proves nothing about what it holds, and a held set quietly
+ * missing one branch's numbers tells the allocator those numbers are free --
+ * failing open on exactly the question being asked. An incomplete reading is
+ * published as incomplete and the handler refuses to grant against it.
+ *
+ * A ref that does not EXIST is different and is not incompleteness: a deleted
+ * branch holds nothing. That distinction is the reader's (`migration-inventory`)
+ * and is simply carried through here.
+ *
+ * @module migration-held-set
+ */
+import { type MigrationInventoryDeps, type JournalEntry } from './migration-inventory.js';
+import { type MigrationScheme } from './migration-manifest.js';
+/** A ref to read, and the tip it was at when it was read. */
+export interface HeldRefReading {
+    /** The ref as asked for (a branch name). */
+    ref: string;
+    /** The commit the ref was at, or null when it does not exist / was unreadable. */
+    tip: string | null;
+    /** What happened: read / absent / unreadable. */
+    outcome: 'read' | 'absent' | 'unreadable';
+    /** Ordinals this ref holds. Empty for absent or unreadable. */
+    ordinals: string[];
+    /** Why it could not be read, when `outcome` is 'unreadable'. */
+    reason?: string;
+}
+/** Every number a product's refs currently hold, and how completely it is known. */
+export interface MigrationHeldSet {
+    /** The declared scheme, carried so the grant need not re-read the declaration. */
+    scheme: MigrationScheme;
+    /**
+     * Every ordinal held by any ref that was read, de-duplicated and sorted.
+     * String sort IS ordinal sort: both schemes are zero-padded fixed width.
+     */
+    held: string[];
+    /** Per-ref detail, including the tip each reading was taken at. */
+    readings: HeldRefReading[];
+    /**
+     * False when ANY ref was unreadable. An incomplete held set must not be
+     * granted against: the numbers of the ref that failed would read as free.
+     */
+    complete: boolean;
+    /** When this reading was taken (epoch ms). */
+    readAt: number;
+}
+/** A product that declares no migration numbering, or one whose declaration is broken. */
+export type MigrationHeldSetResult = {
+    kind: 'undeclared';
+} | {
+    kind: 'declarationUnreadable';
+    reason: string;
+} | {
+    kind: 'held';
+    heldSet: MigrationHeldSet;
+};
+/** Seams: the inventory reader's, plus the clock (so a test can pin `readAt`). */
+export interface MigrationHeldSetDeps extends MigrationInventoryDeps {
+    now: () => number;
+}
+/** Real git, real declaration reader, real clock. */
+export declare function defaultMigrationHeldSetDeps(): MigrationHeldSetDeps;
+/**
+ * The ordinals a ref's JOURNAL registers, normalised to the product's width.
+ *
+ * WHY THE JOURNAL COUNTS AT ALL. On a hand-registered product the journal is
+ * half the record: a migration is its numbered filename AND its `idx` entry. A
+ * ref can register an idx whose file is not visible -- mid-rename, a file
+ * removed but the entry left, a journal edited ahead of the file -- and a held
+ * set built from filenames alone reports that number free. The allocator then
+ * grants it, and the product ends with two migrations at one position, which is
+ * the failure this whole mechanism exists to remove.
+ *
+ * WHY NORMALISATION IS REQUIRED, NOT COSMETIC. The journal records `idx` as a
+ * NUMBER (352) while the filename carries it zero-padded (`0352`). Unioning the
+ * two raw would put both `352` and `0352` in the held set -- two widths -- and
+ * the candidate rule refuses a product whose ordinals are not one fixed width.
+ * A naive union would therefore break every claim on exactly the products this
+ * fixes. So a journal idx is padded to the width the product uses.
+ *
+ * WHEN IT CANNOT BE NORMALISED, THE READING IS INCOMPLETE. An idx wider than
+ * the width, one that is not a plain number, and -- the case this argument was
+ * missing -- ANY idx at all when no width is established. Dropping such an
+ * entry silently is the fail-open; guessing a placement is worse; and using the
+ * raw value is worst, because it is neither dropped nor refused but published
+ * as though it were a number on this product. It is reported instead, and the
+ * caller refuses to grant against the reading rather than granting around the
+ * part it could not read.
+ *
+ * @param width The product's ordinal width, or null when none is established.
+ *              See `resolveOrdinalWidth`.
+ */
+export declare function journalOrdinals(journal: readonly JournalEntry[] | undefined, width: number | null): {
+    ordinals: string[];
+    unnormalisable: string[];
+};
+/**
+ * The width this product's ordinals are padded to, across the WHOLE reading.
+ *
+ * A PROPERTY OF THE PRODUCT, NOT OF ONE REF. It used to be derived per ref,
+ * from that ref's own filenames -- so a ref holding only a journal entry had no
+ * width, and a ref holding files a moment before the reading had one. The width
+ * a number is padded to cannot depend on which branch you happen to be looking
+ * at; it is the product's numbering convention, and it is read once for the
+ * whole reading.
+ *
+ * Declaration first (it fixes the width authoritatively -- no inventoried file
+ * can disagree with a pattern it had to match), then the files, which must all
+ * agree. Null when neither establishes one: a product with no declared width
+ * and no files. Every journal entry is then unnormalisable and the reading is
+ * incomplete, which is the honest answer -- the alternative was publishing a
+ * bare `351` and granting `352` into a four-digit namespace.
+ */
+export declare function resolveOrdinalWidth(declaredWidth: number | null, fileOrdinals: readonly string[]): number | null;
+/**
+ * Read every ref and fold what they hold into one set.
+ *
+ * @param repoPath The product's repo root.
+ * @param refs     Integration plus every live focus branch. Duplicates are fine
+ *                 (a focus whose branch IS integration reads once).
+ */
+export declare function computeMigrationHeldSet(repoPath: string, refs: readonly string[], deps?: MigrationHeldSetDeps): MigrationHeldSetResult;
+//# sourceMappingURL=migration-held-set.d.ts.map

package/dist/migrations/migration-held-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-held-set.d.ts","sourceRoot":"","sources":["../../src/migrations/migration-held-set.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EAElB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAErF,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,CAAC;IAC1C,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,MAAM,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mEAAmE;IACnE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0FAA0F;AAC1F,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAEhD,kFAAkF;AAClF,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,qDAAqD;AACrD,wBAAgB,2BAA2B,IAAI,oBAAoB,CAElE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,EAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBlD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,MAAM,GAAG,IAAI,CAIf;AA2ID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,oBAAoD,GACzD,sBAAsB,CA4CxB"}