yarramate 1.32.0 → 1.34.0

package/dist/governance.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The governance log (#560, ADR 0160): the RAID log's risks and
+ * assumptions as the model holds them, derived the way the responsibility
+ * matrix is derived and never authored. One row per risk or assumption:
+ * its owner and status, what it threatens or bears on, what mitigates it,
+ * the latest review attestation, what it supersedes, and the groupings it
+ * aggregates into (an adopter's severity or likelihood classes, which the
+ * engine carries without knowing the scale). Issues and open questions are
+ * the adopter's and the interrogation's; the engine never sees an issue.
+ *
+ * Deterministic: identical inputs give identical bytes, so CI can diff it.
+ */
+import type { ResolvedProfileContext, SemanticGraph } from './compiler.js';
+import { type GovernanceType } from './governance-kinds.js';
+export interface GovernanceSource {
+    readonly path: string;
+    readonly line: number;
+}
+export interface GovernanceRef {
+    readonly id: string;
+    readonly name: string;
+}
+/** The latest review attestation on a row, by date. */
+export interface GovernanceReview {
+    readonly topic: string;
+    readonly on: string;
+    readonly by: string;
+    readonly source: GovernanceSource;
+}
+export interface GovernanceRow {
+    readonly subject: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly type: GovernanceType;
+    readonly status: string | null;
+    readonly description?: string;
+    readonly owner: GovernanceRef | null;
+    /** A risk's outgoing `influence` targets: what it threatens. */
+    readonly threatens: readonly GovernanceRef[];
+    /** An assumption's outgoing `association` targets: what it bears on. */
+    readonly bearsOn: readonly GovernanceRef[];
+    /** Incoming `influence` or `association` sources on a risk: what mitigates it. */
+    readonly mitigatedBy: readonly GovernanceRef[];
+    readonly review: GovernanceReview | null;
+    readonly supersedes: readonly string[];
+    /** The groupings that aggregate this row: an adopter's rating classes. */
+    readonly groupedBy: readonly GovernanceRef[];
+}
+export interface GovernanceLog {
+    readonly format: 'yarramate/governance/v1';
+    readonly workspace: string;
+    readonly summary: {
+        readonly rows: number;
+        readonly risks: number;
+        readonly assumptions: number;
+        readonly unowned: number;
+        readonly unmitigated: number;
+        readonly unconfirmed: number;
+        readonly unreviewed: number;
+    };
+    readonly rows: readonly GovernanceRow[];
+    readonly gaps: {
+        /** Rows with no owner. */
+        readonly unowned: readonly string[];
+        /** Current risks nothing mitigates. */
+        readonly unmitigated: readonly string[];
+        /** Assumptions with no `assumption-confirmed` attestation. */
+        readonly unconfirmed: readonly string[];
+        /** Risks with no `risk-reviewed` attestation. How old is too old is the adopter's. */
+        readonly unreviewed: readonly string[];
+    };
+}
+export interface GovernanceOptions {
+    /** The subjects that may get a row; absent, every risk and assumption. */
+    readonly rows?: readonly string[];
+}
+export declare function buildGovernanceLog(workspace: string, graph: SemanticGraph, profileContext: ResolvedProfileContext, options?: GovernanceOptions): GovernanceLog;
+/** The log as one markdown table a person reads, with the gaps under it. */
+export declare function renderGovernanceMarkdown(log: GovernanceLog): string;

package/dist/governance.js

@@ -0,0 +1,164 @@
+import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, } from './graph-claims.js';
+import { REVIEW_TOPICS, governanceTypeOf, } from './governance-kinds.js';
+const CORE = 'yarramate/core@0.1#';
+const documentOf = (subject) => {
+    const hash = subject.indexOf('#');
+    return hash === -1 ? '' : subject.slice(0, hash);
+};
+const bySubjectOrder = (left, right) => documentOf(left).localeCompare(documentOf(right)) ||
+    left.localeCompare(right);
+const citation = (claim) => ({
+    path: claim.source.path,
+    line: claim.source.line,
+});
+export function buildGovernanceLog(workspace, graph, profileContext, options = {}) {
+    const conceptIds = new Set(graph.subjects.filter(({ type }) => type === 'concept').map(({ id }) => id));
+    const relationshipIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const values = new Map();
+    const refs = new Map();
+    const attestations = new Map();
+    const definingClaims = [];
+    for (const claim of graph.claims) {
+        if (relationshipIds.has(claim.id) && 'ref' in claim.object) {
+            definingClaims.push(claim);
+            continue;
+        }
+        if ('ref' in claim.object) {
+            const key = `${claim.subject} ${claim.predicate}`;
+            refs.set(key, [...(refs.get(key) ?? []), claim.object.ref]);
+            continue;
+        }
+        if (claim.predicate.startsWith(ATTESTATION_PREDICATE_PREFIX)) {
+            attestations.set(claim.subject, [
+                ...(attestations.get(claim.subject) ?? []),
+                claim,
+            ]);
+            continue;
+        }
+        values.set(`${claim.subject} ${claim.predicate}`, claim.object.value);
+    }
+    const value = (subject, predicate) => values.get(`${subject} ${predicate}`);
+    const refsOf = (subject, predicate) => refs.get(`${subject} ${predicate}`) ?? [];
+    const kindOf = (subject) => value(subject, 'yarramate/concept/kind') ?? '';
+    const nameOf = (subject) => value(subject, 'yarramate/concept/name') ?? subject;
+    const refOf = (id) => ({ id, name: nameOf(id) });
+    const typeOf = (subject) => {
+        const kind = kindOf(subject);
+        return governanceTypeOf(profileContext.conceptKindLineages.get(kind), kind);
+    };
+    const coreKindOf = (relationshipKind) => (profileContext.relationshipKindLineages.get(relationshipKind) ?? [
+        relationshipKind,
+    ])[0];
+    const rowIds = (options.rows ?? [...conceptIds])
+        .filter((id) => conceptIds.has(id) && typeOf(id) !== null)
+        .sort(bySubjectOrder);
+    const rowSet = new Set(rowIds);
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const claim of definingClaims) {
+        if (!('ref' in claim.object))
+            continue;
+        const core = coreKindOf(claim.predicate);
+        if (rowSet.has(claim.subject)) {
+            outgoing.set(claim.subject, [
+                ...(outgoing.get(claim.subject) ?? []),
+                { core, to: claim.object.ref },
+            ]);
+        }
+        if (rowSet.has(claim.object.ref)) {
+            incoming.set(claim.object.ref, [
+                ...(incoming.get(claim.object.ref) ?? []),
+                { core, from: claim.subject },
+            ]);
+        }
+    }
+    const targets = (subject, core) => (outgoing.get(subject) ?? [])
+        .filter((edge) => edge.core === `${CORE}${core}`)
+        .map(({ to }) => to)
+        .sort(bySubjectOrder)
+        .map(refOf);
+    const sources = (subject, cores) => (incoming.get(subject) ?? [])
+        .filter((edge) => cores.some((core) => edge.core === `${CORE}${core}`))
+        .map(({ from }) => from)
+        .sort(bySubjectOrder)
+        .map(refOf);
+    const latestReview = (subject, topic) => {
+        let latest = null;
+        for (const claim of attestations.get(subject) ?? []) {
+            if (claim.predicate !== `${ATTESTATION_PREDICATE_PREFIX}${topic}`)
+                continue;
+            if (!('value' in claim.object))
+                continue;
+            const parts = parseAttestationClaimValue(claim.object.value);
+            if (parts === undefined)
+                continue;
+            if (latest === null || parts.on >= latest.on) {
+                latest = { topic, on: parts.on, by: parts.by, source: citation(claim) };
+            }
+        }
+        return latest;
+    };
+    const rows = rowIds.map((subject) => {
+        const type = typeOf(subject);
+        const owner = refsOf(subject, 'yarramate/ownership/owner')[0];
+        const description = value(subject, 'yarramate/concept/description');
+        return {
+            subject,
+            name: nameOf(subject),
+            kind: kindOf(subject),
+            type,
+            status: value(subject, 'yarramate/lifecycle/status') ?? null,
+            ...(description === undefined ? {} : { description }),
+            owner: owner === undefined ? null : refOf(owner),
+            threatens: type === 'risk' ? targets(subject, 'influence') : [],
+            bearsOn: type === 'assumption' ? targets(subject, 'association') : [],
+            mitigatedBy: type === 'risk' ? sources(subject, ['influence', 'association']) : [],
+            review: latestReview(subject, REVIEW_TOPICS[type]),
+            supersedes: [...refsOf(subject, 'yarramate/lineage/supersedes')].sort(),
+            groupedBy: sources(subject, ['aggregation']),
+        };
+    });
+    const ids = (predicate) => rows.filter(predicate).map(({ subject }) => subject);
+    const unowned = ids((row) => row.owner === null);
+    const unmitigated = ids((row) => row.type === 'risk' && row.status === 'current' && row.mitigatedBy.length === 0);
+    const unconfirmed = ids((row) => row.type === 'assumption' && row.review === null);
+    const unreviewed = ids((row) => row.type === 'risk' && row.review === null);
+    return {
+        format: 'yarramate/governance/v1',
+        workspace,
+        summary: {
+            rows: rows.length,
+            risks: rows.filter(({ type }) => type === 'risk').length,
+            assumptions: rows.filter(({ type }) => type === 'assumption').length,
+            unowned: unowned.length,
+            unmitigated: unmitigated.length,
+            unconfirmed: unconfirmed.length,
+            unreviewed: unreviewed.length,
+        },
+        rows,
+        gaps: { unowned, unmitigated, unconfirmed, unreviewed },
+    };
+}
+const escapeCell = (text) => text.replaceAll('|', '\\|');
+const names = (entries) => entries.map(({ name }) => escapeCell(name)).join(', ');
+const list = (ids) => ids.length === 0 ? 'none' : ids.map((id) => `\`${id}\``).join(', ');
+/** The log as one markdown table a person reads, with the gaps under it. */
+export function renderGovernanceMarkdown(log) {
+    const lines = ['# Governance log', ''];
+    lines.push(`Workspace \`${log.workspace}\`: ${log.summary.risks} risk${log.summary.risks === 1 ? '' : 's'}, ${log.summary.assumptions} assumption${log.summary.assumptions === 1 ? '' : 's'}. Derived from the record; edit the native documents, not this file.`, '');
+    if (log.rows.length === 0) {
+        lines.push('_No rows._', '');
+    }
+    else {
+        lines.push('| Subject | Type | Status | Owner | Threatens / bears on | Mitigated by | Review | Grouped by |', '|---|---|---|---|---|---|---|---|');
+        for (const row of log.rows) {
+            const review = row.review === null ? '' : `${row.review.topic} ${row.review.on} by ${escapeCell(row.review.by)}`;
+            lines.push(`| ${escapeCell(row.name)} (\`${row.subject}\`) | ${row.type} | ${row.status ?? ''} | ${row.owner === null ? '' : escapeCell(row.owner.name)} | ${names(row.type === 'risk' ? row.threatens : row.bearsOn)} | ${names(row.mitigatedBy)} | ${review} | ${names(row.groupedBy)} |`);
+        }
+        lines.push('');
+    }
+    lines.push('## Gaps', '', `- Unowned: ${list(log.gaps.unowned)}`, `- Unmitigated (current risks): ${list(log.gaps.unmitigated)}`, `- Unconfirmed assumptions: ${list(log.gaps.unconfirmed)}`, `- Unreviewed risks: ${list(log.gaps.unreviewed)}`, '');
+    return `${lines.join('\n')}\n`;
+}

