yarramate 1.0.0 → 1.2.0

package/catalogues/core-enrichment.yaml

@@ -1,6 +1,6 @@
 format: yarramate/question-catalogue/v1
 id: core-enrichment
-version: "1.0"
+version: "1.1"
 profile: yarramate/core@0.1
 presentation:
   title: Core enrichment interview
@@ -1549,3 +1549,34 @@ questions:
       falsifiable. If nothing in scope is assigned to it, reclassify it
       to a kind that does carry a claim, or retire it with a description
       saying why it sits outside this architecture.
+
+  - id: succession-unscoped
+    wave: hygiene
+    since: "1.1"
+    scope: subject
+    subjects: {}
+    trigger:
+      - condition: unscoped-succession
+    question: >-
+      {subject.name} supersedes a predecessor that is still current. In what
+      respect does it supersede it, and what remains of the predecessor?
+    askPlain: >-
+      {subject.name} takes over from something that is still here. What part
+      does it take over, and what is the old one still needed for?
+    materiality: >-
+      A succession that replaced its predecessor outright says so by the
+      predecessor being gone. One where both are still current is usually
+      partial, and the part it does not cover is exactly what a reader
+      planning against the model needs to know. An unqualified claim reads
+      as a total replacement to every surface that consumes the field, and
+      `ask --compare` reads the field rather than the prose beside it, so a
+      partial succession recorded without its scope turns into a declared
+      removal of something nobody is removing.
+    authority: either
+    resolution: >-
+      Record the respect on the succession entry:
+      `supersedes: [{ subject: <predecessor>, inRespectOf: <the part taken
+      over> }]`. If the succession really is total, retire the predecessor,
+      which says the same thing without a qualifier. If the two subjects
+      simply coexist and neither takes over from the other, the succession
+      is the wrong claim; remove it.

package/dist/ask-command.js

@@ -697,6 +697,7 @@ export function runAskCommand(options, cwd) {
                 format: report.format,
                 workspace: report.workspace,
                 catalogue: report.catalogue,
+                semantics: report.semantics,
                 summary: report.summary,
                 waves: report.waves,
             };

package/dist/compiler.d.ts

