yarramate 1.6.0 → 1.7.0

package/dist/visual-app-lib/types/adapters/visual/workspace-model.d.ts

@@ -57,10 +57,20 @@ export interface DismissedQuestion {
 export declare const interrogationOverlayOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
-}, catalogue: {
+}, 
+/**
+ * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
+ * A set rather than one document so the pane asks the same interview the
+ * CLI does over the same workspace: an editor showing fewer questions than
+ * `design` does over the same files is a disagreement with no symptom.
+ */
+catalogue: {
     readonly path: string;
     readonly source: string;
-}, 
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], 
 /**
  * What the host has already dealt with (#328). Evaluation is unchanged and
  * the model is untouched: this decides only what the pane draws, because a
@@ -83,7 +93,10 @@ export declare const renderedWorkspaceOf: (compiled: {
 }, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary" | "interrogation">, catalogue?: {
     readonly path: string;
     readonly source: string;
-}, dismissed?: readonly DismissedQuestion[]) => {
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], dismissed?: readonly DismissedQuestion[]) => {
     readonly model: VisualRenderedModel;
     readonly views: readonly VisualViewSummary[];
 };

package/dist/visual-app-lib/types/interrogate-command.d.ts

@@ -188,14 +188,29 @@ export interface InterrogationSummary {
 export interface InterrogationReport {
     readonly format: 'yarramate/interrogation-report/v1';
     readonly workspace: string;
+    /** The BASE catalogue, `id@version`. Unchanged in shape by composition. */
     readonly catalogue: string;
