@miadi/connector 0.1.12 → 0.1.14

package/dist/model-preflight.js

@@ -0,0 +1,323 @@
+/**
+ * Mission model-choice preflight (jgwill/Miadi#913 C): a typed, versioned,
+ * read-only answer to "which provider and model fits this mission's task, and
+ * how do we know?" — never an authorization.
+ *
+ * - Policy is deterministic and decided here, not by Jev: the approved provider
+ *   is kept (no switching without a person), Claude Code only when named, an
+ *   uninstalled or sign-in-less provider is ineligible, and a reported launch on
+ *   another provider fails closed as provider_mismatch before anything is asked.
+ * - Jev is consulted only when the caller asks (consult_jev) and the connector's
+ *   environment holds a Jev key. The state sent holds the task type, the
+ *   criticality and the candidates: no task text, mission id, repository name or
+ *   source. Its answer is advisory: below the confidence floor, choosing an
+ *   ineligible option, or failing the answer contract, the preflight abstains.
+ * - Every answer says where its choice came from: jev, static_fallback or
+ *   synthetic_fixture, and Jev's confidence is marked uncalibrated: no calibration
+ *   set exists yet for this question.
+ *
+ * The request and answer checks follow lane-check's decider (smcraft
+ * examples/decision-gate/lane-check/lib/decider.mjs, revision R9), reduced to
+ * the choice questions asked here.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PROVIDERS } from "./providers.js";
+export const PREFLIGHT_CONTRACT = "miadi.mission_model_preflight";
+export const PREFLIGHT_VERSION = 1;
+/** Below this, a Jev choice is not acted on (the ≥0.8 practice of jgwill/Miadi#770). */
+export const JEV_CONFIDENCE_FLOOR = 0.8;
+export const JEV_MODEL = "jev-latest";
+const SUM_TOLERANCE = 0.025;
+export const TASK_TYPES = ["file_relevance", "architecture_refactor", "implementation", "review"];
+export const CRITICALITIES = ["normal", "security_critical"];
+export const REVIEW_TIERS = ["standard", "stronger_reviewer", "human"];
+// ── candidates, by deterministic policy ──
+/** The model a provider's own config names, when it names one. Only that key is read. */
+export function configuredModel(provider, home = homedir()) {
+    try {
+        if (provider === "codex") {
+            const line = readFileSync(join(home, ".codex", "config.toml"), "utf8").split("\n").find((l) => /^\s*model\s*=/.test(l));
+            return line ? (/=\s*"([^"]+)"/.exec(line)?.[1] ?? null) : null;
+        }
+        if (provider === "claude") {
+            const model = JSON.parse(readFileSync(join(home, ".claude", "settings.json"), "utf8"))?.model;
+            return typeof model === "string" && model ? model : null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function candidatesFor(found, approved, modelOf = (p) => configuredModel(p), basis = "approved") {
+    return PROVIDERS.map((spec) => {
+        const a = found.find((p) => p.id === spec.id);
+        const installed = Boolean(a?.installed);
+        const auth = a?.auth_evidence === "found" ? "config_dir_only" : "none";
+        const model = installed ? modelOf(spec.id) : null;
+        let eligible = true;
+        let reason = "Installed, with sign-in evidence (config directory only; quota unknown).";
+        if (!installed)
+            [eligible, reason] = [false, "Not installed on the connector host."];
+        else if (auth === "none")
+            [eligible, reason] = [false, "No sign-in evidence on this host."];
+        else if (approved && spec.id !== approved)
+            [eligible, reason] = [false, `Not the ${basis} provider (${approved}); switching needs a person's approval.`];
+        else if (!approved && !spec.selectable_by_default)
+            [eligible, reason] = [false, `${spec.name} runs only when a request names it.`];
+        return {
+            option: model ? `${spec.id}:${model}` : spec.id,
+            provider: spec.id,
+            model_id: model,
+            model_id_source: model ? "configured_default" : "unknown",
+            installed,
+            ...(a?.version ? { version: a.version } : {}),
+            auth,
+            quota: "unknown",
+            eligible,
+            policy_reason: reason,
+        };
+    });
+}
+/** The least review a task gets, whatever any decider says. Jev may raise it, never lower it. */
+export function reviewFloor(task, criticality) {
+    return criticality === "security_critical" || task === "architecture_refactor" ? "stronger_reviewer" : "standard";
+}
+const tierRank = (t) => REVIEW_TIERS.indexOf(t);
+// ── the Jev request, with nothing private in it ──
+export function decisionState(task, criticality, candidates) {
+    return {
+        task: { type: task, criticality },
+        candidates: candidates
+            .filter((c) => c.installed)
+            .map((c) => ({
+            option: c.option,
+            provider: c.provider,
+            model_id: c.model_id,
+            model_id_source: c.model_id_source,
+            ...(c.capability_note ? { capability_note: c.capability_note } : {}),
+            auth: c.auth,
+            quota: c.quota,
+            eligible: c.eligible,
+        })),
+        policy: "Only an option with eligible true may be chosen. Choose abstain when no eligible option fits the task with the evidence given.",
+    };
+}
+export function hashState(state) {
+    return createHash("sha256").update(JSON.stringify(state)).digest("hex");
+}
+export function buildJevRequest(state, candidates, model = JEV_MODEL) {
+    const fit = {};
+    for (const c of candidates.filter((x) => x.eligible)) {
+        const model = c.model_id ? ` with model ${c.model_id}${c.model_id_source === "configured_default" ? " (its configured default)" : ""}` : ", model unknown";
+        fit[c.option] = `${c.provider}${model}${c.capability_note ? ` (${c.capability_note})` : ""}; sign-in evidence is a config directory only; quota unknown.`;
+    }
+    fit.abstain = "No eligible option fits this task type and criticality on the evidence given.";
+    return {
+        state,
+        model,
+        questions: {
+            fit: {
+                type: "choice",
+                instructions: "Which option in `candidates` best fits a task of type `task.type` with criticality `task.criticality`? A file-relevance task needs high recall; an architecture or refactor task needs a strong model.",
+                criteria: fit,
+            },
+            review_tier: {
+                type: "choice",
+                instructions: "What review should the result of this task get before it is merged?",
+                criteria: {
+                    standard: "One reviewer pass is enough.",
+                    stronger_reviewer: "A stronger model or reviewer must check it: security-relevant files or architecture are involved.",
+                    human: "A person must review it before anything is merged.",
+                },
+            },
+        },
+    };
+}
+const isUnit = (x) => typeof x === "number" && Number.isFinite(x) && x >= 0 && x <= 1;
+/** A choice answer against its question: the failures, empty when it holds. */
+export function checkChoice(criteria, answer) {
+    const out = [];
+    if (!answer || typeof answer !== "object")
+        return ["no answer"];
+    if (answer.type !== "choice")
+        out.push(`answered a ${answer.type}, asked a choice`);
+    if (!isUnit(answer.confidence))
+        out.push(`confidence ${answer.confidence} is not within 0 and 1`);
+    const keys = Object.keys(criteria);
+    const probs = answer.probabilities;
+    if (!probs || typeof probs !== "object")
+        return [...out, "no probabilities"];
+    const outOfRange = Object.keys(probs).filter((k) => !isUnit(probs[k]));
+    if (outOfRange.length)
+        out.push(`probabilities outside 0 and 1: ${outOfRange.join(", ")}`);
+    const missing = keys.filter((k) => !(k in probs));
+    const extra = Object.keys(probs).filter((k) => !keys.includes(k));
+    if (missing.length || extra.length)
+        out.push("probabilities do not cover exactly the declared options");
+    const sum = keys.reduce((acc, k) => acc + (isUnit(probs[k]) ? probs[k] : 0), 0);
+    if (!missing.length && Math.abs(sum - 1) > SUM_TOLERANCE)
+        out.push(`probabilities sum to ${sum.toFixed(3)}`);
+    if (!keys.includes(answer.choice))
+        out.push(`chose ${answer.choice}, not a declared option`);
+    return out;
+}
+// ── the adapter to the real service ──
+/** One call to Jev, never resent: a lost answer may already have been charged. */
+export function jevAdapter(config, fetchImpl = fetch, timeoutMs = 60_000) {
+    return {
+        source: "jev",
+        model: JEV_MODEL,
+        async decide(request) {
+            const t0 = Date.now();
+            const res = await fetchImpl(config.url, {
+                method: "POST",
+                headers: { authorization: `Bearer ${config.apiKey}`, "content-type": "application/json", accept: "application/json" },
+                body: JSON.stringify(request),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const latency_ms = Date.now() - t0;
+            const billing = {};
+            res.headers.forEach((v, k) => {
+                if (k.startsWith("x-jev-"))
+                    billing[k.slice(6).replace(/-/g, "_")] = v;
+            });
+            if (!res.ok)
+                throw new Error(`Jev answered ${res.status}${billing.run_id ? ` [run ${billing.run_id}]` : ""}`);
+            const body = await res.json();
+            return { answers: body?.answers ?? {}, billing: { ...(body?.billing ?? {}), ...billing }, latency_ms };
+        },
+    };
+}
+export const ACTIVATION_PLAN = [
+    "Put JEV_AI_API_KEY (or TYPESAFE_API_KEY) in an environment file readable only by the connector's user, never in the repository or the unit file.",
+    "Add that file to miadi-connector.service as EnvironmentFile and restart the service.",
+    "Call provider_capabilities: router.state must be reachable (GET /v1/models, which runs no inference and is not charged).",
+    "Call mission_model_preflight with consult_jev true on one mission. Each such call is charged by Jev; its billing headers come back in evidence.jev_billing.",
+];
+export async function modelPreflight(input) {
+    const { task, criticality, candidates, approved_provider } = input;
+    const state = decisionState(task, criticality, candidates);
+    const floor = reviewFloor(task, criticality);
+    const eligible = candidates.filter((c) => c.eligible);
+    const base = {
+        contract: PREFLIGHT_CONTRACT,
+        version: PREFLIGHT_VERSION,
+        mission: input.mission,
+        input_hash: hashState(state),
+        task: { type: task, criticality },
+        approved_provider,
+        provider_basis: input.provider_basis ?? "approved",
+        candidates,
+        evidence: { model_cost: "unknown", quota: "unknown" },
+        policy: {
+            deterministic: true,
+            authorizes: false,
+            note: "A recommendation authorizes nothing. Permissions, provider switching, deployment and spending stay with the approved request and a person's decision.",
+        },
+    };
+    const launch = input.launch
+        ? { approved_provider, actual: { ...input.launch, source: "reported" }, mismatch: approved_provider ? input.launch.provider !== approved_provider : null }
+        : { approved_provider, actual: "unverified", mismatch: null };
+    // Fail closed before anything is asked or spent.
+    if (launch.mismatch) {
+        return {
+            ...base,
+            state: "provider_mismatch",
+            decider: { source: "static_fallback", router: "not_requested", calibration: "not_applicable", derivation: "deterministic policy: the reported launch is not the approved provider" },
+            recommendation: {
+                confidence: null,
+                review_tier: floor,
+                explanation: `${(input.provider_basis ?? "approved") === "approved" ? "Approved" : "Requested (not approved)"} ${approved_provider}, reported running on ${input.launch.provider}. Nothing proceeds on an unapproved provider; a person re-approves or the launch is corrected.`,
+                abstain_reasons: ["provider_mismatch"],
+            },
+            launch,
+        };
+    }
+    const fallback = (router, reasons, detail, extra = {}) => {
+        const pick = approved_provider ? eligible.find((c) => c.provider === approved_provider) : eligible[0];
+        const abstain = [...reasons, ...(pick ? [] : [approved_provider ? "approved_provider_ineligible" : "no_eligible_provider"])];
+        return {
+            ...base,
+            state: pick && !reasons.length ? "recommended" : "abstained",
+            decider: {
+                source: "static_fallback",
+                router,
+                calibration: "not_applicable",
+                derivation: approved_provider ? `deterministic policy: the ${input.provider_basis ?? "approved"} provider and its configured default model` : "deterministic policy: preference order codex, pi, copilot; claude only when named",
+                ...(detail ? { detail } : {}),
+            },
+            recommendation: {
+                ...(pick && !reasons.length ? { provider: pick.provider, model_id: pick.model_id } : {}),
+                confidence: null,
+                review_tier: floor,
+                explanation: pick
+                    ? reasons.length
+                        ? `The static policy would keep ${pick.option}, but the preflight abstains: ${reasons.join(", ")}.`
+                        : `${pick.option} by static policy. No task-aware choice was made; its model is the provider's configured default.`
+                    : `No eligible option: ${candidates.map((c) => `${c.provider} (${c.policy_reason})`).join("; ")}`,
+                abstain_reasons: pick && !reasons.length ? [] : abstain,
+            },
+            evidence: { ...base.evidence, ...extra },
+            launch,
+            ...(router === "router_unconfigured" ? { activation_plan: ACTIVATION_PLAN } : {}),
+        };
+    };
+    if (!input.adapter)
+        return fallback(input.routerWhenAbsent ?? "not_requested", []);
+    if (!eligible.length)
+        return fallback("not_requested", [], "No eligible option, so Jev was not asked.");
+    const request = buildJevRequest(state, candidates, input.adapter.model);
+    let answer;
+    try {
+        answer = await input.adapter.decide(request);
+    }
+    catch (error) {
+        return fallback("router_unavailable", ["jev_unavailable"], error instanceof Error ? error.message : String(error));
+    }
+    const fitQ = request.questions.fit.criteria;
+    const tierQ = request.questions.review_tier.criteria;
+    const fit = answer.answers.fit;
+    const tier = answer.answers.review_tier;
+    const failures = [...checkChoice(fitQ, fit).map((f) => `fit: ${f}`), ...checkChoice(tierQ, tier).map((f) => `review_tier: ${f}`)];
+    const spent = { ...(answer.latency_ms !== undefined ? { latency_ms: answer.latency_ms } : {}), ...(answer.billing && Object.keys(answer.billing).length ? { jev_billing: answer.billing } : {}) };
+    if (failures.length)
+        return fallback("invalid_answer", ["jev_invalid_answer"], failures.join("; "), spent);
+    const chosen = eligible.find((c) => c.option === fit.choice);
+    const reviewTier = tierRank(tier.choice) > tierRank(floor) ? tier.choice : floor;
+    const reasons = [];
+    if (fit.choice === "abstain")
+        reasons.push("jev_abstained");
+    else if (!chosen)
+        reasons.push("jev_choice_ineligible");
+    if (fit.confidence < JEV_CONFIDENCE_FLOOR)
+        reasons.push("jev_low_confidence");
+    const recommend = !reasons.length && chosen;
+    return {
+        ...base,
+        state: recommend ? "recommended" : "abstained",
+        decider: {
+            source: input.adapter.source,
+            router: "answered",
+            model: input.adapter.model,
+            calibration: "uncalibrated",
+            confidence_floor: JEV_CONFIDENCE_FLOOR,
+            derivation: "Jev chose among the eligible options; the policy decided eligibility and the review floor, and abstains below the confidence floor",
+        },
+        recommendation: {
+            ...(recommend ? { provider: chosen.provider, model_id: chosen.model_id } : {}),
+            confidence: fit.confidence,
+            probabilities: fit.probabilities,
+            review_tier: reviewTier,
+            explanation: recommend
+                ? `${input.adapter.source === "jev" ? "Jev" : "The synthetic fixture"} chose ${chosen.option} at confidence ${fit.confidence} (uncalibrated); review ${reviewTier}${reviewTier !== tier.choice ? " (the policy floor)" : ""}.`
+                : `Abstained: ${reasons.join(", ")}. ${input.adapter.source === "jev" ? "Jev" : "The fixture"} answered ${fit.choice} at confidence ${fit.confidence}.`,
+            abstain_reasons: reasons,
+        },
+        evidence: { ...base.evidence, ...spent },
+        launch,
+    };
+}

package/dist/providers.d.ts

@@ -42,20 +42,46 @@ export type ProviderResolution = {
  * by an explicit request.
  */
 export declare function resolveProvider(requested: string | undefined, found: ProviderAvailability[]): ProviderResolution;
+/**
+ * Where Jev is reached from this host (jgwill/Miadi#913 C1), by the names
+ * smcraft's lane-check decider uses (examples/decision-gate/lane-check,
+ * jgwill/Miadi#770): JEV_AI_API_KEY at jev-ai.pro, else TYPESAFE_API_KEY at
+ * typesafe.ai, each with an optional base override; MIADI_JEV_URL is kept as a
+ * base override. Only the connector's own environment is read, never a file.
+ * The key stays in the returned object for the adapter; nothing here prints it.
+ */
+export interface JevConfig {
+    service: string;
+    key_name: string;
+    base: string;
+    url: string;
+    models_url: string;
+    /** Never serialised: callers pass the config to the adapter, not to an answer. */
+    readonly apiKey: string;
+}
+export declare const JEV_KEY_NAMES: string[];
+export declare function jevConfigOf(env?: NodeJS.ProcessEnv): JevConfig | null;
 export type RouterPreflight = {
     state: "unconfigured";
     note: string;
 } | {
     state: "reachable";
+    service: string;
+    key_name: string;
     url: string;
+    models: string[];
+    note: string;
 } | {
     state: "router_unavailable";
+    service: string;
+    key_name: string;
     url: string;
     message: string;
 };
 /**
- * The read-only Jev routing preflight (jgwill/Miadi#893, section E): is a Jev
- * decision-aide endpoint configured and reachable from this host? Nothing is
- * sent but a health probe; no key is read here and no source text ever leaves.
+ * The read-only Jev preflight: is a Jev key in the connector's environment, and
+ * does Jev list models for it? GET /v1/models runs no inference and is not
+ * charged. Reachable is not a decision: a scored choice comes only from
+ * mission_model_preflight with consult_jev. No key value is read into an answer.
  */
 export declare function routerPreflight(env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): Promise<RouterPreflight>;

package/dist/providers.js

@@ -95,26 +95,47 @@ export function resolveProvider(requested, found) {
     }
     return { state: "provider_unavailable", message: "No agent provider is installed on the connector host.", available: [] };
 }
+const JEV_SERVICES = [
+    { service: "jev-ai.pro", key: "JEV_AI_API_KEY", baseEnv: "JEV_AI_BASE_URL", base: "https://jev-ai.pro/api" },
+    { service: "typesafe.ai", key: "TYPESAFE_API_KEY", baseEnv: "TYPESAFE_BASE_URL", base: "https://api.typesafe.ai" },
+];
+export const JEV_KEY_NAMES = JEV_SERVICES.map((s) => s.key);
+export function jevConfigOf(env = process.env) {
+    for (const s of JEV_SERVICES) {
+        const apiKey = env[s.key];
+        if (!apiKey)
+            continue;
+        const base = (env[s.baseEnv] || env.MIADI_JEV_URL || s.base).replace(/\/+$/, "");
+        const config = { service: s.service, key_name: s.key, base, url: `${base}/v1/systemone`, models_url: `${base}/v1/models` };
+        Object.defineProperty(config, "apiKey", { value: apiKey, enumerable: false });
+        return config;
+    }
+    return null;
+}
 /**
- * The read-only Jev routing preflight (jgwill/Miadi#893, section E): is a Jev
- * decision-aide endpoint configured and reachable from this host? Nothing is
- * sent but a health probe; no key is read here and no source text ever leaves.
+ * The read-only Jev preflight: is a Jev key in the connector's environment, and
+ * does Jev list models for it? GET /v1/models runs no inference and is not
+ * charged. Reachable is not a decision: a scored choice comes only from
+ * mission_model_preflight with consult_jev. No key value is read into an answer.
  */
 export async function routerPreflight(env = process.env, fetchImpl = fetch) {
-    const url = (env.MIADI_JEV_URL ?? "").replace(/\/$/, "");
-    if (!url) {
+    const jev = jevConfigOf(env);
+    if (!jev) {
         return {
             state: "unconfigured",
-            note: "No MIADI_JEV_URL on the connector host: model/tool routing falls back to the explicit provider policy and the person's choice, never to a silent default.",
+            note: `No ${JEV_KEY_NAMES.join(" or ")} in the connector's environment: model choice falls back to the explicit provider policy and the person's choice, never to a silent default.`,
         };
     }
+    const where = { service: jev.service, key_name: jev.key_name, url: jev.base };
     try {
-        const res = await fetchImpl(`${url}/health`, { signal: AbortSignal.timeout(5000) });
-        if (res.ok)
-            return { state: "reachable", url };
-        return { state: "router_unavailable", url, message: `Jev answered ${res.status}; route by the explicit provider policy instead.` };
+        const res = await fetchImpl(jev.models_url, { headers: { authorization: `Bearer ${jev.apiKey}`, accept: "application/json" }, signal: AbortSignal.timeout(5000) });
+        if (!res.ok)
+            return { state: "router_unavailable", ...where, message: `Jev answered ${res.status} to the model list; route by the explicit provider policy instead.` };
+        const body = await res.json().catch(() => ({}));
+        const models = Array.isArray(body?.models) ? body.models.map((m) => (typeof m === "string" ? m : String(m?.id ?? m?.name ?? ""))).filter(Boolean) : [];
+        return { state: "reachable", ...where, models, note: "Jev lists models for this key. That is reachability, not a decision." };
     }
     catch (error) {
-        return { state: "router_unavailable", url, message: `Jev is not reachable (${error instanceof Error ? error.message : String(error)}); route by the explicit provider policy instead.` };
+        return { state: "router_unavailable", ...where, message: `Jev is not reachable (${error instanceof Error ? error.message : String(error)}); route by the explicit provider policy instead.` };
     }
 }

package/dist/queue-state.js

@@ -1,9 +1,9 @@
 /** Shared, read-only factory queue evidence for every request-state surface. */
 import { existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 export function factoryDir(env = process.env) {
-    return env.MIADI_FACTORY_DIR || join(homedir(), ".miadi", "factory");
+    // The factory's data folder, beside the connector's own /srv/miadi/connector: never a home directory (jgwill/Miadi#911).
+    return env.MIADI_FACTORY_DIR || "/srv/miadi/factory";
 }
 export function runBriefFile(record) {
     return `connector-${record.id.replace(/[^\w-]/g, "-")}.md`;

package/dist/records.d.ts

@@ -1,3 +1,4 @@
+import type { RequestLineage, RequestRevision } from "./revisions.js";
 export declare const CIRCLES: readonly [{
     readonly id: "story";
     readonly glyph: "📖";
@@ -81,13 +82,21 @@ export interface ConnectorRecord {
     supersedes?: string;
     idempotency_key?: string;
     completion_receipt?: Record<string, unknown>;
+    /** A revision of a waiting request: this record carries its whole new content (jgwill/Miadi#919). */
+    revision?: RequestRevision;
+    /** The requests a waiting request adopted as its earlier versions (jgwill/Miadi#919). */
+    lineage?: RequestLineage;
+    /** Folded only: the version the request is at, counted across its lineage. Absent means 1. */
+    version?: number;
 }
 export declare function newRecordId(kind: RecordKind): string;
-/**
- * Fold the ledger: a record superseded by a later one shows the later one's
- * state, approval and receipt, keeping its own id and history.
- */
 export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
 export { readQueueState, runBriefFile } from "./queue-state.js";
 export type { RequestProjection, RequestStage, RequestStanding, RequestDecision, ProjectionContext } from "./request-state.js";
+/**
+ * Fold the ledger: a record superseded by a later one shows the later one's
+ * state, approval and receipt, keeping its own id and history. A revision also
+ * replaces the content (intention, circle, refs, body) and moves the version;
+ * a lineage adds the versions of the requests it adopted (jgwill/Miadi#919).
+ */
 export declare function current(records: ConnectorRecord[]): ConnectorRecord[];

package/dist/records.js

@@ -73,19 +73,27 @@ export const APPROVAL_STATES = ["awaiting_approval", "approved", "declined", "re
 export function newRecordId(kind) {
     return `${kind}:${randomUUID()}`;
 }
+export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
+export { readQueueState, runBriefFile } from "./queue-state.js";
 /**
  * Fold the ledger: a record superseded by a later one shows the later one's
- * state, approval and receipt, keeping its own id and history.
+ * state, approval and receipt, keeping its own id and history. A revision also
+ * replaces the content (intention, circle, refs, body) and moves the version;
+ * a lineage adds the versions of the requests it adopted (jgwill/Miadi#919).
  */
-export { projectRequest, APPROVABLE_KINDS, APPROVABLE } from "./request-state.js";
-export { readQueueState, runBriefFile } from "./queue-state.js";
 export function current(records) {
     const byId = new Map();
     for (const r of records) {
         if (r.supersedes && byId.has(r.supersedes)) {
             const base = byId.get(r.supersedes);
+            const adopted = r.lineage ? r.lineage.adopted.reduce((n, a) => n + (byId.get(a)?.version ?? 1), 0) : 0;
             byId.set(r.supersedes, {
                 ...base,
+                ...(r.revision
+                    ? { intention: r.intention, circle: r.circle ?? base.circle, refs: r.refs, body: r.body, version: r.revision.version }
+                    : r.lineage
+                        ? { version: (base.version ?? 1) + adopted }
+                        : {}),
                 state: r.state ?? base.state,
                 approval_state: r.approval_state ?? base.approval_state,
                 next_action: r.next_action ?? base.next_action,

package/dist/request-state.d.ts

@@ -54,6 +54,10 @@ export interface RequestProjection {
     outstanding: string[];
     /** Every sentence a surface shows under the label, names and instructions included. */
     lines: string[];
+    /** The version the request is at (jgwill/Miadi#919); a decision names it. 1 for a request never revised. */
+    version: number;
+    /** A request retired as an earlier version of another: the request to decide instead. */
+    superseded_by?: string;
 }
 export interface ProjectionContext {
     /** The review service's public address, for receipt_url. Default MIADI_REVIEW_BASE_URL, else the public service. */
@@ -65,5 +69,9 @@ export interface ProjectionContext {
     /** A decision on this request is being recorded now (its run may still be going). */
     recording?: boolean;
 }
-/** The projection of an approvable request, or null for a record that is not one. */
+/**
+ * The projection of an approvable request, or null for a record that is not one. A
+ * request retired as an earlier version of another reads as superseded; a revised one
+ * says its version, and a request sent back says which version answers it (#919).
+ */
 export declare function projectRequest(record: ConnectorRecord, ctx?: ProjectionContext): RequestProjection | null;

package/dist/request-state.js

@@ -17,6 +17,7 @@ const CHOICE_WORDS = {
     request_revision: "Sent back for revision",
     decline: "Declined",
     covered_by_grant: "Covered by the approved run's steering grant",
+    superseded: "Superseded by a later version",
 };
 const OUTCOME_WORDS = {
     queued: "queued for the factory intake",
@@ -37,8 +38,43 @@ function reviewBaseOf(ctx) {
     const base = ctx.reviewBase ?? process.env.MIADI_REVIEW_BASE_URL ?? "https://miadi-review-service.vercel.app";
     return base.replace(/\/$/, "");
 }
-/** The projection of an approvable request, or null for a record that is not one. */
+/**
+ * The projection of an approvable request, or null for a record that is not one. A
+ * request retired as an earlier version of another reads as superseded; a revised one
+ * says its version, and a request sent back says which version answers it (#919).
+ */
 export function projectRequest(record, ctx = {}) {
+    const p = projectCore(record, ctx);
+    if (!p)
+        return null;
+    const version = typeof record.version === "number" && record.version >= 1 ? record.version : 1;
+    const receipt = (record.completion_receipt ?? {});
+    if (record.approval_state === "declined" && receipt.decision === "superseded") {
+        const by = text(receipt.superseded_by);
+        const who = text(receipt.decided_by?.name) || "someone";
+        const when = text(receipt.decided_at) ? ` at ${text(receipt.decided_at)}` : "";
+        const why = text(receipt.reason) ? `: ${text(receipt.reason)}` : "";
+        return {
+            ...p,
+            version,
+            label: "Superseded by a later version",
+            decision: p.decision ? { ...p.decision, choice: "superseded" } : p.decision,
+            ...(by ? { superseded_by: by } : {}),
+            lines: [`Superseded by ${by || "a later request"}, as ${who} asked${when}${why}.`, `Nothing runs from this version. Decide ${by || "the later request"} instead.`],
+        };
+    }
+    const lines = [...p.lines];
+    if (record.approval_state === "awaiting_approval" && receipt.decision === "request_revision" && receipt.answered_by_version) {
+        const who = text(receipt.decided_by?.name) || "someone";
+        const asked = text(receipt.instructions).replace(/[.\s]+$/, "");
+        const answered = Number(receipt.answered_by_version);
+        lines.push(`Sent back for revision by ${who}${asked ? `: ${asked}` : ""}. Version ${answered} ${answered === version ? "answers" : "answered"} it.`);
+    }
+    if (version > 1)
+        lines.unshift(`Version ${version}; the earlier versions stay readable (get_request_history).`);
+    return { ...p, version, lines };
+}
+function projectCore(record, ctx = {}) {
     if (!APPROVABLE.has(record.kind))
         return null;
     const receipt = (record.completion_receipt ?? {});