@@ -135,6 +135,23 @@ export type IncrementalCompilationResult = ({
     readonly incremental: boolean;
     readonly cache: CompilationCache;
 };
+/**
+ * A succession entry: a bare predecessor id, or one with the respect in which
+ * it was superseded.
+ *
+ * The scope is load-bearing rather than decorative. A model claimed that Zoekt
+ * superseded the Elasticsearch indexer, unqualified, while the source it was
+ * built from says Zoekt "handles only code search and does not replace
+ * Elasticsearch". The prose carried the qualifier and the field could not, and
+ * `ask --compare` reads the field, so the declared target architecture became
+ * the deletion of a component that is not being deleted (ADR 0109).
+ */
+export type NativeSuccession = string | {
+    readonly subject: string;
+    readonly inRespectOf: string;
+};
+export declare const successionSubject: (entry: NativeSuccession) => string;
+export declare const successionScope: (entry: NativeSuccession) => string | undefined;
 export { ATTESTATION_PREDICATE_PREFIX, attestationClaimValue, parseAttestationClaimValue, parseConstraintExpectsValue, type AttestationClaimParts, type ConstraintExpectsParts, } from './graph-claims.js';
 interface ResolvedPosition {
     readonly line: number;

package/dist/compiler.js

@@ -48,6 +48,8 @@ const presenceClaimId = (subject, state) => `${subject}~present-in-${utf8Hex(sta
 // position, so reordering the YAML leaves the graph byte-identical.
 const aliasClaimId = (subject, alias) => `${subject}~alias-${utf8Hex(alias)}`;
 const distinctFromClaimId = (subject, other) => `${subject}~distinct-from-${utf8Hex(other)}`;
+export const successionSubject = (entry) => typeof entry === 'string' ? entry : entry.subject;
+export const successionScope = (entry) => typeof entry === 'string' ? undefined : entry.inRespectOf;
 const supersedesClaimId = (subject, predecessor) => `${subject}~supersedes-${utf8Hex(predecessor)}`;
 export { ATTESTATION_PREDICATE_PREFIX, attestationClaimValue, parseAttestationClaimValue, parseConstraintExpectsValue, } from './graph-claims.js';
 const localKindId = (identity) => identity.slice(identity.indexOf('#') + 1);
@@ -605,6 +607,7 @@ function compileWorkspaceResolved(parsed) {
         }
         seenDocumentIds.add(value.id);
     }
+    const forbidRules = [];
     const conceptByQualifiedId = new Map(documents.flatMap(({ value }) => value.concepts.map((concept) => [
         concept.id,
         {
@@ -613,6 +616,20 @@ function compileWorkspaceResolved(parsed) {
             document: value.id,
         },
     ])));
+    for (const { value } of documents) {
+        for (const concept of value.concepts) {
+            for (const rule of concept.forbids ?? []) {
+                forbidRules.push({
+                    declaredBy: concept.id,
+                    relationship: rule.relationship,
+                    ...(rule.from === undefined ? {} : { from: rule.from }),
+                    ...(rule.to === undefined ? {} : { to: rule.to }),
+                    exceptFrom: new Set(rule.exceptFrom ?? []),
+                    exceptTo: new Set(rule.exceptTo ?? []),
+                });
+            }
+        }
+    }
     // Subject identity is the authored id, unique across the workspace, so a
     // reference resolves as written. Kept as a named step rather than inlined
     // because every reference in the model passes through here, and that is
@@ -653,7 +670,7 @@ function compileWorkspaceResolved(parsed) {
         : [
             [
                 concept.id,
-                concept.supersedes.map((predecessor) => qualifyReference(value.id, predecessor)),
+                concept.supersedes.map((predecessor) => qualifyReference(value.id, successionSubject(predecessor))),
             ],
         ])));
     // Self-succession is a cycle of length one, but it has its own diagnostic
@@ -885,14 +902,14 @@ function compileWorkspaceResolved(parsed) {
             }
             for (const [supersedesIndex, predecessor] of (concept.supersedes ?? []).entries()) {
                 const pointer = `/concepts/${index}/supersedes/${supersedesIndex}`;
-                const predecessorIdentity = qualifyReference(value.id, predecessor);
+                const predecessorIdentity = qualifyReference(value.id, successionSubject(predecessor));
                 const subjectIdentity = concept.id;
                 if (!conceptByQualifiedId.has(predecessorIdentity)) {
                     const source = location(['concepts', index, 'supersedes', supersedesIndex], pointer);
                     diagnostics.push({
                         severity: 'error',
                         code: 'YM312',
-                        message: `Unresolved succession reference "${predecessor}"`,
+                        message: `Unresolved succession reference "${successionSubject(predecessor)}"`,
                         path: input.path,
                         pointer,
                         line: source.line,
@@ -1186,6 +1203,32 @@ function compileWorkspaceResolved(parsed) {
                     const tail = candidates.length === 0
                         ? ''
                         : `; ArchiMate 3.2 permits: ${candidates.join(', ')}`;
+                    // A declared rule about the graph, checked against the graph. The
+                    // field is new, so no existing model can violate one: this can only
+                    // fire on a rule someone deliberately wrote (ADR 0108).
+                    for (const rule of forbidRules) {
+                        const kindMatches = rule.relationship === relationship.kind ||
+                            rule.relationship === policy.coreKind;
+                        if (!kindMatches)
+                            continue;
+                        if (rule.from !== undefined && rule.from !== relationship.from) {
+                            continue;
+                        }
+                        if (rule.to !== undefined && rule.to !== relationship.to)
+                            continue;
+                        if (rule.exceptFrom.has(relationship.from))
+                            continue;
+                        if (rule.exceptTo.has(relationship.to))
+                            continue;
+                        const pointer = `/relationships/${index}/kind`;
+                        diagnostics.push({
+                            severity: 'error',
+                            code: 'YM415',
+                            message: `Relationship "${relationship.kind}" from "${relationship.from}" ` +
+                                `to "${relationship.to}" is forbidden by "${rule.declaredBy}"`,
+                            ...location(['relationships', index, 'kind'], pointer),
+                        });
+                    }
                     if (!permitted.has(policy.coreKind)) {
                         const pointer = `/relationships/${index}/kind`;
                         const source = location(['relationships', index, 'kind'], pointer);
@@ -1304,15 +1347,31 @@ function compileWorkspaceResolved(parsed) {
             // predecessor is not required to be retired: the transition period
             // during which both are current is real.
             for (const [supersedesIndex, predecessor] of (concept.supersedes ?? []).entries()) {
-                const predecessorIdentity = qualifyReference(value.id, predecessor);
+                const predecessorIdentity = qualifyReference(value.id, successionSubject(predecessor));
+                const scope = successionScope(predecessor);
+                const successionSource = location(['concepts', index, 'supersedes', supersedesIndex], `/concepts/${index}/supersedes/${supersedesIndex}`);
                 claims.push({
                     id: supersedesClaimId(subject, predecessorIdentity),
                     subject,
                     predicate: 'yarramate/lineage/supersedes',
                     object: { ref: predecessorIdentity },
                     origin: 'declared',
-                    source: location(['concepts', index, 'supersedes', supersedesIndex], `/concepts/${index}/supersedes/${supersedesIndex}`),
+                    source: successionSource,
                 });
+                // The respect is a claim of its own rather than a field on the
+                // succession claim: `GraphClaim` is a triple, and widening it would
+                // widen the published graph schema for one optional string. Its id is
+                // the succession claim's, suffixed, so the two correlate.
+                if (scope !== undefined) {
+                    claims.push({
+                        id: `${supersedesClaimId(subject, predecessorIdentity)}~respect`,
+                        subject,
+                        predicate: 'yarramate/lineage/supersedes-respect',
+                        object: { value: scope },
+                        origin: 'declared',
+                        source: successionSource,
+                    });
+                }
             }
             if (concept.owner !== undefined) {
                 claims.push({

package/dist/design-command.js

@@ -37,6 +37,7 @@ const selectStep = (report, subjectFilter, askPlainById) => {
                         : { askPlain: askPlainTemplate.trim() }),
                     materiality: question.materiality,
                     resolution: question.resolution,
+                    trigger: question.trigger,
                     ...(question.since === undefined ? {} : { since: question.since }),
                 };
             }
@@ -57,6 +58,7 @@ const selectStep = (report, subjectFilter, askPlainById) => {
                     : { askPlain: renderQuestion(askPlainTemplate, first.id, first.name) }),
                 materiality: question.materiality,
                 resolution: question.resolution,
+                trigger: question.trigger,
                 ...(question.since === undefined ? {} : { since: question.since }),
                 subject: {
                     id: first.id,
@@ -74,6 +76,56 @@ const selectStep = (report, subjectFilter, askPlainById) => {
     }
     return null;
 };
+const localKind = (qualified) => {
+    const hash = qualified.lastIndexOf('#');
+    return hash === -1 ? qualified : qualified.slice(hash + 1);
+};
+const skeletonHeader = (documentAddress, op) => [
+    '',
+    'Prefilled skeleton (edit the <placeholders>, save as operations.yaml):',
+    '  format: yarramate/operations/v1',
+    '  operations:',
+    `    - op: ${op}`,
+    `      document: ${documentAddress}`,
+];
+// The skeleton is a rendering of the step's trigger (#289), printed only
+// when a single condition maps unambiguously onto one operation, so a
+// wrong skeleton is never offered; every other trigger leaves the output
+// exactly as before. Kinds print as local names: that is the form a
+// native document declares.
+const renderSkeleton = (step, documentAddress) => {
+    if (documentAddress === undefined || step.trigger.length !== 1)
+        return [];
+    const condition = step.trigger[0];
+    if (condition.condition === 'no-subject-of-kind') {
+        const kinds = condition.kinds.map(localKind);
+        const alternatives = kinds.length > 1 ? `  # or: ${kinds.slice(1).join(', ')}` : '';
+        return [
+            ...skeletonHeader(documentAddress, 'add-concept'),
+            '      concept:',
+            '        id: <kebab-case-id>',
+            `        kind: ${kinds[0]}${alternatives}`,
+            '        name: <one line>',
+        ];
+    }
+    if (condition.condition === 'missing-relationship' &&
+        step.subject !== undefined) {
+        const kinds = condition.kinds.map(localKind);
+        const alternatives = kinds.length > 1 ? `  # or: ${kinds.slice(1).join(', ')}` : '';
+        const swap = condition.direction === 'any' ? '  # or swap the endpoints' : '';
+        const from = condition.direction === 'incoming' ? '<counterpart-id>' : step.subject.id;
+        const to = condition.direction === 'incoming' ? step.subject.id : '<counterpart-id>';
+        return [
+            ...skeletonHeader(documentAddress, 'add-relationship'),
+            '      relationship:',
+            '        id: <kebab-case-id>',
+            `        kind: ${kinds[0]}${alternatives}`,
+            `        from: ${from}${swap}`,
+            `        to: ${to}`,
+        ];
+    }
+    return [];
+};
 export function runDesignCommand(options, cwd) {
     const json = options.includes('--json');
     // Facilitation is a rendering preference, not an interview mode: the
@@ -232,7 +284,21 @@ export function runDesignCommand(options, cwd) {
             if (slice !== undefined) {
                 lines.push('', 'Subject slice:', '', slice.trimEnd());
             }
-            lines.push('', 'Answer by updating the model (one atomic batch):', `  yarramate apply <operations.yaml> ${workspacePath}`, `Then re-run: yarramate design ${workspacePath}`);
+            // The skeleton's document address is the manifest-relative form
+            // when the first document sits under the manifest directory - the
+            // address an author naturally writes and apply accepts (#216) -
+            // falling back to the workspace path, which apply also accepts.
+            const manifestDirectory = workspacePath.includes('/')
+                ? workspacePath.slice(0, workspacePath.lastIndexOf('/'))
+                : '';
+            const firstDocument = workspace.documents[0];
+            const documentAddress = firstDocument === undefined
+                ? undefined
+                : manifestDirectory !== '' &&
+                    firstDocument.startsWith(`${manifestDirectory}/`)
+                    ? firstDocument.slice(manifestDirectory.length + 1)
+                    : firstDocument;
+            lines.push('', 'Answer by updating the model (one atomic batch):', `  yarramate apply <operations.yaml> ${workspacePath}`, ...renderSkeleton(step, documentAddress), `Then re-run: yarramate design ${workspacePath}`);
         }
         return { exitCode: 0, stdout: `${lines.join('\n')}\n`, stderr: '' };
     }

