yarramate 1.18.0 → 1.19.0

package/dist/apply-command.js

@@ -27,6 +27,10 @@ import { validateOperations } from './schema-validation.js';
 // asserted — it never silently shrinks anything.
 const SCALAR_CONCEPT_FIELDS = ['kind', 'name', 'description', 'status', 'owner'];
 const LIST_CONCEPT_FIELDS = ['aka', 'constraints', 'references', 'presentIn', 'attestations', 'distinctFrom', 'supersedes'];
+// The third category (#448). `parts` is the first MAP-valued concept field:
+// it neither replaces like a scalar nor appends like a list, it merges by
+// slot. See `mergeMapField`.
+const MAP_CONCEPT_FIELDS = ['parts'];
 const SCALAR_RELATIONSHIP_FIELDS = ['kind', 'from', 'to', 'name', 'description', 'status', 'mode', 'content'];
 const LIST_RELATIONSHIP_FIELDS = ['references', 'presentIn'];
 // An overlay entry's address is the pair (target, key); everything else it
@@ -233,6 +237,66 @@ const appendListField = (source, map, key, additions) => {
     }
     return spliceValue(source, start, valueEnd, `\n${sequenceEntries(merged, indent + 2)}`);
 };
+// Merge a MAP-valued field by key (#448). A named slot rebinds, an unnamed one
+// is untouched: ADR 0062's convention, where a write enriches what is there and
+// never silently shrinks it. Replacing the whole map would unbind slots the
+// operation never mentioned, which is exactly the silent shrinking that rule
+// forbids.
+//
+// The per-slot work is `setScalarField` against the NESTED map, because
+// inserting or replacing one key of a mapping is what that already does. The
+// source is re-parsed between slots for the same reason the caller re-parses
+// between fields: every splice moves the offsets after it.
+const mergeMapField = (source, locateMap, key, additions) => {
+    const entries = Object.entries(additions);
+    if (entries.length === 0)
+        return source;
+    const map = locateMap(source);
+    if (map === undefined)
+        return source;
+    if (map.flow) {
+        return rewriteFlowItem(source, map, (fields) => ({
+            ...fields,
+            [key]: {
+                ...(fields[key] ?? {}),
+                ...additions,
+            },
+        }));
+    }
+    const existing = nestedMap(map, key);
+    if (existing === undefined) {
+        const pair = pairFor(map, key);
+        const indent = fieldIndentOf(source, map);
+        const rendered = entries
+            .map(([slot, value]) => `${' '.repeat(indent + 2)}${slot}: ${valueText(value)}`)
+            .join('\n');
+        // A `parts` that exists but is not a block mapping (flow, or empty) is
+        // replaced wholesale rather than merged into: there is nothing to preserve
+        // that the entries do not already carry.
+        if (pair !== undefined) {
+            const held = isMap(pair.value)
+                ? pair.value.toJSON()
+                : {};
+            const merged = { ...held, ...additions };
+            const [start, valueEnd] = nodeRange(pair.value);
+            return spliceValue(source, start, valueEnd, `\n${Object.entries(merged)
+                .map(([slot, value]) => `${' '.repeat(indent + 2)}${slot}: ${valueText(value)}`)
+                .join('\n')}`);
+        }
+        return insertBlock(source, itemFieldInsertAt(source, map), `${' '.repeat(indent)}${key}:\n${rendered}\n`);
+    }
+    let updated = source;
+    for (const [slot, value] of entries) {
+        const host = locateMap(updated);
+        if (host === undefined)
+            break;
+        const target = nestedMap(host, key);
+        if (target === undefined)
+            break;
+        updated = setScalarField(updated, target, slot, value);
+    }
+    return updated;
+};
 // Retraction (#115): delete the field's whole entry, from the start of its
 // key line through the end of its value's last line. A flow item is
 // rewritten instead — line-based deletion there would take the whole item
@@ -602,6 +666,14 @@ export const applyOperations = (input) => {
                     continue;
                 source = appendListField(source, itemMap(source, collection, id).map, key, additions);
             }
