@miadi/connector 0.1.12 → 0.1.14

package/dist/mission-status.js

@@ -1,27 +1,70 @@
 import { steerAttempts, steeringGrantOf, checkGrant } from "./steer.js";
 const ISSUE_REF = /^([\w.-]+)\/([\w.-]+)#(\d+)$/;
 const SESSION_REF = /^session:([0-9a-f-]{36})$/;
-/** The record a mission reference resolves to, and how it was found. */
+const MISSION_KINDS = new Set(["run_request", "work_proposal"]);
+const CLOSING_ENDINGS = new Set(["exit", "complete_then_exit"]);
+export const RELEASE_FRESHNESS_MS = 7 * 24 * 3600_000;
+const CLOCK_SKEW_MS = 5 * 60_000;
+/** A release receipt whose target the connector can check itself. */
+const SELF_TARGET = /miadi-connector/;
+/** The issue a mission implements, and how that is known. */
+export function primaryIssueOf(record) {
+    const declared = record.body?.primary_issue;
+    if (typeof declared === "string" && ISSUE_REF.test(declared))
+        return { ref: declared, provenance: "declared" };
+    const first = record.refs.find((r) => ISSUE_REF.test(r));
+    return first ? { ref: first, provenance: "first_issue_ref" } : undefined;
+}
+const newestFirst = (a, b) => b.created_at.localeCompare(a.created_at);
+function candidate(r, relation, provenance) {
+    const primary = primaryIssueOf(r);
+    return { id: r.id, kind: r.kind, created_at: r.created_at, relation, provenance, ...(primary ? { primary_issue: primary.ref } : {}) };
+}
+/** Whether a resolved reference may be acted on: an exact id, or a declared primary nobody else holds. */
+export function authorizesActions(found) {
+    return found.resolution === "exact" || (found.resolution === "declared_primary" && !found.contested);
+}
+/**
+ * The record a mission reference resolves to, how it was found, and every other
+ * candidate. `record` is absent when the reference is ambiguous or only related.
+ * Expects the folded ledger (`current()`), so a superseding record never stands
+ * as a mission of its own.
+ */
 export function resolveMissionSubject(ref, records) {
     const exact = records.find((r) => r.id === ref);
     if (exact)
-        return { record: exact, via: "record_id" };
-    const session = SESSION_REF.exec(ref);
-    if (session) {
-        const citing = records
-            .filter((r) => (r.kind === "run_request" || r.kind === "work_proposal") && r.refs.includes(ref))
-            .sort((a, b) => b.created_at.localeCompare(a.created_at));
-        if (citing.length)
-            return { record: citing[0], via: "session_ref" };
-        return null;
+        return { record: exact, via: "record_id", resolution: "exact", candidates: [] };
+    // A request retired as an earlier version of another (jgwill/Miadi#919) is not a mission of its own.
+    const missions = records.filter((r) => MISSION_KINDS.has(r.kind) && r.completion_receipt?.decision !== "superseded").sort(newestFirst);
+    if (SESSION_REF.test(ref)) {
+        const citing = missions.filter((r) => r.refs.includes(ref));
+        if (!citing.length)
+            return null;
+        if (citing.length === 1)
+            return { record: citing[0], via: "session_ref", resolution: "inferred_primary", candidates: [candidate(citing[0], "cited", "cited_ref")] };
+        return { via: "session_ref", resolution: "ambiguous_mission", candidates: citing.map((r) => candidate(r, "cited", "cited_ref")) };
     }
     if (ISSUE_REF.test(ref)) {
-        const citing = records
-            .filter((r) => (r.kind === "run_request" || r.kind === "work_proposal") && (r.refs.includes(ref) || r.evidence_refs.includes(ref)))
-            .sort((a, b) => b.created_at.localeCompare(a.created_at));
-        if (citing.length)
-            return { record: citing[0], via: "issue_ref" };
-        return null;
+        const citing = missions.filter((r) => r.refs.includes(ref) || r.evidence_refs.includes(ref));
+        if (!citing.length)
+            return null;
+        const cands = citing.map((r) => {
+            const primary = primaryIssueOf(r);
+            return primary?.ref === ref ? candidate(r, "primary", primary.provenance) : candidate(r, "related", "cited_ref");
+        });
+        const declared = cands.filter((c) => c.relation === "primary" && c.provenance === "declared");
+        const inferred = cands.filter((c) => c.relation === "primary" && c.provenance === "first_issue_ref");
+        const pick = (c) => citing.find((r) => r.id === c.id);
+        if (declared.length === 1) {
+            return { record: pick(declared[0]), via: "issue_ref", resolution: "declared_primary", ...(inferred.length ? { contested: true } : {}), candidates: cands };
+        }
+        if (declared.length > 1)
+            return { via: "issue_ref", resolution: "ambiguous_mission", candidates: cands };
+        if (inferred.length === 1)
+            return { record: pick(inferred[0]), via: "issue_ref", resolution: "inferred_primary", candidates: cands };
+        if (inferred.length > 1)
+            return { via: "issue_ref", resolution: "ambiguous_mission", candidates: cands };
+        return { via: "issue_ref", resolution: "related_only", candidates: cands };
     }
     return null;
 }
@@ -48,12 +91,108 @@ function nextAction(record, standing, queue) {
                 : "The request is done. A mission closes when its session's ending is decided, not when this request completes.";
     }
 }