package/dist/evidence.d.ts

@@ -8,15 +8,39 @@ export interface EvidenceObservedValue {
     readonly key: string;
     readonly value: string;
 }
+/**
+ * One search a provider ran and found nothing at, recorded so a reader can
+ * re-run it. yarramate never executes it: the engine has no access to the
+ * subject tree, and gaining one would be a different decision (ADR 0107).
+ */
+export type SearchProbe = {
+    readonly glob: string;
+} | {
+    readonly grep: string;
+    readonly paths?: readonly string[];
+};
+/**
+ * A figure quoted in an evidence message, with how it was produced, so a
+ * reader can tell a measured number from a remembered one and re-derive it at
+ * a later commit.
+ */
+export interface Measurement {
+    readonly value: string;
+    readonly method: string;
+}
+interface ObservationProvenance {
+    readonly searched?: readonly SearchProbe[];
+    readonly measured?: readonly Measurement[];
+}
 export type EvidenceObservation = ({
     readonly subject: string;
     readonly result: EvidenceResult;
     readonly evidence: EvidenceLocator;
-} & Partial<EvidenceObservedValue>) | ({
+} & ObservationProvenance & Partial<EvidenceObservedValue>) | ({
     readonly claim: string;
     readonly result: EvidenceResult;
     readonly evidence: EvidenceLocator;
-} & Partial<EvidenceObservedValue>);
+} & ObservationProvenance & Partial<EvidenceObservedValue>);
 export interface EvidenceDocument {
     readonly format: 'yarramate/evidence/v1';
     readonly id: string;
@@ -60,3 +84,4 @@ export type EvidenceWorkspaceEvaluationResult = {
 export declare function loadEvidence(source: WorkspaceSource): EvidenceLoadResult;
 export declare function evaluateEvidence(graph: SemanticGraph, evidence: EvidenceDocument): EvidenceEvaluationResult;
 export declare function evaluateEvidenceWorkspace(graph: SemanticGraph, evidenceDocuments: readonly EvidenceDocument[]): EvidenceWorkspaceEvaluationResult;
+export {};

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export { applyOperations, landOperations, posixDirectoryOf, type ApplyInput, typ
 export { connectableKinds, draftRelationship, proposeRelationshipId, } 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, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, 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

@@ -16,3 +16,4 @@ export { applyOperations, landOperations, posixDirectoryOf, } from './apply-comm
 export { connectableKinds, draftRelationship, proposeRelationshipId, } from './relationship-drafting.js';
 export { draftConcept, proposeConceptId } from './concept-drafting.js';
 export { deletionBlockers, describeDeletion, draftDeletion, } from './deletion-drafting.js';
+export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';

package/dist/interrogate-command.d.ts

@@ -1,11 +1,38 @@
-import { type Diagnostic, type ResolvedProfileContext, type SemanticGraph, type WorkspaceSource } from './compiler.js';
-interface CatalogueSelector {
-    readonly kinds: readonly string[];
+import type { Diagnostic, ResolvedProfileContext, SemanticGraph, WorkspaceSource } from './compiler.js';
+/**
+ * The version of condition evaluation itself, not of the package.
+ *
+ * A report says which catalogue asked its questions. It could not say which
+ * engine answered them, so a consumer holding stored answers could tell a
+ * model change from a catalogue deepening (via `since`) but not from a change
+ * in what a condition means. ADR 0097 replaced four aspect rules with the
+ * ArchiMate 3.2 table and flipped `missing-relationship` answers for unchanged
+ * models and unchanged questions; ADR 0083's `unconstrained-kind` goes
+ * near-empty under that same table. Neither was visible in any report.
+ *
+ * **Bump this when an existing question's answer can change for an unchanged
+ * model.** Do not bump it for anything else: not a release, not a new
+ * condition, not a catalogue edit, not a rendering change. A version that
+ * moves when answers did not is a version consumers learn to ignore.
+ *
+ * `test/interrogation-semantics.test.ts` fingerprints every condition against
+ * a fixture and fails if evaluation moves without this bumping, so the rule is
+ * enforced rather than remembered.
+ */
+export declare const INTERROGATION_SEMANTICS_VERSION = "1";
+export interface CatalogueSelector {
+    /**
+     * Kinds to select. Absent selects every concept, which is what a
+     * kind-agnostic condition wants: succession can be declared on any subject,
+     * so enumerating the kinds that may carry it would be a list nobody can keep
+     * right rather than a constraint (ADR 0109).
+     */
+    readonly kinds?: readonly string[];
     readonly kindMatching?: 'exact' | 'descendants';
     readonly statuses?: readonly string[];
     readonly documents?: readonly string[];
 }
-type CatalogueCondition = {
+export type CatalogueCondition = {
     readonly condition: 'missing-claim';
     readonly predicate: string;
 } | {
@@ -56,6 +83,8 @@ type CatalogueCondition = {
     readonly condition: 'near-duplicate';
 } | {
     readonly condition: 'unconstrained-kind';
+} | {
+    readonly condition: 'unscoped-succession';
 };
 export interface CatalogueQuestion {
     readonly id: string;
@@ -86,12 +115,12 @@ export interface QuestionCatalogue {
     }[];
     readonly questions: readonly CatalogueQuestion[];
 }
-interface OpenSubject {
+export interface OpenSubject {
     readonly id: string;
     readonly name?: string;
     readonly question: string;
 }
-interface ReportQuestion {
+export interface ReportQuestion {
     readonly id: string;
     readonly scope: 'workspace' | 'subject';
     readonly authority: 'human' | 'agent' | 'either';
@@ -99,23 +128,35 @@ interface ReportQuestion {
     readonly question: string;
     readonly materiality: string;
     readonly resolution: string;
+    /**
+     * The catalogue trigger, verbatim (#289). The conditions that opened a
+     * question are its machine-readable answer shape: a host builds the
+     * matching affordance (a prefilled form, an operations skeleton) from
+     * them instead of re-deriving the shape from its own catalogue copy and
+     * drifting from engine semantics.
+     */
+    readonly trigger: readonly CatalogueCondition[];
     readonly since?: string;
     readonly subjects?: readonly OpenSubject[];
 }
+export interface ReportWave {
+    readonly id: string;
+    readonly name: string;
+    readonly questions: readonly ReportQuestion[];
+}
+export interface InterrogationSummary {
+    readonly questions: number;
+    readonly openQuestions: number;
+    readonly open: number;
+}
 export interface InterrogationReport {
     readonly format: 'yarramate/interrogation-report/v1';
     readonly workspace: string;
     readonly catalogue: string;
-    readonly summary: {
-        readonly questions: number;
-        readonly openQuestions: number;
-        readonly open: number;
-    };
-    readonly waves: readonly {
-        readonly id: string;
-        readonly name: string;
-        readonly questions: readonly ReportQuestion[];
-    }[];
+    /** {@link INTERROGATION_SEMANTICS_VERSION} at the time of evaluation. */
+    readonly semantics: string;
+    readonly summary: InterrogationSummary;
+    readonly waves: readonly ReportWave[];
 }
 export declare const renderQuestion: (template: string, subjectId: string, subjectName: string | undefined, counterparts?: readonly string[]) => string;
 export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext): Omit<InterrogationReport, 'workspace'>;
@@ -128,4 +169,3 @@ export type CatalogueLoadResult = {
 };
 export declare function loadQuestionCatalogue(catalogueSource: WorkspaceSource): CatalogueLoadResult;
 export declare function renderInterrogationReport(report: InterrogationReport): string;
-export {};

package/dist/interrogate-command.js

@@ -10,6 +10,27 @@ import catalogueSchema from '../schema/yarramate-question-catalogue.schema.json'
 const ajv2020Module = Ajv2020Module;
 const Ajv2020 = ajv2020Module.default ?? ajv2020Module;
 const validateCatalogue = new Ajv2020({ allErrors: true }).compile(catalogueSchema);
+/**
+ * The version of condition evaluation itself, not of the package.
+ *
+ * A report says which catalogue asked its questions. It could not say which
+ * engine answered them, so a consumer holding stored answers could tell a
+ * model change from a catalogue deepening (via `since`) but not from a change
+ * in what a condition means. ADR 0097 replaced four aspect rules with the
+ * ArchiMate 3.2 table and flipped `missing-relationship` answers for unchanged
+ * models and unchanged questions; ADR 0083's `unconstrained-kind` goes
+ * near-empty under that same table. Neither was visible in any report.
+ *
+ * **Bump this when an existing question's answer can change for an unchanged
+ * model.** Do not bump it for anything else: not a release, not a new
+ * condition, not a catalogue edit, not a rendering change. A version that
+ * moves when answers did not is a version consumers learn to ignore.
+ *
+ * `test/interrogation-semantics.test.ts` fingerprints every condition against
+ * a fixture and fails if evaluation moves without this bumping, so the rule is
+ * enforced rather than remembered.
+ */
+export const INTERROGATION_SEMANTICS_VERSION = '1';
 const indexGraph = (graph) => {
     const relationshipIds = new Set(graph.subjects
         .filter(({ type }) => type === 'relationship')
@@ -146,7 +167,9 @@ const selectSubjects = (index, selector, profileContext) => {
     // The schema's declared default for kindMatching is descendants, so a
     // profile-derived kind satisfies a catalogue written against its parent.
     const matching = selector.kindMatching ?? 'descendants';
-    let ids = [...index.concepts].filter((id) => kindMatches(index.kindOf.get(id), selector.kinds, matching, profileContext));
+    let ids = selector.kinds === undefined
+        ? [...index.concepts]
+        : [...index.concepts].filter((id) => kindMatches(index.kindOf.get(id), selector.kinds, matching, profileContext));
     if (selector.statuses !== undefined) {
         const statuses = new Set(selector.statuses);
         ids = ids.filter((id) => {
@@ -217,6 +240,28 @@ const conditionHolds = (index, condition, subjectId, profileContext) => {
     switch (condition.condition) {
         case 'missing-claim':
             return !(index.claimsBySubject.get(subjectId) ?? []).some(({ predicate }) => predicate === condition.predicate);
+        case 'unscoped-succession': {
+            // A succession that replaced its predecessor outright says so by the
+            // predecessor being gone. One where both subjects are still current is
+            // usually partial, and the respect is the part a reader needs: a model
+            // claimed Zoekt superseded the Elasticsearch indexer while the source
+            // said Zoekt "does not replace" it for any scope but code search
+            // (ADR 0109). Fires only where the qualifier is missing AND the
+            // predecessor is still current, so a completed replacement stays quiet.
+            const claims = index.claimsBySubject.get(subjectId) ?? [];
+            return claims.some((claim) => {
+                if (claim.predicate !== 'yarramate/lineage/supersedes')
+                    return false;
+                if (!('ref' in claim.object))
+                    return false;
+                const scoped = claims.some((other) => other.predicate === 'yarramate/lineage/supersedes-respect' &&
+                    other.id === `${claim.id}~respect`);
+                if (scoped)
+                    return false;
+                const predecessorStatus = index.statusOf.get(claim.object.ref);
+                return predecessorStatus !== 'retired';
+            });
+        }
         case 'missing-relationship': {
             // Relationship kinds resolve through profile lineage by default, the
             // same rule as selectors: a catalogue written against core kinds must
@@ -398,6 +443,7 @@ export function evaluateCatalogue(catalogue, graph, profileContext) {
                 question: question.question.trim(),
                 materiality: question.materiality.trim(),
                 resolution: question.resolution.trim(),
+                trigger: question.trigger,
                 ...(question.since === undefined ? {} : { since: question.since }),
             };
             if (question.scope === 'workspace') {
@@ -431,6 +477,7 @@ export function evaluateCatalogue(catalogue, graph, profileContext) {
     return {
         format: 'yarramate/interrogation-report/v1',
         catalogue: `${catalogue.id}@${catalogue.version}`,
+        semantics: INTERROGATION_SEMANTICS_VERSION,
         summary: {
             questions: applicableQuestions.length,
             openQuestions,

package/dist/interrogation-entry.d.ts

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

package/dist/interrogation-entry.js

@@ -0,0 +1,10 @@
+// The interrogation engine as a runtime-neutral entry point.
+//
+// The `.` barrel reaches node:fs, node:path and node:child_process through
+// workspace, source-store and attestation-staleness, so a consumer running
+// inside a Worker or a Durable Object cannot take the engine from there
+// without dragging Node in behind it. This subpath carries the pure engine
+// alone: catalogue loading takes a WorkspaceSource, evaluation takes an
+// in-memory graph, and a test pins the import graph free of Node builtins.
+// The same shape the visual-graph projector uses (`./adapter/visual-graph`).
+export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';

package/dist/reconciliation.d.ts

@@ -86,6 +86,13 @@ export interface ReconciliationReport {
         readonly contradicted: number;
         readonly unknown: number;
         readonly notObserved: number;
+        /**
+         * `not-observed` observations naming no search. A negative claim about a
+         * tree nobody read exhaustively is the one result whose message nothing
+         * can check, so the ones offering a reader nothing to re-run are counted
+         * rather than left to read like any other finding (ADR 0107).
+         */
+        readonly unsupportedAbsences?: number;
         readonly subjectsWithoutEvidence: number;
         readonly staleAttestations?: number;
         readonly unconfirmedAttestations?: number;

package/dist/reconciliation.js

@@ -199,6 +199,7 @@ export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
         contradicted: 0,
         unknown: 0,
         notObserved: 0,
+        unsupportedAbsences: 0,
         subjectsWithoutEvidence: unobservedSubjects.length,
         // Attestation staleness is assessed only when the caller derived it
         // (the reconcile command); the counter appears exactly then, so a
@@ -219,6 +220,7 @@ export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
         ...(staleness?.findings ?? []),
         ...unconfirmed,
     ];
+    const absenceNotes = [];
     for (const report of reports) {
         summary.observations += report.observations.length;
         for (const observation of report.observations) {
@@ -228,6 +230,18 @@ export function reconcileEvidenceReports(workspace, reports, graph, staleness) {
             }
             if (observation.result === 'not-observed') {
                 summary.notObserved += 1;
+                // A not-observed asserts a negative, and is the only result whose
+                // message nothing else in the pipeline can check: the locator it
+                // carries points at what the author looked at, not at the absence
+                // they claim. One naming no search offers a reader nothing to
+                // re-run, so it is counted and named rather than left to read like
+                // a checked finding (ADR 0107).
+                if ((observation.searched ?? []).length === 0) {
+                    summary.unsupportedAbsences += 1;
+                    const named = 'subject' in observation ? observation.subject : observation.claim;
+                    absenceNotes.push(`The not-observed observation for ${named} names no search, ` +
+                        `so nothing here can be re-run to test the absence it asserts.`);
+                }
             }
             else {
                 summary[observation.result] += 1;
@@ -260,7 +274,7 @@ 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 ?? [];
+    const notes = [...(staleness?.notes ?? []), ...absenceNotes];
     return {
         format: 'yarramate/reconciliation-report/v1',
         workspace,

package/dist/subject-references.js

@@ -12,6 +12,14 @@ export const SUBJECT_REFERENCE_POSITIONS = [
         path: ['concepts', '*', 'supersedes', '*'],
         form: 'reference',
     },
+    // The scoped succession form, `{ subject, inRespectOf }` (ADR 0109). A
+    // rename has to move this one too, or a scoped succession would silently
+    // keep pointing at the old address while the bare form beside it moved.
+    {
+        group: 'document',
+        path: ['concepts', '*', 'supersedes', '*', 'subject'],
+        form: 'reference',
+    },
     {
         group: 'document',
         path: ['concepts', '*', 'constraints', '*', 'ref'],