domainforge 0.13.0

package/docs/reference/configuration.md

@@ -0,0 +1,202 @@
+# Configuration Reference
+
+This document lists configuration points for DomainForge across CLI usage, environment variables, registry files, and language bindings. Use it as a checklist when preparing environments, CI pipelines, or embedding the engine.
+
+## CLI configuration
+
+### Flags
+
+- `--format`: `human|json` for `parse`, `validate`, and `eval`; `calm|rdf|sbvr|dsl` for `project`.
+- `--registry <path>`: path to `.sea-registry.toml` for namespace resolution.
+- `--out <path>`: write output to a file instead of stdout.
+- `--allow-unknown`: enable three-valued logic (policies and validation tolerate missing facts).
+
+### Environment variables
+
+- `SEA_LOG`: logging level (`trace`, `debug`, `info`, `warn`, `error`).
+- `SEA_REGISTRY`: default registry path if `--registry` is omitted.
+- `SEA_COLOR`: set to `always`/`never`/`auto` to control colorized output.
+
+### Registry file (`.sea-registry.toml`)
+
+```toml
+[registry]
+paths = ["./models/shared", "./models/payments"]
+namespace = "finance"
+```
+
+- `paths`: search paths for imported namespaces.
+- `namespace`: optional default namespace when files omit `Namespace` declarations.
+- Schema lives at `schemas/sea-registry.schema.json`; invalid glob patterns or overlapping matches fail fast.
+- If a file matches multiple namespaces, the longest literal prefix wins; enable `--fail-on-ambiguity` (CLI) when you prefer a hard error.
+- See [`registry.md`](./registry.md) for full format and examples.
+
+## Rust crate features
+
+`domainforge-core` exposes feature flags that enable bindings and CLI components:
+
+- `cli`: builds the `sea` binary.
+- `python`: enables PyO3 bindings (`domainforge`).
+- `typescript`: enables napi-rs bindings (`@godspeedai/domainforge`).
+- `wasm`: builds WASM targets.
+- `serde`: serialization helpers (enabled by default).
+
+Use `cargo build -p domainforge-core --features "cli python"` to combine features; omit unneeded ones for faster builds.
+
+## Python package (`domainforge`)
+
+Configuration entry points:
+
+- Environment variable `SEA_LOG` respected by the underlying Rust logger.
+- Wheel selection: install prebuilt wheels from PyPI or build locally with `pip install maturin && maturin develop`.
+- ABI compatibility: Python 3.8+ on manylinux, macOS universal2, and Windows x86_64 (targets defined in `release-pypi.yml`).
+
+Programmatic options:
+
+- `Graph.parse(source: str, allow_unknown: bool = False)` — set `allow_unknown=True` to mirror CLI `--allow-unknown`.
+- `Graph.evaluate_policy(policy_json: str, allow_unknown: bool = False)` — toggles three-valued logic.
+
+## TypeScript package (`@godspeedai/domainforge`)
+
+Runtime configuration:
+
+- Node.js 18+ recommended (napi v9). Tested on Node 20 in CI.
+- `SEA_LOG` affects native logging if the environment variable is forwarded to the native module.
+- On macOS/Windows, ensure the package is installed for the matching architecture (arm64 vs x64); napi prebuilds cover common targets.
+
+API options:
+
+- `Graph.parse(source: string, options?: { allowUnknown?: boolean })` — optional `allowUnknown` flag.
+- `graph.evaluatePolicy(policyJson: string, options?: { allowUnknown?: boolean })`.
+
+## WASM
+
+Configuration knobs when embedding in the browser:
+
+- Module build: `npm run build:wasm` produces artifacts under `pkg/`.
+- Initialization: pass `init({ module_or_path })` with the correct URL; set `noModule` if using classic scripts.
+- Memory: for large graphs, increase `--stack-size` when bundling with wasm-pack if using custom builds.
+
+## Units and dimensions
+
+Configuration for custom unit systems:
+
+- Declare dimensions/units in the DSL or supply a registry file containing unit definitions for multiple files.
+- To enforce conversions, set a base unit per dimension; missing bases cause validation errors.
+- Use consistent namespace scoping for units when using registries.
+
+## Policy evaluation
+
+- `allow_unknown` / `allowUnknown` toggles Kleene three-valued logic.
+- Policies expect resource, entity, role, and relation IDs; use `sea graph` to inspect IDs before crafting policy JSON.
+- Regex evaluation uses Rust’s `regex` crate; set `REGEX_DEFAULT_MATCH_TIMEOUT_MS` (compile-time feature) if guarding against pathological patterns.
+
+## File locations
+
+- **CLI configuration**: command-line flags and environment variables.
+- **Registry**: `.sea-registry.toml` in project root or provided via `--registry`.
+- **Python**: project-level virtual environment; ensure system `libpython` matches wheel.
+- **TypeScript**: `node_modules/@godspeedai/domainforge` native addon; resolves platform-specific `.node` files.
+- **WASM**: `pkg/` artifacts plus TypeScript typings generated by `wasm-pack`.
+
+## CI usage
+
+- GitHub Actions workflows `release-*.yml` set `MATURIN_PYPI_TOKEN`, `NPM_TOKEN`, and `CARGO_REGISTRY_TOKEN` for publishing.
+- Cache heavy dependencies (`~/.cargo`, `node_modules`, `~/.cache/pip`) to speed up lint/test runs.
+- Example snippet:
+
+```yaml
+- name: Validate DSL fixtures
+  run: |
+    domainforge validate docs/examples/payment.sea --format json
+```
+
+## Troubleshooting configuration
+
+- **`sea` not found**: add `$HOME/.cargo/bin` to `PATH` or reinstall.
+- **Python import errors**: verify virtualenv uses CPython >=3.8 and matches wheel architecture.
+- **TypeScript build errors**: ensure `node-gyp` prerequisites are installed (Xcode CLTs on macOS, Build Tools on Windows).
+- **WASM MIME errors**: serve `.wasm` with `application/wasm` content type when hosting locally.
+
+## Defaults
+
+- Namespace defaults to `"default"` unless set via `Namespace` declaration or registry `namespace`.
+- Units are optional; resources without `units` accept unit-less quantities.
+- Logging defaults to `info` level.
+
+## See also
+
+- [`cli-commands.md`](./cli-commands.md) for command usage.
+- [`../how-tos/install-cli.md`](../how-tos/install-cli.md) for installation prerequisites per platform.
+- [`../explanations/versioning-strategy.md`](../explanations/versioning-strategy.md) for how configuration changes are versioned.
+
+## Logging configuration
+
+`domainforge-core` uses `env_logger` when built with the CLI feature and forwards logs through bindings.
+
+- Levels: `trace`, `debug`, `info`, `warn`, `error`.
+- Enable timestamps: set `RUST_LOG_STYLE=always` when using the CLI; bindings use the default style.
+- Example: `SEA_LOG=debug domainforge validate model.sea` prints parser tokens and validator decisions.
+
+## Output control
+
+- Redirect CLI output with `--out` to avoid mixing logs and structured data.
+- Python: methods return strings (CALM, RDF); write to files using standard IO.
+- TypeScript: prefer `fs.writeFileSync` after calling `graph.exportCalm()`.
+
+## Paths and resolution
+
+- When using `.sea-registry.toml`, paths are resolved relative to the registry file’s location.
+- Namespaces are case-sensitive; mixing `Finance` and `finance` results in distinct namespaces.
+- For CALM imports, the default namespace is `default` unless overridden via `--namespace` (not yet available) or via post-processing.
+
+## Performance tuning
+
+- Rust: build in `--release` for production evaluations; debug builds are slower but provide better error traces.
+- Python: leverage `maturin develop --release` to link against optimized native code.
+- TypeScript: Node picks up the release NAPI build; ensure `NODE_OPTIONS=--max-old-space-size=<MB>` when handling large graphs.
+
+## Security and sandboxing
+
+- CLI does not fetch remote resources; all inputs are local files or stdin.
+- Avoid piping untrusted CALM/DSL directly into production graphs without validation; always run `domainforge validate` first.
+- WASM embedding: host the `.wasm` file from the same origin to avoid CORS and ensure integrity; consider Subresource Integrity (SRI) hashes when serving statically.
+
+## Migrating configurations
+
+- When upgrading from 0.0.x to 0.1.x, review renamed flags (`--pretty` -> `fmt`) and new projections (roles/relations present in CALM/RDF exports).
+- Keep `SEA_REGISTRY` paths updated if you restructure directories; stale paths cause reference errors categorized under `E3xx` codes.
+
+## Platform-specific notes
+
+- **Windows**: prefer using PowerShell with UTF-8 encoding (`$OutputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8`) to avoid string decoding issues.
+- **macOS**: install Command Line Tools (`xcode-select --install`) before building NAPI modules; Homebrew Python may conflict with system Python—activate a virtualenv.
+- **Linux**: ensure `pkg-config` is available for building the Rust crate when linking system libraries.
+
+## Example configuration matrix
+
+| Use case | Recommended flags | Notes |
+| --- | --- | --- |
+| CI validation | `domainforge validate --format json` | Combine with `jq` to fail on violations. |
+| CALM export | `domainforge project --format calm --out calm.json` | Inspect metadata for `sea:version`. |
+| Policy eval with unknowns | `sea eval --allow-unknown` | Mirrors three-valued logic. |
+| Local doc testing | `SEA_LOG=debug domainforge parse docs/examples/*.sea` | Useful when writing tutorials. |
+
+## Persistent configuration
+
+Create a wrapper script (e.g., `./scripts/sea.sh`) to pin flags:
+
+```bash
+#!/usr/bin/env bash
+SEA_LOG=${SEA_LOG:-warn}
+exec sea --registry ./.sea-registry.toml "$@"
+```
+
+Check this script into your repo to standardize behavior across contributors.
+
+## Related files in the repository
+
+- `domainforge-core/src/cli/mod.rs` — defines CLI arguments and defaults.
+- `domainforge-core/src/python/` — Python binding constructors that accept flags.
+- `domainforge-core/src/typescript/` — TypeScript binding options for parse/evaluate.
+- `.github/workflows/` — environment variables used in CI and release jobs.