yarramate 1.7.0 → 1.9.0

package/dist/adapters/visual/session-server.js

@@ -620,6 +620,9 @@ export const startVisualServer = async (options) => {
             compiledWorkspace = {
                 graph: compiled.graph,
                 profileContext: compiled.profileContext,
+                // Threaded whole (ADR 0131): a narrow copy here is how a slot
+                // question would silently never fire in the embedded pane.
+                patternMemberships: compiled.patternMemberships,
             };
             const workspaceModel = renderedWorkspaceOf(compiledWorkspace, views, {
                 authority: rendered.authority,

package/dist/adapters/visual/workspace-model.d.ts

@@ -4,6 +4,7 @@ import type { ResolvedWorkspace } from "../../workspace.js";
 import type { VisualDiagnostic, VisualViewOperation } from "./protocol-contract.js";
 import type { ProjectionDefinition, ProjectionExclusion, ProjectionQuery } from "../../projection.js";
 import type { ResolvedProfileContext, SemanticGraph } from "../../compiler.js";
+import { type CataloguePatternMembership } from "../../interrogate-command.js";
 import type { VisualKindOption, VisualViewSummary } from "./protocol-contract.js";
 import type { VisualInterrogationOverlay, VisualRenderedModel } from "./wire.js";
 /**
@@ -57,6 +58,8 @@ export interface DismissedQuestion {
 export declare const interrogationOverlayOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
+    /** From the compilation (ADR 0131); absent, slot questions stay quiet. */
+    readonly patternMemberships?: readonly CataloguePatternMembership[];
 }, 
 /**
  * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
@@ -90,6 +93,7 @@ dismissed?: readonly DismissedQuestion[]) => VisualInterrogationOverlay | undefi
 export declare const renderedWorkspaceOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
+    readonly patternMemberships?: readonly CataloguePatternMembership[];
 }, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary" | "interrogation">, catalogue?: {
     readonly path: string;
     readonly source: string;

package/dist/adapters/visual/workspace-model.js

@@ -64,7 +64,7 @@ dismissed = []) => {
     const composed = composeCatalogues(Array.isArray(catalogue) ? catalogue : [catalogue]);
     if (!composed.ok)
         return undefined;
-    const report = evaluateCatalogue(composed.composed.catalogue, compiled.graph, compiled.profileContext, undefined, composed.composed.catalogues);
+    const report = evaluateCatalogue(composed.composed.catalogue, compiled.graph, compiled.profileContext, undefined, composed.composed.catalogues, compiled.patternMemberships);
     const dismissedEverywhere = new Set(dismissed
         .filter(({ subject }) => subject === undefined)
         .map(({ questionId }) => questionId));

package/dist/artifact-coverage.d.ts

@@ -0,0 +1,13 @@
+export interface CoverageScopePattern {
+    readonly pattern: string;
+    /** Repository-relative files the pattern selected, sorted. */
+    readonly artifacts: readonly string[];
+}
+export type ArtifactCoverage = {
+    readonly assessed: false;
+    readonly reason: string;
+} | {
+    readonly assessed: true;
+    readonly scope: readonly CoverageScopePattern[];
+};
+export declare function deriveArtifactCoverage(manifestDirectory: string, patterns: readonly string[] | undefined): ArtifactCoverage;

package/dist/artifact-coverage.js

@@ -0,0 +1,58 @@
+import { spawnSync } from 'node:child_process';
+import { globSync } from 'node:fs';
+import { sep } from 'node:path';
+const runGit = (cwd, args) => spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+export function deriveArtifactCoverage(manifestDirectory, patterns) {
+    if (patterns === undefined) {
+        return {
+            assessed: false,
+            reason: 'the workspace manifest declares no coverage scope',
+        };
+    }
+    // The root is the git toplevel of the manifest's directory, never the
+    // process cwd: the same command must report the same coverage wherever it
+    // was invoked (the #216 bug shape), and the repository boundary is git's
+    // to draw, not a directory-layout guess.
+    const toplevel = runGit(manifestDirectory, [
+        'rev-parse',
+        '--show-toplevel',
+    ]);
+    if (toplevel.status !== 0) {
+        return {
+            assessed: false,
+            reason: 'the workspace does not live in a git repository',
+        };
+    }
+    const root = toplevel.stdout.trim();
+    // An artifact is any file git can see: tracked, or untracked and not
+    // ignored. Tracked-only would blind the report to exactly the newest
+    // files — the recurrence this feature exists to catch (ADR 0130).
+    const listed = runGit(root, [
+        'ls-files',
+        '-z',
+        '--cached',
+        '--others',
+        '--exclude-standard',
+    ]);
+    if (listed.status !== 0) {
+        return {
+            assessed: false,
+            reason: `git ls-files failed: ${(listed.stderr ?? '').trim()}`,
+        };
+    }
+    const visible = new Set((listed.stdout ?? '').split('\0').filter((path) => path.length > 0));
+    // Glob matches are intersected with git's view, so a symlink escaping the
+    // repository or a build tree git ignores cannot enter the artifact set
+    // however broad the glob. The intersection also drops directories: git
+    // lists files only.
+    return {
+        assessed: true,
+        scope: patterns.map((pattern) => ({
+            pattern,
+            artifacts: globSync(pattern, { cwd: root })
+                .map((path) => path.split(sep).join('/'))
+                .filter((path) => visible.has(path))
+                .sort((left, right) => left.localeCompare(right)),
+        })),
+    };
+}

package/dist/ask-command.js

@@ -475,7 +475,7 @@ export function runAskCommand(options, cwd) {
             }, workspace, cwd), compilation.profileContext);
             if (!composed.ok)
                 return failed(composed.diagnostics);
