@abseed/spectra-core 0.1.0

package/dist/commit.js

@@ -0,0 +1,96 @@
+/**
+ * Committing a changeset — the review write, over the {@link SpecStore} seam.
+ *
+ * The engine here decides *what* the glossary should become and re-validates that against the
+ * glossary as it is *now* — the source may have been hand-edited since the client last read it. The
+ * persistence — which entries change, and the atomic move to applied — belongs to the store. It lives
+ * in `@abseed/spectra-core`, beside the seam, so every coordinator applies, marks, and rejects identically
+ * (the same reason `proposeChangeset`/`raiseQuestion` do).
+ */
+import { applyOps } from './changeset.js';
+export async function applyChangeset(store, id, request) {
+    const changeset = await store.findChangeset(id);
+    if (!changeset)
+        return { ok: false, status: 404, error: `No pending changeset with id "${id}".` };
+    const indices = [...new Set(request.opIndices)].sort((a, b) => a - b);
+    if (indices.length === 0) {
+        return { ok: false, status: 400, error: 'No ops selected.' };
+    }
+    if (indices.some((index) => !Number.isInteger(index) || !changeset.ops[index])) {
+        return { ok: false, status: 400, error: `Op indices out of range for changeset "${id}".` };
+    }
+    const { terms: before } = await store.readTerms();
+    // Re-run the same validation the UI ran, against the glossary as it is *now*.
+    const result = applyOps(before, indices.map((index) => changeset.ops[index]));
+    // The engine only saw the selected ops, so its indices count within that subset. Report them
+    // as positions in the changeset the caller actually sent.
+    const diagnostics = result.diagnostics.map((diagnostic) => ({
+        ...diagnostic,
+        opIndex: diagnostic.opIndex === null ? null : (indices[diagnostic.opIndex] ?? null),
+    }));
+    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === 'error');
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.severity === 'warning');
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            status: 409,
+            error: 'This selection would leave the glossary broken.',
+            diagnostics,
+            needsAcknowledgement: false,
+        };
+    }
+    if (warnings.length > 0 && !request.acknowledgeWarnings) {
+        return {
+            ok: false,
+            status: 409,
+            error: 'This selection orphans references that still point at what it removes.',
+            diagnostics,
+            needsAcknowledgement: true,
+        };
+    }
+    // The applied ops move to applied; anything left unselected stays pending, so a cherry-pick
+    // never silently discards the ops the human did not accept.
+    const appliedOps = indices.map((index) => changeset.ops[index]);
+    const remainingOps = changeset.ops.filter((_, index) => !indices.includes(index));
+    const { written, deleted, resolvedTo } = await store.commitApplication({
+        changesetId: id,
+        nextTerms: result.terms,
+        appliedOps,
+        remainingOps,
+        appliedAt: new Date().toISOString(),
+    });
+    return {
+        ok: true,
+        appliedOps: indices.length,
+        remainingOps: remainingOps.length,
+        written,
+        deleted,
+        resolvedTo,
+        diagnostics,
+    };
+}
+/**
+ * Records that code has been written for an applied changeset — the human presses a button after
+ * re-running the implementation pass. (The agent's own `mark_implemented` tool guards this with a
+ * snapshot version; this human path just records it.)
+ */
+export async function markImplemented(store, id, at) {
+    const file = await store.markImplemented(id, at);
+    if (file === null)
+        return { ok: false, status: 404, error: `No applied changeset with id "${id}".` };
+    return { ok: true, file };
+}
+export async function rejectChangeset(store, id) {
+    const resolvedTo = await store.rejectChangeset(id);
+    if (resolvedTo === null)
+        return { ok: false, status: 404, error: `No pending changeset with id "${id}".` };
+    return {
+        ok: true,
+        appliedOps: 0,
+        remainingOps: 0,
+        written: [],
+        deleted: [],
+        resolvedTo,
+        diagnostics: [],
+    };
+}

package/dist/conflicts.d.ts

