@xenosystem/agent-interface-core 0.1.3

package/dist/knowledgeBoardProjection.js

@@ -0,0 +1,74 @@
+/**
+ * What a knowledge surface may SHOW — ADE §5.8, the presentation half.
+ *
+ * `knowledge.list` returns every fact ever recorded, including ones a later fact
+ * replaced. This decides which are CURRENT, which are history, and what must be
+ * said about the store keeping them.
+ *
+ * ## 🔴 Superseded facts are history, never deleted and never mixed in
+ *
+ * The store keeps "we use npm" after "we moved to pnpm" on purpose — *"when did
+ * this change, and who decided?"* is a question people ask. But a list that
+ * showed both as current would be worse than one that dropped the old fact: a
+ * reader scanning it comes away believing the workspace holds two contradictory
+ * beliefs, which is exactly what supersession exists to prevent.
+ *
+ * ## The durability warning is not a footnote
+ *
+ * A surface that renders facts identically whether or not they survive a restart
+ * invites someone to teach the workspace something important and lose it. When
+ * the store is not durable, that is the first thing on screen.
+ */
+export function projectKnowledgeBoard(input) {
+    if (!input.available) {
+        return {
+            current: [],
+            history: [],
+            notice: input.reason ?? 'This host is not keeping workspace knowledge.',
+            durable: false,
+        };
+    }
+    // Latest per subject is current; everything earlier is history. Same rule as
+    // `selectWorkspaceKnowledge`, and it has to agree with it — a surface showing
+    // a fact as current that the prompt does not carry would be a lie about what
+    // the agent knows.
+    const currentBySubject = new Map();
+    const history = [];
+    for (const entry of [...input.entries].sort((left, right) => left.at === right.at ? left.id.localeCompare(right.id) : left.at - right.at)) {
+        const existing = currentBySubject.get(entry.subject);
+        if (existing)
+            history.push(existing);
+        currentBySubject.set(entry.subject, entry);
+    }
+    const current = [...currentBySubject.values()].sort((left, right) => {
+        if (Boolean(left.pinned) !== Boolean(right.pinned))
+            return left.pinned ? -1 : 1;
+        return right.at - left.at;
+    });
+    return {
+        current: current.map(toRow),
+        // Newest first: the most recent change is the one being questioned.
+        history: history.sort((left, right) => right.at - left.at).map(toRow),
+        ...(input.durable
+            ? {}
+            : {
+                notice: 'These facts are held in memory only and will be lost when the app closes.',
+            }),
+        durable: input.durable,
+    };
+}
+function toRow(entry) {
+    return {
+        id: entry.id,
+        subject: entry.subject,
+        fact: entry.fact,
+        pinned: Boolean(entry.pinned),
+        // The provider is named when known, because "which model decided this?" is
+        // the first thing anyone asks about a fact they disagree with.
+        provenance: entry.providerId
+            ? `learned by ${entry.providerId} in run ${entry.runId}`
+            : `learned in run ${entry.runId}`,
+        at: entry.at,
+    };
+}
+//# sourceMappingURL=knowledgeBoardProjection.js.map

package/dist/knowledgeBoardProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeBoardProjection.js","sourceRoot":"","sources":["../src/knowledgeBoardProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAwCH,MAAM,UAAU,qBAAqB,CAAC,KAA0B;IAC9D,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO;YACL,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,EAAE;YACX,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,+CAA+C;YACvE,OAAO,EAAE,KAAK;SACf,CAAA;IACH,CAAC;IAED,6EAA6E;IAC7E,8EAA8E;IAC9E,6EAA6E;IAC7E,mBAAmB;IACnB,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAoC,CAAA;IACpE,MAAM,OAAO,GAA+B,EAAE,CAAA;IAC9C,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAC1D,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAC5E,EAAE,CAAC;QACF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACpD,IAAI,QAAQ;YAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACpC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IAC5C,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,GAAG,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAClE,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/E,OAAO,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAA;IAC3B,CAAC,CAAC,CAAA;IAEF,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;QAC3B,oEAAoE;QACpE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;QACrE,GAAG,CAAC,KAAK,CAAC,OAAO;YACf,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,MAAM,EACJ,2EAA2E;aAC9E,CAAC;QACN,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAA;AACH,CAAC;AAED,SAAS,KAAK,CAAC,KAA+B;IAC5C,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;QAC7B,2EAA2E;QAC3E,+DAA+D;QAC/D,UAAU,EAAE,KAAK,CAAC,UAAU;YAC1B,CAAC,CAAC,cAAc,KAAK,CAAC,UAAU,WAAW,KAAK,CAAC,KAAK,EAAE;YACxD,CAAC,CAAC,kBAAkB,KAAK,CAAC,KAAK,EAAE;QACnC,EAAE,EAAE,KAAK,CAAC,EAAE;KACb,CAAA;AACH,CAAC"}

