@xenosystem/agent-interface-core 0.1.3

package/dist/landingQueue.js

@@ -0,0 +1,258 @@
+/**
+ * The serialised path to trunk — §5.7's landing queue.
+ *
+ * Overlap detection says two runs collided. Combination verification says
+ * whether the union was checked. Neither of them *sequences* anything, and
+ * sequencing is the part that makes the other two mean something: if two runs
+ * can land concurrently, the combination each of them verified was not the
+ * combination that landed, and the gate is decorative.
+ *
+ * Pure, and deliberately so. Everything here is a decision about what may land
+ * next; running the checks and moving the git refs are side effects that belong
+ * to the host. A rule that migrates into the executor stops being testable —
+ * that is the split `updaterPolicy.ts` already uses in this repo, for the same
+ * reason.
+ *
+ * ## 🔴 One lands at a time, and that is the whole design
+ *
+ * The queue admits **one** run to `landing` at a time. Not for throughput and
+ * not for tidiness: a verification result is bound to a fingerprint of the
+ * accepted set, and a second run landing in parallel changes that set. Both
+ * runs would then be landing against a combination neither verified — which is
+ * exactly the merge-debt failure this pillar exists to answer, arrived at
+ * through the mechanism built to prevent it.
+ *
+ * ## Accepting a change invalidates every earlier result
+ *
+ * Uncomfortable and correct. The fingerprint covers content, so a run that kept
+ * working after being verified is a different input wearing the same name.
+ * `verdictForCombination` reports that as `stale` rather than `failed`, because
+ * a human's next action differs: re-run the checks, not debug a failure.
+ */
+import { fingerprintCombination, verdictForCombination, } from './combinationVerification.js';
+import { mayLandCombination } from './landingOverlap.js';
+export class LandingQueue {
+    #entries = new Map();
+    /** Insertion order. A Map preserves it, but relying on that implicitly in a
+     *  queue is the kind of assumption that survives a refactor and then does not. */
+    #order = [];
+    #landing;
+    #now;
+    constructor(options = {}) {
+        this.#now = options.now ?? (() => Date.now());
+    }
+    /**
+     * Puts a run in line, or updates the revision of one already waiting.
+     *
+     * Re-enqueuing a run that moved on is not an error and does not lose its
+     * place: an agent that keeps working while queued is the normal case, and
+     * sending it to the back would punish the run that is still being improved.
+     * The revision changes, so the fingerprint changes, so every verification of
+     * the old set correctly goes stale — the ordering does not need to carry that.
+     */
+    enqueue(runId, revision) {
+        const existing = this.#entries.get(runId);
+        if (existing) {
+            // A run that is already landing must not have its revision swapped under
+            // it: the checks that admitted it ran against the old content, and the
+            // whole point of the fingerprint is that new content is a new input.
+            if (existing.state === 'landing')
+                return existing;
+            existing.revision = revision;
+            existing.state = 'queued';
+            delete existing.reason;
+            existing.updatedAt = this.#now();
+            this.#reposition();
+            return existing;
+        }
+        const entry = {
+            runId,
+            revision,
+            state: 'queued',
+            enqueuedAt: this.#now(),
+            updatedAt: this.#now(),
+        };
+        this.#entries.set(runId, entry);
+        this.#order.push(runId);
+        this.#reposition();
+        return entry;
+    }
+    /** Removes a run from the queue entirely — it is no longer trying to land. */
+    remove(runId) {
+        if (this.#landing === runId)
+            this.#landing = undefined;
+        const index = this.#order.indexOf(runId);
+        if (index >= 0)
+            this.#order.splice(index, 1);
+        const removed = this.#entries.delete(runId);
+        this.#reposition();
+        return removed;
+    }
+    /**
+     * The set that would land if the head proceeded.
+     *
+     * The head plus everything already landed is NOT what this returns — landed
+     * work is in trunk and is the baseline, not part of the combination. What is
+     * combined is the head with every other run still in flight, because those are
+     * the changes a check would have to run against for its result to describe
+     * what trunk becomes.
+     */
+    acceptedFor(runId) {
+        return this.#order
+            .map((id) => this.#entries.get(id))
+            .filter((entry) => Boolean(entry))
+            .filter((entry) => entry.state === 'queued' || entry.state === 'landing' || entry.runId === runId)
+            .map((entry) => ({ runId: entry.runId, revision: entry.revision }));
+    }
+    /**
+     * Whether the head may land, and against what.
+     *
+     * 🔴 Computes the verdict itself rather than accepting one. `mayLandCombination`
+     * was written the same way after the first version took a pre-computed
+     * `{ok: true}` and could therefore be satisfied by a caller asserting success
+     * — the gate has to be the thing that decides, or it is a formality.
+     */
+    next(context) {
+        if (this.#landing) {
+            const accepted = this.acceptedFor(this.#landing);
+            return {
+                runId: this.#landing,
+                ok: false,
+                reason: `${this.#landing} is already landing; one run lands at a time so the verified combination is the one that lands`,
+                accepted,
+                fingerprint: fingerprintCombination(accepted),
+            };
+        }
+        const head = this.#order
+            .map((id) => this.#entries.get(id))
+            .find((entry) => entry?.state === 'queued');
+        if (!head) {
+            return { ok: false, reason: 'nothing is waiting to land', accepted: [], fingerprint: 'empty' };
+        }
+        const accepted = this.acceptedFor(head.runId);
+        const fingerprint = fingerprintCombination(accepted);
+        const verdict = mayLandCombination(context.overlaps, accepted, context.verifications);
+        return { runId: head.runId, ok: verdict.ok, reason: verdict.reason, accepted, fingerprint };
+    }
+    /**
+     * Admits the head to `landing`, or records why it was refused.
+     *
+     * Returns the entry so a caller sees the outcome of its own call rather than
+     * having to read the queue back — the same reason `RunObservationService.poll`
+     * returns its snapshot.
+     */
+    admit(context) {
+        const decision = this.next(context);
+        if (!decision.runId)
+            return undefined;
+        const entry = this.#entries.get(decision.runId);
+        if (!entry)
+            return undefined;
+        if (!decision.ok) {
+            // 🔴 A refusal must not silently leave the run `queued`. It would be
+            // retried on every tick, refused every time, and look from the outside
+            // exactly like a queue that is merely slow.
+            if (entry.state === 'queued') {
+                entry.state = 'refused';
+                entry.reason = decision.reason;
+                entry.updatedAt = this.#now();
+                this.#reposition();
+            }
+            return entry;
+        }
+        entry.state = 'landing';
+        delete entry.reason;
+        entry.updatedAt = this.#now();
+        this.#landing = entry.runId;
+        this.#reposition();
+        return entry;
+    }
+    /**
+     * Records how a landing ended.
+     *
+     * `landed` is terminal and leaves the queue; the run is in trunk. `failed`
+     * keeps the entry so a human can see what happened — a landing that vanished
+     * on failure is indistinguishable from one that never started.
+     */
+    settle(runId, outcome) {
+        const entry = this.#entries.get(runId);
+        if (!entry)
+            return undefined;
+        if (this.#landing === runId)
+            this.#landing = undefined;
+        entry.state = outcome.landed ? 'landed' : 'failed';
+        if (outcome.reason)
+            entry.reason = outcome.reason;
+        else
+            delete entry.reason;
+        entry.updatedAt = this.#now();
+        if (outcome.landed) {
+            const index = this.#order.indexOf(runId);
+            if (index >= 0)
+                this.#order.splice(index, 1);
+            this.#entries.delete(runId);
+        }
+        this.#reposition();
+        return entry;
+    }
+    /**
+     * Puts a refused or failed run back in line.
+     *
+     * Explicit rather than automatic: a refusal means something has to change —
+     * the overlap resolved, the checks re-run — and retrying on a timer would
+     * spin against an unchanged verdict while looking like progress.
+     */
+    requeue(runId, revision) {
+        const entry = this.#entries.get(runId);
+        if (!entry || entry.state === 'landing')
+            return entry;
+        entry.revision = revision;
+        entry.state = 'queued';
+        delete entry.reason;
+        entry.updatedAt = this.#now();
+        this.#reposition();
+        return entry;
+    }
+    snapshot() {
+        const entries = this.#order
+            .map((id) => this.#entries.get(id))
+            .filter((entry) => Boolean(entry))
+            .map((entry) => ({ ...entry }));
+        const head = entries.find((entry) => entry.state === 'queued');
+        const accepted = head ? this.acceptedFor(head.runId) : [];
+        return {
+            entries,
+            ...(this.#landing ? { landing: this.#landing } : {}),
+            fingerprint: fingerprintCombination(accepted),
+        };
+    }
+    /** Positions describe the WAITING line only. A landing or refused run has no
+     *  position, because "3rd in line" said of a run that is not in line is worse
+     *  than saying nothing. */
+    #reposition() {
+        let position = 0;
+        for (const runId of this.#order) {
+            const entry = this.#entries.get(runId);
+            if (!entry)
+                continue;
+            if (entry.state === 'queued') {
+                position += 1;
+                entry.position = position;
+            }
+            else {
+                delete entry.position;
+            }
+        }
+    }
+}
+/**
+ * Whether a verification result still describes what would land.
+ *
+ * Exported because the executor needs the same answer as the queue and must not
+ * arrive at it independently: two implementations of "is this result current"
+ * is precisely how a stale green gets trusted.
+ */
+export function verificationIsCurrent(accepted, verifications) {
+    return verdictForCombination(accepted, verifications).ok;
+}
+//# sourceMappingURL=landingQueue.js.map

package/dist/landingQueue.js.map

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

package/dist/markdown/markdownWindowsPaths.d.ts

@@ -0,0 +1,20 @@
+export interface MarkdownFileReference {
+    path: string;
+    label: string;
+}
+export declare function resolveMarkdownLocalFilePath(href?: string): string | null;
+export declare function extractWindowsFilePathsFromToolResult(value: string): string[];
+/**
+ * CommonMark treats a backslash before punctuation as an escape, so a bare path such as
+ * `C:\Users\name\.xeno` loses the separator before `.xeno`. Escape only bare drive paths,
+ * while leaving inline and fenced code untouched because code already preserves backslashes.
+ */
+export declare function protectWindowsPathsForMarkdown(markdown: string): string;
+/**
+ * Turns file references in ordinary prose into inline file chips without rewriting
+ * existing inline/fenced code. Exact token boundaries prevent a directory-shaped
+ * reference such as `C:\Users\name\.xeno` from replacing the prefix of a longer path.
+ */
+export declare function injectMessageFileLinks(markdown: string, refs: MarkdownFileReference[]): string;
+export declare function prepareAgentMarkdown(markdown: string, refs?: MarkdownFileReference[]): string;
+//# sourceMappingURL=markdownWindowsPaths.d.ts.map

package/dist/markdown/markdownWindowsPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownWindowsPaths.d.ts","sourceRoot":"","sources":["../../src/markdown/markdownWindowsPaths.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,4BAA4B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBzE;AAkGD,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAG7E;AAqCD;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyBvE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,qBAAqB,EAAE,GAC5B,MAAM,CAsCR;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,qBAAqB,EAAO,GACjC,MAAM,CAER"}

package/dist/markdown/markdownWindowsPaths.js

@@ -0,0 +1,208 @@
+const WINDOWS_DRIVE_PATH_PATTERN = /\b[A-Za-z]:\\[^\s<>"`]+/g;
+const WINDOWS_FILE_RESULT_PATTERN = /[A-Za-z]:\\[^\n\r<>:"|?*]*?\.[A-Za-z0-9]{1,16}(?=$|[\s"'`)\],;:]|\.(?=$|\s))/gm;
+const MARKDOWN_PATH_PREFIX_BOUNDARY = 'A-Za-z0-9_./\\\\-';
+const MARKDOWN_PATH_SUFFIX_GUARD = '(?![A-Za-z0-9_/\\\\-]|\\.[A-Za-z0-9_])';
+export function resolveMarkdownLocalFilePath(href) {
+    if (!href?.trim())
+        return null;
+    let candidate = href.trim();
+    try {
+        candidate = decodeURIComponent(candidate);
+    }
+    catch {
+        // Keep the original value when a malformed percent escape is present.
+    }
+    candidate = candidate
+        .replace(/^xeno-file:\/\/+/i, '')
+        .replace(/^file:\/\/+/i, '')
+        .replace(/^\/(?=[A-Za-z]:[\\/])/, '');
+    if (!/^[A-Za-z]:[\\/]/.test(candidate))
+        return null;
+    return candidate.replace(/\//g, '\\');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function isEscapedBacktick(markdown, index) {
+    let slashCount = 0;
+    for (let cursor = index - 1; cursor >= 0 && markdown[cursor] === '\\'; cursor -= 1) {
+        slashCount += 1;
+    }
+    return slashCount % 2 === 1;
+}
+function mapMarkdownOutsideCode(markdown, transform) {
+    let output = '';
+    let plainText = '';
+    let cursor = 0;
+    let inlineDelimiterLength = 0;
+    let fence = null;
+    const flushPlainText = () => {
+        if (!plainText)
+            return;
+        output += transform(plainText);
+        plainText = '';
+    };
+    while (cursor < markdown.length) {
+        const atLineStart = cursor === 0 || markdown[cursor - 1] === '\n';
+        if (atLineStart && inlineDelimiterLength === 0) {
+            const nextNewline = markdown.indexOf('\n', cursor);
+            const lineEnd = nextNewline === -1 ? markdown.length : nextNewline + 1;
+            const line = markdown.slice(cursor, lineEnd);
+            const fenceMarker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+            if (fence) {
+                flushPlainText();
+                output += line;
+                if (fenceMarker
+                    && fenceMarker[1][0] === fence.character
+                    && fenceMarker[1].length >= fence.length) {
+                    fence = null;
+                }
+                cursor = lineEnd;
+                continue;
+            }
+            if (fenceMarker) {
+                flushPlainText();
+                const marker = fenceMarker[1];
+                fence = {
+                    character: marker[0],
+                    length: marker.length,
+                };
+                output += line;
+                cursor = lineEnd;
+                continue;
+            }
+        }
+        if (markdown[cursor] === '`' && !isEscapedBacktick(markdown, cursor)) {
+            let runEnd = cursor + 1;
+            while (markdown[runEnd] === '`')
+                runEnd += 1;
+            const delimiterLength = runEnd - cursor;
+            if (inlineDelimiterLength === 0) {
+                flushPlainText();
+                inlineDelimiterLength = delimiterLength;
+            }
+            else if (delimiterLength === inlineDelimiterLength) {
+                inlineDelimiterLength = 0;
+            }
+            output += markdown.slice(cursor, runEnd);
+            cursor = runEnd;
+            continue;
+        }
+        if (inlineDelimiterLength > 0) {
+            output += markdown[cursor];
+        }
+        else {
+            plainText += markdown[cursor];
+        }
+        cursor += 1;
+    }
+    flushPlainText();
+    return output;
+}
+function escapeBareWindowsPaths(value) {
+    return value.replace(WINDOWS_DRIVE_PATH_PATTERN, (path) => (path.replace(/(?<!\\)\\(?!\\)/g, '\\\\')));
+}
+export function extractWindowsFilePathsFromToolResult(value) {
+    if (!value)
+        return [];
+    return value.match(WINDOWS_FILE_RESULT_PATTERN) || [];
+}
+function protectInlineCode(line) {
+    let output = '';
+    let cursor = 0;
+    let codeDelimiterLength = 0;
+    for (let index = 0; index < line.length;) {
+        if (line[index] !== '`') {
+            index += 1;
+            continue;
+        }
+        let end = index + 1;
+        while (line[end] === '`')
+            end += 1;
+        const delimiterLength = end - index;
+        if (codeDelimiterLength === 0) {
+            output += escapeBareWindowsPaths(line.slice(cursor, index));
+            output += line.slice(index, end);
+            codeDelimiterLength = delimiterLength;
+            cursor = end;
+        }
+        else if (delimiterLength === codeDelimiterLength) {
+            output += line.slice(cursor, end);
+            codeDelimiterLength = 0;
+            cursor = end;
+        }
+        index = end;
+    }
+    output += codeDelimiterLength === 0
+        ? escapeBareWindowsPaths(line.slice(cursor))
+        : line.slice(cursor);
+    return output;
+}
+/**
+ * CommonMark treats a backslash before punctuation as an escape, so a bare path such as
+ * `C:\Users\name\.xeno` loses the separator before `.xeno`. Escape only bare drive paths,
+ * while leaving inline and fenced code untouched because code already preserves backslashes.
+ */
+export function protectWindowsPathsForMarkdown(markdown) {
+    if (!markdown || !/[A-Za-z]:\\/.test(markdown))
+        return markdown;
+    let fenceCharacter = null;
+    let fenceLength = 0;
+    return markdown.split(/(\r?\n)/).map((part) => {
+        if (part === '\n' || part === '\r\n')
+            return part;
+        const fence = part.match(/^\s*(`{3,}|~{3,})/);
+        if (fence) {
+            const marker = fence[1];
+            const markerCharacter = marker[0];
+            if (fenceCharacter === null) {
+                fenceCharacter = markerCharacter;
+                fenceLength = marker.length;
+            }
+            else if (markerCharacter === fenceCharacter && marker.length >= fenceLength) {
+                fenceCharacter = null;
+                fenceLength = 0;
+            }
+            return part;
+        }
+        return fenceCharacter === null ? protectInlineCode(part) : part;
+    }).join('');
+}
+/**
+ * Turns file references in ordinary prose into inline file chips without rewriting
+ * existing inline/fenced code. Exact token boundaries prevent a directory-shaped
+ * reference such as `C:\Users\name\.xeno` from replacing the prefix of a longer path.
+ */
+export function injectMessageFileLinks(markdown, refs) {
+    if (!markdown || refs.length === 0)
+        return markdown;
+    let output = markdown;
+    for (const ref of refs) {
+        const label = ref.label.trim();
+        const path = ref.path.trim();
+        if (!label || !path)
+            continue;
+        const chip = `\`${label}\``;
+        const escapedChip = escapeRegExp(chip);
+        const escapedPath = escapeRegExp(path);
+        let replacedExactPath = false;
+        output = mapMarkdownOutsideCode(output, (plainText) => plainText.replace(new RegExp(`(^|[^${MARKDOWN_PATH_PREFIX_BOUNDARY}])(${escapedPath})${MARKDOWN_PATH_SUFFIX_GUARD}`, 'gi'), (_match, prefix) => {
+            replacedExactPath = true;
+            return `${prefix}${chip}`;
+        }));
+        if (!replacedExactPath && !output.includes(chip)) {
+            const escapedLabel = escapeRegExp(label);
+            output = mapMarkdownOutsideCode(output, (plainText) => plainText.replace(new RegExp(`(^|[^${MARKDOWN_PATH_PREFIX_BOUNDARY}])(${escapedLabel})${MARKDOWN_PATH_SUFFIX_GUARD}`, 'gi'), (_match, prefix) => `${prefix}${chip}`));
+        }
+        // Agents sometimes emit the created/opened filename on its own line, e.g.
+        // "Done. Created:\n`file.txt`\nwith:". Keep that chip with the sentence.
+        output = output.replace(new RegExp(`:\\s*\\n+\\s*${escapedChip}`, 'gi'), `: ${chip}`);
+        output = output.replace(new RegExp(`${escapedChip}\\s*\\n+\\s*(?=[A-Za-z0-9(])`, 'gi'), `${chip} `);
+        output = output.replace(new RegExp(`(?<=[A-Za-z0-9])\\s*\\n+\\s*${escapedChip}`, 'gi'), ` ${chip}`);
+    }
+    return output;
+}
+export function prepareAgentMarkdown(markdown, refs = []) {
+    return protectWindowsPathsForMarkdown(injectMessageFileLinks(markdown, refs));
+}
+//# sourceMappingURL=markdownWindowsPaths.js.map

package/dist/markdown/markdownWindowsPaths.js.map

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

package/dist/reviewProjection.d.ts

@@ -0,0 +1,118 @@
+/**
+ * What a review surface is allowed to SHOW — §2.9 and §5.7, as a projection.
+ *
+ * Pure, and in `core` rather than in a component, because every rule here is a
+ * statement about honesty rather than about layout, and the honesty is the part
+ * that must not depend on someone remembering it while writing JSX.
+ * `packages/ui` holds `toolCardProjection` for the same reason — a projection
+ * kept out of the component that renders it.
+ *
+ * ⚠️ This sentence used to say `core` holds it. It does not; it is in
+ * `packages/ui`. Corrected rather than left, because a wrong pointer in a
+ * doc comment sends the next reader to the wrong package.
+ *
+ * ## 🔴 The rule the whole module exists for
+ *
+ * **An incomplete diff must never be presented as a review.** §2.9's claim is
+ * that tier 1 yields a real diff; a diff that quietly omits changes is worse
+ * than no diff, because a reviewer reads "3 files changed" and approves. So an
+ * incomplete snapshot projects to a state a surface cannot render as an ordinary
+ * file list — not to a list with a warning beside it, which is a thing people
+ * learn to skip past.
+ *
+ * ## Unobserved is not empty
+ *
+ * "This run changed nothing" and "nobody was watching" produce the same zero
+ * changes and mean opposite things. They are separate states here, and the
+ * second is not a variant of the first.
+ */
+import type { LandingEntry, LandingState } from './landingQueue.js';
+export interface ReviewChange {
+    path: string;
+    kind: 'added' | 'modified' | 'deleted';
+    /** True when another live run also changed this path — §5.7, surfaced while
+     *  both runs can still act on it. */
+    contested?: boolean;
+}
+/** The snapshot a surface receives, mirroring `run.observation.snapshot`. */
+export interface ReviewSnapshotInput {
+    available: boolean;
+    runId: string;
+    changes: Array<{
+        path: string;
+        kind: 'added' | 'modified' | 'deleted';
+    }>;
+    complete: boolean;
+    droppedEvents: number;
+    problems: string[];
+    reason?: string;
+}
+export interface ReviewOverlapsInput {
+    available: boolean;
+    overlaps: Array<{
+        path: string;
+        runIds: string[];
+        kind: string;
+        unclaimed?: boolean;
+    }>;
+    incompleteRuns: string[];
+    complete: boolean;
+}
+export type ReviewStatus = 
+/** No observation for this run. NOT a review of an empty diff. */
+'unobserved'
+/** Observed, complete, and nothing changed. */
+ | 'clean'
+/** Observed and complete. The only state that may render as a plain diff. */
+ | 'reviewable'
+/** Observed with a known hole. Renders as a warning FIRST, never as a list. */
+ | 'incomplete';
+export interface ReviewProjection {
+    runId: string;
+    status: ReviewStatus;
+    changes: ReviewChange[];
+    counts: {
+        added: number;
+        modified: number;
+        deleted: number;
+        contested: number;
+    };
+    /**
+     * One sentence a human can act on. Present for every status except
+     * `reviewable`, because that is the only one needing no explanation.
+     */
+    notice?: string;
+    /** True only when the diff may be treated as the whole story. */
+    trustworthy: boolean;
+}
+export declare function projectReview(snapshot: ReviewSnapshotInput, overlaps?: ReviewOverlapsInput): ReviewProjection;
+export interface LandingRowProjection {
+    runId: string;
+    state: LandingState;
+    /** "3rd in line", or absent for a run that is not waiting. */
+    positionLabel?: string;
+    /** The queue's own reason, never a re-worded one. */
+    reason?: string;
+    /** True when a human action could move this run forward. */
+    actionable: boolean;
+}
+export interface LandingProjection {
+    rows: LandingRowProjection[];
+    landing?: string;
+    /**
+     * Whether a `land` call could plausibly succeed right now.
+     *
+     * Advisory ONLY. The gate is the host's, and a surface that treated this as
+     * the decision would be a second implementation of it — which is how the two
+     * come to disagree, always in the direction of the optimistic one.
+     */
+    couldLand: boolean;
+    notice?: string;
+}
+export declare function projectLanding(input: {
+    available: boolean;
+    entries: LandingEntry[];
+    landing?: string;
+    reason?: string;
+}): LandingProjection;
+//# sourceMappingURL=reviewProjection.d.ts.map

package/dist/reviewProjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewProjection.d.ts","sourceRoot":"","sources":["../src/reviewProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;IACtC;yCACqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;KAAE,CAAC,CAAA;IACxE,QAAQ,EAAE,OAAO,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAA;IAClB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IACtF,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,MAAM,YAAY;AACtB,kEAAkE;AAChE,YAAY;AACd,+CAA+C;GAC7C,OAAO;AACT,6EAA6E;GAC3E,YAAY;AACd,+EAA+E;GAC7E,YAAY,CAAA;AAEhB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/E;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iEAAiE;IACjE,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,gBAAgB,CA2DlB;AAkBD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,YAAY,CAAA;IACnB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,oBAAoB,EAAE,CAAA;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,iBAAiB,CA+BpB"}