yarramate 1.35.0 → 1.36.0

package/dist/ask-command.js

@@ -605,6 +605,12 @@ export function runAskCommand(options, cwd) {
                 topic,
                 seeds: resolution.seeds,
                 matched: resolution.matched,
+                // The same document the tools entry emits, field for field (ADR 0156),
+                // and `test/tools-entry.test.ts` compares them. The ranked candidates
+                // ride on both (#569).
+                ...(resolution.addressing === 'free-text'
+                    ? { candidates: resolution.candidates }
+                    : {}),
                 ...(neighbourhood === undefined ? {} : { neighbourhood }),
                 result: evaluated,
             };

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export type { LifecycleStatus, ProjectionDefinition, ProjectionLoadResult, Proje
 export { createFileSystemStore, type PendingWrite, type SourceStore, type StoredSource, type WriteConflict, type WriteOutcome, } from './source-store.js';
 export { applyOperations, landOperations, posixDirectoryOf, type ApplyInput, type ApplyOutcome, } from './apply-command.js';
 export { connectableKinds, draftRelationship, proposeRelationshipId, stagedSubjectIds, } from './relationship-drafting.js';
+export { conventionalRelationshipKind, CONVENTION_RULES, type RelationshipConvention, } from './relationship-convention.js';
 export { draftConcept, proposeConceptId } from './concept-drafting.js';
 export { deletionBlockers, describeDeletion, draftDeletion, type DeletionBlocker, } from './deletion-drafting.js';
 export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, conditionInput, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, type CatalogueEvidenceObservation, type CataloguePatternMembership, type CataloguePatternVacancy, type CatalogueInput, 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

@@ -19,6 +19,7 @@ export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, }
 export { createFileSystemStore, } from './source-store.js';
 export { applyOperations, landOperations, posixDirectoryOf, } from './apply-command.js';
 export { connectableKinds, draftRelationship, proposeRelationshipId, stagedSubjectIds, } from './relationship-drafting.js';
+export { conventionalRelationshipKind, CONVENTION_RULES, } from './relationship-convention.js';
 export { draftConcept, proposeConceptId } from './concept-drafting.js';
 export { deletionBlockers, describeDeletion, draftDeletion, } from './deletion-drafting.js';
 export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, conditionInput, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';

package/dist/relationship-convention.d.ts

@@ -0,0 +1,25 @@
+import { type RelationshipKind } from './profile.js';
+/**
+ * One convention, as a named rule. The name is carried into the answer so a
+ * caller can say WHY, which is the difference between guidance a reviewer can
+ * argue with and a number they have to take on faith.
+ */
+export interface RelationshipConvention {
+    readonly kind: RelationshipKind;
+    readonly rule: string;
+    readonly because: string;
+}
+/**
+ * The kind practice expects from `from` to `to`, or `null` where practice has
+ * no expectation.
+ *
+ * Never contradicts the table: an answer is returned only when the table also
+ * permits it, so guidance can never point at an edge `check` would refuse.
+ */
+export declare const conventionalRelationshipKind: (from: string, to: string) => RelationshipConvention | null;
+/** Every rule's name and sentence, for documentation and for the test that checks them. */
+export declare const CONVENTION_RULES: readonly {
+    readonly name: string;
+    readonly kind: RelationshipKind;
+    readonly because: string;
+}[];

package/dist/relationship-convention.js

