yarramate 0.16.0 → 0.18.0

package/dist/adapters/visual/wire.d.ts

@@ -0,0 +1,93 @@
+import type { VISUAL_PROTOCOL_VERSION, VisualAuthority, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFreezeReason, VisualResponse, VisualTerminationReason } from './protocol-contract.js';
+/**
+ * Transport shapes the session server and the browser application both speak.
+ *
+ * These are not protocol documents: they carry validated documents plus the
+ * transport's own acknowledgements, so they are discriminated by `kind` rather
+ * than by a versioned `format`. They live apart from the server because the
+ * browser bundle must import the contract without importing the Node runtime
+ * that serves it — this module holds types only, and every dependency it has on
+ * the protocol is type-only too.
+ */
+/** One promoted candidate as the browser receives it. */
+export interface VisualRenderedModel {
+    readonly candidate: string;
+    readonly authority: VisualAuthority;
+    readonly initialView: string;
+    readonly views: readonly string[];
+    /**
+     * The trusted compiler's own LikeC4 export for this candidate, the document
+     * `createLikeC4Model` consumes. Its internals belong to LikeC4, so the
+     * transport carries it verbatim instead of restating a shape it does not own.
+     */
+    readonly compiled: unknown;
+}
+/**
+ * One line of the conversation, as plain text.
+ *
+ * The server keeps this beside the journal so a browser that reloads or
+ * reconnects sees the conversation it left. It carries no model source, no
+ * credential, and none of the journal's own bookkeeping — only what was said
+ * and who said it.
+ */
+export interface VisualTranscriptRecord {
+    readonly id: string;
+    readonly speaker: 'reviewer' | 'agent';
+    readonly text: string;
+}
+/** Everything the browser needs to render, and nothing that authenticates it. */
+export interface VisualSessionSnapshot {
+    readonly protocolVersion: typeof VISUAL_PROTOCOL_VERSION;
+    readonly sessionId: string;
+    readonly authority: VisualAuthority;
+    readonly title: string;
+    readonly description: string;
+    readonly chatEnabled: boolean;
+    readonly capabilities: VisualCapabilities;
+    readonly webSocketUrl: string;
+    readonly model: VisualRenderedModel;
+    readonly transcript: readonly VisualTranscriptRecord[];
+    /**
+     * Whether the agent still owes an answer to something the reviewer sent. A
+     * browser that reconnects mid-turn reads this rather than inferring the turn
+     * from the transcript, so a reply it never saw does not leave it waiting.
+     */
+    readonly agentTurnOpen: boolean;
+    /**
+     * The structured choice the agent is still waiting on, or `null`. The
+     * question lives in the agent's response and never in the transcript, so a
+     * browser that reloads or reconnects reads it here; without it the reviewer
+     * comes back to a session waiting on a selection they can no longer make.
+     */
+    readonly pendingChoice: VisualChoicePresentPayload | null;
+    /**
+     * Nonce this session's policy admits for the inline styles the diagram
+     * renderer injects. It authorises styling and nothing else, and it is not a
+     * credential: the session cookie is what authenticates this snapshot.
+     */
+    readonly styleNonce: string;
+    readonly lastSequence: number;
+    readonly frozen: boolean;
+}
+/** Server-to-browser transport frame. */
+export type VisualServerFrame = {
+    readonly kind: 'ready';
+    readonly snapshot: VisualSessionSnapshot;
+} | {
+    readonly kind: 'accepted';
+    readonly sequence: number;
+    readonly eventId: string;
+} | {
+    readonly kind: 'rejected';
+    readonly diagnostics: readonly VisualDiagnostic[];
+    readonly frozen?: VisualFreezeReason;
+} | {
+    readonly kind: 'response';
+    readonly response: VisualResponse;
+} | {
+    readonly kind: 'model';
+    readonly model: VisualRenderedModel;
+} | {
+    readonly kind: 'closing';
+    readonly reason: VisualTerminationReason;
+};