package/dist/graph-projection.d.ts

@@ -67,6 +67,23 @@ export interface CanvasEdge {
     readonly kind: string;
     readonly kindLabel: string;
     readonly coreKindLabel: string;
+    /**
+     * The kind whose reading the edge label speaks (ADR 0159): an extension
+     * identity with a reading of its own, else `coreKindLabel`.
+     */
+    readonly readingKind?: string;
+    /**
+     * The responsibility letter this edge carries (#557): R, C or I for the
+     * shipped responsibility kinds and their subkinds, null for every other
+     * kind. The canvas draws these only when the view asks (`showResponsibility`).
+     */
+    readonly responsibility?: ResponsibilityLetter | null;
+    /**
+     * A reading the endpoints decide (ADR 0160): "threatens" for an
+     * influence from a risk, "mitigates" for one into a risk, "bears on" for
+     * an association from an assumption. Absent, the kind's own reading.
+     */
+    readonly reading?: string;
     readonly from: string;
     readonly to: string;
     readonly name: string | null;
@@ -84,4 +101,5 @@ export interface CanvasGraph {
     readonly nodes: readonly CanvasNode[];
     readonly edges: readonly CanvasEdge[];
 }
+import { type ResponsibilityLetter } from './responsibility-kinds.js';
 export declare function projectGraphForCanvas(graph: SemanticGraph, profileContext: ResolvedProfileContext): CanvasGraph;

package/dist/graph-projection.js

@@ -1,5 +1,7 @@
 import { ATTESTATION_PREDICATE_PREFIX, parseAttestationClaimValue, parseConstraintExpectsValue, } from './graph-claims.js';
 import { kindLabelOf } from './kind-label.js';
+import { contextualReading, readingKindOf } from './relationship-reading.js';
+import { responsibilityLetterOf } from './responsibility-kinds.js';
 const CONCEPT_KIND_PREDICATE = 'yarramate/concept/kind';
 const CONCEPT_NAME_PREDICATE = 'yarramate/concept/name';
 const CONCEPT_DESCRIPTION_PREDICATE = 'yarramate/concept/description';
@@ -160,7 +162,7 @@ const projectConcept = (subjectId, claims, profileContext) => {
         attestations,
     };
 };