@@ -0,0 +1,29 @@
+import type { Diagnostic, Op } from './types.js';
+import type { Term } from './types.js';
+export interface PendingItem {
+    /** Changeset id, or `<questionId>:<option label>` for a question's proposal. */
+    id: string;
+    kind: 'changeset' | 'question-option';
+    label: string;
+    ops: Op[];
+}
+export interface ItemReport {
+    id: string;
+    kind: PendingItem['kind'];
+    label: string;
+    /** Problems this item has on its own, against the glossary as it stands. */
+    diagnostics: Diagnostic[];
+}
+export interface Conflict {
+    /** Applying `first` before `second` is what causes the problems below. */
+    first: string;
+    second: string;
+    diagnostics: Diagnostic[];
+}
+export interface ConflictReport {
+    items: ItemReport[];
+    conflicts: Conflict[];
+    /** Items that interact with nothing else — safe in any order, at any time. */
+    independent: string[];
+}
+export declare function analyzePending(terms: Term[], items: PendingItem[]): ConflictReport;

package/dist/conflicts.js

@@ -0,0 +1,64 @@
+/**
+ * "Where should I start?" as a computation rather than a judgement call.
+ *
+ * Every pending item — a changeset, or one option of an unanswered question — is a list
+ * of ops. Whether two of them interact is not a question about term names overlapping
+ * (cs-001 and q-001 both touch `Task` and get along fine); it is a question about whether
+ * applying one *breaks* the other. So rather than analysing statically, this replays them
+ * through the same engine that commits them and reads the diagnostics.
+ *
+ * Order matters and that is the useful part: adding `Project.archived` before dropping
+ * `Project` is fine, and doing it after is an error. "Do this one first" is exactly the
+ * answer being asked for.
+ */
+import { applyOps } from './changeset.js';
+function fingerprint(diagnostic) {
+    return `${diagnostic.severity}|${diagnostic.message}`;
+}
+/**
+ * Problems that only exist because `first` ran before `second` — anything either one
+ * already had on its own is not the pair's fault.
+ */
+function newProblems(terms, first, second) {
+    const alone = new Set([
+        ...applyOps(terms, first.ops).diagnostics.map(fingerprint),
+        ...applyOps(terms, second.ops).diagnostics.map(fingerprint),
+    ]);
+    return applyOps(terms, [...first.ops, ...second.ops]).diagnostics.filter((diagnostic) => !alone.has(fingerprint(diagnostic)));
+}
+export function analyzePending(terms, items) {
+    const reports = items.map((item) => ({
+        id: item.id,
+        kind: item.kind,
+        label: item.label,
+        diagnostics: applyOps(terms, item.ops).diagnostics,
+    }));
+    const conflicts = [];
+    const entangled = new Set();
+    for (const first of items) {
+        for (const second of items) {
+            if (first.id === second.id)
+                continue;
+            // Two options of the same question are alternatives, not a sequence — nobody will
+            // ever apply both, so reporting them as conflicting is noise.
+            if (first.kind === 'question-option' && second.kind === 'question-option') {
+                if (questionOf(first.id) === questionOf(second.id))
+                    continue;
+            }
+            const diagnostics = newProblems(terms, first, second);
+            if (diagnostics.length === 0)
+                continue;
+            conflicts.push({ first: first.id, second: second.id, diagnostics });
+            entangled.add(first.id);
+            entangled.add(second.id);
+        }
+    }
+    return {
+        items: reports,
+        conflicts,
+        independent: items.filter((item) => !entangled.has(item.id)).map((item) => item.id),
+    };
+}
+function questionOf(id) {
+    return id.split(':')[0] ?? id;
+}

