@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/domains/evidence/trust-projection.ts

@@ -0,0 +1,274 @@
+import { RUN_RECEIPT_INTEGRITY_VERSION } from "../dispatch/receipt-integrity.js";
+import {
+	type CanonicalTrustStatus,
+	retiredIntegrityVersionOf,
+	TRUST_STATUS_AXES,
+	type TRUST_STATUS_STATES,
+	type TrustArtifactReference,
+	type TrustStatusAxis,
+} from "./trust-status.js";
+
+/**
+ * The one projection of the canonical trust status every operator surface
+ * renders. The six-axis model stays the source of truth and is never
+ * collapsed into a score here; this module only fixes the words each state is
+ * called and the order the axes are read in, so the dispatch line, the
+ * monitor block, `evidence inspect`, `findings.md`, the Alt+W board, the
+ * receipt view, the eval bridge, and the ACP wire cannot each spell the same
+ * fact differently.
+ *
+ * Two shapes leave this module. `formatTrustSummary` is the compact human
+ * line: it answers who claims the result, what was observed, what was
+ * independently checked, and what is still unknown, without receipt
+ * internals. `summarizeTrustStatus` is the bounded, versioned machine record
+ * behind that line, carrying the axis states and typed references back to
+ * the artifacts the detailed model cites.
+ */
+
+export const TRUST_SUMMARY_VERSION = 1 as const;
+
+/** Reference cap for the machine projection; the canonical model keeps up to 16 per axis. */
+export const TRUST_SUMMARY_MAX_REFS = 8;
+
+/**
+ * How much the run's result can be leaned on, read off the axes in a fixed
+ * order. It is a presentation tier for styling and sorting, never a score:
+ * `reviewed` is the only tier that may be styled as independently verified.
+ */
+export type TrustVerdict = "reviewed" | "grounded" | "unverified" | "compromised" | "unknown";
+
+export const TRUST_VERDICTS: ReadonlyArray<TrustVerdict> = [
+	"reviewed",
+	"grounded",
+	"unverified",
+	"compromised",
+	"unknown",
+];
+
+/** Bounded, versioned machine projection with references to the detailed artifacts. */
+export interface TrustSummaryProjection {
+	version: typeof TRUST_SUMMARY_VERSION;
+	verdict: TrustVerdict;
+	/** The compact human line, byte-identical to what the text surfaces print. */
+	text: string;
+	/** Every axis state, in canonical vocabulary, for machine consumers. */
+	axes: Record<TrustStatusAxis, string>;
+	/** Who asserts the validation fact: `<authority kind>:<id>`, or `worker` when only the run's own prose exists. */
+	claimant: string;
+	/** Axes that answer nothing, so a consumer knows what remains unknown. */
+	unknown: TrustStatusAxis[];
+	/** `<artifact kind>:<id>` pointers to the detailed records, sorted, unique, capped. */
+	refs: string[];
+}
+
+type AxisStates = { [Axis in TrustStatusAxis]: (typeof TRUST_STATUS_STATES)[Axis][number] };
+
+/**
+ * The standardized word for every state. A word is what an operator reads;
+ * the state id is what a machine reads. `mediated` names the `enforced`
+ * autonomy state because that is the receipt grade and the documented
+ * meaning: Clio's own safety gate mediated the run. `inferred` names an
+ * ungrounded validation claim: the worker said it validated, nothing was
+ * observed to have run.
+ */
+export const TRUST_STATE_WORDS: { [Axis in TrustStatusAxis]: Record<AxisStates[Axis], string> } = {
+	artifactIntegrity: {
+		verified: "sealed",
+		failed: "seal broken",
+		absent: "no receipt",
+		unknown: "seal unchecked",
+		not_applicable: "seal not applicable",
+	},
+	validationGrounding: {
+		validated: "grounded",
+		failed: "validation failed",
+		ungrounded: "inferred: validation claimed, none observed",
+		absent: "no validation observed",
+		unknown: "validation unknown",
+		not_applicable: "validation not applicable",
+	},
+	independentReview: {
+		passed: "independently reviewed: pass",
+		failed: "independently reviewed: fail",
+		inconclusive: "independent review inconclusive",
+		not_independent: "review not independent",
+		absent: "not independently reviewed",
+		unknown: "independent review unknown",
+		not_applicable: "independent review not applicable",
+	},
+	contextProvenance: {
+		recorded: "context recorded",
+		invalid: "context record invalid",
+		absent: "context not recorded",
+		unknown: "context unknown",
+		not_applicable: "context not applicable",
+	},
+	autonomyEnforcement: {
+		enforced: "mediated",
+		approximated: "approximated",
+		bypassed: "bypassed",
+		absent: "autonomy not recorded",
+		unknown: "autonomy unknown",
+		not_applicable: "autonomy not applicable",
+	},
+	completionEvidence: {
+		evidenced: "completion evidenced",
+		incomplete: "completion unevidenced",
+		limited: "completion limited",
+		absent: "completion not recorded",
+		unknown: "completion unknown",
+		not_applicable: "completion not applicable",
+	},
+};
+
+/** The word for one axis state; unknown input never throws, it reads as unknown. */
+export function trustStateWord<Axis extends TrustStatusAxis>(axis: Axis, state: string): string {
+	const words = TRUST_STATE_WORDS[axis] as Record<string, string>;
+	return words[state] ?? words.unknown ?? "unknown";
+}
+
+function authorityOf(status: CanonicalTrustStatus, axis: TrustStatusAxis): string | null {
+	const entry = status[axis];
+	return entry.state === "absent" ? null : `${entry.authority.kind}:${entry.authority.id}`;
+}
+
+/**
+ * A seal this build does not verify because its version is retired names
+ * that version and the one in force, so an intact receipt from the previous
+ * release never reads as "seal broken" or as merely unchecked. The state
+ * behind the clause is `unknown`, which is what it is: nothing was checked.
+ */
+function integrityClause(status: CanonicalTrustStatus): string {
+	const retired = retiredIntegrityVersionOf(status.artifactIntegrity);
+	if (retired !== null) return `seal v${retired} retired (this build verifies v${RUN_RECEIPT_INTEGRITY_VERSION})`;
+	return trustStateWord("artifactIntegrity", status.artifactIntegrity.state);
+}
+
+/**
+ * The validation clause names its claimant, because "grounded" alone hides
+ * the difference between a host-run check and a self-reported one.
+ */
+function validationClause(status: CanonicalTrustStatus): string {
+	const entry = status.validationGrounding;
+	const word = trustStateWord("validationGrounding", entry.state);
+	if (entry.state === "absent") return word;
+	if (entry.state === "validated" || entry.state === "failed") return `${word} by ${entry.authority.id}`;
+	// A named external system that could not observe the run is worth naming;
+	// the historical-format placeholder is not an authority anyone can ask.
+	if (entry.state === "unknown" && entry.authority.kind !== "unknown") return `${word} (${entry.authority.id})`;
+	return word;
+}
+
+/** External runtimes name themselves on the autonomy clause so approximation is never anonymous. */
+function autonomyClause(status: CanonicalTrustStatus): string {
+	const entry = status.autonomyEnforcement;
+	const word = trustStateWord("autonomyEnforcement", entry.state);
+	if (entry.state !== "approximated" && entry.state !== "bypassed") return word;
+	return `${word} (${entry.authority.id})`;
+}
+
+/**
+ * The compact human body. Clause order is fixed: integrity, validation with
+ * its claimant, independent review, autonomy, context, completion. Every
+ * surface prints this body verbatim, so two surfaces can only disagree by
+ * reading different canonical input.
+ */
+export function formatTrustSummary(status: CanonicalTrustStatus): string {
+	return [
+		integrityClause(status),
+		validationClause(status),
+		trustStateWord("independentReview", status.independentReview.state),
+		autonomyClause(status),
+		trustStateWord("contextProvenance", status.contextProvenance.state),
+		trustStateWord("completionEvidence", status.completionEvidence.state),
+	].join("; ");
+}
+
+/** The tier and body under one versioned label for receipt-facing surfaces. */
+export function formatTrustSummaryLine(status: CanonicalTrustStatus): string {
+	return `trust v${TRUST_SUMMARY_VERSION}: ${trustVerdict(status)}; ${formatTrustSummary(status)}`;
+}
+
+/**
+ * The drill-down token line: every axis in canonical state ids. This is the
+ * one machine-readable text form; `evidence inspect` and the dispatch and
+ * monitor labels all print it from here.
+ */
+export function formatTrustAxes(status: CanonicalTrustStatus): string {
+	return [`trust_status=v${status.version}`, ...TRUST_STATUS_AXES.map((axis) => `${axis}:${status[axis].state}`)].join(
+		" ",
+	);
+}
+
+function isUnanswered(status: CanonicalTrustStatus, axis: TrustStatusAxis): boolean {
+	const state = status[axis].state;
+	return state === "absent" || state === "unknown";
+}
+
+/**
+ * Read the tier off the axes in priority order. A broken seal, a bypassed
+ * gate, a failed or inferred validation, a failed or correlated review, or a
+ * contradictory context record compromises the result whatever else holds.
+ * An unchecked or missing seal leaves it unknown. Only an authenticated
+ * independent pass is `reviewed`; observed validation without one is
+ * `grounded`; a sealed receipt with nothing observed is `unverified`.
+ */
+export function trustVerdict(status: CanonicalTrustStatus): TrustVerdict {
+	const integrity = status.artifactIntegrity.state;
+	const validation = status.validationGrounding.state;
+	const review = status.independentReview.state;
+	const autonomy = status.autonomyEnforcement.state;
+	if (
+		integrity === "failed" ||
+		autonomy === "bypassed" ||
+		validation === "failed" ||
+		validation === "ungrounded" ||
+		review === "failed" ||
+		review === "not_independent" ||
+		status.contextProvenance.state === "invalid"
+	) {
+		return "compromised";
+	}
+	if (integrity !== "verified") return "unknown";
+	if (review === "passed") return "reviewed";
+	if (validation === "validated") return "grounded";
+	return "unverified";
+}
+
+function claimantOf(status: CanonicalTrustStatus): string {
+	const state = status.validationGrounding.state;
+	if (state === "absent" || state === "ungrounded") return "worker";
+	return authorityOf(status, "validationGrounding") ?? "worker";
+}
+
+function referenceKey(reference: TrustArtifactReference): string {
+	return `${reference.kind}:${reference.id}`;
+}
+
+/** Every artifact the axes cite, as bounded pointers a consumer can resolve. */
+export function trustSummaryReferences(status: CanonicalTrustStatus): string[] {
+	const keys = new Set<string>();
+	for (const axis of TRUST_STATUS_AXES) {
+		const entry = status[axis];
+		if (entry.state === "absent") continue;
+		for (const reference of entry.artifacts) keys.add(referenceKey(reference));
+	}
+	return [...keys].sort().slice(0, TRUST_SUMMARY_MAX_REFS);
+}
+
+/** The bounded machine projection. Flat by design so a depth-capped wire keeps it whole. */
+export function summarizeTrustStatus(status: CanonicalTrustStatus): TrustSummaryProjection {
+	const axes = Object.fromEntries(TRUST_STATUS_AXES.map((axis) => [axis, status[axis].state])) as Record<
+		TrustStatusAxis,
+		string
+	>;
+	return {
+		version: TRUST_SUMMARY_VERSION,
+		verdict: trustVerdict(status),
+		text: formatTrustSummary(status),
+		axes,
+		claimant: claimantOf(status),
+		unknown: TRUST_STATUS_AXES.filter((axis) => isUnanswered(status, axis)),
+		refs: trustSummaryReferences(status),
+	};
+}

