yarramate 0.3.2 → 0.4.0

package/dist/projection.js

@@ -181,3 +181,109 @@ export function renderProjectionMarkdown(result) {
     }
     return `${lines.join('\n')}\n`;
 }
+const estimateTokens = (text) => Math.ceil(text.length / 4);
+export function renderBudgetedContext(result, budgetTokens) {
+    const concepts = result.subjects.filter(({ type }) => type === 'concept');
+    const relationships = result.subjects.filter(({ type }) => type === 'relationship');
+    const title = result.presentation?.title ?? result.projection;
+    const header = [
+        `context ${result.projection} — ${title}`,
+        `subjects: ${concepts.length} concepts, ${relationships.length} relationships`,
+    ];
+    const subjectLines = [];
+    for (const concept of concepts) {
+        const name = claimValue(result.claims, concept.id, 'yarramate/concept/name');
+        const kind = claimValue(result.claims, concept.id, 'yarramate/concept/kind') ??
+            'unknown';
+        const status = claimValue(result.claims, concept.id, 'yarramate/lifecycle/status');
+        subjectLines.push(`- ${concept.id} [${kind.split('#')[1] ?? kind}]` +
+            `${name === undefined ? '' : ` ${name}`}` +
+            `${status === undefined ? '' : ` (${status})`}`);
+    }
+    const relationshipLines = [];
+    for (const relationship of relationships) {
+        const claim = result.claims.find(({ id, object }) => id === relationship.id && 'ref' in object);
+        if (claim !== undefined && 'ref' in claim.object) {
+            const kind = claim.predicate.split('#')[1] ?? claim.predicate;
+            relationshipLines.push(`- ${claim.subject} -${kind}-> ${claim.object.ref}`);
+        }
+    }
+    const descriptionLines = [];
+    for (const subject of result.subjects) {
+        const description = claimValue(result.claims, subject.id, 'yarramate/concept/description') ??
+            claimValue(result.claims, subject.id, 'yarramate/relationship/description');
+        if (description !== undefined) {
+            descriptionLines.push(`- ${subject.id}: ${description}`);
+        }
+    }
+    const detailPredicates = new Set([
+        'yarramate/ownership/owner',
+        'yarramate/constraint/requires',
+        'yarramate/reference/refers-to',
+        'yarramate/access/mode',
+        'yarramate/state/present-in',
+    ]);
+    const detailLines = [];
+    for (const claim of result.claims) {
+        if (!detailPredicates.has(claim.predicate))
+            continue;
+        const value = 'ref' in claim.object ? claim.object.ref : claim.object.value;
+        const predicate = claim.predicate.split('/').pop() ?? claim.predicate;
+        detailLines.push(`- ${claim.subject} ${predicate}: ${value}`);
+    }
+    // Ranked ladder: the two header lines always render; every other line —
+    // including the subject skeleton — competes for the remaining budget in
+    // priority order, and anything dropped is always announced rather than
+    // silently omitted.
+    const sections = [
+        { heading: 'relationships:', lines: relationshipLines },
+        { heading: 'descriptions:', lines: descriptionLines },
+        { heading: 'details:', lines: detailLines },
+    ];
+    const rendered = [...header];
+    const omitted = [];
+    let spent = estimateTokens(rendered.join('\n'));
+    let droppedSubjects = 0;
+    for (const line of subjectLines) {
+        const cost = estimateTokens(line);
+        if (spent + cost > budgetTokens) {
+            droppedSubjects += 1;
+            continue;
+        }
+        rendered.push(line);
+        spent += cost;
+    }
+    if (droppedSubjects > 0) {
+        omitted.push(`subjects ${droppedSubjects} omitted`);
+    }
+    for (const section of sections) {
+        if (section.lines.length === 0)
+            continue;
+        const kept = [section.heading];
+        let sectionSpent = estimateTokens(section.heading);
+        let dropped = 0;
+        for (const line of section.lines) {
+            const cost = estimateTokens(line);
+            if (spent + sectionSpent + cost > budgetTokens) {
+                dropped += 1;
+                continue;
+            }
+            kept.push(line);
+            sectionSpent += cost;
+        }
+        if (kept.length > 1) {
+            rendered.push('', ...kept);
+            spent += sectionSpent;
+        }
+        else {
+            dropped = section.lines.length;
+        }
+        if (dropped > 0) {
+            omitted.push(`${section.heading.replace(':', '')} ${dropped} omitted`);
+        }
+    }
+    if (omitted.length > 0) {
+        rendered.push('', `[budget ${budgetTokens}: ${omitted.join('; ')} — raise --budget or use JSON mode for the complete slice]`);
+    }
+    return `${rendered.join('\n')}\n`;
+}