package/dist/adapters/visual/wire.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/visual-cli.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { type CliResult } from '../cli-support.js';
+export declare const visualUsage: string;
+/**
+ * Where a repository keeps its live sessions, one directory per session. It sits
+ * under the ignored build directory because a session is runtime state: never
+ * canonical, never committed, and pruned by the next start.
+ */
+export declare const VISUAL_SESSION_DIRECTORY: string;
+/**
+ * Every command an agent can run to completion. `start` is not one of them: it
+ * blocks for the life of the session and is dispatched by `runVisualCli`.
+ */
+export declare function runVisualClientCli(args: readonly string[], cwd?: string): Promise<CliResult>;
+/** Where a foreground session publishes, and where it observes its signals. */
+export interface VisualSignalSource {
+    on(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    off(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+export interface VisualStartIo {
+    readonly stdout: (chunk: string) => void;
+    readonly stderr: (chunk: string) => void;
+    /** Defaults to the process itself. */
+    readonly signals?: VisualSignalSource;
+}
+/**
+ * Serves one visual session in the foreground.
+ *
+ * The request is validated before any filesystem or network effect, so a bad
+ * document costs nothing. Exactly one public `visual-session-started/v1` line is
+ * published before the command blocks — it names the private descriptor but
+ * never carries the agent capability, which lives only in that mode 0600 file.
+ * The command then holds the session open until the runtime closes it, whether
+ * that is a signal, an agent stop, or a runtime failure; the runtime recovers
+ * the handoff before it removes the session in every one of those cases.
+ */
+export declare const runVisualStart: (requestPath: string, cwd?: string, io?: VisualStartIo) => Promise<CliResult>;
+/**
+ * The whole binary: `start` blocks and streams its one document through `io`,
+ * every other command runs to completion and returns its document.
+ */
+export declare const runVisualCli: (args: readonly string[], cwd?: string, io?: VisualStartIo) => Promise<CliResult>;

package/dist/adapters/visual-cli.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+import { join } from 'node:path';
+import { isMainModule, versionResult } from '../cli-support.js';
+import { fetchVisualStatus, readVisualJsonDocument, readVisualSessionDescriptor, recoverVisualSessionClient, sendVisualResponse, stopVisualSessionClient, visualClientDiagnostic, visualFailureDiagnostics, visualSessionAlreadyStopped, waitForVisualEvent, } from './visual/client.js';
+import { parseVisualResponse, parseVisualSessionRequest, } from './visual/protocol.js';
+import { startVisualServer } from './visual/session-server.js';
+import { pruneStaleVisualSessions } from './visual/session-store.js';
+export const visualUsage = 'Usage:\n' +
+    '  yarramate-visual start <request.json>\n' +
+    '  yarramate-visual wait <descriptor.json> [--after <sequence>]\n' +
+    '  yarramate-visual respond <descriptor.json> <response.json>\n' +
+    '  yarramate-visual status <descriptor.json>\n' +
+    '  yarramate-visual recover <descriptor.json> [--transcript]\n' +
+    '  yarramate-visual stop <descriptor.json> [--transcript]\n' +
+    '  yarramate-visual --version\n';
+/**
+ * Where a repository keeps its live sessions, one directory per session. It sits
+ * under the ignored build directory because a session is runtime state: never
+ * canonical, never committed, and pruned by the next start.
+ */
+export const VISUAL_SESSION_DIRECTORY = join('.yarramate-out', 'visual');
+/** Terminations that mean the session did not end the way it was asked to. */
+const FAILED_TERMINATION = {
+    'child-failed': true,
+    'browser-timeout': true,
+    'server-failed': true,
+    'compiler-failed': true,
+};
+const usageResult = {
+    exitCode: 2,
+    stdout: '',
+    stderr: visualUsage,
+};
+/**
+ * One document per line: every command an agent drives writes at most one
+ * versioned document, so a caller reads exactly one line per invocation.
+ */
+const documentLine = (value) => `${JSON.stringify(value)}\n`;
+/**
+ * Stdout carries the document that was asked for and nothing else, so a refusal
+ * goes to stderr where it cannot be mistaken for an answer.
+ */
+const refusalResult = (diagnostics) => ({
+    exitCode: 1,
+    stdout: '',
+    stderr: documentLine({
+        format: 'yarramate/visual-diagnostic-result/v1',
+        diagnostics,
+    }),
+});
+/** Sequences are counted, so only a plain non-negative integer is one. */
+const sequenceFlag = (rest) => {
+    if (rest.length === 0)
+        return 0;
+    const [flag, value] = rest;
+    if (flag !== '--after' || value === undefined || rest.length !== 2) {
+        return undefined;
+    }
+    if (!/^(?:0|[1-9][0-9]*)$/.test(value))
+        return undefined;
+    const sequence = Number(value);
+    return Number.isSafeInteger(sequence) ? sequence : undefined;
+};
+const transcriptFlag = (rest) => rest.length === 0
+    ? false
+    : rest.length === 1 && rest[0] === '--transcript'
+        ? true
+        : undefined;
+const waitCliCommand = async (descriptorPath, rest, cwd) => {
+    const after = sequenceFlag(rest);
+    if (after === undefined)
+        return usageResult;
+    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    if (!descriptor.ok)
+        return refusalResult(descriptor.diagnostics);
+    const delivery = await waitForVisualEvent(descriptor.value, after);
+    if (!delivery.ok)
+        return refusalResult(delivery.diagnostics);
+    return {
+        exitCode: 0,
+        // An idle window is not a failure and has no document: the caller polls
+        // again from the sequence it already knows.
+        stdout: delivery.value.waiting ? '' : documentLine(delivery.value.event),
+        stderr: '',
+    };
+};
+const respondCliCommand = async (descriptorPath, rest, cwd) => {
+    const [responsePath, ...trailing] = rest;
+    if (responsePath === undefined || trailing.length > 0)
+        return usageResult;
+    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    if (!descriptor.ok)
+        return refusalResult(descriptor.diagnostics);
+    const document = await readVisualJsonDocument(responsePath, cwd);
+    if (!document.ok)
+        return refusalResult(document.diagnostics);
+    // Validated here as well as by the runtime, so an invalid response never
+    // reaches the session at all.
+    const response = parseVisualResponse(document.value);
+    if (!response.ok)
+        return refusalResult(response.diagnostics);
+    const accepted = await sendVisualResponse(descriptor.value, response.value);
+    if (!accepted.ok)
+        return refusalResult(accepted.diagnostics);
+    return { exitCode: 0, stdout: documentLine(accepted.value), stderr: '' };
+};
+const statusCliCommand = async (descriptorPath, rest, cwd) => {
+    if (rest.length > 0)
+        return usageResult;
+    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    if (!descriptor.ok)
+        return refusalResult(descriptor.diagnostics);
+    const status = await fetchVisualStatus(descriptor.value);
+    if (!status.ok)
+        return refusalResult(status.diagnostics);
+    return { exitCode: 0, stdout: documentLine(status.value), stderr: '' };
+};
+const recoverCliCommand = async (descriptorPath, rest, cwd) => {
+    const includeTranscript = transcriptFlag(rest);
+    if (includeTranscript === undefined)
+        return usageResult;
+    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    if (!descriptor.ok)
+        return refusalResult(descriptor.diagnostics);
+    const handoff = await recoverVisualSessionClient(descriptor.value, includeTranscript);
+    if (!handoff.ok)
+        return refusalResult(handoff.diagnostics);
+    return { exitCode: 0, stdout: documentLine(handoff.value), stderr: '' };
+};
+/**
+ * Converges the session on stopped, and says so however many times it is asked.
+ * The design's failure table requires a repeated stop to report the
+ * already-stopped state, and the first stop takes the descriptor with the
+ * session root, so the second invocation has nothing left to read. That one
+ * shape — descriptor and session root both gone — reports the same benign
+ * already-stopped result the client returns for a retained descriptor: exit 0,
+ * no handoff document, because there is no session left to hand off.
+ *
+ * Every other unreadable descriptor still refuses. Nothing weakens: no
+ * credential is retained, no directory is removed on the strength of a
+ * descriptor that did not parse, and a corrupt, redirected, or foreign
+ * descriptor fails exactly as before.
+ */
+const stopCliCommand = async (descriptorPath, rest, cwd) => {
+    const includeTranscript = transcriptFlag(rest);
+    if (includeTranscript === undefined)
+        return usageResult;
+    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    if (!descriptor.ok) {
+        return (await visualSessionAlreadyStopped(descriptorPath, cwd))
+            ? { exitCode: 0, stdout: '', stderr: '' }
+            : refusalResult(descriptor.diagnostics);
+    }
+    const stopped = await stopVisualSessionClient(descriptor.value, includeTranscript);
+    if (!stopped.ok)
+        return refusalResult(stopped.diagnostics);
+    return {
+        exitCode: 0,
+        // A session that was already gone has no handoff left to publish.
+        stdout: stopped.value === undefined ? '' : documentLine(stopped.value),
+        stderr: '',
+    };
+};
+/**
+ * Every command an agent can run to completion. `start` is not one of them: it
+ * blocks for the life of the session and is dispatched by `runVisualCli`.
+ */
+export async function runVisualClientCli(args, cwd = process.cwd()) {
+    const [command, descriptor, ...rest] = args;
+    if (command === '--version')
+        return versionResult('yarramate-visual');
+    if (descriptor === undefined)
+        return usageResult;
+    switch (command) {
+        case 'wait':
+            return waitCliCommand(descriptor, rest, cwd);
+        case 'respond':
+            return respondCliCommand(descriptor, rest, cwd);
+        case 'status':
+            return statusCliCommand(descriptor, rest, cwd);
+        case 'recover':
+            return recoverCliCommand(descriptor, rest, cwd);
+        case 'stop':
+            return stopCliCommand(descriptor, rest, cwd);
+        default:
+            return usageResult;
+    }
+}
+const processIo = {
+    stdout: (chunk) => void process.stdout.write(chunk),
+    stderr: (chunk) => void process.stderr.write(chunk),
+};
+/**
+ * Serves one visual session in the foreground.
+ *
+ * The request is validated before any filesystem or network effect, so a bad
+ * document costs nothing. Exactly one public `visual-session-started/v1` line is
+ * published before the command blocks — it names the private descriptor but
+ * never carries the agent capability, which lives only in that mode 0600 file.
+ * The command then holds the session open until the runtime closes it, whether
+ * that is a signal, an agent stop, or a runtime failure; the runtime recovers
+ * the handoff before it removes the session in every one of those cases.
+ */
+export const runVisualStart = async (requestPath, cwd = process.cwd(), io = processIo) => {
+    const document = await readVisualJsonDocument(requestPath, cwd);
+    if (!document.ok)
+        return refusalResult(document.diagnostics);
+    const request = parseVisualSessionRequest(document.value);
+    if (!request.ok)
+        return refusalResult(request.diagnostics);
+    const baseDir = join(cwd, VISUAL_SESSION_DIRECTORY);
+    const signals = io.signals ?? process;
+    let handle;
+    try {
+        // A previous runtime's orphans are collected on the critical path of a new
+        // session, bounded per pass so a full directory cannot stall this one.
+        await pruneStaleVisualSessions(baseDir, new Date());
+        handle = await startVisualServer({ request: request.value, baseDir });
+    }
+    catch (cause) {
+        // A failed start has already recovered and removed whatever it created.
+        return refusalResult(visualFailureDiagnostics(cause));
+    }
+    io.stdout(documentLine(handle.started));
+    // One handler for both signals: `stop` converges on the first reason it is
+    // given, so a repeated or second signal is absorbed rather than racing.
+    //
+    // A signal is not a caller, and nothing here awaits the teardown it starts:
+    // a stop that fails is observed rather than left to reach the runtime as an
+    // unhandled rejection and take the whole session down with it. What it could
+    // not tear down is still up, this command is still blocked on `closed`, and
+    // the next signal runs the teardown again.
+    const interrupt = () => {
+        void handle.stop('main-cancelled').catch(() => undefined);
+    };
+    signals.on('SIGINT', interrupt);
+    signals.on('SIGTERM', interrupt);
+    try {
+        const closed = await handle.closed;
+        // The recovered handoff is what the journal says happened; the reason the
+        // stop asked for is only what someone wanted. A session the reviewer ended
+        // is a success even when a cancelling agent is what closed the server, and
+        // a child that died before its handoff is a failure even when it did not.
+        const outcome = closed.handoff?.terminationReason ?? closed.reason;
+        return FAILED_TERMINATION[outcome] === true
+            ? refusalResult([
+                visualClientDiagnostic('YMVS409', `Visual session ${handle.started.sessionId} ended with termination reason "${outcome}"`),
+            ])
+            : { exitCode: 0, stdout: '', stderr: '' };
+    }
+    finally {
+        signals.off('SIGINT', interrupt);
+        signals.off('SIGTERM', interrupt);
+    }
+};
+/**
+ * The whole binary: `start` blocks and streams its one document through `io`,
+ * every other command runs to completion and returns its document.
+ */
+export const runVisualCli = async (args, cwd = process.cwd(), io = processIo) => {
+    if (args[0] !== 'start')
+        return runVisualClientCli(args, cwd);
+    const requestPath = args[1];
+    if (requestPath === undefined || args.length !== 2)
+        return usageResult;
+    return runVisualStart(requestPath, cwd, io);
+};
+if (isMainModule(import.meta.url, process.argv[1])) {
+    void runVisualCli(process.argv.slice(2)).then((result) => {
+        process.stdout.write(result.stdout);
+        process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+    });
+}

package/dist/attestation-staleness.js

@@ -49,7 +49,14 @@ const attestedConcepts = (source, documentId) => {
             }
             const { topic, by, on } = record;
             if (topic !== undefined && by !== undefined && on !== undefined) {
-                attestations.push({ topic, by, on });
+                // The authority is a reference; report it in the same qualified form
+                // the compiler resolves, so one sign-off reads identically in a
+                // staleness finding, a reconcile finding, and the RTM.
+                attestations.push({
+                    topic,
+                    by: by.includes('#') ? by : `${documentId}#${by}`,
+                    on,
+                });
             }
         }
         if (attestations.length === 0)

package/dist/compiler.d.ts

@@ -63,5 +63,17 @@ export type ContextualCompilationResult = {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
 };
+export declare const ATTESTATION_PREDICATE_PREFIX = "yarramate/attestation/";
+export declare const attestationClaimValue: (attestation: {
+    readonly by: string;
+    readonly on: string;
+    readonly recordedBy?: string;
+}) => string;
+export interface AttestationClaimParts {
+    readonly by: string;
+    readonly on: string;
+    readonly recordedBy?: string;
+}
+export declare const parseAttestationClaimValue: (value: string) => AttestationClaimParts | undefined;
 export declare function compileWorkspace(sources: readonly WorkspaceSource[]): CompilationResult;
 export declare const compileWorkspaceWithProfileContext: (sources: readonly WorkspaceSource[]) => ContextualCompilationResult;

package/dist/compiler.js

@@ -37,6 +37,25 @@ const presenceClaimId = (subject, state) => `${subject}~present-in-${Buffer.from
 const aliasClaimId = (subject, alias) => `${subject}~alias-${Buffer.from(alias, 'utf8').toString('hex')}`;
 const distinctFromClaimId = (subject, other) => `${subject}~distinct-from-${Buffer.from(other, 'utf8').toString('hex')}`;
 const supersedesClaimId = (subject, predecessor) => `${subject}~supersedes-${Buffer.from(predecessor, 'utf8').toString('hex')}`;
+export const ATTESTATION_PREDICATE_PREFIX = 'yarramate/attestation/';
+// An attestation claim packs the authority, the date it was given, and
+// the recorder when a machine held the pen. A reference carries no
+// spaces and the date is fixed width, so the three parse back out of one
+// value unambiguously wherever a reader needs them.
+export const attestationClaimValue = (attestation) => attestation.recordedBy === undefined
+    ? `${attestation.by} ${attestation.on}`
+    : `${attestation.by} ${attestation.on} ${attestation.recordedBy}`;
+export const parseAttestationClaimValue = (value) => {
+    const match = /^(\S+) ([0-9]{4}-[0-9]{2}-[0-9]{2})(?: (.+))?$/.exec(value);
+    if (match === null)
+        return undefined;
+    const recordedBy = match[3];
+    return {
+        by: match[1],
+        on: match[2],
+        ...(recordedBy === undefined ? {} : { recordedBy }),
+    };
+};
 const describeAspect = (aspect) => aspect.replace('-', ' ');
 // Candidate order is the policy-matrix declaration order: the resolved kind
 // map inserts core policies first, then extension kinds as declared.
@@ -1128,11 +1147,36 @@ function compileWorkspaceResolved(sources) {
             // evaluates: the claim's existence is what triggers can see, and
             // revocation is deletion, reviewed at the Git boundary.
             for (const [attestationIndex, attestation] of (concept.attestations ?? []).entries()) {
+                // The authority is held to the same rule as ownership: a judgment
+                // is worthless if nobody in the model made it, and a name only the
+                // signer knows cannot be checked by the reviewer reading the diff.
+                const authority = qualifyReference(value.id, attestation.by);
+                if (!conceptByQualifiedId.has(authority)) {
+                    const pointer = `/concepts/${index}/attestations/${attestationIndex}/by`;
+                    const source = location(['concepts', index, 'attestations', attestationIndex, 'by'], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM304',
+                        message: `Unresolved attestation authority reference "${attestation.by}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
                 claims.push({
                     id: `${subject}~attestation-${attestation.topic}`,
                     subject,
-                    predicate: `yarramate/attestation/${attestation.topic}`,
-                    object: { value: `${attestation.by} ${attestation.on}` },
+                    predicate: `${ATTESTATION_PREDICATE_PREFIX}${attestation.topic}`,
+                    object: {
+                        value: attestationClaimValue({
+                            by: authority,
+                            on: attestation.on,
+                            ...(attestation.recordedBy === undefined
+                                ? {}
+                                : { recordedBy: attestation.recordedBy }),
+                        }),
+                    },
                     origin: 'declared',
                     source: location(['concepts', index, 'attestations', attestationIndex, 'topic'], `/concepts/${index}/attestations/${attestationIndex}/topic`),
                 });

package/dist/reconciliation.d.ts

@@ -55,7 +55,22 @@ export interface StaleAttestationFinding {
     readonly changedAt?: string;
     readonly evidence: EvidenceLocator;
 }
-export type ReconciliationFinding = EvidenceFinding | StaleAttestationFinding;
+export interface UnconfirmedAttestationFinding {
+    readonly target: {
+        readonly type: 'subject';
+        readonly id: string;
+    };
+    readonly result: 'unconfirmed-attestation';
+    readonly attestation: {
+        readonly topic: string;
+        readonly by: string;
+        readonly recordedBy: string;
+        readonly on: string;
+    };
+    readonly provider: 'model';
+    readonly declared: DeclaredSource;
+}
+export type ReconciliationFinding = EvidenceFinding | StaleAttestationFinding | UnconfirmedAttestationFinding;
 export interface AttestationStaleness {
     readonly findings: readonly StaleAttestationFinding[];
     readonly notes: readonly string[];
@@ -73,6 +88,7 @@ export interface ReconciliationReport {
         readonly notObserved: number;
         readonly subjectsWithoutEvidence: number;
         readonly staleAttestations?: number;
+        readonly unconfirmedAttestations?: number;
         readonly expectationsCompared: number;
         readonly expectationsWithoutObservation: number;
     };

package/dist/reconciliation.js

@@ -1,3 +1,4 @@
+import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, } from './compiler.js';
 const assertedRelationshipsByClaim = (graph) => {
     const asserted = new Map();
     if (graph === undefined)
@@ -147,10 +148,48 @@ const unobservedCurrentConcepts = (graph, reports) => {
         .map(({ subject }) => subject)
         .sort((left, right) => left.localeCompare(right));
 };
+// A judgment a machine transcribed is not the act the authority
+// performed. The recorder is in the model, so the difference is
+// derivable here: an authority who wrote the record in their own hand
+// names nobody else, and anything else is a claim awaiting confirmation.
+const unconfirmedAttestations = (graph) => {
+    if (graph === undefined)
+        return [];
+    return graph.claims.flatMap((claim) => {
+        if (!claim.predicate.startsWith(ATTESTATION_PREDICATE_PREFIX))
+            return [];
+        if (!('value' in claim.object))
+            return [];
+        const parts = parseAttestationClaimValue(claim.object.value);
+        const recordedBy = parts?.recordedBy;
+        if (parts === undefined || recordedBy === undefined)
+            return [];
+        // The authority is qualified; a recorder naming the same subject,
+        // long form or short, is that authority signing for themselves.
+        const local = parts.by.slice(parts.by.indexOf('#') + 1);
+        if (recordedBy === parts.by || recordedBy === local)
+            return [];
+        return [
+            {
+                target: { type: 'subject', id: claim.subject },
+                result: 'unconfirmed-attestation',
+                attestation: {
+                    topic: claim.predicate.slice(ATTESTATION_PREDICATE_PREFIX.length),
+                    by: parts.by,
+                    recordedBy,
+                    on: parts.on,
+                },
+                provider: 'model',
+                declared: claim.source,
+            },
+        ];
+    });
+};
 export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
     const assertedByClaim = assertedRelationshipsByClaim(graph);
     const unobservedSubjects = unobservedCurrentConcepts(graph, reports);
     const expectations = compareExpectations(graph, reports);
+    const unconfirmed = unconfirmedAttestations(graph);
     const summary = {
         evidenceDocuments: reports.length,
         observations: 0,
@@ -167,10 +206,18 @@ export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
         ...(staleness === undefined
             ? {}
             : { staleAttestations: staleness.findings.length }),
+        // Recorder disagreement is derived from the model alone, so the
+        // counter appears whenever there was a graph to read.
+        ...(graph === undefined
+            ? {}
+            : { unconfirmedAttestations: unconfirmed.length }),
         expectationsCompared: expectations.compared,
         expectationsWithoutObservation: expectations.unobserved.length,
     };
-    const findings = [...(staleness?.findings ?? [])];
+    const findings = [
+        ...(staleness?.findings ?? []),
+        ...unconfirmed,
+    ];
     for (const report of reports) {
         summary.observations += report.observations.length;
         for (const observation of report.observations) {

package/dist/rtm.d.ts

@@ -32,6 +32,7 @@ export interface RtmRealizer {
 export interface RtmAttestation {
     readonly topic: string;
     readonly by: string;
+    readonly recordedBy?: string;
     readonly on: string;
     readonly source: RtmSource;
 }