@@ -0,0 +1,176 @@
+import { conceptKinds, } from './profile.js';
+import { isCoreConceptKindId, permittedRelationshipKinds, } from './relationship-matrix.js';
+/**
+ * The relationship kind ArchiMate practice expects for a pair of core kinds,
+ * where practice has an expectation at all (#571).
+ *
+ * The relationship table is a PERMISSION table. It answers "may I draw this",
+ * and for an application component pointing at an application function it
+ * answers yes six times. Practice is much narrower: across this repository's
+ * own model and the ApertureX reference, 970 relationships over 72 core-kind
+ * pairs, the author used exactly one kind for 34 of the pairs the table lets
+ * them choose among, and used `assignment` for that particular pair 87 times
+ * out of 88. The engine knew the permission and never said the convention, so
+ * every palette offered six, every agent guessed, and a reviewer could never
+ * be told "this pair is usually X and yours is Y".
+ *
+ * ## Where these answers come from
+ *
+ * They are read off ArchiMate's own definitions of the relationships, NOT
+ * fitted to the two records. That direction matters. Both records agree, for
+ * instance, that a business actor points at a constraint with `association`,
+ * 87 times out of 87 - but that is one adopter's house convention for
+ * recording sign-off, not a rule of the language, and blessing it here would
+ * have told every other adopter their own style was wrong. The records are
+ * used as a CHECK: `test/relationship-convention.test.ts` asserts that every
+ * convention declared here matches real practice on a record that has enough
+ * of that pair to have a habit, and prints the disagreements when it does not.
+ *
+ * ## Silence is an answer
+ *
+ * `conventionalRelationshipKind` returns `null` far more often than not, and
+ * that is the point. A pair with no entry here is a pair where the language
+ * genuinely permits several readings and the author must choose: an artifact
+ * pointing at an application function is `realization` 41 times and
+ * `association` 16, a capability pointing at a goal splits evenly, and two
+ * application functions relate by composition, triggering, flow or serving
+ * depending on what the author means. Declaring a convention there would
+ * manufacture confidence the language does not have.
+ *
+ * Nothing here is a rule the compiler enforces. A permitted kind stays
+ * permitted; `check` never reads this file. It is guidance, offered to a
+ * palette, an agent, or a reviewer, and it says nothing when it has nothing
+ * to say.
+ */
+const KIND_META = new Map(conceptKinds.map((kind) => [kind.id, { layer: kind.layer, aspect: kind.aspect }]));
+/** The three service elements: external behaviour a layer offers outward. */
+const SERVICES = new Set([
+    'businessService',
+    'applicationService',
+    'technologyService',
+]);
+/** The three interface elements: the point at which a service is offered. */
+const INTERFACES = new Set([
+    'businessInterface',
+    'applicationInterface',
+    'technologyInterface',
+]);
+const isService = (kind) => SERVICES.has(kind);
+const isInterface = (kind) => INTERFACES.has(kind);
+const isInternalBehaviour = (kind) => KIND_META.get(kind)?.aspect === 'behavior' && !isService(kind);
+/**
+ * Ordered; the first rule that matches answers, and order is load-bearing
+ * twice. A service touching passive structure is `access` before it is
+ * anything else, because a service is behaviour first and an offering second.
+ * And an interface pointing at a service of its own layer is `assignment`,
+ * the interface exposing that service, while an interface pointing at
+ * anything else is `serving`. Both times the specific rule comes first.
+ */
+const RULES = [
+    {
+        name: 'behaviour-uses-data',
+        because: 'behaviour reads, writes or creates the passive structure it touches',
+        kind: 'access',
+        when: (from, to, f, t) => t.aspect === 'passive-structure' &&
+            (isInternalBehaviour(from) || isService(from)) &&
+            // An artifact is passive structure in the technology layer, and
+            // behaviour pointing at one is not "reading a file": both records write
+            // `association` there far more often than `access`. Left to the author.
+            to !== 'artifact',
+    },
+    {
+        name: 'interface-exposes-service',
+        because: 'an interface is assigned to the service it exposes, not to the behaviour that uses it',
+        kind: 'assignment',
+        when: (from, to, f, t) => isInterface(from) && isService(to) && f.layer === t.layer,
+    },
+    {
+        name: 'service-is-offered-outward',
+        because: 'a service is made available to whoever uses it',
+        kind: 'serving',
+        when: (from, _to, _f, t) => (isService(from) || isInterface(from)) &&
+            (t.aspect === 'active-structure' || t.aspect === 'behavior'),
+    },
+    {
+        name: 'grouping-collects-members',
+        because: 'a grouping aggregates what it collects; the members exist without it',
+        kind: 'aggregation',
+        when: (from) => from === 'grouping',
+    },
+    {
+        name: 'artifact-realizes-what-it-implements',
+        because: 'an artifact is the concrete file or deployable that fulfils the thing it stands for',
+        kind: 'realization',
+        when: (from, to, _f, t) => from === 'artifact' &&
+            (t.aspect === 'active-structure' || t.aspect === 'passive-structure') &&
+            to !== 'artifact',
+    },
+    {
+        name: 'active-structure-performs-behaviour',
+        because: 'an active structure element is assigned to the internal behaviour it performs',
+        kind: 'assignment',
+        when: (from, to, f, t) => f.aspect === 'active-structure' &&
+            isInternalBehaviour(to) &&
+            f.layer === t.layer,
+    },
+    {
+        name: 'internal-realizes-service',
+        because: 'the internal element is the concrete thing that fulfils the service its layer offers',
+        kind: 'realization',
+        when: (from, to, f, t) => isService(to) &&
+            f.layer === t.layer &&
+            (f.aspect === 'active-structure' || isInternalBehaviour(from)) &&
+            !isInterface(from),
+    },
+    {
+        name: 'technology-serves-application',
+        // The least certain rule here. The authoring reference lists this pair as
+        // "realizes or serves", two readings: realization when the node IS the
+        // implementation, serving when it hosts one. Both records are unanimous
+        // for `serving`, ten times in ten, so that is what is offered - and the
+        // other reading stays one click away, as every non-conventional kind does.
+        because: 'a technology element is not part of the application it runs; it serves it',
+        kind: 'serving',
+        when: (_from, _to, f, t) => f.layer === 'technology' &&
+            t.layer === 'application' &&
+            (t.aspect === 'active-structure' || t.aspect === 'behavior'),
+    },
+];
+const cache = new Map();
+/**
+ * The kind practice expects from `from` to `to`, or `null` where practice has
+ * no expectation.
+ *
+ * Never contradicts the table: an answer is returned only when the table also
+ * permits it, so guidance can never point at an edge `check` would refuse.
+ */
+export const conventionalRelationshipKind = (from, to) => {
+    const key = `${from}>${to}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const answer = compute(from, to);
+    cache.set(key, answer);
+    return answer;
+};
+const compute = (from, to) => {
+    if (!isCoreConceptKindId(from) || !isCoreConceptKindId(to))
+        return null;
+    const fromMeta = KIND_META.get(from);
+    const toMeta = KIND_META.get(to);
+    if (fromMeta === undefined || toMeta === undefined)
+        return null;
+    for (const rule of RULES) {
+        if (!rule.when(from, to, fromMeta, toMeta))
+            continue;
+        // Guidance that the table forbids would be worse than none: it would send
+        // an author at an edge `check` refuses. A rule that lands outside the
+        // permission is treated as having no answer for this pair.
+        if (!permittedRelationshipKinds(from, to).has(rule.kind))
+            return null;
+        return { kind: rule.kind, rule: rule.name, because: rule.because };
+    }
+    return null;
+};
+/** Every rule's name and sentence, for documentation and for the test that checks them. */
+export const CONVENTION_RULES = RULES.map(({ name, kind, because }) => ({ name, kind, because }));

package/dist/tools/ask.d.ts

@@ -93,6 +93,12 @@ export type AskSlice = AskResultBase & {
     readonly topic?: string;
     readonly seeds?: readonly string[];
     readonly matched?: number;
+    /**
+     * Every concept a term touched, ranked, present on a free-text slice (#569).
+     * The seeds are the first few of these; a caller with a judgment to spend
+     * reorders the list and asks again with `subjects` addressing.
+     */
+    readonly candidates?: readonly SeedCandidate[];
     readonly changed?: {
         readonly range: string;
         readonly concepts: readonly string[];
@@ -172,12 +178,46 @@ export type AskKinds = AskResultBase & {
 export type AskResult = AskOrientation | AskRoster | AskSlice | AskAdvice | AskWhere | AskNext | AskOpen | AskCompare | AskKinds;
 export declare const claimValue: (claims: readonly GraphClaim[], subject: string, predicate: string) => string | undefined;
 export declare const conceptEntries: (graph: SemanticGraph) => readonly ConceptEntry[];
+/**
+ * How many ranked candidates `resolveSeeds` hands back beside the seeds. Thirty
+ * is the shortlist the #569 measurement reranked, and it is a cap rather than a
+ * target: most queries match fewer.
+ */
+export declare const candidateLimit = 30;
+export interface SeedCandidate {
+    readonly id: string;
+    /** How many distinct query terms this concept's text contains. The whole of the ranking. */
+    readonly terms: number;
+}
 export interface SeedResolution {
     readonly addressing: 'free-text' | 'subjects';
     readonly seeds: readonly string[];
     readonly matched: number;
+    /**
+     * Every concept a term touched, ranked, not just the handful that seeded the
+     * slice (#569).
+     *
+     * The term count finds the right subject and then buries it. Measured on the
+     * Halcyon showcase against 32 questions written by someone other than the
+     * author: the subject the asker meant was inside this list 87% of the time
+     * and was the FIRST seed only 43% of the time. Retrieval was not the
+     * weakness; ordering was.
+     *
+     * The engine cannot fix that on its own, because deciding which of several
+     * term-matching concepts actually answers a question is a judgment and this
+     * is a deterministic CLI (ADR 0059). So it hands the list over instead. A
+     * caller with a judgment to spend - an agent, a host with a decision model -
+     * reorders these and calls back with `subjects` addressing, which already
+     * exists. A caller with none uses `seeds` exactly as before.
+     *
+     * Capped, so a one-word query against a large workspace cannot return the
+     * whole record: `candidateLimit`, which a caller may raise.
+     */
+    readonly candidates: readonly SeedCandidate[];
 }
-export declare const resolveSeeds: (terms: readonly string[], entries: readonly ConceptEntry[]) => SeedResolution;
+export declare const resolveSeeds: (terms: readonly string[], entries: readonly ConceptEntry[], options?: {
+    readonly candidates?: number;
+}) => SeedResolution;
 export declare const defaultNeighbourCap = 12;
 export interface SliceEvaluation {
     readonly result: ProjectionResult;

package/dist/tools/ask.js

@@ -48,6 +48,12 @@ export const conceptEntries = (graph) => {
         .sort((left, right) => left.id.localeCompare(right.id));
 };
 const seedLimit = 5;
+/**
+ * How many ranked candidates `resolveSeeds` hands back beside the seeds. Thirty
+ * is the shortlist the #569 measurement reranked, and it is a cap rather than a
+ * target: most queries match fewer.
+ */
+export const candidateLimit = 30;
 // Free text is the default addressing mode: terms match concept ids,
 // names, alternative labels, and descriptions; matching concepts seed the
 // slice. Exact subject ids short-circuit to precise addressing: the
@@ -58,11 +64,19 @@ const seedLimit = 5;
 // aliases would be the one graded field in an otherwise ungraded match,
 // and the whole point of recording the team's actual word for a subject is
 // that it should find it.
-export const resolveSeeds = (terms, entries) => {
+export const resolveSeeds = (terms, entries, options = {}) => {
     const known = new Set(entries.map(({ id }) => id));
     const unique = [...new Set(terms)];
     if (unique.every((term) => known.has(term))) {
-        return { addressing: 'subjects', seeds: unique, matched: unique.length };
+        // Precise addressing named the subjects outright. There is nothing to
+        // rank, so the candidates ARE the seeds: a caller reranking whatever it is
+        // given never has to ask which addressing produced them.
+        return {
+            addressing: 'subjects',
+            seeds: unique,
+            matched: unique.length,
+            candidates: unique.map((id) => ({ id, terms: 1 })),
+        };
     }
     const lowered = [
         ...new Set(terms
@@ -84,6 +98,9 @@ export const resolveSeeds = (terms, entries) => {
         addressing: 'free-text',
         seeds: scored.slice(0, seedLimit).map(({ id }) => id),
         matched: scored.length,
+        candidates: scored
+            .slice(0, Math.max(seedLimit, options.candidates ?? candidateLimit))
+            .map(({ id, score }) => ({ id, terms: score })),
     };
 };
 // On a dense graph, hub seeds make 1-hop connected expansion reach most
@@ -461,6 +478,12 @@ export const askSlice = (workspace, query, options = {}) => guarded(() => {
             topic,
             seeds: resolution.seeds,
             matched: resolution.matched,
+            // Everything a term touched, ranked, so an agent can reorder the list
+            // and ask again with `subjects` rather than take the term count's word
+            // for which five mattered (#569). Only where there was ranking to do.
+            ...(resolution.addressing === 'free-text'
+                ? { candidates: resolution.candidates }
+                : {}),
             ...(neighbourhood === undefined ? {} : { neighbourhood }),
             result: evaluated,
             rendered: renderSlice(evaluated, compiled, options.budget),

package/dist/tools-entry.d.ts

@@ -9,7 +9,7 @@
  */
 export { SHIPPED_CATALOGUE, MissingSourceError, type ToolWorkspace, type ToolResult, type ToolFailure, } from './tools/workspace.js';
 export { designStep, designStepDetailed, type DesignStep, type DesignStepDetailed, type DesignStepOptions, type DesignStepResult, } from './tools/design.js';
-export { askKinds, askNext, askOpen, askOrientation, askRoster, askSlice, conceptEntries, resolveSeeds, sliceProjection, type AskAdvice, type AskCompare, type AskKinds, type AskNext, type AskOpen, type AskOrientation, type AskResult, type AskResultBase, type AskRoster, type AskSlice, type AskWhere, type ConceptEntry, type NeighbourhoodOmission, type OpenQuestionRef, type RelationshipKindSummary, type RelationshipMatrixSummary, type RosterOptions, type SliceOptions, type SliceQuery, } from './tools/ask.js';
+export { askKinds, askNext, askOpen, askOrientation, askRoster, askSlice, candidateLimit, conceptEntries, resolveSeeds, type SeedCandidate, type SeedResolution, sliceProjection, type AskAdvice, type AskCompare, type AskKinds, type AskNext, type AskOpen, type AskOrientation, type AskResult, type AskResultBase, type AskRoster, type AskSlice, type AskWhere, type ConceptEntry, type NeighbourhoodOmission, type OpenQuestionRef, type RelationshipKindSummary, type RelationshipMatrixSummary, type RosterOptions, type SliceOptions, type SliceQuery, } from './tools/ask.js';
 export { checkSources, checkWorkspace, type CheckCounts, type CheckEvaluation, type CheckInput, type CheckOptions, type CheckResult, } from './tools/check.js';
 export { applyBatch, type ApplyResult, type OperationsInput, } from './tools/apply.js';
 export { exportBriefs, exportGraph, exportLikeC4, exportGovernance, exportMarkdown, exportResponsibility, exportRtm, exportWorkbook, type BriefsOptions, type ExportedBriefs, } from './tools/export.js';

package/dist/tools-entry.js

@@ -9,7 +9,7 @@
  */
 export { SHIPPED_CATALOGUE, MissingSourceError, } from './tools/workspace.js';
 export { designStep, designStepDetailed, } from './tools/design.js';
-export { askKinds, askNext, askOpen, askOrientation, askRoster, askSlice, conceptEntries, resolveSeeds, sliceProjection, } from './tools/ask.js';
+export { askKinds, askNext, askOpen, askOrientation, askRoster, askSlice, candidateLimit, conceptEntries, resolveSeeds, sliceProjection, } from './tools/ask.js';
 export { checkSources, checkWorkspace, } from './tools/check.js';
 export { applyBatch, } from './tools/apply.js';
 export { exportBriefs, exportGraph, exportLikeC4, exportGovernance, exportMarkdown, exportResponsibility, exportRtm, exportWorkbook, } from './tools/export.js';