domainforge 0.13.0

package/docs/doc_guidelines.md

@@ -0,0 +1,53 @@
+# Documentation Guidelines — Diataxis + MECE
+
+This file describes expected structure and minimal content for new documentation pages under `docs/new_docs`.
+
+## General guidelines
+
+- Write for a single audience per document.
+- Keep documents focused: one main goal or concept.
+- Use examples and short runnable snippets.
+- Ensure linkages: each tutorial should link to how-tos and references.
+
+## MECE checklist per category
+
+### Tutorials
+
+- Audience and goal
+- Prereqs
+- Step-by-step instructions with runnable examples
+- Troubleshooting
+- Related docs and next steps
+
+### How-Tos
+
+- Short goal/one-liner
+- Step-by-step instructions (copy-paste-able)
+- Common pitfalls and minimal verification steps
+
+### Reference
+
+- Stable, canonical API signatures and CLI options
+- Example code snippets per API
+- Version and compatibility notes
+
+### Explanations
+
+- Problem statement and background
+- Conceptual diagrams and tradeoffs
+- When/how to use the concept and links to examples
+
+### Playbooks
+
+- Clear scope and preconditions
+- Step-by-step runbook with commands to run
+- Safety checks and rollback steps
+- Escalation/contacts
+
+## Tips for maintainers
+
+- Add `tags` at the top or metadata in the document so it can be surfaced by search/index.
+- When adding new reference docs, ensure automated tests (where relevant) are added to `tests/` or `typescript-tests/`.
+- Keep a single source of truth and avoid duplicated explanations. Link instead of copy-paste when possible.
+
+By following these guidelines we achieve clarity, maintainability, and pragmatic coverage for new users, engineers, and operators.

package/docs/explanations/README.md

@@ -0,0 +1,21 @@
+# Explanations — DomainForge
+
+Purpose: Provide background information, architecture, and conceptual explanations to help users understand why things work the way they do.
+
+MECE checklist:
+
+- Intended audience and scope
+- Conceptual diagrams and textual explanation
+- Trades and rationale
+- Links to related Reference and How-Tos
+
+## Current Explanations
+
+- [Architecture Overview](architecture-overview.md)
+- [Graph Store Design](graph-store-design.md)
+- [Cross-Language Binding Strategy](cross-language-binding-strategy.md)
+- [Policy Evaluation Logic](policy-evaluation-logic.md)
+- [Three-Valued Logic](three-valued-logic.md)
+- [Semantic Modeling Concepts](semantic-modeling-concepts.md)
+- [Versioning Strategy](versioning-strategy.md)
+- [Performance Benchmarks](performance-benchmarks.md)

package/docs/explanations/architecture-overview.md