package/dist/landingOverlap.d.ts

@@ -0,0 +1,127 @@
+import { type AcceptedChange, type CombinationVerification } from './combinationVerification.js';
+/**
+ * Conflict-aware landing — ADE spec §5.7, the differentiator.
+ *
+ * > "Detect that two runs touched the same region *before* the merge, and
+ * >  surface it while both agents are still alive to fix it." The failure this
+ * >  answers is **merge debt** — *"every agent's tests pass and the merge is
+ * >  still wrong."*
+ *
+ * ## Why this is computed from OBSERVED diffs, not from claims
+ *
+ * The coordination spec's claims are *a priori*: a run declares intent to touch
+ * a path and the registry refuses a second holder. That is the right primitive
+ * for avoiding collisions, and it is **not sufficient for detecting them**,
+ * because a run can touch a file it never claimed. Nothing forces an agent to
+ * claim before writing, and an agent that surprises us is exactly the one whose
+ * overlap matters.
+ *
+ * Observed change sets are *a posteriori*: they say what actually happened.
+ * `RunDiff` produces them continuously, so an overlap is detectable **while both
+ * runs are still alive** — which is the whole point. After the merge it is
+ * archaeology.
+ *
+ * The two are complementary and the difference is reported: an overlap on a
+ * path neither run claimed was **invisible until now**, while an overlap on a
+ * claimed path means the claim was released or bypassed. A reviewer needs to
+ * know which, because they imply different fixes.
+ *
+ * ## Absence of overlap is not evidence of no overlap
+ *
+ * A run whose observation was degraded or dropped events has a diff with a hole
+ * in it. Comparing two such diffs and reporting "no conflicts" is the
+ * false-clean answer this codebase keeps removing — so completeness travels
+ * with the result, and a caller that ignores it is making a claim the data does
+ * not support.
+ */
+/** One run's observed change set, as the observation service produces it. */
+export interface RunChangeSet {
+    runId: string;
+    /** Container-relative paths, with what happened to each. */
+    changes: Array<{
+        path: string;
+        kind: 'added' | 'modified' | 'deleted';
+    }>;
+    /** False when the run's observation is known to be incomplete. */
+    complete: boolean;
+    /** Paths this run claimed through the coordination registry, if any. */
+    claimedPaths?: string[];
+}
+/**
+ * How two runs collided on one path.
+ *
+ * `delete-vs-edit` is separated from `edit-vs-edit` deliberately: a reviewer's
+ * action differs. Two edits usually merge, badly or well; one run deleting what
+ * another edited cannot be resolved by a merge tool at all, because the
+ * question is whether the file should exist.
+ */
+export type OverlapKind = 'edit-vs-edit' | 'delete-vs-edit' | 'add-vs-add';
+export interface LandingOverlap {
+    path: string;
+    /** Exactly two run ids, sorted, so a pair is reported once rather than twice. */
+    runIds: [string, string];
+    kind: OverlapKind;
+    /**
+     * True when NEITHER run claimed the path.
+     *
+     * The dangerous case: the collision was invisible to the claim registry, so
+     * nothing refused it and nobody was told. An overlap on a claimed path means
+     * a claim was released or bypassed, which is a different conversation.
+     */
+    unclaimed: boolean;
+}
+export interface LandingOverlapReport {
+    overlaps: LandingOverlap[];
+    /**
+     * False when any run's diff was incomplete.
+     *
+     * An empty `overlaps` with `complete: false` means "we found none in what we
+     * could see", which is not the same as "there are none" — and a landing gate
+     * must not treat them as equivalent.
+     */
+    complete: boolean;
+    /** Runs whose observation had a hole, named so the gap is actionable. */
+    incompleteRuns: string[];
+}
+/**
+ * Finds every pair of runs that touched the same path.
+ *
+ * Pairwise by design: a three-way collision surfaces as three pairs, because a
+ * reviewer resolves them two at a time and "runs A, B and C all touched this"
+ * hides which pair actually disagrees.
+ */
+export declare function detectLandingOverlaps(runs: RunChangeSet[]): LandingOverlapReport;
+/**
+ * Whether a landing may proceed.
+ *
+ * 🔴 Refuses on an INCOMPLETE report even with zero overlaps, and that is the
+ * point. §5.7's gate is that the system "refuses to land on a red combination";
+ * a diff with a hole cannot establish the combination is green, so landing on it
+ * would be asserting something unmeasured. Same rule as everywhere else here:
+ * "we saw nothing" and "there is nothing" are different answers.
+ */
+export declare function mayLand(report: LandingOverlapReport): {
+    ok: boolean;
+    reason: string;
+};
+/**
+ * The whole §5.7 gate: no unresolved overlap AND a verification of exactly this
+ * combination.
+ *
+ * Both halves are required and they catch different failures. Overlap detection
+ * asks *did two runs touch the same thing*; combination verification asks *has
+ * anyone checked the union*. A landing can pass either one alone and still be
+ * the failure this section exists for — two runs editing different files whose
+ * combination breaks a third, or one run whose overlap was resolved after the
+ * checks last ran.
+ *
+ * It computes the verdict itself rather than taking one, so a caller cannot
+ * satisfy the gate by passing `{ok: true}` — the first version of this function
+ * did exactly that, and the unwired-module sweep caught the verification half
+ * being reachable from nothing but its own test.
+ */
+export declare function mayLandCombination(report: LandingOverlapReport, accepted: AcceptedChange[], verifications: CombinationVerification[]): {
+    ok: boolean;
+    reason: string;
+};
+//# sourceMappingURL=landingOverlap.d.ts.map

