@telora/mcp-products 0.22.159 → 0.22.165

package/dist/handlers/index.d.ts

@@ -30,3 +30,4 @@ export { registerEndpointTools, handleEndpointTool } from "./endpointHandlers.js
 export { registerServiceDefinitionTools, handleServiceDefinitionTool } from "./serviceDefinitionHandlers.js";
 export { registerStarterRepoTools, handleStarterRepoTool } from "./starterRepoHandlers.js";
 export { registerCodeObservationTools, handleCodeObservationCreate } from "./codeObservationHandlers.js";
+export { registerMigrationClaimTools, handleMigrationClaim } from "./migrationClaimHandlers.js";

package/dist/handlers/index.js

@@ -33,4 +33,5 @@ export { registerEndpointTools, handleEndpointTool } from "./endpointHandlers.js
 export { registerServiceDefinitionTools, handleServiceDefinitionTool } from "./serviceDefinitionHandlers.js";
 export { registerStarterRepoTools, handleStarterRepoTool } from "./starterRepoHandlers.js";
 export { registerCodeObservationTools, handleCodeObservationCreate } from "./codeObservationHandlers.js";
+export { registerMigrationClaimTools, handleMigrationClaim } from "./migrationClaimHandlers.js";
 //# sourceMappingURL=index.js.map

package/dist/handlers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,uDAAuD;AACvD,8EAA8E;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AACnH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EACL,sCAAsC,EACtC,gCAAgC,GACjC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACtG,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,8BAA8B,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAC7G,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,uDAAuD;AACvD,8EAA8E;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AACnH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EACL,sCAAsC,EACtC,gCAAgC,GACjC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACtG,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,8BAA8B,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAC7G,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AACzG,OAAO,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/handlers/migrationClaimHandlers.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ObservationOutcome } from "./migrationObservation.js";
+import { successResult, validationError, type GetCreds, type ToolProfile } from "../shared.js";
+export interface MigrationClaimParams {
+    productId?: string;
+    focusId?: string;
+    tag?: string;
+    agentSessionId?: string;
+}
+export declare function handleMigrationClaim(params: MigrationClaimParams, callApi: (body: Record<string, unknown>) => Promise<unknown>, 
+/**
+ * What THIS repository holds right now. Sent with the claim so the grant is
+ * made against a view taken at grant time, not only against the snapshot the
+ * daemon published earlier -- see migrationObservation.ts. Injected for tests.
+ */
+observe?: () => ObservationOutcome): Promise<ReturnType<typeof successResult> | ReturnType<typeof validationError>>;
+export declare function registerMigrationClaimTools(server: McpServer, getCreds: GetCreds, _profile?: ToolProfile): void;

package/dist/handlers/migrationClaimHandlers.js

