yarramate 0.17.0 → 0.18.0

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;
 }

package/dist/rtm.js

@@ -1,3 +1,4 @@
+import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, } from './compiler.js';
 import { coreLocalKind, isDeclaredNonGoal } from './brief.js';
 import { conceptKinds } from './profile.js';
 // The RTM is one derived reading of the graph: the chain
@@ -28,7 +29,7 @@ export function buildRtm(workspace, graph, profileContext, evidenceReports) {
     for (const claim of graph.claims) {
         if (!('value' in claim.object))
             continue;
-        if (claim.predicate.startsWith('yarramate/attestation/')) {
+        if (claim.predicate.startsWith(ATTESTATION_PREDICATE_PREFIX)) {
             attestationClaims.set(claim.subject, [
                 ...(attestationClaims.get(claim.subject) ?? []),
                 claim,
@@ -204,14 +205,13 @@ export function buildRtm(workspace, graph, profileContext, evidenceReports) {
             .flatMap((claim) => {
             if (!('value' in claim.object))
                 return [];
-            const match = /^(.*) ([0-9]{4}-[0-9]{2}-[0-9]{2})$/.exec(claim.object.value);
-            if (match === null)
+            const parts = parseAttestationClaimValue(claim.object.value);
+            if (parts === undefined)
                 return [];
             return [
                 {
-                    topic: claim.predicate.slice('yarramate/attestation/'.length),
-                    by: match[1],
-                    on: match[2],
+                    topic: claim.predicate.slice(ATTESTATION_PREDICATE_PREFIX.length),
+                    ...parts,
                     source: citation(claim),
                 },
             ];
@@ -330,7 +330,9 @@ export function renderRtmMarkdown(rtm) {
         const attestations = row.attestations.length === 0
             ? 'none'
             : row.attestations
-                .map((attestation) => escapeCell(`${attestation.topic}: ${attestation.by} on ${attestation.on}`) + ` (${cite(attestation.source)})`)
+                .map((attestation) => escapeCell(`${attestation.topic}: ${attestation.by} on ${attestation.on}${attestation.recordedBy === undefined
+                ? ''
+                : `, recorded by ${attestation.recordedBy}`}`) + ` (${cite(attestation.source)})`)
                 .join('<br>');
         lines.push(`| ${requirement} | ${row.status ?? 'undeclared'} | ${lineage} | ${realizers} | ${evidence} | ${attestations} | ${cite(row.source)} |`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

package/schema/yarramate-ask-result.schema.json

@@ -932,6 +932,10 @@
         "subjectsWithoutEvidence": {
           "type": "integer"
         },
+        "unconfirmedAttestations": {
+          "type": "integer",
+          "minimum": 0
+        },
         "expectationsCompared": {
           "type": "integer"
         },

package/schema/yarramate-document.schema.json

@@ -314,6 +314,11 @@
           "pattern": "^[a-z][a-z0-9-]*$"
         },
         "by": {
+          "description": "The authority whose judgment this records, as a subject reference. A sign-off names someone the model already knows, on the same rule as ownership: an authority absent from the model cannot be held to the judgment.",
+          "$ref": "#/$defs/reference"
+        },
+        "recordedBy": {
+          "description": "Who wrote this record, when that is not the attesting authority's own hand. An agent recording a judgment on someone's behalf names itself here, so a sign-off and a transcription of one are never the same bytes.",
           "$ref": "#/$defs/nonEmptyText"
         },
         "on": {

package/schema/yarramate-operations.schema.json

@@ -86,7 +86,8 @@
       "required": [
         "topic",
         "by",
-        "on"
+        "on",
+        "recordedBy"
       ],
       "properties": {
         "topic": {
@@ -94,6 +95,11 @@
           "pattern": "^[a-z][a-z0-9-]*$"
         },
         "by": {
+          "description": "The authority whose judgment this records, resolved against the model as a subject reference once the write lands.",
+          "$ref": "#/$defs/nonEmptyText"
+        },
+        "recordedBy": {
+          "description": "Who is writing this record. Required here and optional in a document: a hand-written sign-off already has a committer, whereas a batch names the agent holding the pen, so an authority's judgment and a machine's transcription of one are never the same bytes.",
           "$ref": "#/$defs/nonEmptyText"
         },
         "on": {

package/schema/yarramate-reconciliation-report.schema.json

@@ -31,6 +31,7 @@
         "notObserved": { "type": "integer", "minimum": 0 },
         "subjectsWithoutEvidence": { "type": "integer", "minimum": 0 },
         "staleAttestations": { "type": "integer", "minimum": 0 },
+        "unconfirmedAttestations": { "type": "integer", "minimum": 0 },
         "expectationsCompared": { "type": "integer", "minimum": 0 },
         "expectationsWithoutObservation": { "type": "integer", "minimum": 0 }
       }
@@ -142,9 +143,43 @@
     "finding": {
       "oneOf": [
         { "$ref": "#/$defs/evidenceFinding" },
-        { "$ref": "#/$defs/staleAttestationFinding" }
+        { "$ref": "#/$defs/staleAttestationFinding" },
+        { "$ref": "#/$defs/unconfirmedAttestationFinding" }
       ]
     },
+    "unconfirmedAttestationFinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target", "result", "attestation", "provider", "declared"],
+      "properties": {
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "id"],
+          "properties": {
+            "type": { "const": "subject" },
+            "id": { "$ref": "#/$defs/subjectIdentity" }
+          }
+        },
+        "result": { "const": "unconfirmed-attestation" },
+        "attestation": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["topic", "by", "recordedBy", "on"],
+          "properties": {
+            "topic": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "by": { "type": "string", "minLength": 1 },
+            "recordedBy": { "type": "string", "minLength": 1 },
+            "on": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+            }
+          }
+        },
+        "provider": { "const": "model" },
+        "declared": { "$ref": "#/$defs/declaredSource" }
+      }
+    },
     "evidenceFinding": {
       "type": "object",
       "additionalProperties": false,

package/skills/yarramate-architecture/references/native-authoring.md

@@ -208,8 +208,9 @@ identified references, not a policy engine or free-form metadata bag.
   name: Shared architecture context
   attestations:
     - topic: adequacy
-      by: reviewer-name
+      by: review-board
       on: "2026-08-01"
+      recordedBy: claude-fable-5
 ```
 
 An attestation records that an authority accepted the subject as adequate
@@ -219,12 +220,23 @@ outside the engine — only the claim's existence is checked. Revoke by
 deleting the entry; both signing and revoking are reviewed at the Git
 boundary (ADR 0056).
 
+`by` is a subject reference, resolved like `owner`: it names a concept the
+model already holds, and an unresolved one is `YM304`, a hard error. A name
+nobody modelled is not an authority. When you write the entry on someone
+else's judgment, name yourself in `recordedBy` rather than putting your own
+handle in `by` — `apply` requires `recordedBy` on every attestation an
+operations batch writes, because a batch is a machine transcribing a
+judgment it did not make (ADR 0082). `reconcile` then reports an
+`unconfirmed-attestation` finding for each record whose recorder is not its
+authority: the sign-off stands, and the report says out loud that a machine
+wrote it down.
+
 A sign-off covers the wording it read. If the subject's `name` or
 `description` changes in a commit after the attestation's `on` date,
 `yarramate reconcile` reports a `stale-attestation` finding naming the
 attestation and the commit that reworded the subject (ADR 0074). Renew
-the sign-off by updating `on` after the rewording. This is a report, not
-a gate: `check --strict` is unaffected.
+the sign-off by updating `on` after the rewording. Neither finding is a
+gate: `check --strict` is unaffected.
 
 ## Rationale and citations