package/dist/landingOverlap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landingOverlap.d.ts","sourceRoot":"","sources":["../src/landingOverlap.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC7B,MAAM,8BAA8B,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;KAAE,CAAC,CAAA;IACxE,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,gBAAgB,GAAG,YAAY,CAAA;AAE1E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,iFAAiF;IACjF,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxB,IAAI,EAAE,WAAW,CAAA;IACjB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,yEAAyE;IACzE,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,oBAAoB,CA4ChF;AAWD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,oBAAoB,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAcrF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,EAC5B,QAAQ,EAAE,cAAc,EAAE,EAC1B,aAAa,EAAE,uBAAuB,EAAE,GACvC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQjC"}

package/dist/landingOverlap.js

@@ -0,0 +1,107 @@
+import { verdictForCombination, } from './combinationVerification.js';
+/**
+ * Finds every pair of runs that touched the same path.
+ *
+ * Pairwise by design: a three-way collision surfaces as three pairs, because a
+ * reviewer resolves them two at a time and "runs A, B and C all touched this"
+ * hides which pair actually disagrees.
+ */
+export function detectLandingOverlaps(runs) {
+    const byPath = new Map();
+    for (const run of runs) {
+        const claimed = new Set(run.claimedPaths ?? []);
+        for (const change of run.changes) {
+            const entries = byPath.get(change.path) ?? [];
+            entries.push({ runId: run.runId, kind: change.kind, claimed: claimed.has(change.path) });
+            byPath.set(change.path, entries);
+        }
+    }
+    const overlaps = [];
+    for (const [path, entries] of byPath) {
+        if (entries.length < 2)
+            continue;
+        for (let left = 0; left < entries.length; left += 1) {
+            for (let right = left + 1; right < entries.length; right += 1) {
+                const a = entries[left];
+                const b = entries[right];
+                // A run touching its own path twice is not a collision. The observation
+                // fold already collapses repeats, but a caller may pass anything.
+                if (a.runId === b.runId)
+                    continue;
+                const runIds = a.runId < b.runId ? [a.runId, b.runId] : [b.runId, a.runId];
+                overlaps.push({
+                    path,
+                    runIds,
+                    kind: classify(a.kind, b.kind),
+                    unclaimed: !a.claimed && !b.claimed,
+                });
+            }
+        }
+    }
+    const incompleteRuns = runs.filter((run) => !run.complete).map((run) => run.runId).sort();
+    return {
+        // Sorted so two runs of the same landing produce comparable output.
+        overlaps: overlaps.sort((left, right) => left.path.localeCompare(right.path) || left.runIds[0].localeCompare(right.runIds[0])),
+        complete: incompleteRuns.length === 0,
+        incompleteRuns,
+    };
+}
+function classify(a, b) {
+    if (a === 'deleted' || b === 'deleted')
+        return 'delete-vs-edit';
+    if (a === 'added' && b === 'added')
+        return 'add-vs-add';
+    return 'edit-vs-edit';
+}
+/**
+ * Whether a landing may proceed.
+ *
+ * 🔴 Refuses on an INCOMPLETE report even with zero overlaps, and that is the
+ * point. §5.7's gate is that the system "refuses to land on a red combination";
+ * a diff with a hole cannot establish the combination is green, so landing on it
+ * would be asserting something unmeasured. Same rule as everywhere else here:
+ * "we saw nothing" and "there is nothing" are different answers.
+ */
+export function mayLand(report) {
+    if (!report.complete) {
+        return {
+            ok: false,
+            reason: `observation was incomplete for ${report.incompleteRuns.join(', ')}, so overlaps cannot be ruled out`,
+        };
+    }
+    if (report.overlaps.length > 0) {
+        return {
+            ok: false,
+            reason: `${report.overlaps.length} overlapping change(s) must be resolved while both runs are alive`,
+        };
+    }
+    return { ok: true, reason: 'no run touched a path another run touched' };
+}
+/**
+ * The whole §5.7 gate: no unresolved overlap AND a verification of exactly this
+ * combination.
+ *
+ * Both halves are required and they catch different failures. Overlap detection
+ * asks *did two runs touch the same thing*; combination verification asks *has
+ * anyone checked the union*. A landing can pass either one alone and still be
+ * the failure this section exists for — two runs editing different files whose
+ * combination breaks a third, or one run whose overlap was resolved after the
+ * checks last ran.
+ *
+ * It computes the verdict itself rather than taking one, so a caller cannot
+ * satisfy the gate by passing `{ok: true}` — the first version of this function
+ * did exactly that, and the unwired-module sweep caught the verification half
+ * being reachable from nothing but its own test.
+ */
+export function mayLandCombination(report, accepted, verifications) {
+    const overlap = mayLand(report);
+    // Overlap first: it is the more actionable of the two, and it is what must be
+    // fixed while both runs are still alive.
+    if (!overlap.ok)
+        return overlap;
+    const verdict = verdictForCombination(accepted, verifications);
+    if (!verdict.ok)
+        return { ok: false, reason: verdict.reason };
+    return { ok: true, reason: `${overlap.reason}; ${verdict.reason}` };
+}
+//# sourceMappingURL=landingOverlap.js.map

