domainforge 0.13.0

package/docs/reference/wasm-api.md

@@ -0,0 +1,420 @@
+# SEA Core WASM Bindings
+
+This document describes the WebAssembly (WASM) bindings for the SEA Core library, enabling browser and edge runtime usage.
+
+## Overview
+
+Phase 9 implements WASM bindings using `wasm-bindgen`, providing a lightweight (<500KB gzipped) module for browser and Node.js environments.
+
+## Prerequisites
+
+1. **Rust toolchain** (1.77+)
+2. **wasm-pack**:
+   ```bash
+   curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+   ```
+3. **wasm-opt** (optional, for size optimization):
+
+   ```bash
+   # macOS
+   brew install binaryen
+
+   # Ubuntu/Debian
+   sudo apt install binaryen
+
+   # Or download from https://github.com/WebAssembly/binaryen/releases
+   ```
+
+## Building
+
+### Quick Build
+
+```bash
+chmod +x scripts/build-wasm.sh
+./scripts/build-wasm.sh
+```
+
+### Manual Build
+
+```bash
+cd domainforge-core
+wasm-pack build --target web --release --out-dir ../pkg --features wasm
+cd ..
+
+# Optional: Optimize with wasm-opt
+wasm-opt -Oz -o pkg/domainforge_core_bg_opt.wasm pkg/domainforge_core_bg.wasm
+mv pkg/domainforge_core_bg_opt.wasm pkg/domainforge_core_bg.wasm
+```
+
+## Testing
+
+### Unit Tests
+
+```bash
+cd domainforge-core
+wasm-pack test --headless --firefox --features wasm
+```
+
+### Browser Testing
+
+1. Build the package:
+
+   ```bash
+   ./scripts/build-wasm.sh
+   ```
+
+2. Start a local server:
+
+   ```bash
+   python3 -m http.server 8000
+   ```
+
+3. Open `http://localhost:8000/examples/browser.html`
+
+## Package Structure
+
+```
+pkg/
+├── package.json          # npm package metadata
+├── index.js              # JavaScript wrapper with lazy loading
+├── README.md             # Package documentation
+├── domainforge_core.js           # Generated WASM bindings
+├── domainforge_core.d.ts         # TypeScript definitions
+└── domainforge_core_bg.wasm      # Compiled WASM binary
+```
+
+## API
+
+The WASM bindings expose the same API as the Rust core:
+
+- `Entity` - Business actors, locations, organizational units
+- `Resource` - Quantifiable subjects of value
+- `Flow` - Transfers of resources between entities
+- `Instance` - Physical instances of resources at locations
+- `ResourceInstance` - Physical instances of resources at locations (use `ResourceInstance.new(name, resourceId, quantity?, namespace?, attributes?)`)
+- `Role` - A role label used to classify entities and to define relations (construct via `Role.new(name, namespace?)`)
+- `Relation` - A relation connecting roles, optionally tied to a flow (`Relation.new(name, subjectRoleId, predicate, objectRoleId, viaFlowId?, namespace?, attributes?)`)
+- `Metric` - Observability metrics collected for flows and resources (created via `Metric.new(name, unit?, namespace?)`)
+- `Mapping` - Used for data projections and mapping definitions across models (mapping constructor: `Mapping.new(...)` - refer to mapping docs for details)
+- `Projection` - Projections allow building derived views (e.g., CALM projections) from the Graph
+- `Graph` - Graph container with validation and traversal (uses IndexMap for deterministic iteration)
+  - `Graph.parse(source)` - Parse DSL to Graph
+  - `Graph.parseToAstJson(source)` - Parse DSL to AST JSON string
+- `formatSource` - Format SEA-DSL source code
+- `checkFormat` - Check if source is already formatted
+
+### Constructor Patterns (November 2025)
+
+**Entities:**
+
+```javascript
+// Default namespace
+const entity = Entity.new("Warehouse"); // namespace() returns "default"
+
+// Explicit namespace
+const entity = Entity.newWithNamespace("Warehouse", "logistics");
+```
+
+**Resources:**
+
+```javascript
+const resource = Resource.new("Cameras", "units"); // Default namespace
+const resource = Resource.newWithNamespace("Cameras", "units", "inventory");
+```
+
+**Flows:**
+
+```javascript
+// Takes ConceptId values - clone before passing
+const flow = Flow.new(resourceId.clone(), fromId.clone(), toId.clone(), 100);
+```
+
+## Usage Examples
+
+### Parse from DSL
+
+```javascript
+import { Graph } from "@godspeedai/domainforge-wasm";
+
+// Supports multiline strings with """ syntax
+const source = `
+  Entity "Warehouse" in logistics
+  Entity """Multi-line
+  Factory Name""" in manufacturing
+  Resource "Cameras" units
+  Flow "Cameras" from "Warehouse" to "Multi-line\\nFactory Name" quantity 100
+`;
+
+const graph = await Graph.parse(source);
+console.log("Entities:", graph.entityCount());
+console.log("Flows:", graph.flowCount());
+
+// Parse to AST JSON directly
+const astJson = Graph.parseToAstJson(source);
+console.log(astJson);
+```
+
+### Build Programmatically
+
+```javascript
+import { Graph, Entity, Resource, Flow } from "@godspeedai/domainforge-wasm";
+
+const graph = new Graph();
+
+// Use new() for default namespace, newWithNamespace() for explicit
+const warehouse = Entity.new("Warehouse");
+const factory = Entity.newWithNamespace("Factory", "manufacturing");
+const cameras = Resource.new("Cameras", "units");
+
+await graph.addEntity(warehouse);
+await graph.addEntity(factory);
+await graph.addResource(cameras);
+
+// Flow constructor takes ConceptId values - clone before passing
+const flow = Flow.new(
+  cameras.id().clone(),
+  warehouse.id().clone(),
+  factory.id().clone(),
+  100
+);
+await graph.addFlow(flow);
+
+// Namespace is always a string (not null)
+console.log(warehouse.namespace()); // "default"
+console.log(factory.namespace()); // "manufacturing"
+```
+
+### Formatting Source Code
+
+```javascript
+import { formatSource, checkFormat } from "@godspeedai/domainforge-wasm";
+
+const source = 'Entity   "Foo"  in    bar';
+
+// Format with defaults
+const formatted = formatSource(source);
+console.log(formatted); // Entity "Foo" in bar
+
+// Format with custom options
+const formatted2 = formatSource(source, 2, false, true, true);
+// args: source, indentWidth, useTabs, preserveComments, sortImports
+
+// Check if formatted
+const isFormatted = checkFormat(source);
+console.log(isFormatted); // false
+```
+
+## Size Optimization
+
+The WASM module is optimized for size:
+
+1. **Cargo.toml** optimizations:
+
+   ```toml
+   [profile.release]
+   opt-level = "z"        # Optimize for size
+   lto = true             # Link-time optimization
+   codegen-units = 1      # Better optimization
+   strip = true           # Strip debug symbols
+   panic = 'abort'        # Smaller panic handler
+   ```
+
+2. **wasm-opt** post-processing:
+
+   ```bash
+   wasm-opt -Oz pkg/domainforge_core_bg.wasm
+   ```
+
+3. **Feature flags** to reduce dependencies:
+   ```toml
+   uuid = { version = "1.6", features = ["v4", "v7", "serde", "wasm-bindgen"] }
+   ```
+
+## Publishing
+
+```bash
+cd pkg
+npm publish --access public
+```
+
+## Troubleshooting
+
+### WASM module fails to load
+
+- Ensure server sends correct MIME type: `application/wasm`
+- Check browser console for detailed errors
+- Verify WASM file exists and is not corrupted
+
+### Size exceeds 500KB
+
+- Run `wasm-opt -Oz` optimization
+- Check for unused dependencies
+- Use feature flags to exclude optional code
+
+### TypeScript errors
+
+- Ensure `domainforge_core.d.ts` is present in `pkg/`
+- Check TypeScript version compatibility (4.5+)
+
+## Architecture
+
+### WASM Bindings Layer
+
+```
+JavaScript/TypeScript
+       ↓
+index.js (Wrapper + lazy loading)
+       ↓
+domainforge_core.js (wasm-bindgen generated)
+       ↓
+domainforge_core_bg.wasm (Compiled Rust)
+       ↓
+Rust Core (primitives, graph, parser)
+```
+
+### Type Conversions
+
+| Rust Type       | WASM Boundary | JavaScript Type |
+| --------------- | ------------- | --------------- |
+| `String`        | `String`      | `string`        |
+| `Uuid`          | `String`      | `string`        |
+| `Decimal`       | `String`      | `string`        |
+| `Option<T>`     | `nullable T`  | `T \| null`     |
+| `Result<T, E>`  | `throws E`    | `Promise<T>`    |
+| `Vec<T>`        | `Array<T>`    | `T[]`           |
+| `HashMap<K, V>` | `Object`      | `object`        |
+
+## Performance
+
+- **Bundle size**: <500KB gzipped ✅
+- **Parse time**: ~1ms for typical models
+- **Memory**: ~2MB runtime overhead
+- **Initialization**: <50ms (lazy loaded)
+- **Deterministic**: IndexMap ensures reproducible results across runs
+
+## CALM Integration (Architecture-as-Code)
+
+Export/import graphs to/from FINOS CALM format:
+
+```javascript
+import { Graph } from "@godspeedai/domainforge-wasm";
+
+// Build your model
+const graph = new Graph();
+// ... add entities, resources, flows ...
+
+// Export to CALM JSON
+const calmJson = await graph.exportCalm();
+console.log(calmJson); // CALM JSON string
+
+// Import from CALM
+const importedGraph = await Graph.importCalm(calmJson);
+```
+
+## Semantic Pack API
+
+The WASM bindings expose semantic pack enums and functions for browser and edge runtime usage.
+
+### Enums
+
+```javascript
+import {
+  SemanticTruth,              // Valid = 0, Invalid = 1, Unknown = 2
+  DiagnosticSeverity,         // Error = 0, Warning = 1, Info = 2, Hint = 3
+  ValidationMode,             // Off = 0, Warn = 1, Strict = 2
+  ApprovalState,              // Candidate = 0, Approved = 1, Rejected = 2
+  SignatureState,             // Unsigned = 0, Signed = 1, InvalidSignature = 2
+  ConceptStatus,              // Active = 0, Proposed = 1, Deprecated = 2, Rejected = 3, ExternalOnly = 4
+  ConceptKind,                // Entity = 0, Resource = 1, Role = 2, Flow = 3, Policy = 4, Metric = 5, Dimension = 6, Unit = 7, External = 8
+  AliasStatus,                // Approved = 0, Deprecated = 1, Ambiguous = 2, Blocked = 3
+  SemanticValidationStatus,   // Passed = 0, Failed = 1, Unknown = 2, Blocked = 3
+} from "@godspeedai/domainforge-wasm";
+```
+
+### Functions
+
+#### semanticPackBuild
+
+Build a semantic pack from input JSON. Returns a JSON string with `pack`, `pack_content_hash`, `meaning_fingerprint`, `pre_pack_diagnostics`, and `build_warnings`.
+
+```javascript
+const result = semanticPackBuild(inputJson);
+const { pack, pack_content_hash, meaning_fingerprint } = JSON.parse(result);
+```
+
+#### semanticPackValidate
+
+Validate a pack's internal consistency. Returns a JSON array of diagnostics.
+
+```javascript
+const diagnosticsJson = semanticPackValidate(packJson);
+```
+
+#### semanticPackValidateGraph
+
+Validate a source against a pack with options. Returns a JSON validation result.
+
+```javascript
+const resultJson = semanticPackValidateGraph(packJson, "source_uri", optionsJson);
+```
+
+#### semanticPackSign
+
+Sign a pack with an Ed25519 private key (PEM string). Returns the signed pack JSON. Throws `JsError` on failure.
+
+```javascript
+const signedJson = semanticPackSign(packJson, privateKeyPem);
+```
+
+#### semanticPackVerify
+
+Verify a pack's Ed25519 signature. Returns `true` if valid, throws `JsError` on failure.
+
+```javascript
+const isValid = semanticPackVerify(packJson, publicKeyPem);
+```
+
+#### semanticPackDiff
+
+Compare two packs. Returns a JSON diff with entries and summary.
+
+```javascript
+const diffJson = semanticPackDiff(oldPackJson, newPackJson);
+```
+
+#### semanticPackHash
+
+Compute the content hash of a pack (excluding signature fields).
+
+```javascript
+const hash = semanticPackHash(packJson);
+```
+
+#### semanticNormalizeKey
+
+Normalize a term for lookup (NFC, case-fold, whitespace collapse).
+
+```javascript
+const normalized = semanticNormalizeKey("  Hello   World  "); // "hello world"
+```
+
+#### semanticResolveConcept
+
+Resolve a term against a pack. Returns a JSON object with `resolved_concept_id`, `semantic_truth`, `diagnostic_code`, `diagnostic_severity`, `message`, and `suggestions`.
+
+```javascript
+const resultJson = semanticResolveConcept("Supplier", packJson, optionsJson);
+const result = JSON.parse(resultJson);
+console.log(result.resolved_concept_id); // "supplier" or null
+console.log(result.semantic_truth);       // "valid", "invalid", or "unknown"
+```
+
+## Related Documentation
+
+- [Phase 9 Plan](../../work/plans/Phase 9_WASM Bindings.md)
+- [Package README](../../pkg/README.md)
+- [Browser Example](../../examples/browser.html)
+
+## License
+
+Apache-2.0

