domainforge 0.13.0

package/docs/plans/cli-ast.md

@@ -0,0 +1,29 @@
+# CLI AST Emission Plan
+
+## Summary
+
+The current `sea` CLI emits **AST v2** (legacy map-based structure). SEA consumes **AST v3** (declarations list), so we rely on `tools/ast_v2_to_v3.py` as a bridge. This works, but **flow annotations are not preserved** in v2 output, which makes downstream linting and IR generation incomplete.
+
+## Current Behavior
+
+- CLI emits v2 AST (`entities/resources/flows` maps).
+- Flow `attributes` are always `{}` even when annotations are present in the SEA-DSL.
+- SEA converts v2 → v3 via `tools/ast_v2_to_v3.py`, but the annotations are already lost.
+
+## Required Fix
+
+**Goal:** Update CLI to emit **AST v3** directly with full annotations on flows.
+
+Steps:
+1. Update `domainforge-core` parser/serializer to expose flow annotations in the AST (not just entities/resources).
+2. Add a CLI flag or default output mode for **AST v3**.
+3. Ensure emitted AST schema matches `tools/schemas/ast-v3.schema.json` in SEA.
+4. Add regression tests: parse a SEA file with `@cqrs`, `@tx`, `@idempotency`, `@read_model` and verify they appear in flow annotations.
+
+## Impact
+
+- Removes the v2 → v3 shim in SEA.
+- Enables correct flow linting and CQRS classification without SDS fallback.
+- Unblocks future AST v4 migrations cleanly.
+
+it should actually emit AST v3 directly with full flow annotations (including the new custom annotations capability).

package/docs/plans/expression-bindings-and-normalizer-integration.md

@@ -0,0 +1,174 @@
+# ADR: Expression/Policy Language Bindings
+
+**Status:** Proposed  
+**Date:** 2025-12-17  
+**Authors:** DomainForge Architecture Team  
+**Depends On:** [Canonical Expression Normalizer](./canonical-normalizer.md)
+
+## Context
+
+The canonical expression normalizer has been implemented in Rust core, but `Expression` and `Policy` types are not exposed in Python, TypeScript, or WASM bindings. This limits the ability for external consumers to:
+
+1. Programmatically construct policy expressions
+2. Use the `normalize()` and `is_equivalent()` methods
+3. Evaluate policies from language-native code
+
+## Decision
+
+Implement full Expression and Policy bindings for all three target languages.
+
+## Scope
+
+### Phase 1: Expression Bindings
+
+Create Expression class/struct with factory methods for all variants:
+
+| Variant         | Factory Method                                                |
+| --------------- | ------------------------------------------------------------- |
+| Literal         | `Expression.literal(value)`                                   |
+| Variable        | `Expression.variable(name)`                                   |
+| Binary          | `Expression.binary(op, left, right)`                          |
+| Unary           | `Expression.unary(op, operand)`                               |
+| Quantifier      | `Expression.quantifier(kind, var, collection, condition)`     |
+| MemberAccess    | `Expression.member_access(object, member)`                    |
+| Cast            | `Expression.cast(operand, target_type)`                       |
+| Aggregation     | `Expression.aggregation(function, collection, field, filter)` |
+| QuantityLiteral | `Expression.quantity(value, unit)`                            |
+| TimeLiteral     | `Expression.time(timestamp)`                                  |
+| IntervalLiteral | `Expression.interval(start, end)`                             |
+
+### Phase 2: Normalization Methods
+
+Add to Expression bindings:
+
+- `normalize()` → `NormalizedExpression`
+- `is_equivalent(other)` → `bool`
+- `to_string()` → display representation
+
+### Phase 3: Policy Bindings
+
+Create Policy class with:
+
+- Constructor: `Policy.new(name, expression)`
+- Builder methods: `with_modality()`, `with_priority()`, etc.
+- `evaluate(graph)` → `EvaluationResult`
+- `normalized_expression()` → `NormalizedExpression`
+
+### Phase 4: NormalizedExpression Bindings
+
+Expose wrapper with:
+
+- `stable_hash()` → deterministic hash
+- `inner()` → access normalized expression
+- `to_string()` → canonical string form
+
+## Files to Modify
+
+| File                                | Changes                                      |
+| ----------------------------------- | -------------------------------------------- |
+| `domainforge-core/src/python/policy.rs`     | Add Expression, Policy, NormalizedExpression |
+| `domainforge-core/src/typescript/policy.rs` | Add Expression, Policy, NormalizedExpression |
+| `domainforge-core/src/wasm/policy.rs`       | Add Expression, Policy, NormalizedExpression |
+| `tests/test_*.py`                   | Python binding tests                         |
+| `typescript-tests/*.test.ts`        | TypeScript binding tests                     |
+
+## Estimated Effort
+
+- **Per binding**: ~200-300 lines of Rust wrapper code
+- **Total**: ~600-900 lines + tests
+- **Timeline**: 1-2 days of focused work
+
+## Alternatives Considered
+
+1. **JSON serialization only** - Parse expressions from JSON instead of factory methods (rejected: less ergonomic)
+2. **String parsing** - Parse DSL strings in bindings (rejected: duplicates parser logic)
+3. **Keep internal** - Only use in Rust/LSP (current state, deferred approach)
+
+---
+
+# ADR: Normalizer CLI Command
+
+**Status:** Proposed  
+**Date:** 2025-12-17
+
+## Context
+
+The canonical normalizer is implemented but not accessible from CLI.
+
+## Decision
+
+Add `domainforge normalize <expr>` command for interactive normalization.
+
+## Proposed Usage
+
+```bash
+# Normalize an expression string
+domainforge normalize "b AND a"
+# Output: (a AND b)
+
+# Show equivalence
+domainforge normalize --check-equiv "a AND b" "b AND a"
+# Output: Equivalent (hash: 0x7f3a...)
+
+# Output normalized form with hash
+domainforge normalize --json "true AND x"
+# Output: {"normalized": "x", "hash": "0x..."}
+```
+
+## Files to Modify
+
+| File                         | Changes                          |
+| ---------------------------- | -------------------------------- |
+| `domainforge-core/src/bin/sea.rs`    | Add `normalize` subcommand       |
+| `domainforge-core/src/parser/mod.rs` | May need expression-only parsing |
+
+## Dependencies
+
+- Requires expression-only parser (currently parses full SEA files)
+- May need `clap` subcommand additions
+
+---
+
+# ADR: LSP Hover Normalization Integration
+
+**Status:** Proposed  
+**Date:** 2025-12-17  
+**Depends On:** Canonical Normalizer (complete)
+
+## Context
+
+LSP hover currently displays policy expressions using `expr.to_string()`. This can produce non-deterministic output for semantically equivalent expressions.
+
+## Decision
+
+Use normalized form in hover signatures for deterministic display.
+
+## Proposed Changes
+
+### domainforge-lsp
+
+| File                           | Changes                                                  |
+| ------------------------------ | -------------------------------------------------------- |
+| `src/hover/symbol_resolver.rs` | Use `expr.normalize().to_string()` for policy signatures |
+
+### Example
+
+**Before:**
+
+```
+Policy tax_check as:
+    (rate > 0) AND (valid == true)
+```
+
+**After (normalized):**
+
+```
+Policy tax_check as:
+    ((0 < rate) AND valid)
+```
+
+## Considerations
+
+- Normalized form may differ from source - consider showing both
+- Performance: normalization is cheap but runs on every hover
+- May want configuration option for "show original vs normalized"