feat: publication-ready scaffold (AbteeX/LumynaX unified surface)

.gitattributes

@@ -1,35 +1,5 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+* text=auto
+*.py text eol=lf
+*.md text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf

LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 AbteeX AI Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,204 @@
+---
+license: apache-2.0
+library_name: custom
+tags:
+- abteex-ai-labs
+- lumynax
+- sovereigncode
+- data-capsule
+- coding-agent
+- governance
+- new-zealand
+- aotearoa
+- sovereign-ai
+- local-first
+language:
+- en
+- mi
+---
+
+# AbteeX SovereignCode
+
+<!-- abteex-sovereigncode-card:v1 -->
+
+<p align="center"><em>Sovereign intelligence, held in the light.</em></p>
+<p align="center"><em>Ko te mārama te tūāpapa &mdash; the light is the foundation.</em></p>
+
+<p align="center">
+  <strong>A local-first coding agent with Data Capsule sovereignty controls.</strong><br/>
+  AbteeX AI Labs &mdash; Aotearoa New Zealand.
+</p>
+
+<p align="center">
+  <a href="#what-it-is">What it is</a> &middot;
+  <a href="#quickstart">Quickstart</a> &middot;
+  <a href="#data-capsule">Data Capsule</a> &middot;
+  <a href="#policy-decision-point">Policy decision point</a> &middot;
+  <a href="#audit-ledger">Audit ledger</a> &middot;
+  <a href="#roadmap">Roadmap</a> &middot;
+  <a href="#companion-products">Companions</a>
+</p>
+
+![SovereignCode](https://img.shields.io/badge/AbteeX-SovereignCode-e08a2c?style=for-the-badge) ![Stage scaffold](https://img.shields.io/badge/stage-product%20scaffold-0a0a0b?style=for-the-badge) ![Runtime python](https://img.shields.io/badge/runtime-python%203.11%2B-726b62?style=for-the-badge) ![License Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-9a5416?style=for-the-badge) ![Card v1](https://img.shields.io/badge/card-v1-111827?style=for-the-badge)
+
+## What It Is
+
+**AbteeX SovereignCode** is the AbteeX AI Labs coding-agent product built on the LumynaX release family. It is conceptually close to an OpenCode-style terminal coding assistant, but the centre of gravity is *AI sovereignty*: every model call, tool call, file edit, and outbound action is evaluated against a **Data Capsule** policy before execution.
+
+It is for organisations that want local-first coding assistance without losing control over source code, regulated records, Iwi or community-held data, health data, procurement records, or other sensitive operational context.
+
+## Five Commitments
+
+| Commitment | Product Meaning |
+| --- | --- |
+| Data capsules | Every workspace, dataset, or customer context can carry machine-readable purpose, residency, retention, export, and training controls. |
+| Policy before tools | Shell commands, file writes, network calls, commits, and model calls are checked **before** execution. |
+| Local-first inference | High-impact or restricted data routes to local or LumynaX-governed models by default. |
+| Human review | External effects require explicit approval, visible diffs, and audit records. |
+| Provenance | Model identity, source files, policy decisions, prompts, outputs, and release metadata remain traceable. |
+
+## Why This Is Different
+
+Most coding agents optimise for speed. SovereignCode optimises for **controlled autonomy**: it can still plan, edit, test, and explain code, but it treats data rights, residency, consent, provenance, and human approval as *runtime primitives* &mdash; not policy text on a wiki.
+
+## Quickstart
+
+Clone and install:
+
+```bash
+hf download AbteeXAILab/sovereigncode --local-dir sovereigncode --repo-type model
+cd sovereigncode
+pip install -r requirements.txt
+```
+
+Evaluate an **allowed** local-edit request against the example capsule:
+
+```bash
+python -m sovereigncode.cli evaluate \
+  --capsule examples/capsule.restricted-nz-code.json \
+  --request examples/request.allowed-local-edit.json
+```
+
+Expected: `allowed: true` with obligations including `write_immutable_audit_record`, `preserve_capsule_id_in_agent_trace`, and `show_diff_before_write_or_commit`.
+
+Evaluate a **denied** training request:
+
+```bash
+python -m sovereigncode.cli evaluate \
+  --capsule examples/capsule.restricted-nz-code.json \
+  --request examples/request.denied-training.json \
+  --allow-denied-exit-zero
+```
+
+Expected: `allowed: false` with reason `capsule.training_allowed = false`.
+
+## Data Capsule
+
+A Data Capsule is the policy envelope attached to a workspace, dataset, tenant, case, source-file set, or prompt context.
+
+```json
+{
+  "capsule_id": "cap-nz-code-001",
+  "subject_id": "abx-workspace",
+  "jurisdiction": "NZ",
+  "sensitivity": "restricted",
+  "allowed_purposes": ["coding_assistance", "inference", "test_generation"],
+  "denied_purposes": ["ad_training", "third_party_resale"],
+  "resident_regions": ["NZ"],
+  "data_classes": ["source_code", "policy", "runtime_logs"],
+  "retention_days": 14,
+  "export_allowed": false,
+  "training_allowed": false
+}
+```
+
+Capsules carry:
+
+- `allowed_purposes` / `denied_purposes`
+- `resident_regions`
+- `retention_days`
+- `training_allowed` / `export_allowed`
+- `data_classes`
+- `schema_context`
+- `consent_record`
+
+## Policy Decision Point
+
+The PDP answers one question before every sensitive action:
+
+> *Can this actor, for this purpose, in this region, using this model/tool, touch this capsule?*
+
+Decisions are one of: `allow`, `deny`, or `allow_with_obligations`. Every decision produces a structured record:
+
+| Field | Meaning |
+| --- | --- |
+| `capsule_id` | The capsule the action touches. |
+| `actor` | Who initiated the action. |
+| `purpose` | Declared purpose (e.g. `coding_assistance`). |
+| `action` | The tool action requested. |
+| `model_id` | Resolved model identity (often via [MaramaRoute](https://huggingface.co/AbteeXAILab/marama-route)). |
+| `decision` | `allow` / `deny` / `allow_with_obligations`. |
+| `reasons` | Ordered list of policy reasons. |
+| `obligations` | Required follow-up actions. |
+| `request_hash` | Stable SHA-256 of the canonical request. |
+| `timestamp` | ISO 8601 UTC. |
+
+## Tool Broker
+
+The broker is the enforcement layer for shell commands, file writes, git commits, network calls, package installs, model calls, retrieval queries, and training jobs. Every tool call passes through the PDP first.
+
+## Audit Ledger
+
+Every decision creates an immutable audit record. Records are append-only and hash-chained &mdash; usable as evidence for regulators, customers, and internal review.
+
+## Sovereignty & Run Contract
+
+| Field | Value |
+| --- | --- |
+| Publisher | AbteeX AI Labs |
+| Family | LumynaX sovereign products |
+| Sovereign intent | Local-first coding assistance with policy-before-tools enforcement. |
+| Runtime residency | Operator's environment; restricted data routes to local or LumynaX-governed models. |
+| License | Apache-2.0 |
+| Stage | Product scaffold &mdash; PDP and audit engine executable; full terminal loop in P1. |
+| Router integration | First-class with [LumynaX MaramaRoute](https://huggingface.co/AbteeXAILab/marama-route). |
+
+## Roadmap
+
+| Milestone | Outcome |
+| --- | --- |
+| **P0 scaffold** *(now)* | Policy engine, audit records, CLI, examples, docs. |
+| **P1 terminal loop** | Local terminal agent with plan / edit / test workflow. |
+| **P2 tool broker** | Policy wrappers for shell, git, file writes, package installs, HTTP. |
+| **P3 MaramaRoute integration** | Sovereign model routing for every model call. |
+| **P4 workspace UI** | Browser console showing plan, policy, diffs, tests, approvals. |
+| **P5 enterprise controls** | Tenant policies, SSO hooks, signed audit exports, policy packs. |
+
+## Source Grounding
+
+The sovereignty model is inspired by the Data Capsule pattern described in the ScienceDirect article identified by PII `S2543925125000166` &mdash; especially its emphasis on semantic metadata, ontology-based federation, and dynamic usage-control policies. This repository uses that idea as product architecture inspiration; it does not copy the paper text or implementation.
+
+## Companion Products
+
+| Product | Purpose |
+| --- | --- |
+| [LumynaX MaramaRoute](https://huggingface.co/AbteeXAILab/marama-route) | Sovereign model router across the LumynaX release family. SovereignCode delegates model selection to MaramaRoute. |
+| [LumynaX Live Demo](https://huggingface.co/spaces/AbteeXAILab/lumynax-live-demo) | Public browser demo of a LumynaX-infused GGUF release. |
+| [SovereignCode Live](https://huggingface.co/spaces/AbteeXAILab/sovereigncode-demo) | Interactive policy evaluator &mdash; paste a capsule and request, see the decision. |
+| [AbteeXAILab on Hugging Face](https://huggingface.co/AbteeXAILab) | The full LumynaX release family. |
+
+## Aotearoa Kaupapa
+
+SovereignCode is built in and for Aotearoa New Zealand. Iwi data sovereignty, health-information governance, and procurement transparency are not retro-fits &mdash; they are the runtime contract. The product treats data rights, residency, consent, provenance, and human approval as primitives.
+
+## Limitations & Responsible Use
+
+- The PDP enforces declared policy. It does not detect every possible deceptive prompt or covert exfiltration channel.
+- The current release is a *product scaffold*. Full terminal loop, tool broker, and workspace UI ship in P1–P4.
+- For high-impact decisions, use human review and domain-specific evaluation.
+- Audit records help, but auditability is a process &mdash; not a guarantee.
+
+---
+
+<p align="center"><em>Local roots, global work. &middot; Sovereignty is a design property, not a deployment option.</em></p>
+<p align="center"><sub>AbteeX AI Labs &middot; <a href="https://abteex.com">abteex.com</a> &middot; <a href="https://lumynax.com">lumynax.com</a> &middot; <a href="https://huggingface.co/AbteeXAILab">huggingface.co/AbteeXAILab</a></sub></p>

architecture.md

@@ -0,0 +1,95 @@
+# AbteeX SovereignCode Architecture
+
+## North Star
+
+SovereignCode should feel like a capable local coding agent, but every action must be accountable to data sovereignty and AI sovereignty controls. The product should never silently send sensitive code or governed data to a remote model, execute an external command, or publish a change without a visible decision trail.
+
+## Control Plane
+
+```text
+User intent
+  -> Workspace indexer
+  -> Data Capsule resolver
+  -> Sovereignty policy decision point
+  -> LumynaX MaramaRoute model selection
+  -> Tool broker
+  -> Human review gate
+  -> Audit ledger
+```
+
+## Core Concepts
+
+### Data Capsule
+
+A Data Capsule is the policy envelope attached to a workspace, dataset, tenant, case, source file set, or prompt context. It carries:
+
+- `allowed_purposes`
+- `denied_purposes`
+- `resident_regions`
+- `retention_days`
+- `training_allowed`
+- `export_allowed`
+- `data_classes`
+- `schema_context`
+- `consent_record`
+
+### Policy Decision Point
+
+The policy decision point answers one question before every sensitive action: can this actor, for this purpose, in this region, using this model/tool, touch this capsule?
+
+The first implementation lives at `src/tinyluminax/products/sovereigncode/policy.py`.
+
+### Tool Broker
+
+The broker is the enforcement layer for:
+
+- Shell commands
+- File writes
+- Git commits
+- Network calls
+- Package installs
+- Model calls
+- Retrieval queries
+- Training or distillation jobs
+
+Each tool call receives a decision: allow, deny, or allow with obligations.
+
+### Audit Ledger
+
+Every decision creates a record containing:
+
+- Capsule id
+- Actor
+- Purpose
+- Action
+- Model id
+- Decision
+- Reasons
+- Obligations
+- Request hash
+- Timestamp
+
+The first implementation lives at `src/tinyluminax/products/sovereigncode/audit.py`.
+
+## Launch Milestones
+
+| Milestone | Outcome |
+| --- | --- |
+| P0 scaffold | Policy engine, audit records, CLI, examples, docs. |
+| P1 terminal loop | Local terminal agent with plan/edit/test workflow. |
+| P2 tool broker | Policy wrappers for shell, git, file writes, package installs, and HTTP. |
+| P3 MaramaRoute integration | Sovereign model routing for every model call. |
+| P4 workspace UI | Browser console showing plan, policy, diffs, tests, and approvals. |
+| P5 enterprise controls | Tenant policies, SSO hooks, signed audit exports, policy packs. |
+
+## Aesthetic Direction
+
+The product should follow the AbteeX/LumynaX visual system:
+
+- White or warm paper background.
+- Obsidian text.
+- Warm amber accent.
+- Thin rule-based layouts.
+- Editorial headings.
+- Mono labels for governance, provenance, and runtime details.
+- No generic purple AI gradients.

configs/default_policy.yaml

@@ -0,0 +1,26 @@
+policy_id: abx-sovereigncode-default-v0
+default_jurisdiction: NZ
+default_resident_regions:
+  - NZ
+high_impact_sensitivity:
+  - personal
+  - restricted
+  - health
+  - iwi
+  - taonga
+default_obligations:
+  - write_immutable_audit_record
+  - preserve_capsule_id_in_agent_trace
+  - show_diff_before_write_or_commit
+denied_without_human_approval:
+  - delete_file
+  - execute_shell
+  - network_export
+  - publish
+  - commit
+remote_model_rule:
+  restricted_data_requires_local_or_lumynax: true
+training_rule:
+  requires_capsule_training_allowed: true
+export_rule:
+  requires_capsule_export_allowed: true

examples/capsule.restricted-nz-code.json

@@ -0,0 +1,28 @@
+{
+  "capsule_id": "cap-nz-code-001",
+  "subject_id": "abx-workspace",
+  "jurisdiction": "NZ",
+  "sensitivity": "restricted",
+  "allowed_purposes": [
+    "coding_assistance",
+    "inference",
+    "test_generation"
+  ],
+  "denied_purposes": [
+    "ad_training",
+    "third_party_resale"
+  ],
+  "resident_regions": [
+    "NZ"
+  ],
+  "data_classes": [
+    "source_code",
+    "policy",
+    "runtime_logs"
+  ],
+  "retention_days": 14,
+  "export_allowed": false,
+  "training_allowed": false,
+  "schema_context": "https://schema.org",
+  "consent_record": "local-operator-policy-v0"
+}

examples/request.allowed-local-edit.json

@@ -0,0 +1,15 @@
+{
+  "actor": "developer",
+  "purpose": "coding_assistance",
+  "action": "read_context",
+  "region": "NZ",
+  "model_id": "AbteeXAILab/lumynax-infused-qwen3-8b-gguf",
+  "data_classes": [
+    "source_code"
+  ],
+  "tool_name": "workspace_reader",
+  "writes_files": false,
+  "exports_data": false,
+  "trains_model": false,
+  "human_approved": false
+}

examples/request.denied-training.json

@@ -0,0 +1,15 @@
+{
+  "actor": "developer",
+  "purpose": "coding_assistance",
+  "action": "train_adapter",
+  "region": "NZ",
+  "model_id": "local/lumynax",
+  "data_classes": [
+    "source_code"
+  ],
+  "tool_name": "trainer",
+  "writes_files": true,
+  "exports_data": false,
+  "trains_model": true,
+  "human_approved": true
+}

product_manifest.json

@@ -0,0 +1,24 @@
+{
+  "product_name": "AbteeX SovereignCode",
+  "slug": "abx-sovereigncode",
+  "publisher": "AbteeX AI Labs",
+  "family": "LumynaX sovereign products",
+  "stage": "product_scaffold",
+  "positioning": "OpenCode-style local coding agent with Data Capsule sovereignty controls",
+  "primary_modules": [
+    "data_capsule_policy",
+    "tool_broker",
+    "lumynax_runtime_adapter",
+    "audit_ledger",
+    "human_review_gate"
+  ],
+  "runtime_entrypoints": [
+    "python -m tinyluminax.products.sovereigncode.cli"
+  ],
+  "brand_system": {
+    "paper": "#fffefa",
+    "ink": "#0a0a0b",
+    "accent": "#e08a2c",
+    "muted": "#726b62"
+  }
+}

pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "abteex-sovereigncode"
+version = "0.1.0"
+description = "AbteeX SovereignCode — local-first coding agent with Data Capsule sovereignty controls."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "AbteeX AI Labs" }]
+keywords = ["lumynax", "sovereignty", "data-capsule", "coding-agent", "aotearoa", "new-zealand"]
+classifiers = [
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = ["pyyaml>=6.0"]
+
+[project.urls]
+Homepage = "https://abteex.com"
+Repository = "https://huggingface.co/AbteeXAILab/sovereigncode"
+Lumynax = "https://lumynax.com"
+
+[project.scripts]
+sovereigncode = "sovereigncode.cli:main"

quickstart.py

@@ -0,0 +1,30 @@
+"""Quickstart for AbteeX SovereignCode.
+
+Runs the two example policy evaluations and prints structured decisions and audit records.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from sovereigncode import build_audit_record, evaluate, load_capsule, load_policy, load_request
+
+
+ROOT = Path(__file__).parent
+EXAMPLES = ROOT / "examples"
+CONFIGS = ROOT / "configs"
+
+
+def run(label: str, capsule_path: Path, request_path: Path) -> None:
+    capsule = load_capsule(capsule_path)
+    request = load_request(request_path)
+    policy = load_policy(CONFIGS / "default_policy.yaml")
+    decision = evaluate(capsule, request, policy)
+    audit = build_audit_record(capsule, request, decision.to_dict())
+    print(f"\n=== {label} ===")
+    print(json.dumps({"decision": decision.to_dict(), "audit": audit.to_dict()}, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    run("ALLOWED local edit", EXAMPLES / "capsule.restricted-nz-code.json", EXAMPLES / "request.allowed-local-edit.json")
+    run("DENIED training",   EXAMPLES / "capsule.restricted-nz-code.json", EXAMPLES / "request.denied-training.json")

requirements.txt

@@ -0,0 +1 @@
+pyyaml>=6.0

sovereigncode/__init__.py

@@ -0,0 +1,15 @@
+"""AbteeX SovereignCode — local-first coding agent with Data Capsule sovereignty controls."""
+from .policy import Decision, evaluate, load_capsule, load_policy, load_request
+from .audit import AuditRecord, build_audit_record, request_hash
+
+__all__ = [
+    "Decision",
+    "evaluate",
+    "load_capsule",
+    "load_policy",
+    "load_request",
+    "AuditRecord",
+    "build_audit_record",
+    "request_hash",
+]
+__version__ = "0.1.0"

sovereigncode/audit.py

@@ -0,0 +1,51 @@
+"""Audit ledger primitives.
+
+Every policy decision creates a record. Records are hash-stable, append-only,
+and chainable for tamper-evident exports.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+
+def _canonical(obj: Any) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def request_hash(request: Dict[str, Any]) -> str:
+    return hashlib.sha256(_canonical(request).encode("utf-8")).hexdigest()
+
+
+@dataclass
+class AuditRecord:
+    capsule_id: str
+    actor: str
+    purpose: str
+    action: str
+    model_id: str
+    decision: str
+    reasons: List[str]
+    obligations: List[str]
+    request_hash: str
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat(timespec="seconds"))
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+def build_audit_record(capsule: Dict[str, Any], request: Dict[str, Any], decision_dict: Dict[str, Any]) -> AuditRecord:
+    return AuditRecord(
+        capsule_id=str(capsule.get("capsule_id", "")),
+        actor=str(request.get("actor", "")),
+        purpose=str(request.get("purpose", "")),
+        action=str(request.get("action", "")),
+        model_id=str(request.get("model_id", "")),
+        decision=str(decision_dict.get("decision", "")),
+        reasons=list(decision_dict.get("reasons", [])),
+        obligations=list(decision_dict.get("obligations", [])),
+        request_hash=request_hash(request),
+    )

sovereigncode/cli.py

@@ -0,0 +1,47 @@
+"""SovereignCode CLI: evaluate a request against a capsule and policy."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .audit import build_audit_record
+from .policy import evaluate, load_capsule, load_policy, load_request
+
+
+DEFAULT_POLICY = Path(__file__).parent.parent / "configs" / "default_policy.yaml"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="sovereigncode", description="AbteeX SovereignCode — Data Capsule policy evaluator.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    ev = sub.add_parser("evaluate", help="Evaluate a request against a capsule.")
+    ev.add_argument("--capsule", required=True, help="Path to capsule JSON.")
+    ev.add_argument("--request", required=True, help="Path to request JSON.")
+    ev.add_argument("--policy", default=str(DEFAULT_POLICY), help="Path to policy YAML (default: configs/default_policy.yaml).")
+    ev.add_argument("--allow-denied-exit-zero", action="store_true", help="Exit 0 even when the decision is deny (useful for examples).")
+
+    args = parser.parse_args()
+
+    if args.cmd == "evaluate":
+        capsule = load_capsule(args.capsule)
+        request = load_request(args.request)
+        policy = load_policy(args.policy)
+        decision = evaluate(capsule, request, policy)
+        audit = build_audit_record(capsule, request, decision.to_dict())
+        out = {
+            "decision": decision.to_dict(),
+            "audit": audit.to_dict(),
+        }
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+        if not decision.allowed and not args.allow_denied_exit_zero:
+            return 2
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sovereigncode/policy.py

@@ -0,0 +1,115 @@
+"""Deterministic Data Capsule policy decision point (PDP).
+
+Answers, for every sensitive action: can this actor, for this purpose, in this
+region, using this model/tool, touch this capsule?
+
+Returns one of three outcomes: allow, deny, or allow_with_obligations.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List
+
+try:
+    import yaml  # type: ignore
+except ImportError:  # pragma: no cover
+    yaml = None
+
+
+@dataclass
+class Decision:
+    allowed: bool
+    decision: str  # "allow" | "deny" | "allow_with_obligations"
+    reasons: List[str] = field(default_factory=list)
+    obligations: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "allowed": self.allowed,
+            "decision": self.decision,
+            "reasons": list(self.reasons),
+            "obligations": list(self.obligations),
+        }
+
+
+def _load_yaml_or_json(path: Path) -> Dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    if path.suffix.lower() in (".yaml", ".yml"):
+        if yaml is None:
+            raise RuntimeError("pyyaml is required to load YAML policies. `pip install pyyaml`.")
+        return yaml.safe_load(text)
+    return json.loads(text)
+
+
+def load_capsule(path: str | Path) -> Dict[str, Any]:
+    return _load_yaml_or_json(Path(path))
+
+
+def load_request(path: str | Path) -> Dict[str, Any]:
+    return _load_yaml_or_json(Path(path))
+
+
+def load_policy(path: str | Path) -> Dict[str, Any]:
+    return _load_yaml_or_json(Path(path))
+
+
+def evaluate(capsule: Dict[str, Any], request: Dict[str, Any], policy: Dict[str, Any]) -> Decision:
+    reasons: List[str] = []
+    obligations: List[str] = list(policy.get("default_obligations", []))
+
+    purpose = request.get("purpose")
+    if purpose in capsule.get("denied_purposes", []):
+        reasons.append(f"purpose `{purpose}` is in capsule.denied_purposes")
+        return Decision(False, "deny", reasons, obligations)
+
+    allowed_purposes = capsule.get("allowed_purposes", [])
+    if allowed_purposes and purpose not in allowed_purposes:
+        reasons.append(f"purpose `{purpose}` is not in capsule.allowed_purposes")
+        return Decision(False, "deny", reasons, obligations)
+
+    region = request.get("region")
+    resident_regions = capsule.get("resident_regions", [])
+    if region and resident_regions and region not in resident_regions:
+        reasons.append(f"region `{region}` is not in capsule.resident_regions `{resident_regions}`")
+        return Decision(False, "deny", reasons, obligations)
+
+    sensitivity = str(capsule.get("sensitivity", "")).lower()
+    high_sensitivity = set(map(str.lower, policy.get("high_impact_sensitivity", [])))
+    is_high = sensitivity in high_sensitivity
+    requires_local = (
+        policy.get("remote_model_rule", {}).get("restricted_data_requires_local_or_lumynax")
+        and is_high
+    )
+    model_id = str(request.get("model_id", "")).lower()
+    if requires_local and not (model_id.startswith("local/") or "lumynax" in model_id):
+        reasons.append("restricted data requires a local or LumynaX-governed model")
+        return Decision(False, "deny", reasons, obligations)
+
+    if request.get("trains_model"):
+        rule = policy.get("training_rule", {})
+        if rule.get("requires_capsule_training_allowed") and not capsule.get("training_allowed", False):
+            reasons.append("training_rule requires capsule.training_allowed = true")
+            return Decision(False, "deny", reasons, obligations)
+
+    if request.get("exports_data"):
+        rule = policy.get("export_rule", {})
+        if rule.get("requires_capsule_export_allowed") and not capsule.get("export_allowed", False):
+            reasons.append("export_rule requires capsule.export_allowed = true")
+            return Decision(False, "deny", reasons, obligations)
+
+    denied_without_approval = set(policy.get("denied_without_human_approval", []))
+    action = request.get("action")
+    if action in denied_without_approval and not request.get("human_approved", False):
+        reasons.append(f"action `{action}` requires human approval")
+        return Decision(False, "deny", reasons, obligations)
+
+    if request.get("writes_files"):
+        obligations.append("show_diff_before_write_or_commit")
+    if is_high:
+        obligations.append("route_to_local_or_lumynax_model")
+
+    obligations = sorted(set(obligations))
+    reasons.append(f"capsule {capsule.get('capsule_id')} permits purpose `{purpose}` in region `{region}`")
+    return Decision(True, "allow_with_obligations" if obligations else "allow", reasons, obligations)