yarramate 0.1.1 → 0.3.0

package/dist/compiler.js

@@ -376,6 +376,11 @@ function compileWorkspaceResolved(sources) {
     ])));
     const qualifyReference = (documentId, reference) => reference.includes('#') ? reference : `${documentId}#${reference}`;
     const architectureStateIds = new Set(documents.flatMap(({ value }) => (value.states ?? []).map((state) => `${value.id}#${state.id}`)));
+    const subjectIds = new Set(documents.flatMap(({ value }) => [
+        ...(value.states ?? []).map((state) => `${value.id}#${state.id}`),
+        ...value.concepts.map((concept) => `${value.id}#${concept.id}`),
+        ...value.relationships.map((relationship) => `${value.id}#${relationship.id}`),
+    ]));
     const architectureStateAfter = new Map(documents.flatMap(({ value }) => (value.states ?? []).flatMap((state) => state.after === undefined
         ? []
         : [
@@ -582,6 +587,36 @@ function compileWorkspaceResolved(sources) {
                     });
                 }
             }
+            const seenReferenceIds = new Set();
+            for (const [referenceIndex, reference] of (concept.references ?? []).entries()) {
+                if (seenReferenceIds.has(reference.id)) {
+                    const pointer = `/concepts/${index}/references/${referenceIndex}/id`;
+                    const source = location(['concepts', index, 'references', referenceIndex, 'id'], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM309',
+                        message: `Duplicate reference ID "${reference.id}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+                seenReferenceIds.add(reference.id);
+                if (!subjectIds.has(qualifyReference(value.id, reference.ref))) {
+                    const pointer = `/concepts/${index}/references/${referenceIndex}/ref`;
+                    const source = location(['concepts', index, 'references', referenceIndex, 'ref'], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM308',
+                        message: `Unresolved subject reference "${reference.ref}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+            }
             for (const [stateIndex, state] of (concept.presentIn ?? []).entries()) {
                 if (!architectureStateIds.has(qualifyReference(value.id, state))) {
                     const pointer = `/concepts/${index}/presentIn/${stateIndex}`;
@@ -599,6 +634,48 @@ function compileWorkspaceResolved(sources) {
             }
         }
         for (const [index, relationship] of value.relationships.entries()) {
+            const seenReferenceIds = new Set();
+            for (const [referenceIndex, reference] of (relationship.references ?? []).entries()) {
+                if (seenReferenceIds.has(reference.id)) {
+                    const pointer = `/relationships/${index}/references/${referenceIndex}/id`;
+                    const source = location([
+                        'relationships',
+                        index,
+                        'references',
+                        referenceIndex,
+                        'id',
+                    ], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM309',
+                        message: `Duplicate reference ID "${reference.id}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+                seenReferenceIds.add(reference.id);
+                if (!subjectIds.has(qualifyReference(value.id, reference.ref))) {
+                    const pointer = `/relationships/${index}/references/${referenceIndex}/ref`;
+                    const source = location([
+                        'relationships',
+                        index,
+                        'references',
+                        referenceIndex,
+                        'ref',
+                    ], pointer);
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'YM308',
+                        message: `Unresolved subject reference "${reference.ref}"`,
+                        path: input.path,
+                        pointer,
+                        line: source.line,
+                        column: source.column,
+                    });
+                }
+            }
             for (const [stateIndex, state] of (relationship.presentIn ?? []).entries()) {
                 const stateIdentity = qualifyReference(value.id, state);
                 if (!architectureStateIds.has(stateIdentity)) {
@@ -785,6 +862,18 @@ function compileWorkspaceResolved(sources) {
                     source: location(['concepts', index, 'constraints', constraintIndex, 'ref'], `/concepts/${index}/constraints/${constraintIndex}/ref`),
                 });
             }
+            for (const [referenceIndex, reference] of (concept.references ?? []).entries()) {
+                claims.push({
+                    id: `${subject}~reference-${reference.id}`,
+                    subject,
+                    predicate: 'yarramate/reference/refers-to',
+                    object: {
+                        ref: qualifyReference(value.id, reference.ref),
+                    },
+                    origin: 'declared',
+                    source: location(['concepts', index, 'references', referenceIndex, 'ref'], `/concepts/${index}/references/${referenceIndex}/ref`),
+                });
+            }
             for (const [stateIndex, state] of (concept.presentIn ?? []).entries()) {
                 const stateIdentity = qualifyReference(value.id, state);
                 claims.push({
@@ -819,6 +908,16 @@ function compileWorkspaceResolved(sources) {
                     source: location(['relationships', index, 'name'], `/relationships/${index}/name`),
                 });
             }
+            if (relationship.description !== undefined) {
+                claims.push({
+                    id: `${id}~description`,
+                    subject: id,
+                    predicate: 'yarramate/relationship/description',
+                    object: { value: relationship.description },
+                    origin: 'declared',
+                    source: location(['relationships', index, 'description'], `/relationships/${index}/description`),
+                });
+            }
             if (relationship.mode !== undefined) {
                 claims.push({
                     id: `${id}~mode`,
@@ -849,6 +948,18 @@ function compileWorkspaceResolved(sources) {
                     source: location(['relationships', index, 'status'], `/relationships/${index}/status`),
                 });
             }
+            for (const [referenceIndex, reference] of (relationship.references ?? []).entries()) {
+                claims.push({
+                    id: `${id}~reference-${reference.id}`,
+                    subject: id,
+                    predicate: 'yarramate/reference/refers-to',
+                    object: {
+                        ref: qualifyReference(value.id, reference.ref),
+                    },
+                    origin: 'declared',
+                    source: location(['relationships', index, 'references', referenceIndex, 'ref'], `/relationships/${index}/references/${referenceIndex}/ref`),
+                });
+            }
             for (const [stateIndex, state] of (relationship.presentIn ?? []).entries()) {
                 const stateIdentity = qualifyReference(value.id, state);
                 claims.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
   ],
   "files": [
     "dist",
+    "assets/likec4",
     "schema",
     "skills/yarramate-architecture",
     "docs/CONSUMING-YARRAMATE.md"
@@ -78,7 +79,7 @@
     "build": "tsc -p tsconfig.build.json",
     "prepack": "pnpm build",
     "docs:dev": "pnpm self:export:likec4 && likec4 serve .yarramate-out/likec4",
-    "format": "likec4 format .yarramate/integrations/likec4/prototype",
+    "format": "likec4 format assets/likec4",
     "self:check": "pnpm build && node dist/cli.js check .yarramate/workspace.yaml",
     "self:check:json": "pnpm build && node dist/cli.js check .yarramate/workspace.yaml --json",
     "self:compile": "pnpm build && node dist/cli.js compile .yarramate/workspace.yaml",

package/schema/yarramate-check-result.schema.json

@@ -17,6 +17,9 @@
       "items": {
         "$ref": "#/$defs/diagnostic"
       }
+    },
+    "counted": {
+      "$ref": "#/$defs/counted"
     }
   },
   "allOf": [
@@ -30,6 +33,7 @@
         "required": ["ok"]
       },
       "then": {
+        "required": ["counted"],
         "properties": {
           "diagnostics": {
             "maxItems": 0
@@ -46,6 +50,17 @@
     }
   ],
   "$defs": {
+    "counted": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["documents", "concepts", "relationships", "states"],
+      "properties": {
+        "documents": { "type": "integer", "minimum": 0 },
+        "concepts": { "type": "integer", "minimum": 0 },
+        "relationships": { "type": "integer", "minimum": 0 },
+        "states": { "type": "integer", "minimum": 0 }
+      }
+    },
     "diagnostic": {
       "type": "object",
       "additionalProperties": false,

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

@@ -92,6 +92,7 @@
           "deterministic-diagnostic-order",
           "git-native-governance",
           "globally-qualified-compiled-identities",
+          "identified-reference-integrity",
           "no-partial-graph-on-error",
           "portable-projection-selectors",
           "source-located-diagnostics"
@@ -110,6 +111,7 @@
           "architectural-quality",
           "automatic-discovery",
           "external-language-conformance",
+          "formal-workflow-semantics",
           "state-scoped-claim-values"
         ]
       }

package/schema/yarramate-document.schema.json

@@ -100,6 +100,9 @@
             "$ref": "#/$defs/constraint"
           }
         },
+        "references": {
+          "$ref": "#/$defs/identifiedReferences"
+        },
         "presentIn": {
           "$ref": "#/$defs/stateReferences"
         }
@@ -118,6 +121,26 @@
         }
       }
     },
+    "identifiedReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "ref"],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "ref": {
+          "$ref": "#/$defs/reference"
+        }
+      }
+    },
+    "identifiedReferences": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/identifiedReference"
+      }
+    },
     "relationship": {
       "type": "object",
       "additionalProperties": false,
@@ -139,6 +162,9 @@
         "name": {
           "$ref": "#/$defs/nonEmptyText"
         },
+        "description": {
+          "$ref": "#/$defs/nonEmptyText"
+        },
         "mode": {
           "enum": ["read", "write", "read-write", "unspecified"]
         },
@@ -148,6 +174,9 @@
         "status": {
           "$ref": "#/$defs/lifecycleStatus"
         },
+        "references": {
+          "$ref": "#/$defs/identifiedReferences"
+        },
         "presentIn": {
           "$ref": "#/$defs/stateReferences"
         }

package/schema/yarramate-likec4-diagnostic-result.schema.json

@@ -34,7 +34,7 @@
                 "const": "error"
               },
               "code": {
-                "enum": ["YMLC101", "YMLC102", "YMLC103", "YMLC104", "YMLC105", "YMLC106"]
+                "enum": ["YMLC101", "YMLC102", "YMLC103", "YMLC104", "YMLC105", "YMLC106", "YMLC107", "YMLC108", "YMLC109", "YMLC110"]
               },
               "message": {
                 "type": "string",

package/schema/yarramate-likec4-project.schema.json

@@ -41,6 +41,7 @@
     },
     "path": {
       "type": "string",
+      "description": "Repository-relative path resolved from the CLI working directory. Parent traversal, absolute paths, and backslashes are rejected.",
       "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
     },
     "subjectIdentity": {

package/skills/yarramate-architecture/references/native-authoring.md

@@ -43,7 +43,11 @@ relationships:
     kind: access
     from: delivery-api
     to: delivery-data
+    description: The API uses the governed record without maintaining a copy.
     mode: read-write
+    references:
+      - id: residency-policy
+        ref: delivery-data
 ```
 
 IDs are document-local and compile to `document-id#subject-id`. Cross-document
@@ -76,6 +80,29 @@ use association when no stronger semantic meaning is justified.
 Ownership is one accountable reference, not approval workflow. Constraints are
 identified references, not a policy engine or free-form metadata bag.
 
+## Rationale and citations
+
+Use `description` on either a concept or relationship for decided narrative
+about that exact subject. Use an identified `references` entry when the
+narrative depends on another concept or relationship and the citation must
+remain checkable:
+
+```yaml
+description: Failure releases the lease and retains partial evidence.
+references:
+  - id: failure-destination
+    ref: retry-pool
+```
+
+Core checks the explicit target and local reference ID. It does not scan prose
+for IDs or interpret descriptions as formal preconditions, postconditions, or
+workflow rules.
+
+For interaction flows, model steps that need identity as behavior concepts and
+model normal or failure transitions as native relationships. A LikeC4 dynamic
+view may order those projected relationships and display their descriptions;
+the view does not become the workflow source of truth.
+
 ## Architecture states
 
 ```yaml
@@ -153,7 +180,9 @@ yarramate add .yarramate/architecture/main.yaml \
   --id delivery-api --kind applicationComponent --name "Delivery API"
 yarramate connect .yarramate/architecture/main.yaml \
   --id api-realizes-service --kind realization \
-  --from delivery-api --to delivery-service
+  --from delivery-api --to delivery-service \
+  --description "The API implements the agreed delivery boundary" \
+  --reference decision-source=delivery-service
 yarramate check .yarramate/workspace.yaml --json
 yarramate compile .yarramate/workspace.yaml
 yarramate context <projection.yaml> .yarramate/workspace.yaml
@@ -161,6 +190,9 @@ yarramate view <projection.yaml> .yarramate/workspace.yaml
 yarramate compare <from-state> <to-state> .yarramate/workspace.yaml
 yarramate evidence <evidence.yaml> .yarramate/workspace.yaml
 yarramate reconcile .yarramate/workspace.yaml
+yarramate-likec4 map --sync \
+  .yarramate/integrations/likec4/subject-mapping.yaml \
+  .yarramate/workspace.yaml
 ```
 
 Treat exit `0` as successful execution, `1` as correctness diagnostics, and