package/dist/coverage.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Coverage, meaning "did we think about this thing's lifecycle" — not "is it correct".
+ *
+ * Nothing here judges an implementation. A term with five expectations is a term someone
+ * thought about five times, which is not the same as a term that works. What this answers is
+ * narrower and more useful: we named `RecurringTask` and gave it attributes, but did anyone
+ * ever say what should happen when a Project holding one is deleted? That question has a
+ * yes-or-no answer computable from the glossary, and an empty answer is a real gap whether or
+ * not the code happens to do the right thing.
+ *
+ * The unit is therefore the **pair**, not the term. Counting expectations per term would have
+ * called `RecurringTask` covered from the day q-002 landed — it had expectations about
+ * completion — while the hole sat in its interaction with deletion. q-004 is exactly that
+ * hole, and it took a second implementation pass to find:
+ *
+ *     deleteProject --ref:Project--> Project <--Task.project-- Task <--parent-- RecurringTask
+ *
+ * Two hops, one of them traversed backwards, plus a subtype step. Nobody sees that by reading
+ * a file, which is the entire argument for computing it.
+ *
+ * Distance is reported rather than filtered on, because it sorts the work. Pairs at distance 1
+ * are usually already covered by the prose — the function's own spec names the entity it
+ * takes. The ones at 2 and beyond are where the questions come from.
+ */
+import type { Expectation, Term } from './types.js';
+export interface CoveragePair {
+    entity: string;
+    action: string;
+    /** 1 when the action names the entity directly; 2+ when reached through the entity graph. */
+    distance: number;
+    /** Ids of live expectations naming both ends. */
+    expectations: string[];
+}
+export interface EntityCoverage {
+    entity: string;
+    pairs: CoveragePair[];
+    covered: number;
+    uncovered: number;
+}
+export interface Coverage {
+    entities: EntityCoverage[];
+    /** Every uncovered pair, nearest first. The work list, in the order worth working it. */
+    gaps: CoveragePair[];
+    /**
+     * Non-functional expectations, listed and never matched. They are properties of a build
+     * rather than of the vocabulary, so they have no pair to land on — counting them here keeps
+     * them visible without letting them inflate a number that means something else.
+     */
+    nonFunctional: string[];
+    /**
+     * Expectations that disagree with a term's spec, and what they disagree with.
+     *
+     * These cover nothing and are not gaps either — they are decisions nobody has made. Whoever
+     * reads this has to settle which side gives before the pair can be covered at all.
+     */
+    contested: Array<{
+        expectation: string;
+        subject: string;
+        quote?: string;
+    }>;
+    /** Expectations naming a term the glossary does not have — renamed, or a typo. */
+    dangling: Array<{
+        expectation: string;
+        term: string;
+    }>;
+}
+export interface CoverageOptions {
+    /**
+     * How far from an action to look for entities it touches. Two reaches the q-004 shape and
+     * keeps the pair list readable; three connects most glossaries to themselves.
+     */
+    maxDistance?: number;
+}
+/**
+ * An expectation covers a pair when it names *both* ends.
+ *
+ * Deliberately strict. Loosening it to "names either" would mark
+ * `deleteProject × RecurringTask` covered on the strength of an expectation about deleting an
+ * empty Project, which is the exact blindness this exists to remove. The cost is that the
+ * board starts almost entirely empty, including for pairs the prose already handles — that is
+ * the honest starting position, not a defect in the measure.
+ */
+export declare function computeCoverage(terms: Term[], expectations: Expectation[], options?: CoverageOptions): Coverage;

package/dist/coverage.js