package/src/domains/evidence/trust-status.ts

@@ -1,5 +1,5 @@
 import type { GateDecisionArtifact, GateDecisionVerification } from "../dispatch/gate-decisions.js";
-import { type ReceiptIntegrityResult, verifyReceiptIntegrity } from "../dispatch/receipt-integrity.js";
+import { RUN_RECEIPT_INTEGRITY_VERSION, verifyReceiptIntegrity } from "../dispatch/receipt-integrity.js";
 import type {
 	RunBriefingProvenance,
 	RunEnvelope,
@@ -459,13 +459,89 @@ function compatibilitySource(receipt: PersistedRunReceiptTrustFacts, field: stri
 const DISPATCH_AUTHORITY: TrustStatusAuthority = { kind: "clio", id: "dispatch" };
 const COMPATIBILITY_AUTHORITY: TrustStatusAuthority = { kind: "unknown", id: "historical-persisted-format" };
 
+/**
+ * A receipt sealed under an integrity version this build no longer verifies.
+ * It is not migrated and not read as evidence, on the same terms as every
+ * prior integrity bump, but it is not a tampered receipt either: nothing was
+ * checked, so nothing failed. The outcome names both versions so an operator
+ * with a store full of last release's runs can tell a retired seal from a
+ * broken one.
+ */
+export interface RetiredReceiptIntegrity {
+	receiptVersion: number;
+	supportedVersion: number;
+}
+
+/**
+ * The dispatch verifier's result, widened with the retired-format diagnosis
+ * this module puts in front of it. A failure without `retired` is the
+ * verifier's own verdict: a malformed seal, a ledger mismatch, or a digest
+ * that does not match the receipt's contents.
+ */
+export type ReceiptIntegrityOutcome = { ok: true } | { ok: false; reason: string; retired?: RetiredReceiptIntegrity };
+
+/** The retired-version diagnosis for a receipt's integrity block, or null when the block is current or unreadable. */
+export function retiredReceiptIntegrity(integrity: unknown): RetiredReceiptIntegrity | null {
+	if (!isRecord(integrity)) return null;
+	const version = integrity.version;
+	if (typeof version !== "number" || !Number.isInteger(version) || version < 1) return null;
+	if (version >= RUN_RECEIPT_INTEGRITY_VERSION) return null;
+	return { receiptVersion: version, supportedVersion: RUN_RECEIPT_INTEGRITY_VERSION };
+}
+
+/** The one sentence every surface prints for a retired seal. It never calls the receipt invalid, broken, or corrupt. */
+export function retiredReceiptIntegrityReason(retired: RetiredReceiptIntegrity): string {
+	return `receipt integrity v${retired.receiptVersion} is retired; this build verifies v${retired.supportedVersion}; the receipt is not read as evidence`;
+}
+
+/**
+ * Verify a receipt against its ledger row, diagnosing a retired seal before
+ * the verifier can report it as a malformed one. Every trust-bearing
+ * verification goes through here so the CLI, the bundle, and the TUI receipt
+ * view agree on what a retired receipt is.
+ */
+export function verifyReceiptIntegrityOutcome(receipt: RunReceipt, envelope: RunEnvelope): ReceiptIntegrityOutcome {
+	const retired = retiredReceiptIntegrity(receipt.integrity);
+	if (retired !== null) return { ok: false, reason: retiredReceiptIntegrityReason(retired), retired };
+	return verifyReceiptIntegrity(receipt, envelope);
+}
+
+const RETIRED_INTEGRITY_SOURCE = /:integrity-v(\d+)-retired$/u;
+
+function retiredIntegritySourceId(runId: string, receiptVersion: number): string {
+	return `run_receipt:${runId}:integrity-v${receiptVersion}-retired`;
+}
+
+/**
+ * The retired integrity version a projected artifact-integrity axis names, or
+ * null when the axis says something else. The compatibility source id is the
+ * only place the persisted projection carries the version, so the human clause
+ * reads it back from there rather than from the receipt.
+ */
+export function retiredIntegrityVersionOf(status: ArtifactIntegrityStatus): number | null {
+	if (status.state !== "unknown" || status.source.kind !== "compatibility") return null;
+	const match = RETIRED_INTEGRITY_SOURCE.exec(status.source.id);
+	return match === null ? null : Number(match[1]);
+}
+
 /** Adapt receipt integrity verification without reading any receipt claim as self-authenticating. */
 export function adaptReceiptIntegrityStatus(
 	receipt: PersistedRunReceiptTrustFacts | null | undefined,
-	verification?: ReceiptIntegrityResult,
+	verification?: ReceiptIntegrityOutcome,
 ): ArtifactIntegrityStatus {
 	if (receipt === null || receipt === undefined) return absentTrustStatus("artifact_missing");
 	const artifacts = [receiptReference(receipt)];
+	// A retired seal was never checked, so the axis is unknown rather than
+	// failed, and the compatibility source names the version it was sealed
+	// under. `failed` stays reserved for a seal this build verified and rejected.
+	if (verification !== undefined && !verification.ok && verification.retired !== undefined) {
+		return attributed(
+			"unknown",
+			{ kind: "compatibility", id: retiredIntegritySourceId(receipt.runId, verification.retired.receiptVersion) },
+			COMPATIBILITY_AUTHORITY,
+			artifacts,
+		);
+	}
 	if (verification === undefined || (verification.ok && receipt.integrity === undefined)) {
 		return attributed(
 			"unknown",
@@ -576,15 +652,46 @@ function validBoundedProjectContext(context: RunProjectContextProvenance): boole
 	);
 }
 
+/**
+ * The one structured message a `none`-tier run can still receive. The tier is
+ * the CLIO-CODER.md handbook policy; the workspace-root message is sent
+ * regardless of it, and the producer records the characters and hash of
+ * every structured message it sent (`projectContextProvenanceFor` in the
+ * dispatch extension). A none-tier block naming exactly this section, with
+ * a well-formed count and hash, is therefore a consistent record of a real
+ * message, not a contradiction. Anything else under a none tier cannot be
+ * explained by the policy: a handbook section the policy forbids, a hash
+ * with no section to hash, or a malformed count.
+ */
+const NONE_TIER_SECTIONS: ReadonlyArray<string> = ["workspace-root"];
+
+function validNoneTierProjectContext(context: RunProjectContextProvenance): boolean {
+	return (
+		context.tier === "none" &&
+		context.sections !== undefined &&
+		context.sections.length === NONE_TIER_SECTIONS.length &&
+		context.sections.every((section) => NONE_TIER_SECTIONS.includes(section)) &&
+		Number.isSafeInteger(context.chars) &&
+		(context.chars ?? -1) >= 0 &&
+		typeof context.contentHash === "string" &&
+		/^[a-f0-9]{64}$/u.test(context.contentHash)
+	);
+}
+
+function recordedProjectContextHash(context: RunProjectContextProvenance | undefined): string | undefined {
+	if (context === undefined) return undefined;
+	if (context.tier === "bounded") return validBoundedProjectContext(context) ? context.contentHash : undefined;
+	return validNoneTierProjectContext(context) ? context.contentHash : undefined;
+}
+
 function contextArtifacts(receipt: PersistedRunReceiptTrustFacts): TrustArtifactReference[] {
 	const artifacts = [receiptReference(receipt)];
 	if (receipt.briefing !== undefined && validBriefing(receipt.briefing)) {
 		artifacts.push(sha256Reference("briefing", `${receipt.runId}:briefing`, receipt.briefing.contentHash));
 	}
-	if (receipt.projectContext?.tier === "bounded" && validBoundedProjectContext(receipt.projectContext)) {
-		artifacts.push(
-			sha256Reference("project_context", `${receipt.runId}:project-context`, receipt.projectContext.contentHash),
-		);
+	const recordedHash = recordedProjectContextHash(receipt.projectContext);
+	if (recordedHash !== undefined) {
+		artifacts.push(sha256Reference("project_context", `${receipt.runId}:project-context`, recordedHash));
 	}
 	return uniqueBoundedReferences(artifacts);
 }
@@ -604,12 +711,23 @@ export function adaptRunReceiptContextStatus(
 		return attributed("unknown", compatibilitySource(receipt, "projectContext"), COMPATIBILITY_AUTHORITY, artifacts);
 	}
 	if (context.tier === "none") {
-		if (context.chars !== undefined || context.contentHash !== undefined || context.sections !== undefined) {
-			return attributed("invalid", source, DISPATCH_AUTHORITY, artifacts);
+		const bare = context.chars === undefined && context.contentHash === undefined && context.sections === undefined;
+		if (bare) {
+			// Nothing structured was sent: the axis does not apply unless a
+			// briefing was recorded, which is context of its own.
+			return receipt.briefing === undefined
+				? attributed("not_applicable", source, DISPATCH_AUTHORITY, artifacts)
+				: attributed("recorded", source, DISPATCH_AUTHORITY, artifacts);
 		}
-		return receipt.briefing === undefined
-			? attributed("not_applicable", source, DISPATCH_AUTHORITY, artifacts)
-			: attributed("recorded", source, DISPATCH_AUTHORITY, artifacts);
+		// The workspace-root message is the one thing a none-tier run receives,
+		// and its record is valid; every other none-tier content shape is a
+		// record the policy cannot account for.
+		return attributed(
+			validNoneTierProjectContext(context) ? "recorded" : "invalid",
+			source,
+			DISPATCH_AUTHORITY,
+			artifacts,
+		);
 	}
 	return attributed(validBoundedProjectContext(context) ? "recorded" : "invalid", source, DISPATCH_AUTHORITY, artifacts);
 }
@@ -639,18 +757,19 @@ export function adaptRunReceiptAutonomyStatus(
 }
 
 export interface AdaptRunReceiptTrustOptions {
-	integrity?: ReceiptIntegrityResult;
+	integrity?: ReceiptIntegrityOutcome;
 }
 
 function receiptClaimsAreAuthenticated(
 	receipt: PersistedRunReceiptTrustFacts | null | undefined,
-	integrity: ReceiptIntegrityResult | undefined,
+	integrity: ReceiptIntegrityOutcome | undefined,
 ): boolean {
 	return receipt?.integrity !== undefined && integrity?.ok === true;
 }
 
 function unauthenticatedReceiptProjection(
 	receipt: PersistedRunReceiptTrustFacts | null | undefined,
+	integrity: ReceiptIntegrityOutcome | undefined,
 ): TrustStatusProjection {
 	if (receipt === null || receipt === undefined) {
 		return {
@@ -682,6 +801,15 @@ function unauthenticatedReceiptProjection(
 			),
 		};
 	}
+	// A retired seal leaves the receipt unread rather than rejected: its axes
+	// are absent because the format is historical, not because a check failed.
+	if (integrity !== undefined && !integrity.ok && integrity.retired !== undefined) {
+		return {
+			validationGrounding: absentTrustStatus("historical_format"),
+			contextProvenance: absentTrustStatus("historical_format"),
+			autonomyEnforcement: absentTrustStatus("historical_format"),
+		};
+	}
 	// The artifact-integrity axis retains the failure diagnostic. No other
 	// axis reads a field from a receipt that failed authentication.
 	return {
@@ -703,7 +831,7 @@ export function adaptRunReceiptTrustStatus(
 				contextProvenance: adaptRunReceiptContextStatus(receipt),
 				autonomyEnforcement: adaptRunReceiptAutonomyStatus(receipt),
 			}
-		: unauthenticatedReceiptProjection(receipt);
+		: unauthenticatedReceiptProjection(receipt, options.integrity);
 	return composeTrustStatus({
 		artifactIntegrity: adaptReceiptIntegrityStatus(receipt, options.integrity),
 		...receiptProjection,
@@ -715,7 +843,7 @@ export function adaptRunReceiptTrustStatus(
 }
 
 export interface RunReceiptTrustInspection {
-	integrity: ReceiptIntegrityResult;
+	integrity: ReceiptIntegrityOutcome;
 	status: CanonicalTrustStatus;
 }
 
@@ -728,14 +856,14 @@ export function inspectRunReceiptTrustStatus(
 	receipt: RunReceipt | null | undefined,
 	envelope: RunEnvelope | null | undefined,
 ): RunReceiptTrustInspection {
-	let integrity: ReceiptIntegrityResult;
+	let integrity: ReceiptIntegrityOutcome;
 	if (receipt === null || receipt === undefined) {
 		integrity = { ok: false, reason: "receipt unavailable" };
 	} else if (envelope === null || envelope === undefined) {
 		integrity = { ok: false, reason: "run ledger envelope unavailable" };
 	} else {
 		try {
-			integrity = verifyReceiptIntegrity(receipt, envelope);
+			integrity = verifyReceiptIntegrityOutcome(receipt, envelope);
 		} catch (error) {
 			integrity = {
 				ok: false,

package/src/domains/evidence/types.ts

@@ -23,7 +23,11 @@ export const EVIDENCE_TAGS = [
 	"escalation",
 	"external-bypass",
 	"external-approximation",
+	"independent-review",
+	"context-provenance",
+	"completion-evidence",
 	"receipt-integrity",
+	"receipt-retired",
 	"protected-artifact",
 	"tool-loop",
 	"test-failure",