nexus-control 0.6.0__tar.gz

nexus_control-0.6.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.benchmarks/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Linting / Type checking
+.ruff_cache/
+.mypy_cache/
+.pyright/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

nexus_control-0.6.0/ARCHITECTURE.md

@@ -0,0 +1,178 @@
+# Architecture: How Nexus-Control Works
+
+## One Sentence
+
+Nexus-Control turns governance + execution into a single, verifiable artifact.
+
+Not logs. Not reports. A file you can hash.
+
+## The Core Flow
+
+```
+┌──────────────────┐
+│  Control Bundle  │
+│  (Intent)        │
+│                  │
+│  - decision      │
+│  - policy        │
+│  - approvals     │
+│  - constraints   │
+│  - template      │
+└────────┬─────────┘
+         │ control_digest
+         │
+         ▼
+┌──────────────────┐        ┌──────────────────────────────────┐
+│  Router          │        │        Audit Package              │
+│  (Execution)     │        │                                  │
+│                  │───────▶│  binding_digest = sha256(         │
+│  Reference mode: │        │    canonical_json({               │
+│    run_id        │        │      package_version,             │
+│    router_digest │        │      control_digest,              │
+│                  │        │      router_digest,               │
+│  Embedded mode:  │        │      control_router_link_digest   │
+│    full bundle   │        │    })                             │
+│    cross-check   │        │  )                                │
+└──────────────────┘        └──────────────────────────────────┘
+         ▲                                    ▲
+         │                                    │
+         └──── control_router_link_digest ────┘
+               (why this execution was allowed)
+```
+
+## What Each Layer Means
+
+### 1. Control Bundle — What was allowed
+
+Governance intent:
+- **Decision**: the request (goal, mode, constraints)
+- **Policy**: approval rules, allowed modes, capabilities
+- **Approvals**: who approved, when, with what comment
+- **Template**: named policy snapshot (if used)
+
+Its integrity is captured as `control_digest`.
+
+### 2. Router — What actually ran
+
+Execution identity, not a log stream.
+
+| Mode | Contains | Use Case |
+|------|----------|----------|
+| **Reference** (default) | `run_id` + `router_digest` | CI, internal systems, continuous operation |
+| **Embedded** | Full router bundle + optional cross-check | Regulators, external auditors, long-term archival |
+
+Both modes are cryptographically equivalent at the binding layer.
+
+### 3. Control–Router Link — Why this execution was allowed
+
+The most important idea. The link explicitly states:
+**this control bundle authorized that router execution.**
+
+This prevents:
+- Replay attacks
+- Execution substitution
+- Post-hoc justification
+
+Its integrity is captured as `control_router_link_digest`.
+
+### 4. Binding Digest — The point of no ambiguity
+
+```
+binding_digest = sha256(canonical_json({
+    package_version: "0.6",
+    control_digest,
+    router_digest,
+    control_router_link_digest
+}))
+```
+
+If **any** component changes — intent, execution, linkage, or schema —
+the digest breaks. This is the audit truth anchor.
+
+## Verification Model
+
+```
+verify_audit_package()
+│
+├─ binding_digest           recompute from binding fields
+├─ control_bundle_digest    recompute from control bundle content
+├─ binding_control_match    binding ↔ control bundle consistency
+├─ binding_router_match     binding ↔ router section consistency
+├─ binding_link_match       binding ↔ control-router link consistency
+└─ router_digest            embedded router bundle integrity (if applicable)
+```
+
+Properties:
+- **No short-circuiting** — all failures reported
+- **Machine-verifiable** — CI/CD safe
+- **Regulator-readable** — structured JSON output
+
+## Event-Sourced Foundation
+
+All state is derived by replaying an immutable event log:
+
+```
+decisions (header)
+  └── decision_events (append-only log)
+        ├── DECISION_CREATED
+        ├── POLICY_ATTACHED
+        ├── APPROVAL_GRANTED
+        ├── APPROVAL_REVOKED
+        ├── EXECUTION_REQUESTED
+        ├── EXECUTION_STARTED
+        ├── EXECUTION_COMPLETED
+        └── EXECUTION_FAILED
+```
+
+No mutable state. No hidden writes. Replay is deterministic.
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     nexus-control                        │
+│                                                         │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────────┐  │
+│  │ request │ │ approve │ │ execute │ │ audit export │  │
+│  └────┬────┘ └────┬────┘ └────┬────┘ └──────┬───────┘  │
+│       │           │           │              │          │
+│       ▼           ▼           ▼              ▼          │
+│  ┌──────────────────────────────────────────────────┐   │
+│  │            Decision Store (SQLite)                │   │
+│  │  - Event log (append-only)                       │   │
+│  │  - Replay for state                              │   │
+│  │  - Deterministic digest computation              │   │
+│  │  - Export/import with integrity verification      │   │
+│  └──────────────────────────────────────────────────┘   │
+│                          │                               │
+└──────────────────────────┼───────────────────────────────┘
+                           │
+                           ▼
+                 ┌─────────────────┐
+                 │  nexus-router   │
+                 │  (execution)    │
+                 └─────────────────┘
+```
+
+Control plane stores **links, not copies**. Router remains the flight recorder.
+
+## Design Guarantees
+
+| Guarantee | Mechanism |
+|-----------|-----------|
+| Deterministic digests | Canonical JSON (`sort_keys=True, separators=(",",":")`) |
+| Digest schema immutability | Inputs frozen per `package_version` |
+| Tamper evidence | SHA-256 binding across all components |
+| Full failure visibility | `verify_audit_package()` runs all checks |
+| Portable artifacts | JSON bundles with `from_dict()` / `to_dict()` roundtrip |
+| No hidden state | `meta.exported_at` and provenance excluded from digests |
+
+## What This Replaces
+
+| Old World | Nexus-Control |
+|-----------|---------------|
+| Logs | Artifacts |
+| Trust | Verification |
+| PDFs | Digests |
+| "Approved in Jira" | Cryptographic linkage |
+| After-the-fact audits | Built-in auditability |

nexus_control-0.6.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: nexus-control
+Version: 0.6.0
+Summary: Orchestration and approval layer for nexus-router executions
+Project-URL: Homepage, https://github.com/mcp-tool-shop/nexus-control
+Project-URL: Repository, https://github.com/mcp-tool-shop/nexus-control
+Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
+License-Expression: MIT
+Keywords: approval,audit,mcp,nexus,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: nexus-router>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.350; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+> ⚠️ **This repository has moved to [nexus-suite](https://github.com/mcp-tool-shop/nexus-suite)**
+> Source now lives at: `src/nexus-control/`
+
+---
+
+# nexus-control
+
+**Orchestration and approval layer for nexus-router executions.**
+
+A thin control plane that turns "router can execute" into "org can safely decide to execute" — with cryptographic proof.
+
+## Core Promise
+
+Every execution is tied to:
+- A **decision** (the request + policy)
+- A **policy** (approval rules, allowed modes, constraints)
+- An **approval trail** (who approved, when, with what comment)
+- A **nexus-router run_id** (for full execution audit)
+- An **audit package** (cryptographic binding of governance to execution)
+
+Everything is exportable, verifiable, and replayable.
+
+> See [ARCHITECTURE.md](ARCHITECTURE.md) for the full mental model and design guarantees.
+
+## Installation
+
+```bash
+pip install nexus-control
+```
+
+Or from source:
+```bash
+git clone https://github.com/mcp-tool-shop/nexus-control
+cd nexus-control
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from nexus_control import NexusControlTools
+from nexus_control.events import Actor
+
+# Initialize (uses in-memory SQLite by default)
+tools = NexusControlTools(db_path="decisions.db")
+
+# 1. Create a request
+result = tools.request(
+    goal="Rotate production API keys",
+    actor=Actor(type="human", id="alice@example.com"),
+    mode="apply",
+    min_approvals=2,
+    labels=["prod", "security"],
+)
+request_id = result.data["request_id"]
+
+# 2. Get approvals
+tools.approve(request_id, actor=Actor(type="human", id="alice@example.com"))
+tools.approve(request_id, actor=Actor(type="human", id="bob@example.com"))
+
+# 3. Execute (with your router)
+result = tools.execute(
+    request_id=request_id,
+    adapter_id="subprocess:mcpt:key-rotation",
+    actor=Actor(type="system", id="scheduler"),
+    router=your_router,  # RouterProtocol implementation
+)
+
+print(f"Run ID: {result.data['run_id']}")
+
+# 4. Export audit package (cryptographic proof of governance + execution)
+audit = tools.export_audit_package(request_id)
+print(audit.data["digest"])  # sha256:...
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `nexus-control.request` | Create an execution request with goal, policy, and approvers |
+| `nexus-control.approve` | Approve a request (supports N-of-M approvals) |
+| `nexus-control.execute` | Execute approved request via nexus-router |
+| `nexus-control.status` | Get request state and linked run status |
+| `nexus-control.inspect` | Read-only introspection with human-readable output |
+| `nexus-control.template.create` | Create a named, immutable policy template |
+| `nexus-control.template.get` | Retrieve a template by name |
+| `nexus-control.template.list` | List all templates with optional label filtering |
+| `nexus-control.export_bundle` | Export a decision as a portable, integrity-verified bundle |
+| `nexus-control.import_bundle` | Import a bundle with conflict modes and replay validation |
+| `nexus-control.export_audit_package` | Export audit package binding governance to execution |
+
+## Audit Packages (v0.6.0)
+
+A single JSON artifact that cryptographically binds:
+- **What was allowed** (control bundle)
+- **What actually ran** (router execution)
+- **Why it was allowed** (control-router link)
+
+Into one verifiable `binding_digest`.
+
+```python
+from nexus_control import export_audit_package, verify_audit_package
+
+# Export
+result = export_audit_package(store, decision_id)
+package = result.package
+
+# Verify (6 independent checks, no short-circuiting)
+verification = verify_audit_package(package)
+assert verification.ok
+```
+
+Two router modes:
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| **Reference** | `run_id` + `router_digest` | CI, internal systems |
+| **Embedded** | Full router bundle included | Regulators, long-term archival |
+
+## Decision Templates (v0.3.0)
+
+Named, immutable policy bundles that can be reused across decisions:
+
+```python
+tools.template_create(
+    name="prod-deploy",
+    actor=Actor(type="human", id="platform-team"),
+    min_approvals=2,
+    allowed_modes=["dry_run", "apply"],
+    require_adapter_capabilities=["timeout"],
+    labels=["prod"],
+)
+
+# Use template with optional overrides
+result = tools.request(
+    goal="Deploy v2.1.0",
+    actor=actor,
+    template_name="prod-deploy",
+    override_min_approvals=3,  # Stricter for this deploy
+)
+```
+
+## Decision Lifecycle (v0.4.0)
+
+Computed lifecycle with blocking reasons and timeline:
+
+```python
+from nexus_control import compute_lifecycle
+
+lifecycle = compute_lifecycle(decision, events, policy)
+
+# Blocking reasons (triage-ladder ordered)
+for reason in lifecycle.blocking_reasons:
+    print(f"{reason.code}: {reason.message}")
+
+# Timeline with truncation
+for entry in lifecycle.timeline:
+    print(f"  {entry.seq}  {entry.label}")
+```
+
+## Export/Import Bundles (v0.5.0)
+
+Portable, integrity-verified decision bundles:
+
+```python
+# Export
+bundle_result = tools.export_bundle(decision_id)
+bundle_json = bundle_result.data["canonical_json"]
+
+# Import with conflict handling
+import_result = tools.import_bundle(
+    bundle_json,
+    conflict_mode="new_decision_id",
+    replay_after_import=True,
+)
+```
+
+Conflict modes: `reject_on_conflict`, `new_decision_id`, `overwrite`
+
+## Data Model
+
+### Event-Sourced Design
+
+All state is derived by replaying an immutable event log:
+
+```
+decisions (header)
+  └── decision_events (append-only log)
+        ├── DECISION_CREATED
+        ├── POLICY_ATTACHED
+        ├── APPROVAL_GRANTED
+        ├── APPROVAL_REVOKED
+        ├── EXECUTION_REQUESTED
+        ├── EXECUTION_STARTED
+        ├── EXECUTION_COMPLETED
+        └── EXECUTION_FAILED
+```
+
+### Policy Model
+
+```python
+Policy(
+    min_approvals=2,
+    allowed_modes=["dry_run", "apply"],
+    require_adapter_capabilities=["timeout"],
+    max_steps=50,
+    labels=["prod", "finance"],
+)
+```
+
+### Approval Model
+
+- Counted by distinct `actor.id`
+- Can include `comment` and optional `expires_at`
+- Can be revoked (before execution)
+- Execution requires approvals to satisfy policy **at execution time**
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests (203 tests)
+pytest
+
+# Type check (strict mode)
+pyright
+
+# Lint
+ruff check .
+```
+
+## Project Structure
+
+```
+nexus-control/
+├── nexus_control/
+│   ├── __init__.py          # Public API + version
+│   ├── tool.py              # MCP tool entrypoints (11 tools)
+│   ├── store.py             # SQLite event store
+│   ├── events.py            # Event type definitions
+│   ├── policy.py            # Policy validation + router compilation
+│   ├── decision.py          # State machine + replay
+│   ├── lifecycle.py         # Blocking reasons, timeline, progress
+│   ├── template.py          # Named immutable policy templates
+│   ├── export.py            # Decision bundle export
+│   ├── import_.py           # Bundle import with conflict modes
+│   ├── bundle.py            # Bundle types + digest computation
+│   ├── audit_package.py     # Audit package types + verification
+│   ├── audit_export.py      # Audit package export + rendering
+│   ├── canonical_json.py    # Deterministic serialization
+│   └── integrity.py         # SHA-256 helpers
+├── schemas/                 # JSON schemas for tool inputs
+├── tests/                   # 203 tests across 9 test files
+├── ARCHITECTURE.md          # Mental model + design guarantees
+├── QUICKSTART.md
+├── README.md
+└── pyproject.toml
+```
+
+## License
+
+MIT

nexus_control-0.6.0/QUICKSTART.md

@@ -0,0 +1,170 @@
+# Quickstart: nexus-control
+
+Get operational in 5 minutes.
+
+## Install
+
+```bash
+pip install nexus-control
+```
+
+## The 3-Command Flow
+
+### 1. Create a Decision
+
+```python
+from nexus_control import NexusControlTools
+from nexus_control.events import Actor
+
+tools = NexusControlTools(db_path="control.db")
+
+result = tools.request(
+    goal="rotate production API keys",
+    actor=Actor(type="human", id="alice"),
+    mode="apply",
+    min_approvals=2,
+    allowed_modes=["dry_run", "apply"],
+    labels=["prod", "security"],
+)
+
+request_id = result.data["request_id"]
+print(f"Created: {request_id}")
+# Created: 550e8400-e29b-41d4-a716-446655440000
+```
+
+### 2. Approve (N-of-M)
+
+```python
+# First approval
+tools.approve(
+    request_id=request_id,
+    actor=Actor(type="human", id="alice"),
+    comment="Reviewed plan, looks safe",
+)
+
+# Second approval - now approved
+result = tools.approve(
+    request_id=request_id,
+    actor=Actor(type="human", id="bob"),
+    comment="LGTM",
+)
+
+print(f"Approved: {result.data['is_approved']}")
+# Approved: True
+```
+
+### 3. Execute
+
+```python
+# You provide the router (nexus-router instance)
+from nexus_router import Router
+
+router = Router(...)  # Your router setup
+
+result = tools.execute(
+    request_id=request_id,
+    adapter_id="subprocess:mcpt:key-rotation",
+    actor=Actor(type="system", id="scheduler"),
+    router=router,
+    dry_run=False,
+)
+
+print(f"Run ID: {result.data['run_id']}")
+print(f"Steps: {result.data['steps_executed']}")
+```
+
+## Check Status
+
+```python
+status = tools.status(request_id)
+
+print(f"State: {status.data['state']}")
+print(f"Goal: {status.data['goal']}")
+print(f"Approvals: {status.data['active_approvals']}/{status.data['policy']['min_approvals']}")
+print(f"Run ID: {status.data['executions'][-1]['run_id']}")
+```
+
+## Export Audit Record
+
+```python
+audit = tools.export_audit_record(request_id)
+
+# Canonical JSON for archival
+with open(f"audit-{request_id}.json", "w") as f:
+    f.write(audit.data["canonical_json"])
+
+# Integrity digest
+print(f"Digest: {audit.data['record_digest']}")
+```
+
+## Policy Options
+
+```python
+tools.request(
+    goal="...",
+    actor=Actor(type="human", id="alice"),
+
+    # Approval requirements
+    min_approvals=2,                    # Need 2 distinct approvers
+
+    # Execution constraints
+    mode="apply",                       # Requested mode
+    allowed_modes=["dry_run", "apply"], # What policy permits
+    max_steps=50,                       # Passed to router
+
+    # Adapter requirements
+    require_adapter_capabilities=["timeout", "external"],
+
+    # Governance
+    labels=["prod", "finance"],         # For routing/filtering
+)
+```
+
+## Dry Run First
+
+```python
+# Execute in dry_run mode even if request was for apply
+result = tools.execute(
+    request_id=request_id,
+    adapter_id="adapter",
+    actor=Actor(type="human", id="alice"),
+    router=router,
+    dry_run=True,  # Override to dry_run
+)
+
+# Review output, then execute for real
+result = tools.execute(
+    request_id=request_id,
+    adapter_id="adapter",
+    actor=Actor(type="human", id="alice"),
+    router=router,
+    dry_run=False,
+)
+```
+
+## Timeline View
+
+```python
+status = tools.status(request_id, include_events=True)
+
+for event in status.data["events"]:
+    print(f"{event['ts']} | {event['event_type']} | {event['actor']['id']}")
+
+# 2024-01-15T10:00:00Z | DECISION_CREATED | alice
+# 2024-01-15T10:00:00Z | POLICY_ATTACHED | alice
+# 2024-01-15T10:05:00Z | APPROVAL_GRANTED | alice
+# 2024-01-15T10:10:00Z | APPROVAL_GRANTED | bob
+# 2024-01-15T10:15:00Z | EXECUTION_REQUESTED | scheduler
+# 2024-01-15T10:15:01Z | EXECUTION_STARTED | nexus-control
+# 2024-01-15T10:15:30Z | EXECUTION_COMPLETED | nexus-control
+```
+
+## What Makes This Useful
+
+1. **Audit trail**: Every action has an actor, timestamp, and digest
+2. **N-of-M approvals**: Real approval workflows, not just flags
+3. **Policy enforcement**: Mode restrictions, capability requirements
+4. **Router integration**: Links to nexus-router run_id for full execution audit
+5. **Exportable**: Canonical JSON records for compliance/archival
+
+That's operational power.