@@ -0,0 +1,148 @@
+import { computeBacklinks } from './backlinks.js';
+/** Terms that *do* something — the lifecycle side of a pair. */
+const ACTION_TYPES = new Set(['function', 'event']);
+/**
+ * Terms a lifecycle happens *to*. `attribute-type` is deliberately absent: Priority and
+ * RecurrenceRule are value shapes carried by other terms, not things with a life of their own,
+ * and walking through them would connect everything to everything.
+ */
+const SUBJECT_TYPES = new Set(['entity']);
+/** A term and every term that inherits from it, transitively. */
+function withSubtypes(backlinks, name) {
+    const found = new Set();
+    const queue = [name];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (found.has(current))
+            continue;
+        found.add(current);
+        queue.push(...(backlinks.children[current] ?? []));
+    }
+    return [...found];
+}
+/**
+ * Which entities each action touches, and how far away they are.
+ *
+ * Subtypes come free — they sit at the same distance as their supertype rather than one hop
+ * further, because a RecurringTask *is* a Task. Anything that touches Task touches every
+ * RecurringTask by definition, and charging a hop for that would push the most interesting
+ * pairs out past the limit.
+ *
+ * Supertypes are deliberately not walked. An action naming `RecurringTask` outright has said
+ * what it means; adding `Task` back would list a pair nobody asked about.
+ */
+function reachFrom(terms, backlinks, action, maxDistance) {
+    const byName = new Map(terms.map((term) => [term.name, term]));
+    const isSubject = (name) => SUBJECT_TYPES.has(byName.get(name)?.type ?? '');
+    const distances = new Map();
+    const admit = (name, distance) => {
+        if (!isSubject(name))
+            return;
+        for (const subtype of withSubtypes(backlinks, name)) {
+            const known = distances.get(subtype);
+            if (known === undefined || known > distance)
+                distances.set(subtype, distance);
+        }
+    };
+    for (const reference of backlinks.bySource[action.name] ?? []) {
+        if (reference.kind === 'attribute')
+            admit(reference.to, 1);
+    }
+    for (let distance = 2; distance <= maxDistance; distance += 1) {
+        for (const [name, known] of [...distances]) {
+            if (known !== distance - 1)
+                continue;
+            // Undirected on purpose. `Task.project: ref:Project` is the only edge between those two
+            // terms, and it points the wrong way for the question being asked — deleteProject
+            // reaches Project, and Project's Tasks are what block it.
+            for (const reference of backlinks.bySource[name] ?? []) {
+                if (reference.kind === 'attribute')
+                    admit(reference.to, distance);
+            }
+            for (const reference of backlinks.byTarget[name] ?? []) {
+                if (reference.kind === 'attribute')
+                    admit(reference.from, distance);
+            }
+        }
+    }
+    return distances;
+}
+/**
+ * An expectation covers a pair when it names *both* ends.
+ *
+ * Deliberately strict. Loosening it to "names either" would mark
+ * `deleteProject × RecurringTask` covered on the strength of an expectation about deleting an
+ * empty Project, which is the exact blindness this exists to remove. The cost is that the
+ * board starts almost entirely empty, including for pairs the prose already handles — that is
+ * the honest starting position, not a defect in the measure.
+ */
+export function computeCoverage(terms, expectations, options = {}) {
+    const maxDistance = options.maxDistance ?? 2;
+    const backlinks = computeBacklinks(terms);
+    const known = new Set(terms.map((term) => term.name));
+    // Retired expectations are history: they record what was once expected and must not keep a
+    // pair looking covered after the statement that covered it was withdrawn.
+    const live = expectations.filter((expectation) => expectation.supersededBy === null);
+    /**
+     * An expectation that contradicts a spec covers nothing, and this is the load-bearing line.
+     *
+     * Coverage means somebody has said what should happen *and the glossary agrees*. A
+     * contradicted expectation is not a settled answer wearing an expectation's clothes — it is
+     * an open disagreement, and counting it would mark the pair as thought-through at the exact
+     * moment it is most in dispute. So the pair stays a gap, and the disagreement shows up
+     * separately in `contested`, where it reads as work rather than as coverage.
+     */
+    const contested = live.filter((expectation) => expectation.contested.some((clash) => clash.kind === 'contradicts'));
+    const contestedIds = new Set(contested.map((expectation) => expectation.id));
+    const functional = live.filter((expectation) => expectation.kind === 'functional' && !contestedIds.has(expectation.id));
+    const actions = terms.filter((term) => ACTION_TYPES.has(term.type));
+    const entities = new Map(terms.filter((term) => SUBJECT_TYPES.has(term.type)).map((term) => [term.name, []]));
+    for (const action of actions) {
+        for (const [entity, distance] of reachFrom(terms, backlinks, action, maxDistance)) {
+            const pairs = entities.get(entity);
+            if (!pairs)
+                continue;
+            pairs.push({
+                entity,
+                action: action.name,
+                distance,
+                expectations: functional
+                    .filter((expectation) => expectation.terms.includes(entity) && expectation.terms.includes(action.name))
+                    .map((expectation) => expectation.id),
+            });
+        }
+    }
+    const summaries = [...entities]
+        .map(([entity, pairs]) => {
+        pairs.sort((left, right) => left.distance - right.distance || left.action.localeCompare(right.action));
+        return {
+            entity,
+            pairs,
+            covered: pairs.filter((pair) => pair.expectations.length > 0).length,
+            uncovered: pairs.filter((pair) => pair.expectations.length === 0).length,
+        };
+    })
+        .sort((left, right) => left.entity.localeCompare(right.entity));
+    return {
+        entities: summaries,
+        gaps: summaries
+            .flatMap((summary) => summary.pairs)
+            .filter((pair) => pair.expectations.length === 0)
+            .sort((left, right) => left.distance - right.distance ||
+            left.entity.localeCompare(right.entity) ||
+            left.action.localeCompare(right.action)),
+        nonFunctional: live
+            .filter((expectation) => expectation.kind === 'non-functional')
+            .map((expectation) => expectation.id),
+        contested: contested.flatMap((expectation) => expectation.contested
+            .filter((clash) => clash.kind === 'contradicts')
+            .map((clash) => ({
+            expectation: expectation.id,
+            subject: clash.subject,
+            ...(clash.quote ? { quote: clash.quote } : {}),
+        }))),
+        dangling: live.flatMap((expectation) => expectation.terms
+            .filter((term) => !known.has(term))
+            .map((term) => ({ expectation: expectation.id, term }))),
+    };
+}