package/dist/source-document.d.ts

@@ -1,4 +1,4 @@
-import type { ValidateFunction } from 'ajv';
+import type { ErrorObject, ValidateFunction } from 'ajv';
 import { LineCounter, parseDocument } from 'yaml';
 import type { Diagnostic, WorkspaceSource } from './compiler.js';
 export interface SourceLocation {
@@ -20,5 +20,7 @@ export type SourceDocumentResult<T> = {
     readonly diagnostics: readonly Diagnostic[];
 };
 export declare const diagnosticOrder: (left: Diagnostic, right: Diagnostic) => number;
+export declare const describeSchemaViolation: (error: Pick<ErrorObject, "keyword" | "message" | "params">) => string;
+export declare const closestCandidate: (value: string, candidates: Iterable<string>) => string | undefined;
 export declare function locateSourcePath(sourcePath: string, yaml: ReturnType<typeof parseDocument>, lineCounter: LineCounter, yamlPath: readonly (string | number)[], pointer: string): SourceLocation;
 export declare function loadSourceDocument<T>(source: WorkspaceSource, validate: ValidateFunction, schemaLabel: string): SourceDocumentResult<T>;

package/dist/source-document.js

@@ -4,6 +4,48 @@ export const diagnosticOrder = (left, right) => left.path.localeCompare(right.pa
     left.column - right.column ||
     left.code.localeCompare(right.code) ||
     left.message.localeCompare(right.message);
+export const describeSchemaViolation = (error) => {
+    const base = error.message ?? error.keyword;
+    if (error.keyword === 'const') {
+        return `${base}: expected ${JSON.stringify(error.params.allowedValue)}`;
+    }
+    if (error.keyword === 'enum' &&
+        Array.isArray(error.params.allowedValues)) {
+        const allowed = error.params.allowedValues;
+        const shown = allowed
+            .slice(0, 8)
+            .map((value) => JSON.stringify(value))
+            .join(', ');
+        return `${base}: ${shown}${allowed.length > 8 ? ', …' : ''}`;
+    }
+    return base;
+};
+const editDistance = (left, right) => {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= left.length; i += 1) {
+        let diagonal = previous[0];
+        previous[0] = i;
+        for (let j = 1; j <= right.length; j += 1) {
+            const above = previous[j];
+            previous[j] = Math.min(above + 1, previous[j - 1] + 1, diagonal + (left[i - 1] === right[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return previous[right.length];
+};
+export const closestCandidate = (value, candidates) => {
+    const threshold = Math.max(2, Math.floor(value.length / 4));
+    let best;
+    let bestDistance = threshold + 1;
+    for (const candidate of [...candidates].sort()) {
+        const distance = editDistance(value.toLowerCase(), candidate.toLowerCase());
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+};
 export function locateSourcePath(sourcePath, yaml, lineCounter, yamlPath, pointer) {
     const node = yaml.getIn(yamlPath, true);
     const offset = typeof node === 'object' &&
@@ -62,7 +104,7 @@ export function loadSourceDocument(source, validate, schemaLabel) {
                     code: 'YM201',
                     message: property
                         ? `Property "${property}" is not allowed`
-                        : `${schemaLabel} schema violation: ${error.message ?? error.keyword}`,
+                        : `${schemaLabel} schema violation: ${describeSchemaViolation(error)}`,
                     ...location,
                 };
             })

package/dist/status-command.d.ts

@@ -0,0 +1,2 @@
+import { type CliResult } from './cli-support.js';
+export declare function runStatusCommand(options: readonly string[], cwd: string): CliResult;

package/dist/status-command.js

@@ -0,0 +1,171 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseDocument } from 'yaml';
+import { runCheckCommand } from './check-command.js';
+import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
+import { compileWorkspace } from './compiler.js';
+import { evaluateEvidenceWorkspace, loadEvidence } from './evidence.js';
+import { loadProjection } from './projection.js';
+import { reconcileEvidenceReports, } from './reconciliation.js';
+import { loadWorkspaceManifest } from './workspace.js';
+const plural = (count, singular, pluralForm) => `${count} ${count === 1 ? singular : (pluralForm ?? `${singular}s`)}`;
+export function runStatusCommand(options, cwd) {
+    const json = options.includes('--json');
+    const paths = options.filter((option) => option !== '--json');
+    const [workspacePath] = paths;
+    if (paths.length !== 1 ||
+        workspacePath === undefined ||
+        workspacePath.startsWith('-')) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    try {
+        const manifestSource = readFileSync(resolve(cwd, workspacePath), 'utf8');
+        if (parseDocument(manifestSource).get('format') !==
+            'yarramate/workspace/v1') {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: 'status requires an explicit workspace manifest (yarramate/workspace/v1)\n',
+            };
+        }
+        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+        if (!loadedWorkspace.ok) {
+            return {
+                exitCode: 1,
+                stdout: json
+                    ? diagnosticJson(loadedWorkspace.diagnostics)
+                    : humanDiagnostics(loadedWorkspace.diagnostics),
+                stderr: '',
+            };
+        }
+        const workspace = loadedWorkspace.workspace;
+        const checked = runCheckCommand([workspacePath, '--json'], cwd);
+        const checkPayload = JSON.parse(checked.stdout);
+        const projections = workspace.projections.map((path) => {
+            const loaded = loadProjection({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            });
+            return loaded.ok
+                ? {
+                    id: loaded.projection.id,
+                    path,
+                    ...(loaded.projection.presentation?.title === undefined
+                        ? {}
+                        : { title: loaded.projection.presentation.title }),
+                }
+                : { id: path, path };
+        });
+        let documents = workspace.documents.map((path) => ({ id: path, path }));
+        let states = [];
+        let reconciliation;
+        if (checkPayload.ok) {
+            const compilation = compileWorkspace([...workspace.profiles, ...workspace.documents].map((path) => ({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            })));
+            if (compilation.ok) {
+                const sourceByDocument = new Map(compilation.graph.documents.map((document) => [
+                    document.id,
+                    document.source,
+                ]));
+                documents = workspace.documents.map((path) => {
+                    const id = [...sourceByDocument.entries()].find(([, source]) => source === path)?.[0];
+                    return { id: id ?? path, path };
+                });
+                states = compilation.graph.claims
+                    .filter(({ predicate }) => predicate === 'yarramate/state/type')
+                    .map(({ subject, object }) => ({
+                    id: subject,
+                    type: 'value' in object && typeof object.value === 'string'
+                        ? object.value
+                        : 'baseline',
+                }));
+                if (workspace.evidence.length > 0) {
+                    const evidenceDocuments = workspace.evidence.flatMap((path) => {
+                        const loaded = loadEvidence({
+                            path,
+                            source: readFileSync(resolve(cwd, path), 'utf8'),
+                        });
+                        return loaded.ok ? [loaded.evidence] : [];
+                    });
+                    const evaluation = evaluateEvidenceWorkspace(compilation.graph, evidenceDocuments);
+                    if (evaluation.ok) {
+                        reconciliation = reconcileEvidenceReports(workspace.id, evaluation.reports).summary;
+                    }
+                }
+            }
+        }
+        const result = {
+            format: 'yarramate/status-result/v1',
+            workspace: workspace.id,
+            ok: checkPayload.ok,
+            check: {
+                ok: checkPayload.ok,
+                diagnostics: checkPayload.ok ? [] : checkPayload.diagnostics,
+                ...(checkPayload.counted === undefined
+                    ? {}
+                    : { counted: checkPayload.counted }),
+            },
+            ...(reconciliation === undefined ? {} : { reconciliation }),
+            inventory: {
+                documents,
+                profiles: workspace.profiles,
+                states,
+                projections,
+                evidence: workspace.evidence,
+                adapterMappings: workspace.adapterMappings,
+                contracts: workspace.contracts,
+            },
+        };
+        if (json) {
+            return {
+                exitCode: result.ok ? 0 : 1,
+                stdout: `${JSON.stringify(result, null, 2)}\n`,
+                stderr: '',
+            };
+        }
+        const lines = [];
+        const counted = result.check.counted;
+        lines.push(`Workspace ${result.workspace}: check ${result.ok ? 'ok' : 'failing'}` +
+            (counted === undefined
+                ? ''
+                : ` (${plural(counted.concepts, 'concept')}, ` +
+                    `${plural(counted.relationships, 'relationship')}, ` +
+                    `${plural(counted.states, 'state')}, ` +
+                    `${plural(counted.documents, 'document')})`));
+        if (!result.ok) {
+            lines.push(`Diagnostics: ${plural(result.check.diagnostics.length, 'error')}; run \`yarramate check ${workspacePath}\` for details`);
+        }
+        if (result.reconciliation !== undefined) {
+            lines.push(`Reconciliation: ${plural(result.reconciliation.observations, 'observation')}, ` +
+                `${result.reconciliation.confirmed} confirmed, ` +
+                `${plural(result.reconciliation.findings, 'finding')}` +
+                (result.reconciliation.findings > 0
+                    ? ` (${result.reconciliation.contradicted} contradicted, ` +
+                        `${result.reconciliation.unknown} unknown, ` +
+                        `${result.reconciliation.notObserved} not observed)`
+                    : ''));
+        }
+        lines.push(`Documents: ${documents.map(({ id }) => id).join(', ') || 'none'}`);
+        if (states.length > 0) {
+            lines.push(`States: ${states.map(({ id, type }) => `${id} (${type})`).join(', ')}`);
+        }
+        lines.push(`Projections: ${projections
+            .map(({ id, title }) => title === undefined ? id : `${id} — ${title}`)
+            .join('; ') || 'none'}`);
+        lines.push(`Profiles: ${workspace.profiles.length} · ` +
+            `Evidence: ${workspace.evidence.length} · ` +
+            `Adapter mappings: ${workspace.adapterMappings.length} · ` +
+            `Contracts: ${workspace.contracts.length}`);
+        return {
+            exitCode: result.ok ? 0 : 1,
+            stdout: `${lines.join('\n')}\n`,
+            stderr: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+}

package/docs/CONSUMING-YARRAMATE.md

@@ -143,3 +143,51 @@ yarramate-graphify observe \
 Graphify extraction remains a separate installation and operation. The
 adapter observes only explicitly mapped nodes and never promotes them into
 canonical architecture.
+
+## MCP server for agent harnesses
+
+Harnesses that load MCP servers can connect the bundled read-only adapter:
+
+```json
+{
+  "mcpServers": {
+    "yarramate": {
+      "command": "yarramate-mcp"
+    }
+  }
+}
+```
+
+It exposes `yarramate_status`, `yarramate_check`, `yarramate_reconcile`,
+and `yarramate_context` (projection path or ad-hoc subjects, with an
+optional token budget). Every tool call executes the same stable CLI in
+the server's working directory; nothing mutates native documents, and
+authoring stays with the CLI and Git review.
+
+## Continuous drift signal in CI
+
+The repository root ships a composite GitHub Action that checks the
+workspace and reports intent-vs-evidence drift on every pull request:
+
+```yaml
+name: architecture
+on: pull_request
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: yarrasys/yarramate@main
+        with:
+          workspace: .yarramate/workspace.yaml
+```
+
+The job fails on deterministic correctness errors and, by default, when
+reconciliation reports contradicted claims; unknown and not-observed
+findings are reported in the job summary without failing. Set
+`fail-on-contradiction: 'false'` to make the whole signal advisory. The
+action never mutates sources — it runs only the read-only `check` and
+`reconcile` commands, so it is safe as a required check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -58,6 +58,7 @@
     "./schema/likec4-kind-mapping": "./schema/yarramate-likec4-kind-mapping.schema.json",
     "./schema/likec4-check-result": "./schema/yarramate-likec4-check-result.schema.json",
     "./schema/state-comparison": "./schema/yarramate-state-comparison.schema.json",
+    "./schema/status-result": "./schema/yarramate-status-result.schema.json",
     "./schema/graph-v2": "./schema/yarramate-graph-v2.schema.json",
     "./schema/workspace": "./schema/yarramate-workspace.schema.json",
     "./schema/evidence": "./schema/yarramate-evidence.schema.json",
@@ -69,7 +70,8 @@
   "bin": {
     "yarramate": "dist/cli.js",
     "yarramate-likec4": "dist/adapters/likec4-cli.js",
-    "yarramate-graphify": "dist/adapters/graphify-cli.js"
+    "yarramate-graphify": "dist/adapters/graphify-cli.js",
+    "yarramate-mcp": "dist/adapters/mcp-cli.js"
   },
   "packageManager": "pnpm@11.7.0",
   "engines": {

package/schema/yarramate-core-contract.schema.json

@@ -34,7 +34,11 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "schema", "packageExport"],
+        "required": [
+          "id",
+          "schema",
+          "packageExport"
+        ],
         "properties": {
           "id": {
             "$ref": "#/$defs/formatIdentity"
@@ -55,14 +59,19 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["name", "binary"],
+        "required": [
+          "name",
+          "binary"
+        ],
         "properties": {
           "name": {
             "enum": [
               "init",
               "add",
               "connect",
+              "new",
               "check",
+              "status",
               "compile",
               "view",
               "context",