-            const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues);
+            const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues, compilation.patternMemberships);
             const result = {
                 format: 'yarramate/ask-result/v1',
                 workspace: workspace.id,
@@ -719,7 +719,7 @@ export function runAskCommand(options, cwd) {
                 evidenceObservations.push(...loaded.evidence.observations);
             }
             const report = {
-                ...evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues),
+                ...evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues, compilation.patternMemberships),
                 workspace: workspace.id,
             };
             // Field by field, to fix key ORDER in the emitted JSON. Every optional
@@ -1021,7 +1021,7 @@ export function runAskCommand(options, cwd) {
                 return failed(loaded.diagnostics);
             evidenceDocuments.push(loaded.evidence);
         }
-        const report = evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues);
+        const report = evaluateCatalogue(composed.composed.catalogue, graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations), composed.composed.catalogues, compilation.patternMemberships);
         const openQuestions = [];
         for (const wave of report.waves) {
             for (const question of wave.questions) {

package/dist/cli.js

@@ -10,6 +10,7 @@ import { runExportCommand } from './export-command.js';
 import { runApplyCommand } from './apply-cli.js';
 import { runDesignCommand } from './design-command.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
+import { deriveArtifactCoverage } from './artifact-coverage.js';
 import { deriveAttestationStaleness } from './attestation-staleness.js';
 import { reconcileEvidenceReports } from './reconciliation.js';
 import { loadWorkspaceManifest } from './workspace.js';
@@ -84,9 +85,13 @@ const runReconciliation = (options, cwd) => {
             source: readFileSync(resolve(cwd, path), 'utf8'),
             documentId: documentIdByPath.get(path) ?? path,
         })));
+        // Coverage anchors on the manifest's own directory, not the process
+        // cwd, so the same command reports the same coverage wherever it was
+        // invoked (ADR 0130).
+        const coverage = deriveArtifactCoverage(dirname(resolve(cwd, workspacePath)), loadedWorkspace.manifest.coverage);
         return {
             exitCode: 0,
-            stdout: `${JSON.stringify(reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports, compilation.graph, staleness), null, 2)}\n`,
+            stdout: `${JSON.stringify(reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports, compilation.graph, staleness, coverage), null, 2)}\n`,
             stderr: '',
         };
     }

package/dist/compiler.d.ts

@@ -94,9 +94,31 @@ export interface ResolvedProfileContext {
      */
     readonly permittedRelationshipKinds: (fromKindIdentity: string, toKindIdentity: string) => ReadonlySet<RelationshipKind> | undefined;
 }