package/dist/expectationCheck.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Checking a draft expectation *before* it exists.
+ *
+ * The write path for expectations used to be direct, on the argument that adding one is safe
+ * by construction — the worst it can do is turn a check red. That is true and it is not the
+ * whole cost. An expectation that contradicts a term's spec fails an implementation pass that
+ * cannot fix it: the implementer may not edit `specs/`, and deliberately has no tool to retire
+ * an expectation, so the round trip ends in "ask the human" having spent a pass to get there.
+ * Cheap to write down, expensive to discover.
+ *
+ * The other reason is the one only the author knows: "I just noticed something" is often "I
+ * forgot what we already decided". A draft is worth reading against the glossary for the same
+ * reason a changeset is — which is what every other write here already does. Expectations were
+ * the exception, and the exception was wrong.
+ *
+ * What this file catches is only what can be decided by looking, never by understanding:
+ * a term that does not exist, and a draft already written down. Whether a draft *contradicts*
+ * a spec is a question about meaning and belongs to @spec — see server/src/expectationCheck.ts.
+ * Splitting them this way matters: these findings are always available, instantly, with no
+ * credential and no model, so the gate still does something useful when the agent cannot run.
+ */
+import type { Clash, Expectation, Term } from './types.js';
+/**
+ * A finding and a stored conflict are the same thing on purpose.
+ *
+ * What the check reports is exactly what gets written onto the expectation when the author
+ * raises it anyway. Two shapes here would mean a translation step, and a translation step is
+ * where the quote gets dropped and the finding degrades into "there was a problem once".
+ */
+export type Finding = Clash;
+export type FindingKind = Clash['kind'];
+export interface ExpectationDraft {
+    kind: Expectation['kind'];
+    terms: string[];
+    given: string;
+    expect: string;
+}
+export declare function checkDraft(draft: ExpectationDraft, terms: Term[], expectations: Expectation[]): Finding[];
+/** The spec text of every term a draft names — what @spec has to read to judge it. */
+export declare function materialFor(draft: ExpectationDraft, terms: Term[]): Array<{
+    name: string;
+    spec: string;
+}>;

package/dist/expectationCheck.js

@@ -0,0 +1,86 @@
+const STOPWORDS = new Set([
+    'a', 'an', 'and', 'any', 'are', 'as', 'at', 'be', 'been', 'but', 'by', 'does', 'for', 'from',
+    'has', 'have', 'in', 'is', 'it', 'its', 'not', 'of', 'on', 'or', 'that', 'the', 'then', 'this',
+    'to', 'was', 'were', 'when', 'which', 'with',
+]);
+/** Lowercase, punctuation to spaces, stopwords dropped — so wording varies but content does not. */
+function contentTokens(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(' ')
+        .filter((token) => token.length > 1 && !STOPWORDS.has(token)));
+}
+function jaccard(left, right) {
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let shared = 0;
+    for (const token of left)
+        if (right.has(token))
+            shared += 1;
+    return shared / (left.size + right.size - shared);
+}
+/**
+ * How alike two statements have to be before this calls them the same thing.
+ *
+ * Set by what it costs to be wrong in each direction. A false duplicate is one line of text
+ * the author reads and dismisses; a missed duplicate is two statements of one rule that drift
+ * apart until they disagree and nobody knows which is current. So it leans towards flagging,
+ * and the finding is advisory — it never refuses the write.
+ */
+const DUPLICATE = 0.6;
+export function checkDraft(draft, terms, expectations) {
+    const findings = [];
+    const known = new Set(terms.map((term) => term.name));
+    for (const term of draft.terms) {
+        if (!known.has(term)) {
+            findings.push({
+                kind: 'unknown-term',
+                subject: term,
+                detail: `No term named "${term}". Coverage matches on names, so this would count towards nothing.`,
+            });
+        }
+    }
+    const draftTokens = contentTokens(`${draft.given} ${draft.expect}`);
+    const draftSet = new Set(draft.terms);
+    const draftTerms = [...draft.terms].sort().join(',');
+    for (const existing of expectations) {
+        if (existing.supersededBy !== null)
+            continue;
+        const similarity = jaccard(draftTokens, contentTokens(`${existing.given} ${existing.expect}`));
+        const sameTerms = [...existing.terms].sort().join(',') === draftTerms;
+        // Wording alone is not enough, and this cost a false positive to learn: "reopenTask
+        // changes nothing and does not error" scored 0.6 against "completeTask changes nothing
+        // and does not error", because the idempotence boilerplate is most of both sentences and
+        // the one word that distinguishes them is the function name. Two statements about
+        // different functions are not the same statement however alike they read — so a duplicate
+        // also has to be about the same subject, meaning one term set contains the other.
+        const aboutTheSameThing = sameTerms ||
+            existing.terms.every((term) => draftSet.has(term)) ||
+            draft.terms.every((term) => existing.terms.includes(term));
+        if (similarity >= DUPLICATE && aboutTheSameThing) {
+            findings.push({
+                kind: 'duplicate',
+                subject: existing.id,
+                detail: `${existing.id} already says close to this. Two statements of one rule drift apart; supersede it instead if the wording needs fixing.`,
+                quote: existing.given ? `Given ${existing.given} — ${existing.expect}` : existing.expect,
+            });
+        }
+        else if (sameTerms) {
+            findings.push({
+                kind: 'overlaps',
+                subject: existing.id,
+                detail: `${existing.id} is about exactly the same terms. Fine if it covers a different situation — worth a look if it does not.`,
+                quote: existing.given ? `Given ${existing.given} — ${existing.expect}` : existing.expect,
+            });
+        }
+    }
+    return findings;
+}
+/** The spec text of every term a draft names — what @spec has to read to judge it. */
+export function materialFor(draft, terms) {
+    return draft.terms
+        .map((name) => terms.find((term) => term.name === name))
+        .filter((term) => term !== undefined)
+        .map((term) => ({ name: term.name, spec: term.spec }));
+}