package/dist/landingOverlap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"landingOverlap.js","sourceRoot":"","sources":["../src/landingOverlap.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAGtB,MAAM,8BAA8B,CAAA;AAwFrC;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAoB;IACxD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqG,CAAA;IAE3H,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,CAAA;QAC/C,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;YAC7C,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACxF,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAClC,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAqB,EAAE,CAAA;IACrC,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,SAAQ;QAChC,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;YACpD,KAAK,IAAI,KAAK,GAAG,IAAI,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC9D,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAE,CAAA;gBACxB,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAE,CAAA;gBACzB,wEAAwE;gBACxE,kEAAkE;gBAClE,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;oBAAE,SAAQ;gBACjC,MAAM,MAAM,GAAqB,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAA;gBAC5F,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI;oBACJ,MAAM;oBACN,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;oBAC9B,SAAS,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO;iBACpC,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;IAEzF,OAAO;QACL,oEAAoE;QACpE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CACrB,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACd,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CACvF;QACD,QAAQ,EAAE,cAAc,CAAC,MAAM,KAAK,CAAC;QACrC,cAAc;KACf,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CACf,CAA0C,EAC1C,CAA0C;IAE1C,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAA;IAC/D,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,OAAO;QAAE,OAAO,YAAY,CAAA;IACvD,OAAO,cAAc,CAAA;AACvB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,MAA4B;IAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,kCAAkC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC;SAC9G,CAAA;IACH,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,mEAAmE;SACrG,CAAA;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAA;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA4B,EAC5B,QAA0B,EAC1B,aAAwC;IAExC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC/B,8EAA8E;IAC9E,yCAAyC;IACzC,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,OAAO,CAAA;IAC/B,MAAM,OAAO,GAAG,qBAAqB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAA;IAC9D,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;IAC7D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAA;AACrE,CAAC"}