+/**
+ * One slot of one pattern instance, and the subject bound into it
+ * (ADR 0131). Compile CONTEXT, not graph content: `parts` binds existing
+ * subjects (#268), the binding is consumed during expansion, and the graph
+ * stays indistinguishable from a hand-authored one — so the compile result
+ * is the only place this fact survives. `pattern` is the kind identity
+ * (`yarrasys/api-led@1.0#api`), the naming ADR 0129 chose: identity that
+ * travels, never a document path.
+ */
+export interface PatternMembership {
+    readonly member: string;
+    readonly slot: string;
+    readonly instance: string;
+    readonly pattern: string;
+}
 export type CompilationResult = {
     readonly ok: true;
     readonly graph: SemanticGraph;
+    /**
+     * Optional in the type although the compiler always emits it: this
+     * shape is published, and a required addition is free for readers
+     * and a break for constructors. Read it as `?? []` — and thread it
+     * to `evaluateCatalogue`, or `fills-pattern-slot` never fires.
+     */
+    readonly patternMemberships?: readonly PatternMembership[];
 } | {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
@@ -105,6 +127,7 @@ export type ContextualCompilationResult = {
     readonly ok: true;
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
+    readonly patternMemberships?: readonly PatternMembership[];
 } | {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];

package/dist/compiler.js

@@ -2332,8 +2332,24 @@ function compileWorkspaceResolved(parsed) {
     if (diagnostics.length > 0) {
         return diagnosticFailure(diagnostics);
     }
+    // Membership survives the compile as context (ADR 0131): one entry per
+    // bound slot, sorted so the emission is deterministic. Always emitted,
+    // possibly empty — an empty array is a workspace with no bindings, while
+    // an evaluation missing the array is a caller that never looked.
+    const patternMemberships = patternInstances
+        .flatMap(({ instance, pattern, bindings }) => [...bindings].map(([slot, member]) => ({
+        member,
+        slot,
+        instance,
+        pattern: pattern.kindIdentity,
+    })))
+        .sort((left, right) => left.member.localeCompare(right.member) ||
+        left.pattern.localeCompare(right.pattern) ||
+        left.instance.localeCompare(right.instance) ||
+        left.slot.localeCompare(right.slot));
     return {
         ok: true,
+        patternMemberships,
         profileContext: {
             conceptKindLineages: immutableMap([...conceptKindByIdentity]
                 .sort(([left], [right]) => left.localeCompare(right))
@@ -2418,7 +2434,13 @@ function compileWorkspaceResolved(parsed) {
 }
 export function compileWorkspace(sources) {
     const result = compileWorkspaceResolved(parseSources(sources).parsed);
-    return result.ok ? { ok: true, graph: result.graph } : result;
+    return result.ok
+        ? {
+            ok: true,
+            graph: result.graph,
+            patternMemberships: result.patternMemberships,
+        }
+        : result;
 }
 export const compileWorkspaceWithProfileContext = (sources) => compileWorkspaceResolved(parseSources(sources).parsed);
 /**

package/dist/design-command.js

@@ -246,7 +246,7 @@ export function runDesignCommand(options, cwd) {
                 };
             }
         }
-        const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues);
+        const report = evaluateCatalogue(composed.composed.catalogue, compilation.graph, compilation.profileContext, evidenceObservations, composed.composed.catalogues, compilation.patternMemberships);
         // Keyed by the QUALIFIED id, matching what the report now carries.
         const askPlainById = new Map(composed.composed.catalogue.questions.flatMap((question) => question.askPlain === undefined
             ? []

package/dist/index.d.ts

@@ -8,8 +8,9 @@ export { loadWorkspaceManifest, type ResolvedWorkspace, type WorkspaceManifest,
 export { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, type EvidenceDocument, type EvidenceEvaluationResult, type EvidenceLoadResult, type EvidenceLocator, type EvidenceObservation, type EvidenceObservedValue, type EvidenceReport, type EvidenceResult, type EvidenceWorkspaceEvaluationResult, } from './evidence.js';
 export { constraintExpectsPredicate, reconcileEvidenceReports, type AssertedRelationship, type AttestationStaleness, type DeclaredSource, type EvidenceFinding, type ExpectationComparison, type ReconciliationFinding, type ReconciliationReport, type StaleAttestationFinding, type UnobservedExpectation, } from './reconciliation.js';
 export { deriveAttestationStaleness } from './attestation-staleness.js';
+export { deriveArtifactCoverage, type ArtifactCoverage, type CoverageScopePattern, } from './artifact-coverage.js';
 export { buildRtm, renderRtmMarkdown, type RequirementsTraceabilityMatrix, type RtmAttestation, type RtmContextEntry, type RtmDescopedEntry, type RtmEvidenceVerdict, type RtmLineageEntry, type RtmRealizer, type RtmRow, type RtmSource, } from './rtm.js';
-export type { CompilationCache, CompilationResult, ContextualCompilationResult, IncrementalCompilationResult, ParsedWorkspaceSource, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
+export type { CompilationCache, CompilationResult, ContextualCompilationResult, IncrementalCompilationResult, ParsedWorkspaceSource, PatternMembership, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
 export { canonicalProjection, evaluateProjection, explainProjection, loadProjection, renderProjectionMarkdown, type ConceptFacet, type ProjectionExclusion, } from './projection.js';
 export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, type AdapterMapping, type AdapterMappingLoadResult, type AdapterMappingValidationResult, type AdapterMappingsValidationResult, type AdapterSubjectMapping, } from './adapter-mapping.js';
 export type { LifecycleStatus, ProjectionDefinition, ProjectionLoadResult, ProjectionResult, } from './projection.js';
@@ -18,4 +19,4 @@ export { applyOperations, landOperations, posixDirectoryOf, type ApplyInput, typ
 export { connectableKinds, draftRelationship, proposeRelationshipId, stagedSubjectIds, } from './relationship-drafting.js';
 export { draftConcept, proposeConceptId } from './concept-drafting.js';
 export { deletionBlockers, describeDeletion, draftDeletion, type DeletionBlocker, } from './deletion-drafting.js';
-export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, type CatalogueEvidenceObservation, type CataloguePatternMembership, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export { loadWorkspaceManifest, } from './workspace.js';
 export { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 export { constraintExpectsPredicate, reconcileEvidenceReports, } from './reconciliation.js';
 export { deriveAttestationStaleness } from './attestation-staleness.js';
+export { deriveArtifactCoverage, } from './artifact-coverage.js';
 export { buildRtm, renderRtmMarkdown, } from './rtm.js';
 export { canonicalProjection, evaluateProjection, explainProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
 export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, } from './adapter-mapping.js';

package/dist/interrogate-command.d.ts

@@ -89,6 +89,18 @@ export type CatalogueCondition = {
     readonly condition: 'unchallenged-evidence';
 } | {
     readonly condition: 'has-any-subject';
+} | {
+    /**
+     * The subject fills a slot of a pattern instance (ADR 0131). A GUARD,
+     * per the #334 split: it says a question applies here, and an
+     * ordinary condition beside it says what would answer it. Bare, it
+     * means bound into any slot of any instance; `patternKinds` narrows
+     * by the pattern's kind identity (never a document path, ADR 0129)
+     * and `slots` by part name.
+     */
+    readonly condition: 'fills-pattern-slot';
+    readonly patternKinds?: readonly string[];
+    readonly slots?: readonly string[];
 };
 /**
  * One observation from the workspace's evidence overlay, reduced to what
@@ -107,6 +119,21 @@ export interface CatalogueEvidenceObservation {
     readonly result: 'confirmed' | 'contradicted' | 'unknown' | 'not-observed';
     readonly searched?: readonly unknown[];
 }
+/**
+ * One slot of one pattern instance and the subject bound into it, as
+ * interrogation reads it. Shaped structurally rather than importing the
+ * compiler's {@link PatternMembership} for the same reason
+ * {@link CatalogueEvidenceObservation} is: the pure engine entry keeps
+ * owning its whole input surface, and a host passes
+ * `compilation.patternMemberships` without the compiler's types. Only
+ * `fills-pattern-slot` reads it (ADR 0131).
+ */
+export interface CataloguePatternMembership {
+    readonly member: string;
+    readonly slot: string;
+    readonly instance: string;
+    readonly pattern: string;
+}
 export interface CatalogueQuestion {
     readonly id: string;
     readonly wave: string;
@@ -210,7 +237,15 @@ export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: S
  * the report. A fifth optional parameter rather than an options object,
  * because this signature is published and a consumer already calls it.
  */
-catalogues?: readonly string[]): Omit<InterrogationReport, 'workspace'>;
+catalogues?: readonly string[], 
+/**
+ * Pattern memberships from the compilation (ADR 0131) — pass
+ * `compilation.patternMemberships`, or `fills-pattern-slot` conditions
+ * never fire. A sixth optional parameter for the same reason
+ * `catalogues` is a fifth: this signature is published and a consumer
+ * already calls it.
+ */
+patternMemberships?: readonly CataloguePatternMembership[]): Omit<InterrogationReport, 'workspace'>;
 export type CatalogueLoadResult = {
     readonly ok: true;
     readonly catalogue: QuestionCatalogue;

package/dist/interrogate-command.js

@@ -236,8 +236,20 @@ const linkageHits = (index, condition, subjectId, profileContext) => {
         return counterparts.some((counterpart) => kindMatches(index.kindOf.get(counterpart), condition.counterpartKinds, matching, profileContext));
     });
 };
-const conditionHolds = (index, condition, subjectId, profileContext, evidence) => {
+const conditionHolds = (index, condition, subjectId, profileContext, evidence, memberships) => {
     switch (condition.condition) {
+        case 'fills-pattern-slot':
+            // Absent memberships stay quiet: the caller did not derive them, so
+            // participation is unknown, not absent — the same rule
+            // `unchallenged-evidence` applies to a missing overlay and
+            // `unconstrained-kind` to a missing profile context (ADR 0131).
+            return (memberships !== undefined &&
+                subjectId !== undefined &&
+                memberships.some((membership) => membership.member === subjectId &&
+                    (condition.patternKinds === undefined ||
+                        condition.patternKinds.includes(membership.pattern)) &&
+                    (condition.slots === undefined ||
+                        condition.slots.includes(membership.slot))));
         case 'has-any-subject':
             // The guard a late wave needs to say "only once the model has
             // substance" (#334). An empty model is not an architecture at rest -
@@ -459,13 +471,21 @@ export function evaluateCatalogue(catalogue, graph, profileContext, evidence,
  * the report. A fifth optional parameter rather than an options object,
  * because this signature is published and a consumer already calls it.
  */
-catalogues) {
+catalogues, 
+/**
+ * Pattern memberships from the compilation (ADR 0131) — pass
+ * `compilation.patternMemberships`, or `fills-pattern-slot` conditions
+ * never fire. A sixth optional parameter for the same reason
+ * `catalogues` is a fifth: this signature is published and a consumer
+ * already calls it.
+ */
+patternMemberships) {
     const index = indexGraph(graph);
     let open = 0;
     let openQuestions = 0;
     const applicableQuestions = catalogue.questions.filter((question) => questionIsApplicable(question, graph.profiles));
     const waveOpens = (wave) => wave.opensWhen === undefined ||
-        wave.opensWhen.every((condition) => conditionHolds(index, condition, undefined, profileContext, evidence));
+        wave.opensWhen.every((condition) => conditionHolds(index, condition, undefined, profileContext, evidence, patternMemberships));
     const waves = catalogue.waves.map((wave) => ({
         id: wave.id,
         name: wave.name,
@@ -490,14 +510,14 @@ catalogues) {
                     ...(question.since === undefined ? {} : { since: question.since }),
                 };
                 if (question.scope === 'workspace') {
-                    const isOpen = question.trigger.every((condition) => conditionHolds(index, condition, undefined, profileContext, evidence));
+                    const isOpen = question.trigger.every((condition) => conditionHolds(index, condition, undefined, profileContext, evidence, patternMemberships));
                     if (isOpen) {
                         open += 1;
                         openQuestions += 1;
                     }
                     return { ...base, open: isOpen };
                 }
-                const matches = selectSubjects(index, question.subjects, profileContext).filter((id) => question.trigger.every((condition) => conditionHolds(index, condition, id, profileContext, evidence)));
+                const matches = selectSubjects(index, question.subjects, profileContext).filter((id) => question.trigger.every((condition) => conditionHolds(index, condition, id, profileContext, evidence, patternMemberships)));
                 if (matches.length === 0) {
                     return { ...base, open: false };
                 }
@@ -556,7 +576,7 @@ const kindReferencesOf = (catalogue) => {
     const fromCondition = (condition, path) => {
         if (typeof condition !== 'object' || condition === null)
             return;
-        for (const field of ['kinds', 'counterpartKinds']) {
+        for (const field of ['kinds', 'counterpartKinds', 'patternKinds']) {
             const value = condition[field];
             if (!Array.isArray(value))
                 continue;

package/dist/interrogation-entry.d.ts

@@ -1 +1 @@
-export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCompositionResult, type ComposedCatalogue, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCompositionResult, type ComposedCatalogue, type CatalogueCondition, type CatalogueEvidenceObservation, type CataloguePatternMembership, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';

package/dist/reconciliation.d.ts

@@ -1,5 +1,6 @@
 import type { SemanticGraph } from './compiler.js';
 import type { EvidenceLocator, EvidenceReport, EvidenceResult } from './evidence.js';
+import type { ArtifactCoverage } from './artifact-coverage.js';
 export interface AssertedRelationship {
     readonly from: string;
     readonly to: string;
@@ -98,11 +99,30 @@ export interface ReconciliationReport {
         readonly unconfirmedAttestations?: number;
         readonly expectationsCompared: number;
         readonly expectationsWithoutObservation: number;
+        /**
+         * Files the declared coverage scope selected, and the ones no
+         * observation's `repo:` locator claims (ADR 0130). Both appear exactly
+         * when coverage was assessed, so a report without them is one that
+         * never looked, not one that found nothing.
+         */
+        readonly artifactsInScope?: number;
+        readonly unclaimedArtifacts?: number;
     };
     readonly findings: readonly ReconciliationFinding[];
     readonly unobservedSubjects?: readonly string[];
     readonly unobservedExpectations?: readonly UnobservedExpectation[];
+    /**
+     * The coverage patterns as the manifest declared them, echoed so the
+     * report is honest about what it was asked to look at (ADR 0130).
+     */
+    readonly coverageScope?: readonly string[];
+    /**
+     * In-scope artifacts no observation claims, sorted. Absence, never
+     * accusation: no finding is fabricated and `check --strict` never reads
+     * this (ADR 0130), the line ADR 0049 drew for unobserved subjects.
+     */
+    readonly unclaimedArtifacts?: readonly string[];
     readonly notes?: readonly string[];
 }
 export declare const constraintExpectsPredicate = "yarramate/constraint/expects";
-export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[], graph?: SemanticGraph, staleness?: AttestationStaleness): ReconciliationReport;
+export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[], graph?: SemanticGraph, staleness?: AttestationStaleness, coverage?: ArtifactCoverage): ReconciliationReport;

package/dist/reconciliation.js

@@ -149,6 +149,76 @@ const unobservedCurrentConcepts = (graph, reports) => {
         .map(({ subject }) => subject)
         .sort((left, right) => left.localeCompare(right));
 };
+// An observation claims an artifact when its locator is `repo:<path>`,
+// read syntactically: any `#fragment` stripped, a directory claiming
+// everything beneath it, any other scheme claiming nothing. Resolution
+// and external validity stay with the provider (ADR 0130) — nothing here
+// opens a file or checks one exists.
+const claimedArtifactPaths = (reports) => {
+    const claimed = new Set();
+    for (const report of reports) {
+        for (const observation of report.observations) {
+            const uri = observation.evidence.uri;
+            if (!uri.startsWith('repo:'))
+                continue;
+            const located = uri.slice('repo:'.length);
+            const fragment = located.indexOf('#');
+            // Trailing slashes are stripped with a loop, not a regex: an
+            // anchored /\/+$/ is polynomial on a locator of many slashes, and
+            // locators are library input.
+            let path = fragment === -1 ? located : located.slice(0, fragment);
+            while (path.endsWith('/'))
+                path = path.slice(0, -1);
+            if (path.length > 0)
+                claimed.add(path);
+        }
+    }
+    return claimed;
+};
+const isClaimed = (claimed, artifact) => {
+    if (claimed.has(artifact))
+        return true;
+    for (const path of claimed) {
+        if (artifact.startsWith(`${path}/`))
+            return true;
+    }
+    return false;
+};
+const assessArtifactCoverage = (coverage, reports) => {
+    // An absent argument is a caller that never looked (the strict gate);
+    // an unassessed derivation is a reconcile that looked and could not,
+    // and says why (ADR 0130, the ADR 0074 parallel).
+    if (coverage === undefined)
+        return { notes: [] };
+    if (!coverage.assessed) {
+        return {
+            notes: [`Artifact coverage was not assessed: ${coverage.reason}.`],
+        };
+    }
+    const notes = [];
+    if (coverage.scope.length === 0) {
+        notes.push('The workspace manifest declares an empty coverage scope, so no artifacts were assessed.');
+    }
+    // A dead glob is indistinguishable from a typo, and silently
+    // contributing nothing is how a mistyped pattern would report full
+    // coverage. A note, not a refusal: a coverage scope is a lens, not
+    // load-bearing input (ADR 0130).
+    for (const { pattern, artifacts } of coverage.scope) {
+        if (artifacts.length === 0) {
+            notes.push(`Coverage pattern "${pattern}" matched no artifacts.`);
+        }
+    }
+    const artifacts = [
+        ...new Set(coverage.scope.flatMap(({ artifacts }) => artifacts)),
+    ].sort((left, right) => left.localeCompare(right));
+    const claimed = claimedArtifactPaths(reports);
+    return {
+        scope: coverage.scope.map(({ pattern }) => pattern),
+        artifacts: artifacts.length,
+        unclaimed: artifacts.filter((artifact) => !isClaimed(claimed, artifact)),
+        notes,
+    };
+};
 // 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
@@ -186,11 +256,12 @@ const unconfirmedAttestations = (graph) => {
         ];
     });
 };
-export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
+export function reconcileEvidenceReports(workspace, reports, graph, staleness, coverage) {
     const assertedByClaim = assertedRelationshipsByClaim(graph);
     const unobservedSubjects = unobservedCurrentConcepts(graph, reports);
     const expectations = compareExpectations(graph, reports);
     const unconfirmed = unconfirmedAttestations(graph);
+    const assessedCoverage = assessArtifactCoverage(coverage, reports);
     const summary = {
         evidenceDocuments: reports.length,
         observations: 0,
@@ -215,6 +286,15 @@ export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
             : { unconfirmedAttestations: unconfirmed.length }),
         expectationsCompared: expectations.compared,
         expectationsWithoutObservation: expectations.unobserved.length,
+        // Coverage counters appear exactly when the scope was assessed
+        // (ADR 0130): a report without them never looked; a report carrying
+        // zero looked and found everything claimed.
+        ...(assessedCoverage.artifacts === undefined
+            ? {}
+            : {
+                artifactsInScope: assessedCoverage.artifacts,
+                unclaimedArtifacts: assessedCoverage.unclaimed?.length ?? 0,
+            }),
     };
     const findings = [
         ...(staleness?.findings ?? []),
@@ -274,7 +354,11 @@ export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
         (expectationOf(left)?.key ?? '').localeCompare(expectationOf(right)?.key ?? '') ||
         (expectationOf(left)?.observed ?? '').localeCompare(expectationOf(right)?.observed ?? ''));
     summary.findings = findings.length;
-    const notes = [...(staleness?.notes ?? []), ...absenceNotes];
+    const notes = [
+        ...(staleness?.notes ?? []),
+        ...absenceNotes,
+        ...assessedCoverage.notes,
+    ];
     return {
         format: 'yarramate/reconciliation-report/v1',
         workspace,
@@ -284,6 +368,13 @@ export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
         ...(expectations.unobserved.length === 0
             ? {}
             : { unobservedExpectations: expectations.unobserved }),
+        ...(assessedCoverage.scope === undefined
+            ? {}
+            : { coverageScope: assessedCoverage.scope }),
+        ...(assessedCoverage.unclaimed === undefined ||
+            assessedCoverage.unclaimed.length === 0
+            ? {}
+            : { unclaimedArtifacts: assessedCoverage.unclaimed }),
         ...(notes.length === 0 ? {} : { notes }),
     };
 }