+const str = (v) => (typeof v === "string" ? v.trim() : "");
+/** name@version from "npm:@scope/name@1.2.3" or "@scope/name@1.2.3". */
+function artifactVersion(artifact) {
+    const m = /^(?:npm:)?((?:@[\w.-]+\/)?[\w.-]+)@(\d[\w.+-]*)$/.exec(artifact.trim());
+    return m ? { pkg: m[1], version: m[2] } : undefined;
+}
+/** Records that carry evidence about this mission: itself, then any record citing its id, newest first. */
+function evidenceRecords(record, records) {
+    const citing = records.filter((r) => r.id !== record.id && (r.refs.includes(record.id) || r.evidence_refs.includes(record.id))).sort(newestFirst);
+    return [record, ...citing];
+}
+function releaseTruth(record, records, deps, now) {
+    let claimed = false;
+    for (const r of evidenceRecords(record, records)) {
+        const receipt = (r.completion_receipt ?? {});
+        const rel = (receipt.release ?? r.body?.release);
+        if (rel && typeof rel === "object") {
+            const ev = { artifact: str(rel.artifact), target: str(rel.target), verified_at: str(rel.verified_at), verification: str(rel.verification) };
+            const at = Date.parse(ev.verified_at);
+            if (!ev.artifact || !ev.target || !ev.verification || Number.isNaN(at) || at > now.getTime() + CLOCK_SKEW_MS) {
+                claimed = true;
+                continue;
+            }
+            const approver = str((record.completion_receipt ?? {}).decided_by?.person_id);
+            const evidence = { ...ev, record: r.id, by: r.actor.name, by_approver: Boolean(approver) && r.actor.person_id === approver };
+            const av = artifactVersion(ev.artifact);
+            const self = av && SELF_TARGET.test(ev.target) ? deps.liveVersionOf?.(av.pkg) : undefined;
+            if (av && self !== undefined) {
+                evidence.live_version = self;
+                if (self !== av.version)
+                    return { released: "live_mismatch", release_evidence: evidence };
+            }
+            if (now.getTime() - at > (deps.releaseFreshnessMs ?? RELEASE_FRESHNESS_MS))
+                return { released: "stale", release_evidence: evidence };
+            return { released: self !== undefined ? "verified" : "receipt_recorded", release_evidence: evidence };
+        }
+        if (r.id === record.id && (receipt.published || receipt.version))
+            claimed = true;
+    }
+    return { released: claimed ? "claimed_unverified" : "no_evidence" };
+}
+/**
+ * The approved ending that closes this mission: it names the mission in its own `mission` field (one ending,
+ * one mission; a citation in refs is not enough) and, when the mission names sessions, ends one of them.
+ */
+function closureTruth(record, records, missionSessions) {
+    const endings = records
+        .filter((r) => {
+        const b = (r.body ?? {});
+        if (r.kind !== "session_completion_proposal" || r.approval_state !== "approved" || b.mission !== record.id)
+            return false;
+        if (!CLOSING_ENDINGS.has(str(b.ending)))
+            return false;
+        return missionSessions.size === 0 || missionSessions.has(str(b.session_id));
+    })
+        .sort(newestFirst);
+    const e = endings[0];
+    if (!e)
+        return undefined;
+    const receipt = (e.completion_receipt ?? {});
+    const sessionId = str(e.body.session_id);
+    return {
+        record: e.id,
+        ending: str(e.body.ending),
+        session_id: sessionId,
+        session_bound: missionSessions.has(sessionId),
+        ...(str(receipt.decided_by?.name) ? { decided_by: str(receipt.decided_by.name) } : {}),
+        ...(str(receipt.decided_at) ? { decided_at: str(receipt.decided_at) } : {}),
+    };
+}
 export async function missionStatus(ref, records, deps) {
     const notes = [];
     const found = resolveMissionSubject(ref, records);
     if (!found)
         return { ref, found: false, notes: ["No mission record resolves from this reference."] };
+    if (!found.record) {
+        const ambiguous = found.resolution === "ambiguous_mission";
+        return {
+            ref,
+            found: false,
+            via: found.via,
+            identity: { resolution: found.resolution, authorizes_actions: false, candidates: found.candidates },
+            next_authorized_action: "Name the mission by its record id. Nothing is steered, released or closed against this reference.",
+            notes: [
+                ambiguous
+                    ? "Several requests hold this reference as their primary mission; none is chosen for you, the newest included."
+                    : "Requests cite this reference only as related; none implements it, so it names no mission.",
+            ],
+        };
+    }
     const { record, via } = found;
+    const primary = primaryIssueOf(record);
+    const identity = {
+        resolution: found.resolution,
+        ...(found.contested ? { contested: true } : {}),
+        authorizes_actions: authorizesActions(found),
+        ...(primary ? { primary_issue: primary } : {}),
+        candidates: found.candidates,
+    };
+    if (found.resolution === "inferred_primary") {
+        notes.push(`Resolved by inference (${via === "session_ref" ? "the only request citing this session" : "the first issue in the request's refs"}). Name ${record.id} before any steer, release or closure.`);
+    }
     const standing = deps.projectOf(record) ?? undefined;
     const queue = deps.queueOf?.(record);
     const now = deps.now?.() ?? new Date();
@@ -64,7 +203,6 @@ export async function missionStatus(ref, records, deps) {
     const named = String(record.body.session ?? "") || undefined;
     const seen = new Set();
     const addSession = (session, association) => {
-        const key = `${association}:${session}`;
         if (seen.has(session))
             return;
         seen.add(session);
@@ -74,7 +212,6 @@ export async function missionStatus(ref, records, deps) {
             live: live ? (live.has(session) ? "running" : "absent") : "unknown",
             ...(deps.paneBusy && live?.has(session) ? { activity: deps.paneBusy(session) } : {}),
         });
-        void key;
     };
     if (typeof briefTo === "string" && briefTo)
         addSession(briefTo.replace(/^new:/, ""), "brief_target");
@@ -91,14 +228,22 @@ export async function missionStatus(ref, records, deps) {
         notes.push("Live session state was not joined (the viewer's tier or the host does not allow it).");
     const issues = [];
     if (deps.issueOf) {
-        for (const r of [...record.refs, ...record.evidence_refs]) {
+        for (const r of [...new Set([...record.refs, ...record.evidence_refs])]) {
             const m = ISSUE_REF.exec(r);
             if (!m)
                 continue;
-            const issue = await deps
-                .issueOf(m[1], m[2], m[3])
-                .catch(() => ({ state: "unavailable" }));
-            issues.push({ ref: r, state: issue.state, ...(issue.title ? { title: issue.title } : {}), ...(issue.merged !== undefined ? { merged: issue.merged } : {}) });
+            const issue = await deps.issueOf(m[1], m[2], m[3]).catch(() => ({ state: "unverified", access: "unreachable" }));
+            issues.push({
+                ref: r,
+                relation: primary?.ref === r ? "primary" : "related",
+                state: issue.state,
+                ...(issue.title ? { title: issue.title } : {}),
+                ...(issue.merged !== undefined ? { merged: issue.merged } : {}),
+                ...(issue.access ? { access: issue.access } : {}),
+            });
+        }
+        if (issues.some((i) => i.state === "unverified")) {
+            notes.push("Some GitHub references could not be read by the connector; they are unverified, not missing.");
         }
     }
     const grant = steeringGrantOf(record);
@@ -108,22 +253,47 @@ export async function missionStatus(ref, records, deps) {
     const receipt = (record.completion_receipt ?? {});
     const anyLive = sessions.some((s) => s.live === "running");
     const prs = issues.filter((i) => i.merged !== undefined);
+    const unverifiedRefs = issues.some((i) => i.state === "unverified");
+    const release = releaseTruth(record, records, deps, now);
+    const missionSessions = new Set(sessions.map((x) => x.session.replace(/^session:/, "")));
+    const closure = closureTruth(record, records, missionSessions);
+    const choice = standing?.decision?.choice ?? (str(receipt.decision) || undefined);
+    const instructions = standing?.decision?.instructions ?? (str(receipt.instructions) || undefined);
     const stageTruth = {
         approved: record.approval_state === "approved",
+        approval: {
+            state: record.approval_state ?? "not_required",
+            ...(choice ? { choice } : {}),
+            ...(instructions ? { instructions } : {}),
+            outstanding: standing?.outstanding ?? [],
+        },
         queued: queue?.state === "queued" || queue?.state === "delivered",
         delivered: queue?.state === "delivered",
         running: anyLive ? "evidence" : "no_evidence",
-        pr_merged: prs.length ? (prs.every((p) => p.merged) ? "merged" : "open_or_absent") : "no_pr",
-        released: receipt.published || receipt.version ? "evidence" : "no_evidence",
-        closed: standing?.stage === "completed" && standing?.standing === "done",
+        request_completed: record.state === "completed",
+        pr_merged: unverifiedRefs ? "unverified" : prs.length ? (prs.every((p) => p.merged) ? "merged" : "open_or_absent") : "no_pr",
+        released: release.released,
+        ...(release.release_evidence ? { release_evidence: release.release_evidence } : {}),
+        closed: Boolean(closure),
+        ...(closure ? { closure_evidence: closure } : {}),
     };
     if (stageTruth.running === "no_evidence" && record.approval_state === "approved") {
         notes.push("No bound session shows live; an idle or absent pane is not proof of completion or failure.");
     }
+    if (stageTruth.request_completed && !stageTruth.closed) {
+        notes.push("The request completed; the mission stays open until an approved session ending cites it.");
+    }
+    if (stageTruth.pr_merged === "merged" && stageTruth.released !== "verified" && stageTruth.released !== "receipt_recorded") {
+        notes.push("Merged is not released: no fresh production check is recorded for this mission.");
+    }
+    if (found.contested) {
+        notes.push("This request declares the issue, and an earlier request holds it by inference; neither is acted on by issue. Name the record id.");
+    }
     return {
         ref,
         found: true,
         via,
+        identity,
         subject: {
             id: record.id,
             kind: record.kind,
@@ -138,7 +308,9 @@ export async function missionStatus(ref, records, deps) {
         issues,
         steering: { grant: grantState, attempts_used: attempts, ...(grant?.max_attempts !== undefined ? { max_attempts: grant.max_attempts } : {}) },
         stage_truth: stageTruth,
-        next_authorized_action: nextAction(record, standing ?? null, queue),
+        next_authorized_action: identity.authorizes_actions
+            ? nextAction(record, standing ?? null, queue)
+            : `Not authorizing (${found.contested ? "contested" : "inferred"}): call mission_status with ${record.id} before acting. ${nextAction(record, standing ?? null, queue)}`,
         notes,
     };
 }

package/dist/model-preflight.d.ts

@@ -0,0 +1,144 @@
+import { type JevConfig, type ProviderAvailability, type ProviderId } from "./providers.js";
+export declare const PREFLIGHT_CONTRACT = "miadi.mission_model_preflight";
+export declare const PREFLIGHT_VERSION = 1;
+/** Below this, a Jev choice is not acted on (the ≥0.8 practice of jgwill/Miadi#770). */
+export declare const JEV_CONFIDENCE_FLOOR = 0.8;
+export declare const JEV_MODEL = "jev-latest";
+export declare const TASK_TYPES: readonly ["file_relevance", "architecture_refactor", "implementation", "review"];
+export type TaskType = (typeof TASK_TYPES)[number];
+export declare const CRITICALITIES: readonly ["normal", "security_critical"];
+export type Criticality = (typeof CRITICALITIES)[number];
+export declare const REVIEW_TIERS: readonly ["standard", "stronger_reviewer", "human"];
+export type ReviewTier = (typeof REVIEW_TIERS)[number];
+export interface ModelCandidate {
+    /** provider, or provider:model when a model is known; the option Jev is asked to choose. */
+    option: string;
+    provider: ProviderId;
+    /** A concrete model id when the host shows one, else null. */
+    model_id: string | null;
+    /** configured_default: the provider's own config names it; it is not proof of what a launch will use. */
+    model_id_source: "configured_default" | "fixture" | "unknown";
+    /** What is known of the model's strength, with its source; absent on a live host, where nothing is measured yet. */
+    capability_note?: string;
+    installed: boolean;
+    version?: string;
+    /** Config-directory evidence only: never a verified sign-in. */
+    auth: "config_dir_only" | "none";
+    quota: "unknown";
+    eligible: boolean;
+    policy_reason: string;
+}
+export interface LaunchEvidence {
+    provider: ProviderId;
+    model?: string;
+    /** What shows it (a process line, a pane header); reported by the caller, not checked by the connector. */
+    evidence: string;
+}
+export type PreflightState = "recommended" | "abstained" | "provider_mismatch";
+export type DeciderSource = "jev" | "static_fallback" | "synthetic_fixture";
+export type RouterState = "answered" | "not_requested" | "router_unconfigured" | "router_unavailable" | "invalid_answer";
+export interface ModelPreflight {
+    contract: typeof PREFLIGHT_CONTRACT;
+    version: typeof PREFLIGHT_VERSION;
+    state: PreflightState;
+    mission: {
+        id: string;
+        resolution: string;
+        authorizes_actions: boolean;
+        primary_issue?: string;
+    };
+    /** sha256 of the decision state (what Jev sees or would see), for audit and replay. */
+    input_hash: string;
+    task: {
+        type: TaskType;
+        criticality: Criticality;
+    };
+    approved_provider: ProviderId | null;
+    /** approved: the request was approved with this provider. requested: it is not approved (yet); the provider is only asked for. */
+    provider_basis: "approved" | "requested";
+    candidates: ModelCandidate[];
+    decider: {
+        source: DeciderSource;
+        router: RouterState;
+        model?: string;
+        calibration: "uncalibrated" | "not_applicable";
+        confidence_floor?: number;
+        derivation: string;
+        detail?: string;
+    };
+    recommendation: {
+        provider?: ProviderId;
+        model_id?: string | null;
+        confidence: number | null;
+        probabilities?: Record<string, number>;
+        review_tier: ReviewTier;
+        explanation: string;
+        abstain_reasons: string[];
+    };
+    evidence: {
+        latency_ms?: number;
+        jev_billing?: Record<string, string>;
+        model_cost: "unknown";
+        quota: "unknown";
+    };
+    launch: {
+        approved_provider: ProviderId | null;
+        actual: "unverified" | (LaunchEvidence & {
+            source: "reported";
+        });
+        mismatch: boolean | null;
+    };
+    policy: {
+        deterministic: true;
+        authorizes: false;
+        note: string;
+    };
+    activation_plan?: string[];
+}
+/** What a decider returns for one request: answers by question id, and what the call cost. */
+export interface DeciderAnswer {
+    answers: Record<string, unknown>;
+    billing?: Record<string, string>;
+    latency_ms?: number;
+}
+export interface JevAdapter {
+    source: "jev" | "synthetic_fixture";
+    model: string;
+    decide(request: JevRequest): Promise<DeciderAnswer>;
+}
+export interface JevRequest {
+    state: Record<string, unknown>;
+    model: string;
+    questions: Record<string, {
+        type: "choice";
+        instructions: string;
+        criteria: Record<string, string>;
+    }>;
+}
+/** The model a provider's own config names, when it names one. Only that key is read. */
+export declare function configuredModel(provider: ProviderId, home?: string): string | null;
+export declare function candidatesFor(found: ProviderAvailability[], approved: ProviderId | null, modelOf?: (p: ProviderId) => string | null, basis?: "approved" | "requested"): ModelCandidate[];
+/** The least review a task gets, whatever any decider says. Jev may raise it, never lower it. */
+export declare function reviewFloor(task: TaskType, criticality: Criticality): ReviewTier;
+export declare function decisionState(task: TaskType, criticality: Criticality, candidates: ModelCandidate[]): Record<string, unknown>;
+export declare function hashState(state: unknown): string;
+export declare function buildJevRequest(state: Record<string, unknown>, candidates: ModelCandidate[], model?: string): JevRequest;
+/** A choice answer against its question: the failures, empty when it holds. */
+export declare function checkChoice(criteria: Record<string, string>, answer: any): string[];
+/** One call to Jev, never resent: a lost answer may already have been charged. */
+export declare function jevAdapter(config: JevConfig, fetchImpl?: typeof fetch, timeoutMs?: number): JevAdapter;
+export interface PreflightInput {
+    mission: ModelPreflight["mission"];
+    approved_provider: ProviderId | null;
+    provider_basis?: "approved" | "requested";
+    task: TaskType;
+    criticality: Criticality;
+    candidates: ModelCandidate[];
+    launch?: LaunchEvidence;
+    /** The decider to consult, when the caller asked for one; absent means static fallback only. */
+    adapter?: JevAdapter;
+    /** Why no adapter: not_requested or router_unconfigured. */
+    routerWhenAbsent?: "not_requested" | "router_unconfigured";
+}
+export declare const ACTIVATION_PLAN: string[];
+export declare function modelPreflight(input: PreflightInput): Promise<ModelPreflight>;