@@ -0,0 +1,217 @@
+// ---------------------------------------------------------------------------
+// Migration-number claim tool (consolidated):
+//   telora_product_migration (claim | list)
+//
+// THE RULE THIS TOOL EXISTS TO MAKE POSSIBLE: a migration number is claimed
+// once, through Telora, BEFORE the file is named. Never read from your own
+// worktree.
+//
+// Why: two focuses armed concurrently on one product each work in their own
+// worktree, cut from the same base. A team that picks the next number by
+// reading the highest one it can see picks the same number its sibling just
+// picked. Measured 2026-09-22 on Tinker Tailor: from base 0351, two armed
+// focuses both authored 0352, 0353, 0354 and 0355. Git sees no conflict (the
+// files have different names), the merge admits it, and the breakage appears
+// only when the migrations are applied in order -- after which repairing it is
+// a renumber of every file plus the journal tail plus every reference.
+//
+// The number is granted from the union of what integration holds, what every
+// live focus branch holds, and every outstanding claim -- none of which a
+// single worktree can see. The grant is atomic at the database, so two teams
+// claiming in the same instant cannot receive one number.
+// ---------------------------------------------------------------------------
+import { z } from "zod";
+import { observeLocalMigrations } from "./migrationObservation.js";
+import { callProductApi, successResult, validationError, wrapHandler, LIST_INDEX_NOTE, } from "../shared.js";
+export async function handleMigrationClaim(params, callApi, 
+/**
+ * What THIS repository holds right now. Sent with the claim so the grant is
+ * made against a view taken at grant time, not only against the snapshot the
+ * daemon published earlier -- see migrationObservation.ts. Injected for tests.
+ */
+observe = observeLocalMigrations) {
+    if (!params.productId)
+        return validationError("productId required for claim");
+    const contested = [];
+    for (let attempt = 1; attempt <= MAX_CLAIM_ATTEMPTS; attempt += 1) {
+        // WHAT THIS REPOSITORY HOLDS -- and, when it cannot say, saying so instead
+        // of saying nothing.
+        //
+        // Ordinals are additive: they only ever join the taken set, so they can
+        // raise the granted number and can never make two teams share one. The
+        // report of what could NOT be read is not additive evidence at all -- it
+        // tells the allocator the view is partial -- so it is sent whole, even when
+        // the refs that WERE read happened to hold nothing.
+        //
+        // An INCOMPLETE reading is refused HERE rather than sent. There is nothing
+        // useful to transmit: the fields would describe a subset of the repository
+        // with no way for the handler to know what is missing, and the handler's
+        // own fallback -- grant against the daemon's older leased snapshot -- is
+        // exactly the window this reader exists to close. A refusal is retryable; a
+        // number granted twice is not.
+        const observed = observe();
+        if (observed.kind === "incomplete")
+            return refuseIncomplete(observed.reason);
+        const body = {
+            action: "migration_claim_create",
+            productId: params.productId,
+        };
+        if (observed.kind === "observed") {
+            const { observation } = observed;
+            body.observedHeld = observation.observedHeld;
+            body.observedRefs = observation.observedRefs;
+            body.observedAt = observation.observedAt;
+            body.observedUnreadable = observation.observedUnreadable;
+            body.observedTips = observation.observedTips;
+        }
+        else {
+            // GENUINELY NOTHING TO OBSERVE -- no repository, or a product that
+            // declares no numbering. Declared explicitly so the handler can tell a
+            // deliberate omission from a claimant that simply sent no fields; the two
+            // used to be the same wire message.
+            body.observationScope = observed.reason;
+        }
+        if (params.focusId !== undefined)
+            body.focusId = params.focusId;
+        if (params.tag !== undefined)
+            body.tag = params.tag;
+        if (params.agentSessionId !== undefined)
+            body.agentSessionId = params.agentSessionId;
+        const result = await callApi(body);
+        const ordinal = String(result.claim.ordinal);
+        // ─── THE BARRIER ─────────────────────────────────────────────────────────
+        //
+        // THE WINDOW THIS CLOSES. Everything above bounds the reading; nothing
+        // above makes it hold THROUGH the insert. The scan ends, the request
+        // crosses the network, the row is inserted -- and in those hundreds of
+        // milliseconds a sibling worktree can commit a migration it never claimed.
+        // The number just granted is then one a branch already holds, and no party
+        // to the grant could have known: the handler has no git, and this process
+        // had already stopped looking.
+        //
+        // So it looks AGAIN, after the grant, and asks the one question that
+        // matters: is the number I was given still free on every branch? A grant
+        // that fails that check is not returned. The next attempt re-reads, and
+        // that reading now CONTAINS the sibling's ordinal, so the allocator is
+        // asked for a number above it.
+        //
+        // This does not make the grant atomic against the repository -- nothing on
+        // either side of the boundary can be, because a commit that does not exist
+        // yet is unobservable. What it does is make the unobservable interval
+        // bounded and CHECKED: a number that lost the race is detected and
+        // discarded rather than handed to a team that writes a file at it.
+        //
+        // THE LOSING CLAIM IS LEFT STANDING, deliberately. Its ordinal really is
+        // taken -- by the sibling's unclaimed file -- so releasing it would offer
+        // that number to a third team. It stays until the lifecycle releases it
+        // with its focus, and the file that took it is named to the team that wrote
+        // it by the unclaimed-migration record.
+        if (observed.kind !== "observed")
+            return granted(result, params);
+        const after = observe();
+        if (after.kind !== "observed") {
+            // LOSS OF VERIFICATION, NOT PROOF OF FREEDOM.
+            //
+            // The pre-grant reading was complete, so this process WAS in a declared
+            // repository moments ago. A second reading that now answers `incomplete`
+            // -- or `not_applicable`, which after a complete one means a transient
+            // `rev-parse` failure or a declaration that just disappeared -- has not
+            // established that the number still is free. It has established that
+            // nothing can currently say.
+            //
+            // Returning the ordinal there is the barrier declaring success on the
+            // strength of its own failure. The claim ROW stays (its ordinal may well
+            // be taken, and releasing it would offer that number to a third team),
+            // but the caller is refused and retries.
+            const reason = after.kind === "incomplete"
+                ? after.reason
+                : `the repository stopped being readable mid-claim (${after.reason})`;
+            return refuseIncomplete(`${reason} -- a number was granted and could NOT be confirmed still free`);
+        }
+        if (!after.observation.observedHeld.includes(ordinal)) {
+            return granted(result, params);
+        }
+        contested.push(ordinal);
+    }
+    return validationError(`Cannot claim a migration number: ${contested.length} grant(s) `
+        + `(${contested.join(", ")}) were each taken by a branch between the reading they were `
+        + `made against and the moment they were granted. That is a sibling writing migrations `
+        + `without claiming them -- the rule this tool exists to enforce -- rather than ordinary `
+        + `contention. Find the unclaimed files on the other branches before retrying.`);
+}
+/** How many times a grant may lose the scan-to-insert race before refusing. */
+const MAX_CLAIM_ATTEMPTS = 3;
+/** The refusal for a reading that could not be completed. */
+function refuseIncomplete(reason) {
+    return validationError(`Cannot claim a migration number: this repository could not be read completely `
+        + `(${reason}). The claim is not attempted, because granting against a partial view of `
+        + `the branches is how two teams receive one number. Retry; if it persists, check the `
+        + `repository rather than numbering by hand.`);
+}
+/** A grant that survived the barrier. */
+function granted(result, params) {
+    return successResult({
+        claim: result.claim,
+        // Stated back rather than assumed: the number is the one to write, and the
+        // tag recorded here is the INTENT -- the file may carry a different one,
+        // and the confirm pass records what the file actually carries.
+        use: `${String(result.claim.ordinal)}${params.tag ? `_${params.tag}` : ""}`,
+    });
+}
+export function registerMigrationClaimTools(server, getCreds, _profile = 'full') {
+    server.tool("telora_product_migration", "CLAIM A MIGRATION NUMBER BEFORE YOU NAME THE FILE. Never pick a migration " +
+        "number by reading your own worktree: two focuses armed at once on one " +
+        "product are cut from the same base, so 'the next free number' computed " +
+        "locally is the same number your sibling just computed. Git sees no conflict " +
+        "(the filenames differ), the merge admits it, and it surfaces only when the " +
+        "migrations run in order. This tool grants a number free across integration, " +
+        "every live focus branch, and every outstanding claim -- atomically, so two " +
+        "teams claiming in the same instant never receive one number. Pass the tag " +
+        "you intend to use; the file may end up named differently and that is fine " +
+        "(the daemon confirms the claim with the tag the file actually carries). " +
+        "REFUSALS are never a guessed number: migration_numbering_unavailable means " +
+        "the product declares no numbering (telora.migrations.json) or its " +
+        "declaration is broken; migration_held_set_unavailable means no daemon has " +
+        "reported what the branches hold, or a branch could not be read, so granting " +
+        "would be guessing. Fix the cause -- do not fall back to numbering by hand. " +
+        "Actions: claim a number (productId, usually with focusId + tag), or list " +
+        "what a product or focus holds." +
+        LIST_INDEX_NOTE, {
+        action: z.enum(["claim", "list"]).describe("Action to perform"),
+        productId: z.string().uuid().optional().describe("Product UUID the migration belongs to (required for claim and list)"),
+        migrationClaimId: z.string().uuid().optional().describe("Migration-claim UUID (self id; reserved for future get/by-id reads)"),
+        focusId: z.string().uuid().optional().describe("Focus UUID the claim is made for -- the claim follows this branch, and is released if the focus ends without the file. Omit only for a claim made outside a focus."),
+        tag: z.string().max(200).optional().describe("The migration name you intend to use (the part after the number). Recorded as intent; the file may carry a different tag and the daemon confirms with the real one."),
+        agentSessionId: z.string().uuid().optional().describe("Provenance: the session making the claim"),
+        includeReleased: z.boolean().optional().describe("List: include released claims (the history). Default: live claims only."),
+        limit: z.number().int().min(1).max(500).optional().describe("Max results (1-500, default 50)"),
+        offset: z.number().int().min(0).optional().describe("Number of results to skip (default 0)"),
+    }, wrapHandler(async (params) => {
+        switch (params.action) {
+            case "claim": {
+                return handleMigrationClaim(params, (body) => callProductApi(getCreds(), body));
+            }
+            case "list": {
+                if (!params.productId)
+                    return validationError("productId required for list");
+                const body = {
+                    action: "migration_claim_list",
+                    productId: params.productId,
+                };
+                if (params.focusId !== undefined)
+                    body.focusId = params.focusId;
+                if (params.includeReleased !== undefined)
+                    body.includeReleased = params.includeReleased;
+                if (params.limit !== undefined)
+                    body.limit = params.limit;
+                if (params.offset !== undefined)
+                    body.offset = params.offset;
+                const result = await callProductApi(getCreds(), body);
+                return successResult({ items: result.claims, totalCount: result.totalCount });
+            }
+            default:
+                return validationError(`Unknown action: ${params.action}`);
+        }
+    }));
+}
+//# sourceMappingURL=migrationClaimHandlers.js.map