package/dist/expectations.d.ts

@@ -0,0 +1,66 @@
+import type { Author, Clash, Expectation, ExpectationKind, RecordStatus } from './types.js';
+import type { SpecStore } from './specStore.js';
+export interface RaiseExpectationRequest {
+    kind: ExpectationKind;
+    terms: string[];
+    given?: string;
+    expect: string;
+    pass: string;
+    from?: string;
+    file?: string;
+    /** Draft or published. Absent means `ready` — agents omit it; a human may save a draft. */
+    status?: RecordStatus;
+    /**
+     * What the check found and the author went ahead regardless. Carried on the write rather than
+     * recomputed here — the check is a separate call, and recomputing would let a draft be accepted
+     * against one glossary and stored against another.
+     */
+    contested?: Clash[];
+}
+export type ExpectationOutcome = {
+    ok: false;
+    error: string;
+    status?: number;
+    currentRev?: number;
+} | {
+    ok: true;
+    id: string;
+    file: string;
+    expectation: Expectation;
+};
+export declare function raiseExpectation(store: SpecStore, request: RaiseExpectationRequest, author: Author): Promise<ExpectationOutcome>;
+/**
+ * Publish a draft expectation — draft → ready. A draft counts toward nothing; publishing puts it into
+ * coverage and the versioned contract. Rewrites in place, keeping its id and file. Idempotent.
+ */
+export declare function publishExpectation(store: SpecStore, id: string, expectedRev?: number): Promise<ExpectationOutcome>;
+/**
+ * Re-reads a live expectation against the specs as they are now, and rewrites what it clashes with.
+ * The `check` is injected — a coordinator provides how a clash is found (a model pass, or the core
+ * checks only). It never retires anything: if the disagreement survives, the expectation stays live
+ * and contested and a human decides.
+ */
+export declare function recheckExpectation(store: SpecStore, id: string, check: (expectation: Expectation, others: Expectation[]) => Promise<Clash[]>, expectedRev?: number): Promise<ExpectationOutcome>;
+export interface SupersedeRequest {
+    /** What the replacement says. Omit to retire the expectation outright. */
+    replacement?: Omit<RaiseExpectationRequest, 'pass' | 'from' | 'file'> & {
+        pass?: string;
+    };
+    /** Why it moved. Recorded on the replacement's origin, or lost. */
+    note: string;
+}
+export type SupersedeOutcome = {
+    ok: false;
+    error: string;
+    status: number;
+    currentRev?: number;
+} | {
+    ok: true;
+    retired: string;
+    replacement: Expectation | null;
+};
+/**
+ * Retire an expectation, optionally replacing it. The replacement is written first and the original
+ * moved second, so a crash between them leaves a duplicate-looking pair rather than a gap.
+ */
+export declare function supersedeExpectation(store: SpecStore, id: string, request: SupersedeRequest, author: Author, expectedRev?: number): Promise<SupersedeOutcome>;