package/dist/landingQueue.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 { type AcceptedChange, type CombinationVerification } from './combinationVerification.js';
+import { type LandingOverlapReport } from './landingOverlap.js';
+/**
+ * Where a run is on its way to trunk.
+ *
+ * `refused` is separate from `failed` on purpose: refused means the gate said no
+ * — the combination was unverified, stale, red, or overlapping — and the run is
+ * still perfectly good work awaiting a fix. `failed` means the landing itself
+ * broke: the merge conflicted, the push was rejected, the remote was gone. One
+ * is a decision, the other is an accident, and they call for different actions.
+ */
+export type LandingState = 'queued' | 'landing' | 'landed' | 'refused' | 'failed';
+export interface LandingEntry {
+    runId: string;
+    /** Changes whenever the run's content changes; feeds the fingerprint. */
+    revision: string;
+    state: LandingState;
+    /** Position in line, 1-based. `undefined` once it is no longer waiting. */
+    position?: number;
+    /** Why it is in this state, in terms a human can act on. */
+    reason?: string;
+    enqueuedAt: number;
+    updatedAt: number;
+}
+export interface LandingQueueSnapshot {
+    entries: LandingEntry[];
+    /** The run currently landing, if any. At most one, always. */
+    landing?: string;
+    /** The fingerprint of what would land if the head went now. */
+    fingerprint: string;
+}
+/** What the queue needs to know about the world to decide. */
+export interface LandingContext {
+    /** Overlaps among the LIVE runs, from observed diffs. */
+    overlaps: LandingOverlapReport;
+    /** Results, each carrying the fingerprint of the set it ran against. */
+    verifications: CombinationVerification[];
+}
+export interface LandingDecision {
+    /** The run that may proceed, when one may. */
+    runId?: string;
+    ok: boolean;
+    reason: string;
+    /** The set the caller must verify and land, so it cannot compose its own. */
+    accepted: AcceptedChange[];
+    fingerprint: string;
+}
+export declare class LandingQueue {
+    #private;
+    constructor(options?: {
+        now?: () => number;
+    });
+    /**
+     * 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: string, revision: string): LandingEntry;
+    /** Removes a run from the queue entirely — it is no longer trying to land. */
+    remove(runId: string): boolean;
+    /**
+     * 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: string): AcceptedChange[];
+    /**
+     * 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: LandingContext): LandingDecision;
+    /**
+     * 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: LandingContext): LandingEntry | undefined;
+    /**
+     * 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: string, outcome: {
+        landed: boolean;
+        reason?: string;
+    }): LandingEntry | undefined;
+    /**
+     * 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: string, revision: string): LandingEntry | undefined;
+    snapshot(): LandingQueueSnapshot;
+}
+/**
+ * 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 declare function verificationIsCurrent(accepted: AcceptedChange[], verifications: CombinationVerification[]): boolean;
+//# sourceMappingURL=landingQueue.d.ts.map

package/dist/landingQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"landingQueue.d.ts","sourceRoot":"","sources":["../src/landingQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC7B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAEnF;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,QAAQ,CAAA;AAEZ,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,YAAY,CAAA;IACnB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,wEAAwE;IACxE,aAAa,EAAE,uBAAuB,EAAE,CAAA;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,6EAA6E;IAC7E,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,qBAAa,YAAY;;gBAQX,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAIhD;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY;IA2BtD,8EAA8E;IAC9E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAS9B;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAQ5C;;;;;;;OAOG;IACH,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe;IAyB9C;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,GAAG,SAAS;IA2BxD;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY,GAAG,SAAS;IAiB9F;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAWlE,QAAQ,IAAI,oBAAoB;CA8BjC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,cAAc,EAAE,EAC1B,aAAa,EAAE,uBAAuB,EAAE,GACvC,OAAO,CAET"}