package/dist/handlers/migrationClaimHandlers.js.map

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

package/dist/handlers/migrationObservation.d.ts

@@ -0,0 +1,181 @@
+/** What the claimant's own repository holds, right now. */
+export interface MigrationObservation {
+    /** Every ordinal any local branch holds, deduplicated. */
+    observedHeld: string[];
+    /** How many refs were read -- evidence the observation is not vacuous. */
+    observedRefs: number;
+    /** When it was taken (epoch ms). */
+    observedAt: number;
+    /**
+     * Refs this observation could NOT read.
+     *
+     * NAMED RATHER THAN DROPPED. A ref that could not be read holds an unknown
+     * set of ordinals, and "unknown" silently folded in as "none" is the exact
+     * shape of fail-open the daemon's own reader refuses. The handler treats a
+     * non-empty list as a partial view and refuses the grant, retryably --
+     * symmetric with `migration_held_set_unavailable` on the daemon's side. A
+     * caller with NO repository at all reports no observation and is unaffected;
+     * this is only about a repository that exists and could not be fully read.
+     */
+    observedUnreadable: string[];
+    /**
+     * Every ref that was read, with the commit it pointed at. Recorded on the
+     * granted row, so "which commits did the allocator look at?" is answered by
+     * the claim rather than reconstructed afterwards.
+     */
+    observedTips: Record<string, string>;
+}
+/** A repo's migration declaration, as much of it as this reader needs. */
+interface Declaration {
+    dir: string;
+    filePattern: string;
+    scheme: MigrationScheme;
+    journal?: {
+        path?: string;
+    };
+}
+/** The two numbering schemes; an unrecognised value is malformed, never defaulted. */
+type MigrationScheme = "sequential" | "timestamp";
+/** The ordinals a declaration's pattern reads out of a list of paths. */
+export declare function ordinalsFromPaths(paths: readonly string[], declaration: Declaration): string[];
+/**
+ * The width the declaration's own ordinal group fixes, when it fixes one.
+ *
+ * WHY THE DECLARATION AND NOT THE FILES. A journal entry is a bare index --
+ * `2`, not `0002` -- so placing it needs a width, and reading that width from
+ * the matching migration FILES fails in exactly the case that matters: a
+ * sibling branch that has advanced its journal but has no file this pattern
+ * matches, or a ref carrying journal entries and no migration file at all.
+ * The idx was then dropped, and against a stale heartbeat the allocator could
+ * grant the very number the journal already holds. The declaration fixes the
+ * width independently of what any ref happens to contain.
+ *
+ * Only a pattern that PINS the width answers -- `\d{4}` or `[0-9]{4}`. A
+ * variable-width group (`\d+`) fixes nothing and returns null, which is the
+ * honest answer rather than a guess.
+ */
+export declare function declaredOrdinalWidth(filePattern: string): number | null;
+/**
+ * What reading a declared journal produced.
+ *
+ * A JOURNAL THAT CANNOT BE READ IS NOT AN EMPTY JOURNAL. This used to answer
+ * `[]` for unparseable text, a missing `entries` array, and an index it could
+ * not place -- indistinguishable from a journal that genuinely registers
+ * nothing. Against a heartbeat taken before a journal-only advance, that drops
+ * the held idx and lets the allocator grant the number again: the exact
+ * fail-open the observation exists to close, arriving through the one input
+ * that has no file to corroborate it.
+ */
+export type JournalReading = {
+    ok: true;
+    ordinals: string[];
+} | {
+    ok: false;
+    reason: "unparseable" | "no_entries" | "unplaceable_entry";
+};
+/** The idx values a journal registers, normalised to the width in use. */
+export declare function readJournalOrdinals(text: string, width: number | null): JournalReading;
+/**
+ * What reading a file produced.
+ *
+ * ABSENT AND UNREADABLE ARE DIFFERENT ANSWERS, and collapsing them to `null` is
+ * how a transient failure came to mean "this product opted out". A missing
+ * declaration is a product that does not use the allocator; a declaration that
+ * exists and could not be read is a repository this process cannot currently
+ * describe, and granting against the daemon's older snapshot alone is exactly
+ * what the claimant's reading exists to prevent.
+ */
+export type FileReading = {
+    kind: "read";
+    text: string;
+} | {
+    kind: "absent";
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+/**
+ * VALIDATE TO THE CANONICAL CONTRACT.
+ *
+ * The rules here are the daemon's, transcribed:
+ * `packages/daemon/src/migrations/migration-manifest.ts` is the single
+ * definition, and `migration-manifest-parity.test.ts` pins that this reader
+ * accepts and rejects the same declarations it does.
+ *
+ * WHY TRANSCRIBED RATHER THAN IMPORTED. This package is published and installed
+ * on daemon hosts by itself; it cannot depend on `@telora/daemon`. The parity
+ * test is what keeps a transcription from drifting into a second, laxer
+ * contract.
+ *
+ * WHY IT MATTERS THAT THEY AGREE. A claimant that accepts a declaration the
+ * daemon calls unreadable reports a COMPLETE observation of a repository it
+ * cannot actually read -- an empty one, because a pattern that does not compile
+ * matches nothing -- and a focus-scoped claim then grants against the daemon's
+ * older published snapshot with an empty "current" reading vouching for it.
+ * Every present-but-invalid declaration must reach the same verdict on both
+ * sides: not usable.
+ */
+export declare function validateDeclaration(parsed: unknown): {
+    ok: true;
+    declaration: Declaration;
+} | {
+    ok: false;
+    problem: string;
+};
+/** Injected seams, so the reader is testable over a real temp repo or a fake. */
+export interface ObservationDeps {
+    cwd: () => string;
+    runGit: (args: string[], cwd: string) => string | null;
+    readFile: (path: string) => FileReading;
+    now: () => number;
+}
+export declare const defaultObservationDeps: ObservationDeps;
+/**
+ * What observing this process's repository produced.
+ *
+ * THE THREE OUTCOMES ARE NOT INTERCHANGEABLE, and collapsing them to
+ * "observation or null" is what let a failed read be served as though the
+ * caller simply had no repository. The edge then treated the absence as an
+ * empty VALID report and granted against the daemon's older leased snapshot
+ * alone -- which is precisely the window the observation exists to close.
+ *
+ *   - `not_applicable` -- there is genuinely nothing to observe: no repository,
+ *     or a product that declares no numbering. The grant proceeds on the
+ *     daemon's reading exactly as it did before this reader existed. This is
+ *     the ONLY silent path, and it is silent on purpose: refusing here would
+ *     block claiming for every caller outside a checkout.
+ *   - `incomplete` -- there IS a declared repository and it could not be read
+ *     whole. Nothing is sent and the claim is not attempted: a partial view
+ *     folded in as "nothing" is how a held number reads as free.
+ *   - `observed` -- a complete reading, taken over a ref set that did not move
+ *     while it was being taken.
+ */
+export type ObservationOutcome = {
+    kind: "observed";
+    observation: MigrationObservation;
+} | {
+    kind: "not_applicable";
+    reason: "no_repository" | "no_declaration";
+} | {
+    kind: "incomplete";
+    reason: string;
+};
+/**
+ * Observe every local branch's migration ordinals, right now.
+ *
+ * READ BY COMMIT, NOT BY NAME. The tips are captured once, up front, and every
+ * tree and journal below is read through the captured SHA. Reading through the
+ * mutable branch NAME meant a branch that moved mid-scan was reported at its
+ * OLD tip while its NEW tree had been folded in -- `granted_against_tips` then
+ * recorded provenance that was simply false, naming commits the allocator had
+ * not looked at.
+ *
+ * AND THE SET IS RE-CHECKED AFTERWARDS. Reading each ref by SHA makes the
+ * individual reads coherent; it does not make the SET of them a single moment.
+ * A sibling that commits, or a branch created, between the first ref and the
+ * last is invisible to a scan that never looks again -- so the enumeration is
+ * repeated at the end, and any difference makes the whole reading `incomplete`
+ * rather than a snapshot of no particular instant.
+ */
+export declare function observeLocalMigrations(deps?: ObservationDeps): ObservationOutcome;
+export {};