-const projectRelationship = (relationshipId, allClaims, ownClaims, profileContext) => {
+const projectRelationship = (relationshipId, allClaims, ownClaims, profileContext, conceptKindOf = new Map()) => {
     // A relationship's defining claim is asymmetric: its id is the
     // relationship's subject id, but its own `subject` field is the
     // from-concept, so it lives in the from-concept's claim group, not this
@@ -170,6 +172,15 @@ const projectRelationship = (relationshipId, allClaims, ownClaims, profileContex
         throw new Error(`Relationship "${relationshipId}" is missing its defining claim`);
     }
     const kind = definingClaim.predicate;
+    const lineage = profileContext.relationshipKindLineages.get(kind);
+    const coreKindLabel = kindLabelOf(lineage?.[0] ?? kind);
+    const endpointLineage = (subject) => {
+        const conceptKind = conceptKindOf.get(subject);
+        return conceptKind === undefined
+            ? undefined
+            : profileContext.conceptKindLineages.get(conceptKind);
+    };
+    const reading = contextualReading(endpointLineage(definingClaim.subject), endpointLineage(claimRef(definingClaim)), coreKindLabel);
     const nameClaim = ownClaims.find((claim) => claim.predicate === RELATIONSHIP_NAME_PREDICATE);
     const descriptionClaim = ownClaims.find((claim) => claim.predicate === RELATIONSHIP_DESCRIPTION_PREDICATE);
     const modeClaim = ownClaims.find((claim) => claim.predicate === ACCESS_MODE_PREDICATE);
@@ -181,7 +192,10 @@ const projectRelationship = (relationshipId, allClaims, ownClaims, profileContex
         document: definingClaim.source.path,
         kind,
         kindLabel: kindLabelOf(kind),
-        coreKindLabel: kindLabelOf(profileContext.relationshipKindLineages.get(kind)?.[0] ?? kind),
+        coreKindLabel,
+        readingKind: readingKindOf(lineage, coreKindLabel),
+        responsibility: responsibilityLetterOf(lineage, kind),
+        ...(reading === undefined ? {} : { reading }),
         from: definingClaim.subject,
         to: claimRef(definingClaim),
         name: nameClaim === undefined ? null : claimValue(nameClaim),
@@ -210,6 +224,13 @@ const projectRelationship = (relationshipId, allClaims, ownClaims, profileContex
 };
 export function projectGraphForCanvas(graph, profileContext) {
     const claimsBySubject = groupClaimsBySubject(graph.claims);
+    // Each concept's authored kind, for the readings an edge's endpoints decide.
+    const conceptKindOf = new Map();
+    for (const claim of graph.claims) {
+        if (claim.predicate === CONCEPT_KIND_PREDICATE && 'value' in claim.object) {
+            conceptKindOf.set(claim.subject, claim.object.value);
+        }
+    }
     const nodes = [];
     const edges = [];
     for (const subject of graph.subjects) {
@@ -218,7 +239,7 @@ export function projectGraphForCanvas(graph, profileContext) {
             nodes.push(projectConcept(subject.id, ownClaims, profileContext));
         }
         else {
-            edges.push(projectRelationship(subject.id, graph.claims, ownClaims, profileContext));
+            edges.push(projectRelationship(subject.id, graph.claims, ownClaims, profileContext, conceptKindOf));
         }
     }
     nodes.sort(compareById);

package/dist/index.d.ts

@@ -10,6 +10,10 @@ export { constraintExpectsPredicate, reconcileEvidenceReports, type AssertedRela
 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 { buildResponsibilityMatrix, renderResponsibilityMarkdown, type RaciLetter, type ResponsibilityCell, type ResponsibilityCellSource, type ResponsibilityMatrix, type ResponsibilityOptions, type ResponsibilityPerson, type ResponsibilityRow, type ResponsibilitySource, } from './responsibility.js';
+export { PEOPLE_KINDS, RESPONSIBILITY_KINDS, RESPONSIBILITY_PROFILE, responsibilityLetterOf, type ResponsibilityLetter, } from './responsibility-kinds.js';
+export { buildGovernanceLog, renderGovernanceMarkdown, type GovernanceLog, type GovernanceOptions, type GovernanceRef, type GovernanceReview, type GovernanceRow, type GovernanceSource, } from './governance.js';
+export { GOVERNANCE_KINDS, GOVERNANCE_PROFILE, REVIEW_TOPICS, governanceTypeOf, type GovernanceType, } from './governance-kinds.js';
 export type { CompilationCache, CompilationResult, ContextualCompilationResult, IncrementalCompilationResult, ParsedWorkspaceSource, PatternMembership, PatternPortShape, PatternShape, PatternSlotShape, PatternVacancy, PatternWireShape, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
 export { canonicalProjection, evaluateProjection, explainProjection, instanceClosureOf, 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';

package/dist/index.js

@@ -10,6 +10,10 @@ export { constraintExpectsPredicate, reconcileEvidenceReports, } from './reconci
 export { deriveAttestationStaleness } from './attestation-staleness.js';
 export { deriveArtifactCoverage, } from './artifact-coverage.js';
 export { buildRtm, renderRtmMarkdown, } from './rtm.js';
+export { buildResponsibilityMatrix, renderResponsibilityMarkdown, } from './responsibility.js';
+export { PEOPLE_KINDS, RESPONSIBILITY_KINDS, RESPONSIBILITY_PROFILE, responsibilityLetterOf, } from './responsibility-kinds.js';
+export { buildGovernanceLog, renderGovernanceMarkdown, } from './governance.js';
+export { GOVERNANCE_KINDS, GOVERNANCE_PROFILE, REVIEW_TOPICS, governanceTypeOf, } from './governance-kinds.js';
 export { canonicalProjection, evaluateProjection, explainProjection, instanceClosureOf, loadProjection, renderProjectionMarkdown, } from './projection.js';
 export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, } from './adapter-mapping.js';
 export { createFileSystemStore, } from './source-store.js';

package/dist/projection.d.ts

@@ -84,6 +84,11 @@ export interface ProjectionDefinition {
         readonly showLifecycle?: boolean;
         readonly showEvidence?: boolean;
         readonly showOwnership?: boolean;
+        /**
+         * Whether responsibility edges draw on the canvas (#557, ADR 0159). Off
+         * when absent: the subject's properties read the letters either way.
+         */
+        readonly showResponsibility?: boolean;
         /**
          * Whether an unnamed relationship is labelled with its reading - "serves",
          * "served by", "realizes" - or left to its line style and arrowhead

package/dist/projection.js

@@ -71,6 +71,7 @@ export function canonicalProjection(projection) {
                     ...(presentation.showLifecycle === undefined ? {} : { showLifecycle: presentation.showLifecycle }),
                     ...(presentation.showEvidence === undefined ? {} : { showEvidence: presentation.showEvidence }),
                     ...(presentation.showOwnership === undefined ? {} : { showOwnership: presentation.showOwnership }),
+                    ...(presentation.showResponsibility === undefined ? {} : { showResponsibility: presentation.showResponsibility }),
                     ...(presentation.showKindLabels === undefined ? {} : { showKindLabels: presentation.showKindLabels }),
                     ...(presentation.notation === undefined ? {} : { notation: presentation.notation }),
                 },
@@ -637,6 +638,9 @@ export function evaluateProjection(graph, projection, profileContext, membership
                     ...(projection.presentation.showOwnership === undefined
                         ? {}
                         : { showOwnership: projection.presentation.showOwnership }),
+                    ...(projection.presentation.showResponsibility === undefined
+                        ? {}
+                        : { showResponsibility: projection.presentation.showResponsibility }),
                     ...(projection.presentation.showKindLabels === undefined
                         ? {}
                         : { showKindLabels: projection.presentation.showKindLabels }),

package/dist/relationship-reading.d.ts

@@ -13,6 +13,39 @@
  * reads an access.
  */
 export declare const RELATIONSHIP_READING: Readonly<Record<string, string>>;
+/**
+ * Readings for the extension kinds the package ships (ADR 0159), keyed by
+ * their full identity: a profile's subkind of one of these reads the same,
+ * which `readingKindOf` resolves through the lineage.
+ */
+export declare const EXTENSION_READING: Readonly<Record<string, string>>;
+/**
+ * The kind whose reading an edge speaks: the most specific member of the
+ * lineage (ancestor-first) that has a reading of its own, else the core kind.
+ */
+export declare const readingKindOf: (lineage: readonly string[] | undefined, coreKind: string) => string;
+/**
+ * Readings that depend on the SOURCE kind as well as the relationship
+ * (ADR 0160): a risk "threatens" what it influences, where anything else
+ * "influences" it; an assumption "bears on" what it associates. Keyed by
+ * the source kind's identity, then the relationship's core kind, and
+ * resolved through the source's lineage so a profile's subkind of `risk`
+ * threatens too.
+ */
+export declare const SOURCE_CONTEXTUAL_READING: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/**
+ * Readings that depend on the TARGET kind: a work package, deliverable,
+ * constraint or decision "mitigates" the risk it influences. Consulted
+ * after the source table, so a risk that influences another risk still
+ * "threatens" it.
+ */
+export declare const TARGET_CONTEXTUAL_READING: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/**
+ * The reading an edge speaks when its endpoints decide it, or undefined
+ * when the relationship kind alone does (the tables above are consulted
+ * source first). `coreKind` is the relationship's core kind label.
+ */
+export declare const contextualReading: (sourceLineage: readonly string[] | undefined, targetLineage: readonly string[] | undefined, coreKind: string) => string | undefined;
 export declare const REVERSED_READING: Readonly<Record<string, string>>;
 /**
  * `acme/p@1#applicationComponent` reads "application component" and
@@ -25,4 +58,4 @@ export declare const humanizeKind: (kind: string) => string;
  * and gets it only where one exists; a kind with no passive reading keeps its
  * active one, so a caller can pass the layering's answer straight through.
  */
-export declare const relationshipReading: (coreKind: string, reversed?: boolean) => string;
+export declare const relationshipReading: (kind: string, reversed?: boolean) => string;

package/dist/relationship-reading.js

@@ -25,6 +25,68 @@ export const RELATIONSHIP_READING = {
     influence: 'influences',
     association: 'is associated with',
 };
+/**
+ * Readings for the extension kinds the package ships (ADR 0159), keyed by
+ * their full identity: a profile's subkind of one of these reads the same,
+ * which `readingKindOf` resolves through the lineage.
+ */
+export const EXTENSION_READING = {
+    'yarramate/policy@0.2#responsible': 'is responsible for',
+    'yarramate/policy@0.2#consulted': 'is consulted on',
+    'yarramate/policy@0.2#informed': 'is informed of',
+};
+/**
+ * The kind whose reading an edge speaks: the most specific member of the
+ * lineage (ancestor-first) that has a reading of its own, else the core kind.
+ */
+export const readingKindOf = (lineage, coreKind) => {
+    if (lineage !== undefined) {
+        for (let index = lineage.length - 1; index >= 0; index -= 1) {
+            const member = lineage[index];
+            if (EXTENSION_READING[member] !== undefined)
+                return member;
+        }
+    }
+    return coreKind;
+};
+/**
+ * Readings that depend on the SOURCE kind as well as the relationship
+ * (ADR 0160): a risk "threatens" what it influences, where anything else
+ * "influences" it; an assumption "bears on" what it associates. Keyed by
+ * the source kind's identity, then the relationship's core kind, and
+ * resolved through the source's lineage so a profile's subkind of `risk`
+ * threatens too.
+ */
+export const SOURCE_CONTEXTUAL_READING = {
+    'yarramate/policy@0.3#risk': { influence: 'threatens' },
+    'yarramate/policy@0.3#assumption': { association: 'bears on' },
+};
+/**
+ * Readings that depend on the TARGET kind: a work package, deliverable,
+ * constraint or decision "mitigates" the risk it influences. Consulted
+ * after the source table, so a risk that influences another risk still
+ * "threatens" it.
+ */
+export const TARGET_CONTEXTUAL_READING = {
+    'yarramate/policy@0.3#risk': { influence: 'mitigates' },
+};
+const lookupContextual = (table, lineage, coreKind) => {
+    if (lineage === undefined)
+        return undefined;
+    for (let index = lineage.length - 1; index >= 0; index -= 1) {
+        const phrase = table[lineage[index]]?.[coreKind];
+        if (phrase !== undefined)
+            return phrase;
+    }
+    return undefined;
+};
+/**
+ * The reading an edge speaks when its endpoints decide it, or undefined
+ * when the relationship kind alone does (the tables above are consulted
+ * source first). `coreKind` is the relationship's core kind label.
+ */
+export const contextualReading = (sourceLineage, targetLineage, coreKind) => lookupContextual(SOURCE_CONTEXTUAL_READING, sourceLineage, coreKind) ??
+    lookupContextual(TARGET_CONTEXTUAL_READING, targetLineage, coreKind);
 export const REVERSED_READING = {
     serving: 'served by',
     realization: 'realized by',
@@ -47,6 +109,7 @@ export const humanizeKind = (kind) => {
  * and gets it only where one exists; a kind with no passive reading keeps its
  * active one, so a caller can pass the layering's answer straight through.
  */
-export const relationshipReading = (coreKind, reversed = false) => (reversed ? REVERSED_READING[coreKind] : undefined) ??
-    RELATIONSHIP_READING[coreKind] ??
-    humanizeKind(coreKind);
+export const relationshipReading = (kind, reversed = false) => (reversed ? REVERSED_READING[kind] : undefined) ??
+    EXTENSION_READING[kind] ??
+    RELATIONSHIP_READING[kind] ??
+    humanizeKind(kind);

package/dist/responsibility-kinds.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The three responsibility relationship kinds and the letters they carry
+ * (#557, ADR 0159): `yarramate/policy@0.2#responsible`, `#consulted` and
+ * `#informed`, each a subkind of core `association` from a person to the
+ * subject they answer for. Accountable is not a kind: it is the existing
+ * `yarramate/ownership/owner` claim. Pure, so the canvas projection, the
+ * matrix builder and the editor read one table.
+ */
+export declare const RESPONSIBILITY_PROFILE = "yarramate/policy@0.2";
+export type ResponsibilityLetter = 'R' | 'C' | 'I';
+export declare const RESPONSIBILITY_KINDS: Readonly<Record<'responsible' | 'consulted' | 'informed', string>>;
+export declare const RESPONSIBILITY_LETTERS: Readonly<Record<string, ResponsibilityLetter>>;
+export declare const OWNER_PREDICATE = "yarramate/ownership/owner";
+/** The core kinds a person subject may be, ancestors of any profile's own. */
+export declare const PEOPLE_KINDS: readonly string[];
+/**
+ * The letter a relationship kind carries, read through its lineage
+ * (ancestor-first) so a profile's own subkind of `responsible` is still an
+ * R; `null` for every other kind.
+ */
+export declare const responsibilityLetterOf: (lineage: readonly string[] | undefined, kind: string) => ResponsibilityLetter | null;
+/** Whether a concept kind is a person, read through its lineage. */
+export declare const isPeopleKind: (lineage: readonly string[] | undefined, kind: string) => boolean;

package/dist/responsibility-kinds.js

@@ -0,0 +1,43 @@
+/**
+ * The three responsibility relationship kinds and the letters they carry
+ * (#557, ADR 0159): `yarramate/policy@0.2#responsible`, `#consulted` and
+ * `#informed`, each a subkind of core `association` from a person to the
+ * subject they answer for. Accountable is not a kind: it is the existing
+ * `yarramate/ownership/owner` claim. Pure, so the canvas projection, the
+ * matrix builder and the editor read one table.
+ */
+export const RESPONSIBILITY_PROFILE = 'yarramate/policy@0.2';
+export const RESPONSIBILITY_KINDS = {
+    responsible: `${RESPONSIBILITY_PROFILE}#responsible`,
+    consulted: `${RESPONSIBILITY_PROFILE}#consulted`,
+    informed: `${RESPONSIBILITY_PROFILE}#informed`,
+};
+export const RESPONSIBILITY_LETTERS = {
+    [RESPONSIBILITY_KINDS.responsible]: 'R',
+    [RESPONSIBILITY_KINDS.consulted]: 'C',
+    [RESPONSIBILITY_KINDS.informed]: 'I',
+};
+export const OWNER_PREDICATE = 'yarramate/ownership/owner';
+/** The core kinds a person subject may be, ancestors of any profile's own. */
+export const PEOPLE_KINDS = [
+    'yarramate/core@0.1#businessActor',
+    'yarramate/core@0.1#businessRole',
+    'yarramate/core@0.1#businessCollaboration',
+    'yarramate/core@0.1#stakeholder',
+];
+/**
+ * The letter a relationship kind carries, read through its lineage
+ * (ancestor-first) so a profile's own subkind of `responsible` is still an
+ * R; `null` for every other kind.
+ */
+export const responsibilityLetterOf = (lineage, kind) => {
+    for (const member of lineage ?? [kind]) {
+        const letter = RESPONSIBILITY_LETTERS[member];
+        if (letter !== undefined)
+            return letter;
+    }
+    return RESPONSIBILITY_LETTERS[kind] ?? null;
+};
+/** Whether a concept kind is a person, read through its lineage. */
+export const isPeopleKind = (lineage, kind) => (lineage ?? [kind]).some((member) => PEOPLE_KINDS.includes(member)) ||
+    PEOPLE_KINDS.includes(kind);