+            if (operation.op === 'update-concept') {
+                for (const key of MAP_CONCEPT_FIELDS) {
+                    const additions = payload[key];
+                    if (additions === undefined)
+                        continue;
+                    source = mergeMapField(source, (current) => itemMap(current, collection, id)?.map, key, additions);
+                }
+            }
             for (const key of removals) {
                 const removed = removeField(source, itemMap(source, collection, id).map, key);
                 if (removed === undefined) {

package/dist/ask-command.js

@@ -735,6 +735,7 @@ export function runAskCommand(options, cwd) {
                     ? {}
                     : { catalogues: report.catalogues }),
                 semantics: report.semantics,
+                inputs: report.inputs,
                 summary: report.summary,
                 waves: report.waves,
             };

package/dist/compiler.js

@@ -689,6 +689,7 @@ function compileWorkspaceResolved(parsed) {
                     name: slot,
                     kindIdentity: kind.identity,
                     required: part.required === true,
+                    kindMatching: part.kindMatching === 'descendants' ? 'descendants' : 'exact',
                 });
             }
             if (!slotsOk)
@@ -2130,13 +2131,27 @@ function compileWorkspaceResolved(parsed) {
                 }
                 boundTo.set(target, slot);
                 const actual = kindOfSubject.get(target);
-                if (actual !== slotShape.kindIdentity) {
+                // `descendants` admits any kind whose lineage includes the slot kind
+                // (#449), which is what the word already means on catalogue selectors
+                // and on `missing-relationship`. It fails safe: minted wiring is
+                // checked against the relationship table using the ACTUAL bound
+                // subjects' kinds, so a descendant that is not a legal endpoint is
+                // still refused by the ordinary relationship check rather than
+                // slipping through on the pattern's authority.
+                const admitted = actual === slotShape.kindIdentity ||
+                    (slotShape.kindMatching === 'descendants' &&
+                        actual !== undefined &&
+                        (conceptKindByIdentity.get(actual)?.lineage ?? []).includes(slotShape.kindIdentity));
+                if (!admitted) {
                     diagnostics.push({
                         severity: 'error',
                         code: 'YM417',
                         message: `Part "${slot}" of "${instance}" binds "${target}", which is ` +
                             `"${actual ?? 'not a concept'}"; the pattern declares this part ` +
-                            `"${slotShape.kindIdentity}"`,
+                            `"${slotShape.kindIdentity}"` +
+                            (slotShape.kindMatching === 'descendants'
+                                ? ' or a kind descending from it'
+                                : ''),
                         path: where.path,
                         pointer: where.pointer,
                         line: where.line,

package/dist/index.d.ts

@@ -19,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 CataloguePatternMembership, type CataloguePatternVacancy, 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, 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

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

package/dist/interrogate-command.d.ts

@@ -347,9 +347,69 @@ export interface InterrogationReport {
     readonly catalogues?: readonly string[];
     /** {@link INTERROGATION_SEMANTICS_VERSION} at the time of evaluation. */
     readonly semantics: string;
+    /**
+     * Which optional inputs the evaluation was GIVEN (#450). A condition that
+     * reads one it was not given stays quiet, which is right - the caller did
+     * not look - but a quiet condition and a satisfied one are both
+     * `open: false`, so without this a host summing closed questions reads
+     * "nothing was supplied" as "nothing is missing". For an absence question
+     * like `missing-part` the silent direction is "the interview is satisfied",
+     * which stops an agent working rather than making it do redundant work.
+     *
+     * `asked: false` (#375, ADR 0132) says the same thing one level up, for a
+     * selector that matched no subject. This is the level below it, for inputs.
+     * It is a separate field rather than a third `asked` value because `asked`
+     * is published and because "no subject" and "no data" are different facts a
+     * host acts on differently.
+     *
+     * REQUIRED, on ADR 0110's reasoning for `trigger`: the fact exists for every
+     * report, so an optional field would force every consumer to write an
+     * absent-case branch for a case that cannot occur. Every key is present on
+     * every report, so a host reads a boolean rather than testing for presence.
+     *
+     * To find which QUESTIONS could not be evaluated, join a question's echoed
+     * `trigger` to this map through {@link conditionInput}.
+     */
+    readonly inputs: Readonly<Record<CatalogueInput, boolean>>;
     readonly summary: InterrogationSummary;
     readonly waves: readonly ReportWave[];
 }
+/**
+ * What a condition needs in order to mean anything: a subject, or only the
+ * workspace (#400).
+ *
+ * A wave gate evaluates with NO subject, and the catalogue schema offered the
+ * whole vocabulary in that position, so a subject-scope condition in
+ * `opensWhen` produced a wave that silently never opened (`has-linkage`,
+ * `near-duplicate`, `fills-pattern-slot`) or a gate that was silently inert
+ * (`missing-linkage`, `isolated`, `missing-claim`, `missing-constraint`) —
+ * measured, both halves. Neither was refused. That is the same failure
+ * `YM914` already refuses from a different cause: a gate nothing can satisfy
+ * is indistinguishable from a gate that is merely unmet.
+ *
+ * This is a `Record` over the union's discriminant rather than a list of the
+ * workspace-scope names, and that is the point. An allowlist cannot fail for
+ * the author who wrote it (CONTRIBUTING.md's ninth rule), so a new condition
+ * must not be able to arrive and be quietly absent from a gate check. Here it
+ * cannot: adding a member to `CatalogueCondition` is a TYPECHECK ERROR until
+ * its scope is declared, so the compiler asks the question rather than this
+ * table remembering the answer.
+ */
+/**
+ * An optional input to {@link evaluateCatalogue} that some condition needs in
+ * order to mean anything (#450).
+ *
+ * `catalogues` is not one: it names contributing catalogues in the report and
+ * no condition reads it, so withholding it cannot silence anything.
+ */
+export type CatalogueInput = 'profileContext' | 'evidence' | 'patternMemberships' | 'patternVacancies';
+/**
+ * The input this condition goes quiet without, if any (#450). Published beside
+ * {@link conditionScope} so a host can join a report's echoed trigger to its
+ * `inputs` and answer the question it actually has: which of the questions in
+ * front of me could not be evaluated?
+ */
+export declare const conditionInput: (condition: CatalogueCondition) => CatalogueInput | undefined;
 export declare const conditionScope: (condition: CatalogueCondition) => 'workspace' | 'subject';
 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, evidence?: readonly CatalogueEvidenceObservation[], 

package/dist/interrogate-command.js

@@ -232,26 +232,59 @@ const linkageHits = (index, condition, subjectId, profileContext) => {
     });
 };
 /**
- * What a condition needs in order to mean anything: a subject, or only the
- * workspace (#400).
+ * Which optional input each condition goes QUIET without, or `undefined` for
+ * one that needs none (#450).
  *
- * A wave gate evaluates with NO subject, and the catalogue schema offered the
- * whole vocabulary in that position, so a subject-scope condition in
- * `opensWhen` produced a wave that silently never opened (`has-linkage`,
- * `near-duplicate`, `fills-pattern-slot`) or a gate that was silently inert
- * (`missing-linkage`, `isolated`, `missing-claim`, `missing-constraint`) —
- * measured, both halves. Neither was refused. That is the same failure
- * `YM914` already refuses from a different cause: a gate nothing can satisfy
- * is indistinguishable from a gate that is merely unmet.
+ * A condition that reads an input it was not given returns `false`, which is
+ * correct - the caller did not look, so the answer is unknown rather than
+ * negative - but byte-identical to a satisfied condition. This table is what
+ * lets a report say which of the two happened.
  *
- * This is a `Record` over the union's discriminant rather than a list of the
- * workspace-scope names, and that is the point. An allowlist cannot fail for
- * the author who wrote it (CONTRIBUTING.md's ninth rule), so a new condition
- * must not be able to arrive and be quietly absent from a gate check. Here it
- * cannot: adding a member to `CatalogueCondition` is a TYPECHECK ERROR until
- * its scope is declared, so the compiler asks the question rather than this
- * table remembering the answer.
+ * A `Record` over the union's discriminant for the same reason
+ * {@link CONDITION_SCOPE} is one, and the reason is CONTRIBUTING's ninth rule:
+ * a hand-written list of "which conditions need data" is a closed enumeration
+ * authored by whoever knew today's conditions, and a new condition would join
+ * the engine and be quietly absent from it. Here it cannot - adding a member to
+ * `CatalogueCondition` is a TYPECHECK ERROR until its dependency is declared.
+ *
+ * The other direction is closed too: a new member of {@link CatalogueInput}
+ * fails to compile until {@link InterrogationReport}'s `inputs` reports it.
+ *
+ * `unconstrained-kind` is the only condition that goes quiet without
+ * `profileContext`. Others pass it to helpers for lineage widening, where its
+ * absence narrows what matches rather than silencing the condition.
  */
+const CONDITION_INPUTS = {
+    'has-any-subject': undefined,
+    'no-subject-of-kind': undefined,
+    'has-subject-of-kind': undefined,
+    'below-subject-count': undefined,
+    'no-state-defined': undefined,
+    'exists-linkage': undefined,
+    'no-linkage-exists': undefined,
+    'missing-claim': undefined,
+    'missing-relationship': undefined,
+    isolated: undefined,
+    'missing-linkage': undefined,
+    'has-linkage': undefined,
+    'missing-constraint': undefined,
+    'missing-flow-content': undefined,
+    'missing-reference': undefined,
+    'missing-attestation': undefined,
+    'near-duplicate': undefined,
+    'unconstrained-kind': 'profileContext',
+    'unscoped-succession': undefined,
+    'unchallenged-evidence': 'evidence',
+    'fills-pattern-slot': 'patternMemberships',
+    'missing-part': 'patternVacancies',
+};
+/**
+ * The input this condition goes quiet without, if any (#450). Published beside
+ * {@link conditionScope} so a host can join a report's echoed trigger to its
+ * `inputs` and answer the question it actually has: which of the questions in
+ * front of me could not be evaluated?
+ */
+export const conditionInput = (condition) => CONDITION_INPUTS[condition.condition];
 const CONDITION_SCOPE = {
     'has-any-subject': 'workspace',
     'no-subject-of-kind': 'workspace',
@@ -648,6 +681,15 @@ patternVacancies) {
             ? {}
             : { catalogues }),
         semantics: INTERROGATION_SEMANTICS_VERSION,
+        // What the caller actually handed over (#450). Every key present on every
+        // report, so a host reads a boolean rather than testing for presence. A
+        // new member of `CatalogueInput` will not compile until it appears here.
+        inputs: {
+            profileContext: profileContext !== undefined,
+            evidence: evidence !== undefined,
+            patternMemberships: patternMemberships !== undefined,
+            patternVacancies: patternVacancies !== undefined,
+        },
         summary: {
             // Questions in OPENED waves only (#334, ADR 0125). A closed wave's
             // questions have not been asked, so counting them in the denominator
@@ -1195,6 +1237,24 @@ export function renderInterrogationReport(report) {
             `${report.summary.open} open ` +
             `(${report.summary.openQuestions} of ${report.summary.questions} questions)`,
     ];
+    // Named only when it MATTERS (#450): an input this catalogue's own triggers
+    // read, that the caller did not supply. Listing every input on every report
+    // would be noise a reader learns to skip, and the one line that mattered
+    // would be skipped with it. Derived from (inputs withheld) x (conditions
+    // actually used), which is the question a reader has rather than the one the
+    // field literally answers.
+    const withheld = [
+        ...new Set(report.waves.flatMap((wave) => wave.questions.flatMap((question) => question.trigger
+            .map((condition) => conditionInput(condition))
+            .filter((input) => input !== undefined && !report.inputs[input])))),
+    ].sort();
+    if (withheld.length > 0) {
+        // Not a warning about the model: a warning about this evaluation. The
+        // questions reading those conditions answered "no" because nothing was
+        // handed over, which is indistinguishable from "satisfied" in the lines
+        // below.
+        lines.push(`  note: ${withheld.join(', ')} not supplied — questions reading ${withheld.length === 1 ? 'it' : 'them'} could not be evaluated`);
+    }
     for (const wave of report.waves) {
         lines.push('', `== ${wave.name} ==`);
         // A wave that has not opened must not read like one whose questions are

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 CataloguePatternMembership, 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, conditionInput, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCompositionResult, type ComposedCatalogue, 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/interrogation-entry.js

@@ -7,4 +7,4 @@
 // 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, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, conditionInput, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';

package/dist/operations.d.ts

@@ -32,6 +32,20 @@ export interface ConceptFields {
     readonly constraints?: readonly ConstraintReference[];
     readonly references?: readonly IdentifiedReference[];
     readonly presentIn?: readonly string[];
+    /**
+     * The subjects this instance binds into its pattern's slots (ADR 0123),
+     * keyed by part name (#448). The first MAP-valued concept field, so it is a
+     * third category beside the scalars and the lists rather than a schema line.
+     *
+     * `update-concept` MERGES by slot: a named slot rebinds, an unnamed one is
+     * untouched. That is ADR 0062's convention rather than a new decision — a
+     * write enriches what is there and never silently shrinks it — and
+     * replace-whole-map would quietly unbind slots the operation never
+     * mentioned. Retraction is coarse, `remove: ['parts']`, because a second
+     * retraction idiom for one field reads fine to whoever wrote it and traps
+     * everyone else.
+     */
+    readonly parts?: Readonly<Record<string, string>>;
     readonly attestations?: ReadonlyArray<{
         readonly topic: string;
         readonly by: string;