@@ -0,0 +1,109 @@
+# Architecture Overview
+
+DomainForge (SEA) is built on a **Rust-first, multi-language** architecture designed to provide a single source of truth for semantic modeling while remaining accessible to developers in Python, TypeScript, and the web.
+
+## High-Level Architecture
+
+The system is organized as a central Rust core that projects its functionality outwards to other ecosystems through high-performance bindings.
+
+```mermaid
+graph TD
+    subgraph "Core (Rust)"
+        Grammar[Pest Grammar] --> Parser[AST Parser]
+        Parser --> Primitives[Core Primitives]
+        Primitives --> Graph[Graph Store]
+        Primitives --> Policy[Policy Engine]
+        Graph --> CALM[CALM Export]
+        Graph --> KG[Knowledge Graph]
+    end
+
+    subgraph "Bindings"
+        PyO3[PyO3 Bindings]
+        Napi[napi-rs Bindings]
+        Wasm[wasm-bindgen]
+    end
+
+    subgraph "Ecosystems"
+        Python[Python SDK]
+        TS[TypeScript SDK]
+        Browser[Web/React Apps]
+        CLI[CLI Tools]
+    end
+
+    Primitives --> PyO3
+    Primitives --> Napi
+    Primitives --> Wasm
+
+    PyO3 --> Python
+    Napi --> TS
+    Wasm --> Browser
+    Graph --> CLI
+```
+
+## Core Components (`domainforge-core`)
+
+The `domainforge-core` crate is the canonical implementation of the Semantic Enterprise Architecture DSL.
+
+### 1. Grammar & Parsing
+
+
+
+
+
+
+
+- **Source**: `domainforge-core/grammar/sea.pest`
+
+- **Technology**: [Pest](https://pest.rs/) (PEG parser)
+
+- **Role**: Defines the authoritative syntax. All language changes start here. The parser generates an Abstract Syntax Tree (AST) which is then lowered into semantic primitives.
+
+
+
+
+
+### 2. Primitives
+
+
+
+- **Location**: `domainforge-core/src/primitives/`
+
+
+- **Types**: `Entity`, `Resource`, `Flow`, `Instance`, `Policy`
+- **Role**: These are the domain objects. They are rich structs containing metadata, configuration, and relationships. They are designed to be serialized/deserialized and passed across FFI boundaries.
+
+
+
+### 3. Graph Store
+
+
+- **Location**: `domainforge-core/src/graph/mod.rs`
+- **Technology**: `IndexMap` (for deterministic iteration)
+
+- **Role**: Acts as the in-memory database for the model. It resolves references (e.g., linking a Flow to its source Entity) and enables graph traversal algorithms.
+
+### 4. Policy Engine
+
+- **Location**: `domainforge-core/src/policy/`
+- **Logic**: Three-valued logic (True, False, Unknown)
+- **Role**: Evaluates constraints against the model. It handles type inference and expression evaluation.
+
+## Binding Strategy
+
+We do not reimplement logic in other languages. Instead, we wrap the Rust types.
+
+- **Python**: Uses [PyO3](https://pyo3.rs/). Rust structs are exposed as Python classes. Methods call directly into Rust code.
+- **TypeScript**: Uses [napi-rs](https://napi.rs/). High-performance Node.js addons.
+ - **WASM**: Uses [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen). Allows the full compiler and policy engine to run in the browser.
+
+## Key Design Principles
+
+1. **Canonical Core**: Business logic exists only in Rust. If a bug is fixed in Core, it is fixed for Python, TS, and CLI simultaneously.
+2. **Deterministic Execution**: We use `IndexMap` instead of `HashMap` to ensure that policy evaluation order and export formats are stable across runs.
+3. **Zero-Copy (where possible)**: Bindings attempt to reference memory rather than copy it, though serialization is sometimes necessary for complex object graphs.
+
+## See Also
+
+- [Semantic Modeling Concepts](semantic-modeling-concepts.md)
+- [Cross-Language Binding Strategy](cross-language-binding-strategy.md)
+- [Graph Store Design](graph-store-design.md)

package/docs/explanations/cross-language-binding-strategy.md

@@ -0,0 +1,68 @@
+# Cross-Language Binding Strategy
+
+DomainForge is designed to be usable from Python, TypeScript, and WebAssembly while maintaining a single, high-performance Rust core. This document explains how we achieve this.
+
+## The "Wrapper" Pattern
+
+We do not rewrite business logic. We wrap Rust structs in language-specific containers.
+
+### Python (PyO3)
+
+- **Crate**: `pyo3`
+- **Implementation**: `domainforge-core/src/python/`
+- **Mechanism**: Rust structs are annotated with `#[pyclass]`. Methods are annotated with `#[pymethods]`.
+- **Memory**: Python objects hold a reference to the underlying Rust data. When the Python object is garbage collected, the Rust memory is freed (if no other references exist).
+
+### TypeScript (napi-rs)
+
+- **Crate**: `napi`
+- **Implementation**: `domainforge-core/src/typescript/`
+- **Mechanism**: We define structs that mirror the core primitives but are compatible with N-API.
+- **Async**: Heavy operations (like parsing large files) can be offloaded to the libuv thread pool to avoid blocking the Node.js event loop.
+
+### WebAssembly (wasm-bindgen)
+
+- **Crate**: `wasm-bindgen`
+- **Implementation**: `domainforge-core/src/wasm/`
+- **Mechanism**: Rust types are compiled to WASM. JavaScript "glue code" is generated to bridge the gap.
+- **Constraint**: WASM runs in a sandbox. File I/O is not directly available; input must be passed as strings or byte arrays.
+
+## Synchronization Rules
+
+To maintain consistency, we follow strict rules:
+
+1. **Core First**: Changes happen in `domainforge-core` first.
+2. **Update All Bindings**: If a field is added to `Entity` in Rust, it *must* be exposed in Python and TypeScript immediately.
+3. **Unified Testing**: `just all-tests` runs the test suites for all languages. A failure in Python bindings blocks the Rust PR.
+
+## Error Handling
+
+Rust errors (`Result<T, E>`) are mapped to language-specific exceptions:
+
+- **Rust**: `domainforge_core::error::SeaError`
+- **Python**: `sea.SeaError` (inherits from `Exception`)
+- **TypeScript**: `Error` object with specific code properties.
+
+## Build isolation and feature flags
+
+- Cargo features are mutually exclusive for Python and TypeScript builds; do **not** enable both in a single build.
+
+  ```toml
+  [features]
+  default = []
+  python = ["pyo3", "pythonize"]
+  typescript = ["napi", "napi-derive"]
+  three_valued_logic = []
+  ```
+
+- Build commands by target:
+  - **Python**: `maturin develop --features python,three_valued_logic` (or `maturin build --release ...`), then `pytest`/`just python-test`.
+  - **TypeScript**: `npm run build` (or `cargo build --features typescript,three_valued_logic` for debugging), then `npm test`.
+  - **WASM**: `wasm-pack build domainforge-core --target web --features wasm` (see the WASM tutorial for serving).
+- When switching between bindings, run `cargo clean` to avoid cross-contamination of artifacts and symbol leaks.
+
+## See Also
+
+- [Architecture Overview](architecture-overview.md)
+- [Adding a New Primitive](../playbooks/adding-new-primitive.md)
+- [Troubleshoot NAPI Builds](../how-tos/troubleshoot-napi-builds.md)

package/docs/explanations/graph-store-design.md

@@ -0,0 +1,47 @@
+# Graph Store Design
+
+The Graph Store (`domainforge-core/src/graph/mod.rs`) is the in-memory database that holds the semantic model. It is designed for performance, correctness, and deterministic behavior.
+
+## Data Structure: IndexMap
+
+We use `indexmap::IndexMap` instead of the standard library's `HashMap` for all primary collections (Entities, Flows, Resources).
+
+### Why?
+
+1. **Determinism**: `HashMap` iteration order is randomized (SipHash). This means running the same policy on the same model could produce errors in a different order, or result in different generated code output (e.g., Terraform files changing order every run).
+2. **Stability**: `IndexMap` preserves insertion order. This ensures that `forall` loops in policies always visit nodes in a predictable sequence.
+
+## Node and Edge Model
+
+The graph is not a generic adjacency matrix. It is a structured collection of typed stores:
+
+```rust
+pub struct Graph {
+    pub entities: IndexMap<ConceptId, Entity>,
+    pub resources: IndexMap<ConceptId, Resource>,
+    pub flows: Vec<Flow>, // Flows are edges
+    // ...
+}
+```
+
+- **Nodes**: Entities and Resources are nodes. They are indexed by `ConceptId` (a hash of namespace + name).
+- **Edges**: Flows are directed edges connecting nodes. They are stored separately to allow fast iteration over all interactions.
+
+## Query Patterns
+
+The graph supports specific access patterns optimized for policy evaluation:
+
+- **Lookup by ID**: O(1) access to any Entity or Resource.
+- **Flow Traversal**: "Get all flows originating from Entity X".
+- **Type Filtering**: "Get all Resources of type 'database'".
+
+## Performance Characteristics
+
+- **Parsing**: Linear time relative to file size.
+- **Graph Construction**: Near-linear. Resolution of references happens in a second pass.
+- **Policy Evaluation**: Depends on complexity. Simple `forall` is O(N). Nested quantifiers can be O(N^2).
+
+## See Also
+
+- [Architecture Overview](architecture-overview.md)
+- [Policy Evaluation Logic](policy-evaluation-logic.md)

package/docs/explanations/performance-benchmarks.md

@@ -0,0 +1,63 @@
+# Performance Benchmarks for Three-Valued Logic
+
+This note summarizes the tri-state (three-valued) performance benchmarks and how to run them.
+
+## Why it matters
+
+Policy evaluation defaults to three-valued logic. Benchmarks show the runtime overhead is modest (≈10% worst case) and often neutral or faster when data contains `Unknown` values.
+
+## How to run
+
+- **Criterion suite (recommended)**: statistical results and HTML reports.
+
+  ```bash
+  cd domainforge-core
+  cargo bench --bench null_overhead
+  # view reports under target/criterion/
+  ```
+
+- **Quick micro-benchmark (sanity)**:
+
+  ```bash
+  cargo test --release -p domainforge-core --lib -- --ignored bench_microbench --nocapture
+  ```
+
+## Results snapshot
+
+- Criterion output shows lower/median/upper bounds of the 95% confidence interval. Use the median for comparisons.
+- Sample findings from recent runs (1k items):
+
+| Benchmark | Median (µs) | vs strict | Notes |
+| --- | --- | --- | --- |
+| Strict sum (baseline) | 8.23 | baseline | No null handling |
+| Nullable, 0% nulls | 9.09 | +10.4% | Worst case |
+| Nullable, 10% nulls | 7.61 | -7.5% | Typical |
+| Nullable, 50% nulls | 4.05 | -51% | Sparse |
+| Non-null, 10% nulls | 7.33 | -11% | Filters nulls |
+
+- Micro-benchmark sanity check: ~4.9% overhead at 10% nulls.
+
+## When to re-run
+
+- After changing policy evaluation, `ThreeValuedBool`, or Decimal handling.
+- Before releases to confirm no regressions in tri-state toggling or parsing hot paths.
+
+## Appendix: raw outputs and files
+
+- Benchmark code: `domainforge-core/benches/null_overhead.rs`
+- Micro-bench: `domainforge-core/src/policy/three_valued_microbench.rs`
+- Sample raw Criterion output:
+
+  ```
+  sum_baseline/sum_strict_1k
+                          time:   [7.9087 µs 8.2293 µs 8.6586 µs]
+
+  three_valued_sum/sum_nullable/0pct_null
+                          time:   [8.5873 µs 9.0864 µs 9.6445 µs]
+  ```
+
+## See also
+
+- [Three-Valued Logic](three-valued-logic.md)
+- [Policy Evaluation Logic](policy-evaluation-logic.md)
+- [CLI Commands](../reference/cli-commands.md) (`bench` targets are Rust-only; CI can run `cargo bench`)

package/docs/explanations/policy-evaluation-logic.md

@@ -0,0 +1,106 @@
+# Policy Evaluation Logic
+
+The policy engine is the brain of DomainForge. It verifies that an architecture model adheres to defined rules. This document explains how policies are parsed, evaluated, and enforced.
+
+## Evaluation Flow
+
+```mermaid
+graph LR
+    A[Source .sea File] --> B[Parser]
+    B --> C[AST]
+    C --> D[Graph Store]
+    D --> E[Policy Engine]
+    E --> F{Result}
+    F -->|Pass| G[Success]
+    F -->|Fail| H[Validation Error]
+```
+
+## Expression Parsing
+
+Policies are written in a subset of the SEA DSL designed for logic. Expressions are parsed into an expression tree defined in `domainforge-core/src/policy/expression.rs`.
+
+Common expression types:
+
+- **Quantifiers**: `forall`, `exists`
+- **Comparisons**: `==`, `!=`, `>`, `<`
+- **Logical Operators**: `and`, `or`, `not`, `implies`
+- **Property Access**: `f.from.type`
+
+## Variable Binding
+
+When a quantifier is evaluated (e.g., `forall f in Flow`), the engine:
+
+1. Iterates deterministically over the collection (`Flow`).
+2. Binds the current item to the variable name (`f`).
+3. Evaluates the inner expression body with this context.
+
+## Evaluation Order
+
+Evaluation is strictly deterministic due to the use of `IndexMap` in the underlying graph store.
+
+1. **Global Scope**: Constants and global definitions are loaded.
+2. **Policy Iteration**: Policies are evaluated in the order they appear in the source file (or import order).
+3. **Short-Circuiting**:
+   - `forall`: Stops at the first `False` result (returns `False`).
+   - `exists`: Stops at the first `True` result (returns `True`).
+
+## Three-Valued Logic
+
+The engine uses Kleene's three-valued logic (`True`, `False`, `Unknown`).
+
+- If a property is missing (e.g., `f.encryption`), the comparison returns `Unknown` rather than crashing or defaulting to false.
+- This allows policies to distinguish between "bad architecture" (False) and "incomplete architecture" (Unknown).
+
+### Runtime toggle
+
+- Three-valued logic is **on by default**. Switch to strict boolean evaluation via:
+  - Rust: `graph.set_evaluation_mode(false)`
+  - Python: `graph.set_evaluation_mode(False)`
+  - TypeScript/WASM: `graph.setEvaluationMode(false)`
+- Use this only for environments that require binary pass/fail semantics; unknown facts will then be treated as errors.
+
+## Side Effects
+
+Policy evaluation is **read-only**. It cannot modify the graph. It produces a list of `ValidationResult` objects, which contain:
+- The policy name.
+- The result (Pass/Fail/Unknown).
+- A trace of the specific elements that caused a failure (e.g., the specific Flow that violated the rule).
+
+### ValidationResult & TraceEntry schema
+
+The policy engine returns a structured `ValidationResult` that is convenient to consume in CI and automation. The JSON schema is:
+
+```json
+{
+    "policyName": "string",
+    "result": "Pass|Fail|Unknown",
+    "violations": [
+        {
+            "id": "string",         // UUID of the primitive involved
+            "type": "Entity|Resource|Flow|Instance|Role|Relation",
+            "displayName": "string", // optional human-readable name
+            "path": ["string"],      // optional path (e.g., ["flows", "0"]) for locating in larger payloads
+            "details": {              // optional free-form details useful for diagnostics
+                 "field": "value"
+            }
+        }
+    ]
+}
+```
+
+Example `ValidationResult` (policy failure):
+
+```json
+{
+    "policyName": "payment_threshold",
+    "result": "Fail",
+    "violations": [
+        { "id": "3a3e5d08-...", "type":"Flow", "displayName":"Money transfer", "path":["flows","0"], "details":{"quantity": 15000, "expectedMax": 10000} }
+    ]
+}
+```
+
+## See Also
+
+- [Three-Valued Logic](three-valued-logic.md)
+- [Graph Store Design](graph-store-design.md)

package/docs/explanations/semantic-modeling-concepts.md

@@ -0,0 +1,109 @@
+# Semantic Modeling Concepts
+
+DomainForge uses a specific set of primitives to model enterprise architecture. Unlike generic diagramming tools, these primitives have semantic meaning that allows for automated analysis, policy enforcement, and code generation.
+
+## The Core Primitives
+
+### 1. Entity
+
+**What it is**: A logical component, service, actor, or system boundary.
+**When to use**: Use Entities to represent *who* or *what* is performing actions.
+**Examples**: `Customer`, `PaymentService`, `InventorySystem`.
+
+```sea
+Entity "PaymentService"
+```
+
+### 2. Resource
+
+**What it is**: Passive data, infrastructure, or state that is acted upon.
+**When to use**: Use Resources to represent databases, queues, file stores, or API endpoints.
+**Examples**: `UserDatabase`, `OrderQueue`, `S3Bucket`.
+
+```sea
+Resource "UserDatabase" units
+```
+
+`units` denotes a count-based unit (i.e., number of instances/items). Use `units` for raw counts or specify another unit (e.g., `kg`, `USD`) when applicable; this aligns the resource with the `Unit` registry so flow quantities and aggregations can be compared consistently.
+
+### 3. Flow
+
+**What it is**: A directional interaction between two concepts, often involving a resource.
+**When to use**: Use Flows to model data movement, API calls, or dependencies.
+**Key Attribute**: Flows are strictly typed (e.g., `read`, `write`, `trigger`).
+
+```sea
+flow "Payment" {
+    from = "PaymentService",
+    to = "UserDatabase",
+    interaction = "write",
+    quantity = 1
+}
+```
+
+### 4. Instance
+
+**What it is**: A concrete realization of an Entity or Resource in a specific environment.
+**When to use**: Use Instances to model physical deployments (e.g., "Production Payment Service" vs "Staging Payment Service").
+
+```sea
+Instance prod_payment_db of "UserDatabase" {
+    env: "production",
+    region: "us-east-1"
+}
+```
+
+### 5. Policy
+
+**What it is**: A constraint or rule that must be true for the model to be valid.
+**When to use**: Use Policies to enforce security, compliance, or architectural standards.
+
+```sea
+Policy secure_writes as:
+    forall f in flows: (f.to = "UserDatabase" and f.quantity >= 1)
+```
+
+## Modeling Patterns
+
+### The "Actor-Action-Object" Pattern
+
+Most architectural interactions can be modeled as:
+
+- **Actor**: An Entity (e.g., WebServer)
+- **Action**: A Flow (e.g., reads from)
+- **Object**: A Resource (e.g., Database)
+
+### The "Service-to-Service" Pattern
+
+Direct communication between services is modeled as a Flow between two Entities.
+
+- `Frontend` -> (Flow: HTTP/REST) -> `Backend`
+
+## Semantic vs. Visual
+
+In DomainForge, the *meaning* comes first. A box on a diagram is just a rendering of an Entity. Because the model is semantic, we can ask questions like:
+
+- "Show me all services that write to the UserDatabase."
+- "Are there any flows crossing trust boundaries without encryption?"
+
+## Semantic Packs
+
+While the primitives above define individual concepts in a single .sea file, **semantic packs** provide organization-wide vocabulary governance. A semantic pack is a deterministic, review-gated, signed JSON artifact that defines an organization's approved business concepts, relations, metrics, dimensions, units, aliases, and mapping rules.
+
+Semantic packs serve as the authoritative vocabulary that the DomainForge LSP and CI validators use to check .sea source files. When you write `Entity "PaymentService"` in a .sea file, the LSP resolves that name against the loaded semantic pack and reports diagnostics if the term is unknown, ambiguous, deprecated, or rejected.
+
+Key properties of semantic packs:
+
+- **Review-gated**: Every concept in an approved pack must have a matching human review record.
+- **Signed**: Packs can be signed with Ed25519 to provide tamper evidence.
+- **Three-valued truth**: Concept resolution returns `valid`, `invalid`, or `unknown`---not just true/false.
+- **Deterministic**: Two builds from identical inputs produce bit-for-bit identical output.
+
+For full details, see [Semantic Packs](../semantic-packs.md).
+
+## See Also
+
+- [Policy Evaluation Logic](policy-evaluation-logic.md)
+- [Architecture Overview](architecture-overview.md)
+- [Semantic Packs](../semantic-packs.md)
+- [Semantic Diagnostic Codes](../diagnostics.md)

package/docs/explanations/three-valued-logic.md

@@ -0,0 +1,66 @@
+# Three-Valued Logic
+
+DomainForge uses **Kleene's Three-Valued Logic (3VL)** for policy evaluation. This is a critical design choice for modeling architecture, where information is often incomplete.
+
+## The Three States
+
+1. **True**: The statement is demonstrably true.
+2. **False**: The statement is demonstrably false.
+3. **Unknown**: There is insufficient information to determine truth.
+
+## Why Not Boolean?
+
+In standard boolean logic, `null` or missing values often default to `False` or cause errors. In architecture modeling:
+
+- **Scenario**: You have a policy "All databases must be encrypted".
+- **Model**: You define a database `UserDB` but forget to specify the `encrypted` property.
+- **Boolean Logic**: `UserDB.encrypted == true` evaluates to `False`. The policy fails. You think the DB is unencrypted.
+- **3VL**: `UserDB.encrypted` is `Unknown`. The comparison evaluates to `Unknown`. The policy result is `Unknown`.
+
+This distinction tells the architect: "I don't know if this is safe yet," rather than "This is unsafe."
+
+## Truth Tables
+
+### NOT (Negation)
+| Input | Result |
+|-------|--------|
+| True | False |
+| False | True |
+| Unknown | Unknown |
+
+### AND (Conjunction)
+| A | B | Result |
+|---|---|--------|
+| True | True | True |
+| True | False | False |
+| True | Unknown | Unknown |
+| False | True | False |
+| False | False | False |
+| False | Unknown | False |
+| Unknown | True | Unknown |
+| Unknown | False | False |
+| Unknown | Unknown | Unknown |
+
+### OR (Disjunction)
+| A | B | Result |
+|---|---|--------|
+| True | True | True |
+| True | False | True |
+| True | Unknown | True |
+| False | True | True |
+| False | False | False |
+| False | Unknown | Unknown |
+| Unknown | True | True |
+| Unknown | False | Unknown |
+| Unknown | Unknown | Unknown |
+
+## Practical Implications
+
+When writing policies:
+
+- **Strict Enforcement**: If you want to fail on unknowns, check for them explicitly or ensure your CI pipeline treats `Unknown` as a failure for production releases.
+- **Progressive Modeling**: 3VL allows models to evolve. You can run policies against a partial sketch of a system without getting flooded with false positives.
+
+## See Also
+
+- [Policy Evaluation Logic](policy-evaluation-logic.md)