+    /**
+     * Every contributing catalogue as `id@version`, base first, when more than
+     * one contributed (#345, ADR 0129). Optional so that adding it breaks no
+     * constructor, and `catalogue` keeps its value shape so it breaks no reader.
+     */
+    readonly catalogues?: readonly string[];
     /** {@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, evidence?: readonly CatalogueEvidenceObservation[]): Omit<InterrogationReport, 'workspace'>;
+export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext, evidence?: readonly CatalogueEvidenceObservation[], 
+/**
+ * Contributing catalogues, from {@link composeCatalogues}. Composition
+ * happens BEFORE evaluation and hands this function an ordinary catalogue,
+ * so the only thing evaluation learns about composition is what to name in
+ * the report. A fifth optional parameter rather than an options object,
+ * because this signature is published and a consumer already calls it.
+ */
+catalogues?: readonly string[]): Omit<InterrogationReport, 'workspace'>;
 export type CatalogueLoadResult = {
     readonly ok: true;
     readonly catalogue: QuestionCatalogue;
@@ -203,5 +218,71 @@ export type CatalogueLoadResult = {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
 };
+/**
+ * A catalogue is qualified on the way OUT, never in what an author writes.
+ *
+ * The authored schema keeps ids local (`^[a-z][a-z0-9-]*$`) and that does not
+ * change; a consultant writes `regulator-signoff`, not
+ * `consulting#regulator-signoff`. The engine qualifies when it composes, which
+ * is the only moment two catalogues can be confused for each other.
+ *
+ * NO VERSION, and that is the decision rather than an omission (ADR 0129).
+ * `core-enrichment` went 1.0 to 1.3 in a single day renaming nothing; a
+ * versioned identity would have stranded every stored dismissal in every
+ * adopter's database three times that day, for changes that removed no
+ * question. Versioned identity is safe for things that are AUTHORED - a
+ * document keeps naming the version it was written against and an author
+ * updates it deliberately - and unsafe for things that are STORED, because a
+ * row in someone's database has no author to update it.
+ */
+export declare const qualifiedQuestionId: (catalogueId: string, questionId: string) => string;
+export interface ComposedCatalogue {
+    /**
+     * The composed catalogue, ready for `evaluateCatalogue`. Structurally a
+     * `QuestionCatalogue`, but its question ids are QUALIFIED, so it is a
+     * composition result rather than something an author could have written and
+     * must never be validated against the authored schema again.
+     */
+    readonly catalogue: QuestionCatalogue;
+    /** Every contributing catalogue as `id@version`, base first. */
+    readonly catalogues: readonly string[];
+}
+export type CatalogueCompositionResult = {
+    readonly ok: true;
+    readonly composed: ComposedCatalogue;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+/**
+ * Compose a base catalogue with the ones a workspace carries (#345, ADR 0129).
+ *
+ * ADDITIVE. `--catalogue` and `MountOptions.catalogue` replace the base; this
+ * adds to it, which is what lets a consultant author a question at any point
+ * in an engagement with no product release.
+ *
+ * A WAVE IS DECLARED EXACTLY ONCE across the resolved set, and any catalogue
+ * may contribute questions to a wave it did not declare. That one rule settles
+ * three questions composition would otherwise raise. Wave identity: a project
+ * catalogue joins a declared wave rather than colliding with it. Ordering:
+ * only a declaration places a wave, so the base's order is untouched and new
+ * waves append. And the `opensWhen` precedence ADR 0125 made load-bearing does
+ * not arise at all, because there is only ever one declarer to ask.
+ *
+ * QUALIFICATION IS A PROPERTY OF COMPOSITION, NOT OF EVALUATION. A caller
+ * that hands `evaluateCatalogue` a catalogue directly still gets local ids,
+ * exactly as before this existed. Route through here even for ONE catalogue -
+ * which is what every CLI verb does - and ids are qualified from the start, so
+ * they do not change later when a workspace first carries a question of its
+ * own. That transition is the one thing an adopter keying stored judgments on
+ * a question id must not experience, and composing unconditionally is how it
+ * is avoided.
+ *
+ * ID COLLISIONS DISSOLVE rather than being resolved. Two catalogues may both
+ * carry `outcome-missing`; qualified, they are two different questions. There
+ * is no merge rule, no last-wins and no refusal, because there is nothing to
+ * merge.
+ */
+export declare function composeCatalogues(sources: readonly WorkspaceSource[], profileContext?: ResolvedProfileContext): CatalogueCompositionResult;
 export declare function loadQuestionCatalogue(catalogueSource: WorkspaceSource, profileContext?: ResolvedProfileContext): CatalogueLoadResult;
 export declare function renderInterrogationReport(report: InterrogationReport): string;

package/dist/visual-app-lib/types/projection.d.ts

@@ -108,6 +108,53 @@ export interface ProjectionExclusion {
     readonly id: string;
     readonly facet: ConceptFacet;
 }
+/** A query facet naming something the model does not have. */
+export interface UnmatchedSelector {
+    readonly facet: string;
+    readonly value: string;
+    /** The closest name the facet does offer, when one is close enough to be a likely typo. */
+    readonly nearest?: string;
+}
+/**
+ * Every value in a projection query that names nothing.
+ *
+ * A projection is a DOCUMENT, and a query holds references the same way a
+ * relationship does. YarraMate refuses a relationship pointing at a concept
+ * that does not exist; it did not refuse a query naming a state that does not
+ * exist, and the symptom is silent. `states: [target-stat]` selects no state,
+ * which selects no subject, which exports a clean empty artifact with exit 0.
+ * Someone hands that to a client.
+ *
+ * Checked at `check`, not at `export`, because the typo is in a file rather
+ * than in an invocation: CI catches it, and every verb over the same
+ * projection inherits the guard instead of each growing its own.
+ *
+ * ONLY FACETS WITH A CLOSED NAMESPACE ARE CHECKED. `statuses` and
+ * `excludeStatuses` are schema enums, refused upstream before this runs.
+ * Everything else names something: `owners` and `constraints` are REFS to
+ * concepts, which the compiler itself proves by refusing an unresolved owner
+ * with YM304, so their namespace is the subject list like `subjects`.
+ *
+ * Each namespace is derived the way the FILTER derives it, so the check cannot
+ * drift from what it guards: `documents` reads the same provenance the
+ * `documents` facet compares against, and `states` is the same
+ * `yarramate/state/type` scan `conceptSelector` runs.
+ *
+ * A kind whose profile is not loaded is DORMANT rather than wrong, the same
+ * distinction #351 drew for question catalogues, so the kind facets are
+ * checked only when a profile context is present.
+ *
+ * An empty RESULT is not reported here and must not be. A query whose every
+ * name resolves and which selects nothing is a real answer to a real question:
+ * a target state nobody has populated yet is empty, correctly.
+ */
+export declare function unmatchedSelectors(graph: SemanticGraph, projection: ProjectionDefinition, profileContext?: ResolvedProfileContext): readonly UnmatchedSelector[];
+/**
+ * {@link unmatchedSelectors} as diagnostics, built HERE rather than at each
+ * caller so `check`, and anything that adopts this later, refuse in identical
+ * words with an identical code.
+ */
+export declare function projectionReferenceDiagnostics(source: WorkspaceSource, projection: ProjectionDefinition, graph: SemanticGraph, profileContext?: ResolvedProfileContext): readonly Diagnostic[];
 /**
  * Every concept a query leaves out, and the facet that left it out.
  *

package/dist/visual-app-lib/types/workspace.d.ts

@@ -7,6 +7,7 @@ export interface WorkspaceManifest {
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
     readonly patterns?: readonly string[];
+    readonly questions?: readonly string[];
     readonly evidence?: readonly string[];
     readonly contracts?: readonly string[];
 }
@@ -17,6 +18,20 @@ export interface ResolvedWorkspace {
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
     readonly patterns: readonly string[];
+    /**
+     * Question catalogues the workspace itself carries (#345, ADR 0129).
+     * ADDITIVE to the shipped catalogue: `--catalogue` replaces the base, this
+     * adds to it, which is what lets a consultant author a question mid
+     * engagement without a product release.
+     *
+     * OPTIONAL in the type although `loadWorkspaceManifest` always populates it,
+     * and that is deliberate. `ResolvedWorkspace` is published, and adding
+     * `patterns` to it as a required field broke a consumer's production module:
+     * a required field is free for readers and a break for CONSTRUCTORS. Six
+     * fixtures in this repository construct one, which is the same signal from
+     * inside. Read it as `workspace.questions ?? []`.
+     */
+    readonly questions?: readonly string[];
     readonly evidence: readonly string[];
     readonly contracts: readonly string[];
 }

package/dist/workbook-import-entry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `yarramate/workbook/import` — reading an edited workbook back, for a host
+ * that has no Node.
+ *
+ * A SEPARATE subpath from `yarramate/workbook` rather than more exports on it,
+ * because the package declares no `sideEffects` field and a bundler must
+ * therefore assume every module might have one. A Worker that only GENERATES
+ * workbooks would otherwise carry the reader, the merge and the operations
+ * emitter it never calls, and small bundles are the reason the xlsx container
+ * is hand-written in the first place (#355).
+ *
+ * Held to the same bar as `./workbook` and `./interrogation` by
+ * `test/export-purity.test.ts`: no Node builtins, no `ws`, no session server,
+ * no runtime import of the compiler. `workbook-read.ts` imports nothing at
+ * all; inflation uses `DecompressionStream('deflate-raw')`, which Workers,
+ * browsers and Node 18+ all have.
+ *
+ * The reader is ASYNC and the writer is not, deliberately. A workbook this
+ * package wrote has stored entries and inline strings, but one a person saved
+ * from Excel comes back deflated and shared-stringed, and inflation is only
+ * offered as a stream.
+ *
+ * What a host still owns: reading the bytes, evaluating the projection that
+ * says what the workbook SHOULD hold now, and applying the operations. This
+ * entry turns bytes into sheets, sheets into a merge report, and a merge
+ * report into `yarramate/operations/v1`.
+ */
+export { readWorkbook, unzipEntries, columnIndexOf, decodeXmlText, type WorkbookRead, type ZipReadFailure, } from './workbook-read.js';
+export { mergeWorkbook, mergeSheet, keySheet, baselineSheets, isDerivedColumn, type KeyedSheet, type CellChange, type Conflict, type MergeReport, } from './workbook-merge.js';
+export { operationsFrom, operationsDocument, type OperationsResult, } from './workbook-operations.js';

package/dist/workbook-import-entry.js

@@ -0,0 +1,30 @@
+/**
+ * `yarramate/workbook/import` — reading an edited workbook back, for a host
+ * that has no Node.
+ *
+ * A SEPARATE subpath from `yarramate/workbook` rather than more exports on it,
+ * because the package declares no `sideEffects` field and a bundler must
+ * therefore assume every module might have one. A Worker that only GENERATES
+ * workbooks would otherwise carry the reader, the merge and the operations
+ * emitter it never calls, and small bundles are the reason the xlsx container
+ * is hand-written in the first place (#355).
+ *
+ * Held to the same bar as `./workbook` and `./interrogation` by
+ * `test/export-purity.test.ts`: no Node builtins, no `ws`, no session server,
+ * no runtime import of the compiler. `workbook-read.ts` imports nothing at
+ * all; inflation uses `DecompressionStream('deflate-raw')`, which Workers,
+ * browsers and Node 18+ all have.
+ *
+ * The reader is ASYNC and the writer is not, deliberately. A workbook this
+ * package wrote has stored entries and inline strings, but one a person saved
+ * from Excel comes back deflated and shared-stringed, and inflation is only
+ * offered as a stream.
+ *
+ * What a host still owns: reading the bytes, evaluating the projection that
+ * says what the workbook SHOULD hold now, and applying the operations. This
+ * entry turns bytes into sheets, sheets into a merge report, and a merge
+ * report into `yarramate/operations/v1`.
+ */
+export { readWorkbook, unzipEntries, columnIndexOf, decodeXmlText, } from './workbook-read.js';
+export { mergeWorkbook, mergeSheet, keySheet, baselineSheets, isDerivedColumn, } from './workbook-merge.js';
+export { operationsFrom, operationsDocument, } from './workbook-operations.js';

package/dist/workbook.js

@@ -239,6 +239,21 @@ export const buildWorkbookSheets = (result, provenance) => {
         ['4.', 'Deleting a row does NOT delete anything. Removals are reported, never applied.'],
         ['5.', 'Send the file back and import it. Your edits are merged; only a field changed on both sides is refused.'],
         [],
+        [],
+        ['What this holds, and what it does not'],
+        [
+            '',
+            `A projection is a QUERY, so this workbook is the slice it names: ${conceptRows.length - 1} concepts and ${relationshipRows.length - 1} relationships.`,
+        ],
+        [
+            '',
+            'Everything the model knows about a subject that IS here is here, including anything these columns do not model, on 07 Other Facts.',
+        ],
+        [
+            '',
+            'A subject outside the slice has no row, and importing this file cannot change it. A narrow workbook is safe against a wide model.',
+        ],
+        [],
         ['Sheets beginning ~ are machinery. Do not edit them.'],
     ];
     const listColumns = [

package/dist/workspace.d.ts

@@ -7,6 +7,7 @@ export interface WorkspaceManifest {
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
     readonly patterns?: readonly string[];
+    readonly questions?: readonly string[];
     readonly evidence?: readonly string[];
     readonly contracts?: readonly string[];
 }
@@ -17,6 +18,20 @@ export interface ResolvedWorkspace {
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
     readonly patterns: readonly string[];
+    /**
+     * Question catalogues the workspace itself carries (#345, ADR 0129).
+     * ADDITIVE to the shipped catalogue: `--catalogue` replaces the base, this
+     * adds to it, which is what lets a consultant author a question mid
+     * engagement without a product release.
+     *
+     * OPTIONAL in the type although `loadWorkspaceManifest` always populates it,
+     * and that is deliberate. `ResolvedWorkspace` is published, and adding
+     * `patterns` to it as a required field broke a consumer's production module:
+     * a required field is free for readers and a break for CONSTRUCTORS. Six
+     * fixtures in this repository construct one, which is the same signal from
+     * inside. Read it as `workspace.questions ?? []`.
+     */
+    readonly questions?: readonly string[];
     readonly evidence: readonly string[];
     readonly contracts: readonly string[];
 }

package/dist/workspace.js

@@ -107,6 +107,7 @@ export function loadWorkspaceManifest(source, cwd) {
         projections: expand('projections', 'projection', value.projections),
         adapterMappings: expand('adapterMappings', 'adapter mapping', value.adapterMappings),
         patterns: expand('patterns', 'pattern', value.patterns ?? []),
+        questions: expand('questions', 'question catalogue', value.questions ?? []),
         evidence: expand('evidence', 'evidence', value.evidence ?? []),
         contracts: expand('contracts', 'Core contract', value.contracts ?? []),
     };

package/docs/CONSUMING-YARRAMATE.md

@@ -444,6 +444,18 @@ query:
     - target-state
 ```
 
+**Which makes a workbook a SLICE, and it is worth being plain about that.** An
+omitted facet imposes no constraint, so `query: {}` exports the whole model,
+and every facet you name narrows it. For a subject the query selected, nothing
+is dropped: the projection filters claims by subject membership rather than by
+predicate, so every fact about an included subject arrives, and `07 Other
+Facts` catches whatever the named columns do not model. For a subject it did
+not select, there is simply no row, and a missing row is never a deletion, so
+**a narrow workbook cannot damage a wide model on the way back in**. The
+`00 Read Me` sheet says all of this and reports the counts the slice actually
+has, because an FDE handed a filtered workbook with no note will read it as
+the model.
+
 **Reading the sheets.** Column A is always the id and is what the model is
 keyed on. A column headed `↳ … (auto)` is derived for readability and is
 ignored on the way back. Kind and status columns are drawn from the compiled
@@ -472,6 +484,57 @@ did not touch merges even if the repository moved on; only a field changed on
 is reported and never treated as a deletion, and a new row needs its `Document`
 column filled in.
 
+**On a host with no Node**, `yarramate/workbook/import` publishes the same
+three steps the CLI runs, so ingesting a workbook is not CLI-only:
+
+```ts
+import {
+  readWorkbook,
+  baselineSheets,
+  mergeWorkbook,
+  operationsFrom,
+  operationsDocument,
+} from 'yarramate/workbook/import'
+
+const read = await readWorkbook(bytes)
+if (!read.ok) return refuse(read.reason)
+
+const ancestor = read.sheets.get('~Baseline')
+if (ancestor === undefined) return refuse('not produced by yarramate export xlsx')
+
+const report = mergeWorkbook(
+  read.sheets,
+  baselineSheets(ancestor),
+  buildWorkbookSheets(currentResult, provenance),
+)
+if (report.conflicts.length > 0) return refuse(report.conflicts)
+
+const { operations, refusals } = operationsFrom(report, read.sheets)
+await apply(operationsDocument(operations))
+```
+
+`readWorkbook` is **async** while the writer is synchronous, and deliberately
+so: a workbook this package wrote has stored entries and inline strings, but
+one a person saved from Excel comes back deflated and shared-stringed, and
+inflation is only offered as a stream (`DecompressionStream('deflate-raw')`,
+present on Workers, in browsers and in Node 18+). Keeping the writer
+synchronous is what stops it infecting a synchronous store on the host side.
+
+It is a **separate subpath** from `yarramate/workbook` on purpose. The package
+declares no `sideEffects` field, so a bundler must assume every module might
+have one and cannot shake an unused re-export away; a host that only generates
+workbooks would otherwise carry the reader, the merge and the operations
+emitter it never calls. `test/export-purity.test.ts` holds the two entries
+disjoint as well as pure.
+
+The host keeps three jobs: reading the bytes, evaluating the projection that
+says what the model holds **now** (the third argument to `mergeWorkbook`, which
+is what measures repo drift in the same terms the author edited in), and
+applying the operations. Refusal wording is the host's too. The `Conflict`
+values name the sheet, row, column, what the author wrote, what the workspace
+now holds and their common ancestor, which reads like a merge tool rather than
+like something you hand a consultant.
+
 ## MCP server for agent harnesses
 
 Harnesses that load MCP servers can connect the bundled read-only adapter:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -62,6 +62,10 @@
       "types": "./dist/workbook-entry.d.ts",
       "import": "./dist/workbook-entry.js"
     },
+    "./workbook/import": {
+      "types": "./dist/workbook-import-entry.d.ts",
+      "import": "./dist/workbook-import-entry.js"
+    },
     "./visual-app": {
       "types": "./dist/visual-app-lib/editor.d.ts",
       "import": "./dist/visual-app-lib/editor.js"

package/schema/yarramate-interrogation-report.schema.json

@@ -24,6 +24,15 @@
       "type": "string",
       "minLength": 1
     },
+    "catalogues": {
+      "description": "Every catalogue that contributed, as id@version, base first (#345, ADR 0129). Present only when more than one did. OPTIONAL, and `catalogue` keeps naming the base with its existing value shape, because turning that field into an array would break every reader: an optional additive field is free for readers and does not force constructors. Question ids in this report are qualified as catalogue#question and carry NO version, so a catalogue version bump strands no stored judgment keyed on them; the versions live here instead.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
     "semantics": {
       "type": "string",
       "minLength": 1,

package/schema/yarramate-question-catalogue.schema.json

@@ -44,9 +44,9 @@
       }
     },
     "waves": {
-      "description": "Ordered interview phases. Array order is interview order. The wave taxonomy is catalogue opinion, not engine semantics.",
+      "description": "Ordered interview phases. Array order is interview order. The wave taxonomy is catalogue opinion, not engine semantics. MAY BE EMPTY (#345, ADR 0129): a catalogue that only contributes questions to waves ANOTHER catalogue declared is the ordinary shape of a project catalogue, and requiring a wave here would force it to declare one it does not want - which is refused as a duplicate the moment two catalogues do it. Evaluated alone, a catalogue with no waves and a question naming one is YM911, correctly: nothing declares it.",
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -112,7 +112,6 @@
       "description": "Which subjects a subject-scope question applies to. Field vocabulary mirrors the projection query selector (ADR 0017).",
       "type": "object",
       "additionalProperties": false,
-      
       "properties": {
         "kinds": {
           "type": "array",

package/schema/yarramate-workspace.schema.json

@@ -32,6 +32,10 @@
       "description": "yarramate/pattern/v1 documents: the shape a concept kind promises, and the wiring the compiler mints between an instance and the parts it binds (ADR 0123). Structure, where profiles declare vocabulary. Optional, like evidence and contracts.",
       "$ref": "#/$defs/patterns"
     },
+    "questions": {
+      "description": "yarramate/question-catalogue/v1 documents the WORKSPACE carries: questions true of this engagement and nowhere else (#345, ADR 0129). ADDITIVE to the shipped catalogue rather than replacing it, which is what --catalogue and MountOptions.catalogue do. Question ids are qualified as catalogue#question on the way out, so two catalogues may carry the same local id. A wave is declared exactly once across the resolved set, and any catalogue may contribute questions to a wave it did not declare. Optional, like patterns, evidence and contracts.",
+      "$ref": "#/$defs/patterns"
+    },
     "adapterMappings": {
       "$ref": "#/$defs/patterns"
     },