@principled/cairn 1.0.0-beta

package/README.md

@@ -0,0 +1,182 @@
+# Cairn — Goals, Values, and Principles
+
+A decision traceability framework. Define your goals, values, and principles in YAML. Trace every decision back to what drives it. Link decisions to the code, documents, and artifacts they produce.
+
+## Install
+
+```bash
+npm install -g @principled/cairn
+```
+
+> **Note:** `gvp` is available as an alias for `cairn`.
+
+## Quick Start
+
+```bash
+# Initialize a GVP library
+mkdir -p .gvp/library
+cat > .gvp/library/project.yaml << 'EOF'
+meta:
+  name: my-project
+  scope: project
+
+goals:
+  - id: G1
+    name: Ship reliable software
+    statement: Deliver software that works correctly.
+    tags: []
+    maps_to: []
+
+values:
+  - id: V1
+    name: Simplicity
+    statement: Complexity must earn its place.
+    tags: []
+    maps_to: [my-project:G1]
+
+decisions:
+  - id: D1
+    name: Use TypeScript
+    rationale: Type safety and npm ecosystem.
+    tags: []
+    maps_to: [my-project:G1, my-project:V1]
+    refs:
+      - file: src/index.ts
+        identifier: main
+        role: implements
+EOF
+
+# Validate
+cairn validate
+
+# Export
+cairn export --format json
+cairn export --format markdown
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `cairn validate` | Validate the GVP library |
+| `cairn validate --coverage` | Include coverage checks (orphan identifiers, decisions without refs) |
+| `cairn validate --scope staged` | Scope validation to staged git changes |
+| `cairn export --format <fmt>` | Export catalog to json, csv, markdown, or dot |
+| `cairn add <category> <name>` | Add a new element with auto-assigned ID |
+| `cairn edit <element> --field key=value` | Modify an existing element |
+| `cairn review` | Find stale elements needing review |
+| `cairn review <element>` | Review a specific element |
+| `cairn inspect <element>` | View element details |
+| `cairn inspect <element> --trace` | Trace element to its goals and values |
+| `cairn inspect --ref file::identifier --trace` | "Why does this code exist?" |
+| `cairn query --category decision` | Filter elements by category, tag, status |
+| `cairn query --refs-file src/foo.ts` | Find elements referencing a file |
+| `cairn diff <commitA> <commitB>` | Trace code changes back to decisions |
+| `cairn analyze` | Detect unmapped relationships via similarity |
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Load specific config file |
+| `--no-config` | Skip all config files |
+| `-c key=value` | Inline config override |
+| `--strict` | Promote warnings to errors |
+| `-v` / `-vv` / `-vvv` | Verbose output |
+
+## Validation Codes
+
+### Errors
+
+| Code | Name | Description |
+|------|------|-------------|
+| E001 | BROKEN_REFERENCE | `maps_to` target not found |
+| E002 | DUPLICATE_ELEMENT_ID | Duplicate element ID within a document |
+| E003 | BROKEN_INHERITANCE | Inherited document not found |
+| E004 | SCHEMA_VALIDATION | Element fails schema validation |
+
+### Warnings
+
+| Code | Name | Description |
+|------|------|-------------|
+| W001 | EMPTY_MAPS_TO | Non-root active element has no `maps_to` |
+| W002 | EMPTY_DOCUMENT | Document has no active elements |
+| W003 | MAPPING_RULES_VIOLATION | Element doesn't satisfy category mapping rules |
+| W004 | ORPHAN_ELEMENT | Isolated element (no incoming or outgoing edges) |
+| W005 | SELF_DOCUMENT_MAPPING | Element maps only within its own document |
+| W006 | STALE_ELEMENT | Element has unreviewed updates |
+| W007 | UNDEFINED_TAG | Element uses tag not in definitions |
+| W008 | DUPLICATE_CATEGORY_DEF | Duplicate category definition within library siblings |
+| W009 | ID_SEQUENCE_GAP | Gap in element ID sequence |
+| W010 | REF_FILE_MISSING | Ref points to nonexistent file |
+| W011 | REF_IDENTIFIER_MISSING | Ref identifier not found in file |
+| W012 | ORPHAN_IDENTIFIER | Identifier not referenced by any element (coverage pass) |
+| W013 | DECISION_NO_REFS | Decision has no refs (coverage pass) |
+| W014 | NO_ROOT_TRACE | Element cannot trace to any root element transitively |
+
+## Config
+
+Config files are discovered in this order (closer scope wins):
+
+1. `/etc/gvp/config.yaml` (system)
+2. `~/.config/gvp/config.yaml` (global)
+3. `.gvp/config.yaml` (project)
+4. `.gvp.yaml` (local, gitignored)
+
+Environment variables: `GVP_CONFIG_SYSTEM`, `GVP_CONFIG_GLOBAL`, `GVP_CONFIG_PROJECT`, `GVP_CONFIG_LOCAL`
+
+```yaml
+# .gvp/config.yaml
+user:
+  name: "Your Name"
+  email: "you@example.com"
+
+strict: false
+suppress_diagnostics: []
+default_timezone: "America/New_York"
+
+priority:
+  elements: ancestor      # ancestor-wins for elements
+  definitions: descendant  # descendant-wins for definitions
+
+# Coverage settings (patterns use glob syntax via minimatch: *, **, ?)
+coverage:
+  exclude:
+    - "README.md"
+    - ".gvp/**"
+    - "**/*.test.ts"
+    - "docs/**"
+```
+
+## Built-in Categories
+
+| Category | Prefix | Root | Primary Field |
+|----------|--------|------|---------------|
+| goal | G | yes | statement |
+| value | V | yes | statement |
+| constraint | C | yes | impact |
+| principle | P | no | statement |
+| rule | R | no | statement |
+| heuristic | H | no | statement |
+| decision | D | no | rationale |
+| milestone | M | no | description |
+
+## Refs — Linking Decisions to Artifacts
+
+Any element can have `refs` linking it to external files:
+
+```yaml
+refs:
+  - file: src/catalog/catalog.ts
+    identifier: Catalog
+    role: implements  # defines | implements | uses | extends
+```
+
+The `refs` system is domain-agnostic — it works with any file type that has a registered parser (TypeScript, Markdown, YAML built-in).
+
+## Documentation
+
+- [Getting Started](docs/guide/getting-started.md) — Set up GVP on a new project
+- [Command Reference](docs/guide/workflow.md#quick-reference) — Command reference
+- [Workflow Guide](docs/guide/workflow.md) — End-to-end design → implementation → review workflow
+- [Lightweight Capture](docs/guide/lightweight-capture.md) — ~5 min decision capture after brainstorming sessions

package/dist/analysis/analyzer.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingProvider } from './embedding-provider.js';
+import type { Element } from '../model/element.js';
+export interface SimilarityResult {
+    elementA: Element;
+    elementB: Element;
+    similarity: number;
+}
+/**
+ * Find potentially related but unmapped element pairs (DEC-10.9).
+ * Returns pairs above the similarity threshold that aren't connected via maps_to.
+ */
+export declare function findUnmappedRelationships(elements: Element[], provider: EmbeddingProvider, threshold?: number): Promise<SimilarityResult[]>;
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/analysis/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/analysis/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,GAAE,MAAY,GACtB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA6C7B"}

package/dist/analysis/analyzer.js

@@ -0,0 +1,47 @@
+/**
+ * Find potentially related but unmapped element pairs (DEC-10.9).
+ * Returns pairs above the similarity threshold that aren't connected via maps_to.
+ */
+export async function findUnmappedRelationships(elements, provider, threshold = 0.7) {
+    // Embed all elements
+    const embeddings = new Map();
+    for (const el of elements) {
+        const text = `${el.name} ${el.get(el.categoryName === 'decision' ? 'rationale' : 'statement') ?? ''}`;
+        embeddings.set(el.hashKey(), await provider.embed(text));
+    }
+    // Build maps_to lookup for connected pairs
+    const connected = new Set();
+    for (const el of elements) {
+        for (const ref of el.maps_to) {
+            connected.add(`${el.hashKey()}:${ref}`);
+            // Also check reverse (since maps_to is directional but we want any connection)
+            const target = elements.find(e => e.toLibraryId() === ref || e.hashKey() === ref);
+            if (target) {
+                connected.add(`${target.hashKey()}:${el.toLibraryId()}`);
+            }
+        }
+    }
+    // Compare all pairs
+    const results = [];
+    for (let i = 0; i < elements.length; i++) {
+        for (let j = i + 1; j < elements.length; j++) {
+            const elA = elements[i];
+            const elB = elements[j];
+            // Skip if already connected
+            const keyAB = `${elA.hashKey()}:${elB.toLibraryId()}`;
+            const keyBA = `${elB.hashKey()}:${elA.toLibraryId()}`;
+            if (connected.has(keyAB) || connected.has(keyBA))
+                continue;
+            const embA = embeddings.get(elA.hashKey());
+            const embB = embeddings.get(elB.hashKey());
+            if (!embA || !embB)
+                continue;
+            const sim = provider.similarity(embA, embB);
+            if (sim >= threshold) {
+                results.push({ elementA: elA, elementB: elB, similarity: sim });
+            }
+        }
+    }
+    return results.sort((a, b) => b.similarity - a.similarity);
+}
+//# sourceMappingURL=analyzer.js.map

package/dist/analysis/analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.js","sourceRoot":"","sources":["../../src/analysis/analyzer.ts"],"names":[],"mappings":"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"}

package/dist/analysis/embedding-provider.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Abstract embedding provider interface (DEC-10.8).
+ * Plugin point for different embedding backends.
+ */
+export declare abstract class EmbeddingProvider {
+    abstract readonly name: string;
+    /** Generate an embedding vector for text */
+    abstract embed(text: string): Promise<number[]>;
+    /** Compute similarity between two vectors (0-1, higher = more similar) */
+    similarity(a: number[], b: number[]): number;
+}
+//# sourceMappingURL=embedding-provider.d.ts.map

package/dist/analysis/embedding-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.d.ts","sourceRoot":"","sources":["../../src/analysis/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,8BAAsB,iBAAiB;IACrC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAE/C,0EAA0E;IAC1E,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM;CAY7C"}

package/dist/analysis/embedding-provider.js

@@ -0,0 +1,21 @@
+/**
+ * Abstract embedding provider interface (DEC-10.8).
+ * Plugin point for different embedding backends.
+ */
+export class EmbeddingProvider {
+    /** Compute similarity between two vectors (0-1, higher = more similar) */
+    similarity(a, b) {
+        // Default: cosine similarity
+        if (a.length !== b.length || a.length === 0)
+            return 0;
+        let dot = 0, normA = 0, normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom === 0 ? 0 : dot / denom;
+    }
+}
+//# sourceMappingURL=embedding-provider.js.map

package/dist/analysis/embedding-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.js","sourceRoot":"","sources":["../../src/analysis/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAgB,iBAAiB;IAMrC,0EAA0E;IAC1E,UAAU,CAAC,CAAW,EAAE,CAAW;QACjC,6BAA6B;QAC7B,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACtD,IAAI,GAAG,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC;QAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;YACrB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;YACvB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACzB,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC;IACvC,CAAC;CACF"}

package/dist/analysis/index.d.ts

@@ -0,0 +1,4 @@
+export { EmbeddingProvider } from './embedding-provider.js';
+export { StubEmbeddingProvider } from './stub-provider.js';
+export { findUnmappedRelationships, type SimilarityResult } from './analyzer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/analysis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/analysis/index.js

@@ -0,0 +1,4 @@
+export { EmbeddingProvider } from './embedding-provider.js';
+export { StubEmbeddingProvider } from './stub-provider.js';
+export { findUnmappedRelationships } from './analyzer.js';
+//# sourceMappingURL=index.js.map

package/dist/analysis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAyB,MAAM,eAAe,CAAC"}

package/dist/analysis/stub-provider.d.ts

@@ -0,0 +1,12 @@
+import { EmbeddingProvider } from './embedding-provider.js';
+/**
+ * Stub embedding provider for alpha.
+ * Uses simple bag-of-words hashing -- not production quality,
+ * but exercises the interface for testing.
+ */
+export declare class StubEmbeddingProvider extends EmbeddingProvider {
+    readonly name = "stub";
+    private readonly dimensions;
+    embed(text: string): Promise<number[]>;
+}
+//# sourceMappingURL=stub-provider.d.ts.map

package/dist/analysis/stub-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-provider.d.ts","sourceRoot":"","sources":["../../src/analysis/stub-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,iBAAiB;IAC1D,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAM;IAE3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAmB7C"}

package/dist/analysis/stub-provider.js

@@ -0,0 +1,30 @@
+import { EmbeddingProvider } from './embedding-provider.js';
+/**
+ * Stub embedding provider for alpha.
+ * Uses simple bag-of-words hashing -- not production quality,
+ * but exercises the interface for testing.
+ */
+export class StubEmbeddingProvider extends EmbeddingProvider {
+    name = 'stub';
+    dimensions = 64;
+    async embed(text) {
+        // Simple deterministic hash-based embedding for testing
+        const words = text.toLowerCase().split(/\W+/).filter(w => w.length > 0);
+        const vector = new Array(this.dimensions).fill(0);
+        for (const word of words) {
+            for (let i = 0; i < word.length; i++) {
+                const idx = (word.charCodeAt(i) * (i + 1)) % this.dimensions;
+                vector[idx] = (vector[idx] ?? 0) + 1;
+            }
+        }
+        // Normalize
+        const norm = Math.sqrt(vector.reduce((s, v) => s + v * v, 0));
+        if (norm > 0) {
+            for (let i = 0; i < vector.length; i++) {
+                vector[i] = (vector[i] ?? 0) / norm;
+            }
+        }
+        return vector;
+    }
+}
+//# sourceMappingURL=stub-provider.js.map

package/dist/analysis/stub-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-provider.js","sourceRoot":"","sources":["../../src/analysis/stub-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,iBAAiB;IACjD,IAAI,GAAG,MAAM,CAAC;IACN,UAAU,GAAG,EAAE,CAAC;IAEjC,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,wDAAwD;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACxE,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAa,CAAC;QAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;gBAC7D,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QACD,YAAY;QACZ,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9E,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACvC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;YACtC,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/catalog/catalog.d.ts

@@ -0,0 +1,40 @@
+import type { Document } from '../model/document.js';
+import type { Element } from '../model/element.js';
+import type { ResolvedInheritance } from '../inheritance/inheritance-resolver.js';
+import type { GVPConfig } from '../config/schema.js';
+import { CategoryRegistry } from '../model/category-registry.js';
+import { type LibraryDefinitionSnapshot } from './category-merger.js';
+import { Graph } from '../model/graph.js';
+/**
+ * The assembled, validated, queryable GVP catalog (DEC-5.7: construction fails fast).
+ * Immutable after construction.
+ */
+export declare class Catalog {
+    private readonly _config;
+    private readonly _registry;
+    private readonly _documents;
+    private readonly _elements;
+    private readonly _elementsByCategory;
+    private readonly _mergedDefinitions;
+    constructor(resolvedInheritance: ResolvedInheritance, config: GVPConfig);
+    get config(): GVPConfig;
+    get registry(): CategoryRegistry;
+    get documents(): Document[];
+    /** Get all elements across all documents */
+    getAllElements(): Element[];
+    /** Get elements by category name */
+    getElementsByCategory(categoryName: string): Element[];
+    /** Get element by hash key (source:documentPath:id) */
+    getElement(hashKey: string): Element | undefined;
+    /** Get merged tag definitions */
+    getTags(): Record<string, {
+        description: string;
+    }>;
+    /** Get per-library definition snapshot (DEC-2.12) */
+    getLibrarySnapshot(source: string): LibraryDefinitionSnapshot | undefined;
+    /** Build ancestors graph for an element (DEC-6.1, DEC-6.5) */
+    ancestors(element: Element): Graph;
+    /** Build descendants graph for an element (DEC-6.1, DEC-6.5) */
+    descendants(element: Element): Graph;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/catalog/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,EAGN,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyB;IAC7D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoB;gBAE3C,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,EAAE,SAAS;IA+DvE,IAAI,MAAM,IAAI,SAAS,CAEtB;IACD,IAAI,QAAQ,IAAI,gBAAgB,CAE/B;IACD,IAAI,SAAS,IAAI,QAAQ,EAAE,CAE1B;IAED,4CAA4C;IAC5C,cAAc,IAAI,OAAO,EAAE;IAI3B,oCAAoC;IACpC,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,EAAE;IAItD,uDAAuD;IACvD,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIhD,iCAAiC;IACjC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAIlD,qDAAqD;IACrD,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS;IAIzE,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;IAQlC,gEAAgE;IAChE,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK;CAGrC"}

package/dist/catalog/catalog.js

@@ -0,0 +1,118 @@
+import { CategoryRegistry } from '../model/category-registry.js';
+import { loadDefaults } from '../schema/defaults-loader.js';
+import { mergeDefinitions, } from './category-merger.js';
+import { validateMergedCategories } from './post-merge-validation.js';
+import { buildAncestorsGraph, buildDescendantsGraph, } from '../model/graph.js';
+/**
+ * The assembled, validated, queryable GVP catalog (DEC-5.7: construction fails fast).
+ * Immutable after construction.
+ */
+export class Catalog {
+    _config;
+    _registry;
+    _documents;
+    _elements; // hashKey -> Element
+    _elementsByCategory;
+    _mergedDefinitions;
+    constructor(resolvedInheritance, config) {
+        this._config = config;
+        this._documents = resolvedInheritance.orderedDocuments;
+        // Step 0: Apply config_overrides from documents (DEC-2.4, DEC-2.13)
+        // Iterate in DFS order (ancestors first = ancestor-wins)
+        const appliedOverrides = new Set();
+        for (const doc of this._documents) {
+            const overrides = doc.meta.config_overrides;
+            if (!overrides)
+                continue;
+            for (const [key, override] of Object.entries(overrides)) {
+                // DEC-4.8: user identity is personal, excluded from config_overrides
+                if (key === 'user')
+                    continue;
+                if (override.mode === 'replace') {
+                    // Ancestor-wins: only set if not already set by an earlier ancestor
+                    if (!appliedOverrides.has(key)) {
+                        this._config[key] = override.value;
+                        appliedOverrides.add(key);
+                    }
+                }
+                else if (override.mode === 'additive') {
+                    // Accumulate: arrays concatenated, ancestor first
+                    const existing = this._config[key];
+                    if (Array.isArray(existing) && Array.isArray(override.value)) {
+                        this._config[key] = [...existing, ...override.value];
+                    }
+                    else {
+                        this._config[key] = override.value;
+                    }
+                }
+            }
+        }
+        // Step 1: Merge definitions across documents
+        const defDirection = config.priority?.definitions ?? 'descendant';
+        this._mergedDefinitions = mergeDefinitions(this._documents, defDirection);
+        // Step 2: Build registry from defaults + merged user definitions
+        const defaults = loadDefaults();
+        let registry = CategoryRegistry.fromDefaults(defaults);
+        if (Object.keys(this._mergedDefinitions.categories).length > 0 ||
+            Object.keys(this._mergedDefinitions.allFieldSchemas).length > 0) {
+            const userAll = Object.keys(this._mergedDefinitions.allFieldSchemas).length > 0
+                ? { field_schemas: this._mergedDefinitions.allFieldSchemas }
+                : undefined;
+            registry = registry.merge(this._mergedDefinitions.categories, userAll);
+        }
+        this._registry = registry;
+        // Step 3: Post-merge validation (DEC-3.6, DEC-5.7: throws on error)
+        validateMergedCategories(registry.categories);
+        // Step 4: Index all elements
+        this._elements = new Map();
+        this._elementsByCategory = new Map();
+        for (const doc of this._documents) {
+            for (const element of doc.getAllElements()) {
+                this._elements.set(element.hashKey(), element);
+                const catElements = this._elementsByCategory.get(element.categoryName) ?? [];
+                catElements.push(element);
+                this._elementsByCategory.set(element.categoryName, catElements);
+            }
+        }
+    }
+    get config() {
+        return this._config;
+    }
+    get registry() {
+        return this._registry;
+    }
+    get documents() {
+        return [...this._documents];
+    }
+    /** Get all elements across all documents */
+    getAllElements() {
+        return [...this._elements.values()];
+    }
+    /** Get elements by category name */
+    getElementsByCategory(categoryName) {
+        return [...(this._elementsByCategory.get(categoryName) ?? [])];
+    }
+    /** Get element by hash key (source:documentPath:id) */
+    getElement(hashKey) {
+        return this._elements.get(hashKey);
+    }
+    /** Get merged tag definitions */
+    getTags() {
+        return this._mergedDefinitions.tags;
+    }
+    /** Get per-library definition snapshot (DEC-2.12) */
+    getLibrarySnapshot(source) {
+        return this._mergedDefinitions.librarySnapshots.get(source);
+    }
+    /** Build ancestors graph for an element (DEC-6.1, DEC-6.5) */
+    ancestors(element) {
+        return buildAncestorsGraph(element, (ref) => {
+            return this.getAllElements().find((e) => e.toLibraryId() === ref || e.hashKey() === ref);
+        });
+    }
+    /** Build descendants graph for an element (DEC-6.1, DEC-6.5) */
+    descendants(element) {
+        return buildDescendantsGraph(element, this.getAllElements());
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/catalog/catalog.ts"],"names":[],"mappings":"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"}

package/dist/catalog/category-merger.d.ts

@@ -0,0 +1,25 @@
+import type { Document } from '../model/document.js';
+import type { CategoryDefinition } from '../schema/category-definition.js';
+import type { FieldSchemaEntry } from '../schema/field-schema.js';
+export interface LibraryDefinitionSnapshot {
+    categories: Record<string, CategoryDefinition>;
+    tags: Record<string, {
+        description: string;
+    }>;
+}
+export interface MergedDefinitions {
+    categories: Record<string, CategoryDefinition>;
+    tags: Record<string, {
+        description: string;
+    }>;
+    allFieldSchemas: Record<string, FieldSchemaEntry>;
+    librarySnapshots: Map<string, LibraryDefinitionSnapshot>;
+}
+/**
+ * Merge category definitions across documents (DEC-2.1, DEC-2.2, DEC-2.7, DEC-2.8).
+ *
+ * @param orderedDocuments - Documents in DFS order (ancestors first)
+ * @param definitionDirection - 'ancestor' or 'descendant' (from config priority.definitions)
+ */
+export declare function mergeDefinitions(orderedDocuments: Document[], definitionDirection?: 'ancestor' | 'descendant'): MergedDefinitions;
+//# sourceMappingURL=category-merger.d.ts.map

package/dist/catalog/category-merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"category-merger.d.ts","sourceRoot":"","sources":["../../src/catalog/category-merger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAClD,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;CAC1D;AAYD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,QAAQ,EAAE,EAC5B,mBAAmB,GAAE,UAAU,GAAG,YAA2B,GAC5D,iBAAiB,CAsEnB"}

package/dist/catalog/category-merger.js

@@ -0,0 +1,75 @@
+/**
+ * Deep merge field_schemas: target is base, source overrides (DEC-2.2).
+ */
+function deepMergeFieldSchemas(base, override) {
+    return { ...base, ...override };
+}
+/**
+ * Merge category definitions across documents (DEC-2.1, DEC-2.2, DEC-2.7, DEC-2.8).
+ *
+ * @param orderedDocuments - Documents in DFS order (ancestors first)
+ * @param definitionDirection - 'ancestor' or 'descendant' (from config priority.definitions)
+ */
+export function mergeDefinitions(orderedDocuments, definitionDirection = 'descendant') {
+    const mergedCategories = {};
+    const mergedTags = {};
+    const mergedAll = {};
+    const librarySnapshots = new Map();
+    // Iterate in the direction where the winner comes LAST
+    // descendant-wins: iterate ancestors first, descendants overwrite
+    // ancestor-wins: iterate descendants first, ancestors overwrite
+    const docs = definitionDirection === 'descendant'
+        ? orderedDocuments // ancestors first, descendants overwrite
+        : [...orderedDocuments].reverse(); // descendants first, ancestors overwrite
+    for (const doc of docs) {
+        // Merge category definitions from this document
+        const docCategories = doc.getCategoryDefinitions();
+        for (const [name, def] of Object.entries(docCategories)) {
+            if (mergedCategories[name]) {
+                // Deep merge field_schemas
+                const existingSchemas = mergedCategories[name].field_schemas ?? {};
+                const newSchemas = def.field_schemas ?? {};
+                mergedCategories[name] = {
+                    ...mergedCategories[name],
+                    ...def,
+                    field_schemas: Object.keys(existingSchemas).length || Object.keys(newSchemas).length
+                        ? deepMergeFieldSchemas(existingSchemas, newSchemas)
+                        : undefined,
+                };
+            }
+            else {
+                mergedCategories[name] = { ...def };
+            }
+        }
+        // Merge tag definitions
+        const docTags = doc.getTagDefinitions();
+        for (const [name, tag] of Object.entries(docTags)) {
+            mergedTags[name] = tag;
+        }
+        // Merge _all field_schemas from user documents (DEC-2.8)
+        const docAllSchemas = doc.meta.definitions?._all;
+        if (docAllSchemas &&
+            typeof docAllSchemas === 'object' &&
+            'field_schemas' in docAllSchemas) {
+            const schemas = docAllSchemas
+                .field_schemas;
+            if (schemas) {
+                Object.assign(mergedAll, schemas);
+            }
+        }
+        // Capture per-library snapshot (DEC-2.12)
+        if (!librarySnapshots.has(doc.source)) {
+            librarySnapshots.set(doc.source, {
+                categories: { ...mergedCategories },
+                tags: { ...mergedTags },
+            });
+        }
+    }
+    return {
+        categories: mergedCategories,
+        tags: mergedTags,
+        allFieldSchemas: mergedAll,
+        librarySnapshots,
+    };
+}
+//# sourceMappingURL=category-merger.js.map