package/docs/semantic-pack-review.md

@@ -0,0 +1,144 @@
+# Semantic Pack Review Process
+
+Every semantic pack that transitions from `candidate` to `approved` must pass a review gate. This document describes the review manifest format, the allowed decisions, and the checks the build system performs.
+
+## Why Review Is Required
+
+Semantic packs define the vocabulary that downstream tools---the LSP, CI validators, code generators---treat as authoritative. An unreviewed pack that introduces a misspelled concept name or an ambiguous alias can silently corrupt generated code, produce misleading diagnostics, or break compatibility with existing consumers.
+
+Review is the **bootstrapping boundary**: it is the moment when a human confirms that the vocabulary is intentional, the definitions are correct, and the ownership is assigned. The build system enforces that every active concept in an approved pack has a matching review record.
+
+## Review Manifest Format
+
+Review records are stored as JSONL (one JSON object per line). Each record captures a single review decision:
+
+```jsonl
+{"decision_id":"rev-001","subject_type":"concept","subject_id":"supplier","decision":"approve","rationale":"Approved after stakeholder review","reviewer":"alice@acme.com","reviewed_at":"2025-06-01T10:00:00Z","definition_hash":"sha256:a1b2c3...","previous_definition_hash":null,"new_definition_hash":null}
+{"decision_id":"rev-002","subject_type":"concept","subject_id":"warehouse","decision":"approve","rationale":"Matches supply chain taxonomy","reviewer":"bob@acme.com","reviewed_at":"2025-06-01T11:00:00Z","definition_hash":"sha256:d4e5f6...","previous_definition_hash":null,"new_definition_hash":null}
+```
+
+### Fields
+
+| Field                        | Type   | Description                                                        |
+|------------------------------|--------|--------------------------------------------------------------------|
+| `decision_id`                | string | Unique identifier for this review decision.                        |
+| `subject_type`               | string | What is being reviewed. Currently `concept`.                       |
+| `subject_id`                 | string | The `id` of the concept being reviewed.                            |
+| `decision`                   | string | The review decision. See below for allowed values.                 |
+| `rationale`                  | string | Human-readable explanation for the decision.                       |
+| `reviewer`                   | string | Identifier for the reviewer (email, username, or system ID).       |
+| `reviewed_at`                | string | RFC 3339 timestamp of when the review occurred.                    |
+| `definition_hash`            | string | The definition hash at the time of review.                         |
+| `previous_definition_hash`   | string | (Optional) The hash before a minor amendment.                      |
+| `new_definition_hash`        | string | (Optional) The hash after a minor amendment.                       |
+
+## Allowed Decision Values
+
+| Decision                              | Effect                                                                 |
+|---------------------------------------|------------------------------------------------------------------------|
+| `approve`                             | The concept is approved for inclusion in the pack.                     |
+| `reject`                              | The concept must not appear in an approved pack.                       |
+| `deprecate`                           | The concept is approved but marked for future removal.                 |
+| `merge_into`                          | The concept should be merged into another concept.                     |
+| `split_required`                      | The concept covers too many meanings and must be split.                |
+| `needs_definition`                    | The concept lacks a definition and must be defined before approval.    |
+| `needs_owner`                         | The concept lacks an owner and must have one assigned.                 |
+| `minor_amendment_no_semantic_change`  | A cosmetic change (formatting, typo fix) that does not alter semantics. |
+
+Only `approve` and `minor_amendment_no_semantic_change` count as passing reviews for the purpose of review coverage.
+
+## Definition Hash Matching
+
+When building an approved pack, the builder validates that each active concept's `definition_hash` matches the hash recorded in the review manifest. This ensures that no concept has been modified after review without a corresponding review record.
+
+The builder checks hashes in order:
+
+1. **Match**: The current definition hash matches the reviewed hash. Pass.
+2. **Minor Amendment**: The decision is `minor_amendment_no_semantic_change` and the `new_definition_hash` matches the current hash. Pass.
+3. **Mismatch**: The current hash differs from the reviewed hash and no minor amendment covers the transition. The build emits an `unreviewed_concept` diagnostic.
+4. **No Review**: No review record exists for this concept. The build emits an `unreviewed_concept` diagnostic.
+
+### What Happens on Mismatch
+
+A hash mismatch blocks the approved build. The error message includes both the reviewed hash and the current hash:
+
+```
+[ERROR] unreviewed_concept: Definition hash mismatch for 'supplier': reviewed='sha256:a1b2c3...', current='sha256:x9y8z7...'
+  hint: Re-review or record minor_amendment_no_semantic_change
+```
+
+To resolve a mismatch:
+
+- **If the change is cosmetic** (whitespace, formatting, typo in examples): add a `minor_amendment_no_semantic_change` review record with `previous_definition_hash` set to the old hash and `new_definition_hash` set to the current hash.
+- **If the change is semantic** (definition text, status, meaning): add a full `approve` review record with the new definition hash.
+
+## Minor Amendment Path
+
+The minor amendment path exists because small formatting changes should not require a full re-review cycle. The rules are:
+
+1. A minor amendment must still have a `decision_id`, a `reviewer`, and a `reviewed_at` timestamp.
+2. The amendment must include both `previous_definition_hash` and `new_definition_hash`.
+3. The amendment does not reset the `meaning_version`---it is explicitly a non-semantic change.
+
+Example minor amendment record:
+
+```jsonl
+{"decision_id":"rev-042","subject_type":"concept","subject_id":"supplier","decision":"minor_amendment_no_semantic_change","rationale":"Fixed typo in counterexample","reviewer":"alice@acme.com","reviewed_at":"2025-06-05T14:00:00Z","definition_hash":"sha256:a1b2c3...","previous_definition_hash":"sha256:a1b2c3...","new_definition_hash":"sha256:m3n4o5..."}
+```
+
+## Operational Cost
+
+Any change to a concept's `text`, `examples`, `counterexamples`, or `status` changes the `definition_hash`. This means:
+
+- **Fixing a typo in an example** changes the hash and forces re-review (or a minor amendment).
+- **Adding a counterexample** changes the hash and forces re-review.
+- **Changing status** (e.g., `active` to `deprecated`) changes the hash.
+
+This is intentional. The hash covers the full definition surface to prevent silent semantic drift. Teams should expect that most changes to active concepts require a review record.
+
+## CLI Usage
+
+### Building an Approved Pack with Review
+
+```bash
+domainforge pack build \
+  --source "models/**/*.sea" \
+  --org acme \
+  --domain logistics \
+  --version 1.1.0 \
+  --meaning-version 1.1.0 \
+  --approval approved \
+  --review reviews/logistics-review.jsonl \
+  --previous-pack packs/acme-logistics-1.0.0.json \
+  --out packs/acme-logistics-1.1.0.json
+```
+
+The `--review` flag points to the JSONL file containing review records. The builder reads all records, validates coverage for active concepts, and checks definition hash matches.
+
+### Review Coverage Errors
+
+If any active concept lacks a passing review, the build fails:
+
+```
+[ERROR] unreviewed_concept: Concept 'new_concept' lacks review approval
+  hint: Add review decision for this concept
+```
+
+### Definition Hash Mismatch Errors
+
+If a concept's definition changed after review without a new review record:
+
+```
+[ERROR] unreviewed_concept: Definition hash mismatch for 'supplier': reviewed='sha256:a1b2c3...', current='sha256:x9y8z7...'
+  hint: Re-review or record minor_amendment_no_semantic_change
+```
+
+## Review Manifest Hash
+
+The builder computes a deterministic hash of the review manifest itself (`review_manifest_hash`). This hash is included in the pack so downstream consumers can verify that the review records used during the build have not been tampered with. The hash is computed by sorting review records by `decision_id` and hashing the canonical JSON representation.
+
+## See Also
+
+- [Semantic Packs](semantic-packs.md) for the overall pack system.
+- [Semantic Pack Signing and Verification](semantic-pack-signing.md) for the signing layer that runs after review.
+- [Semantic Diagnostic Codes](diagnostics.md) for `unreviewed_concept` and related codes.