---
name: aetherfabric
description: >-
  Verifiable AI-data fabric and ML experiment lifecycle CLI (`aether` and
  `aether loom`). Use when running vectorized DuckDB SQL or SQLite WAL/CDC OLTP with
  post-quantum ML-DSA-65 signed Merkle snapshots and incremental CDC deltas,
  tracking ML/agent runs, speculative branches, and sandboxes in Loom, running
  the AST-sandboxed MCP server (`aether mcp`), sealing Solana 128-byte Borsh
  `aether.receipt.v2` envelopes, capturing or verifying `preview-bundle/v1`
  agent trajectories, or executing verified backups and SLO probes.
license: Apache-2.0
metadata:
  author: AetherFabric Contributors
  version: "1.0.0rc1"
  cli: aether
  protocol: preview-bundle/v1
---

# AetherFabric CLI & Loom Skill (`aether`)

AetherFabric is a local-first, verifiable AI-data fabric combining vectorized DuckDB SQL, SQLite WAL + CDC v2 concurrent OLTP, PyArrow zero-copy exports, NIST post-quantum cryptographic receipts (ML-DSA-65 signatures + ML-KEM-768 sessions), Solana 128-byte Borsh state-compression anchoring (`aether.receipt.v2`), an AST-sandboxed MCP server (`aether mcp`), and **Loom** (append-only ML/agent run journals, speculative branches, typed decisions, sandboxes, gated evaluations, signed model registry, and `preview-bundle/v1` trajectory bundles).

## 1. Agent Operating Contract (JSON & Exit Codes)

Every `aether` command emits machine-parseable **JSON on stdout by default** (unless `--card`, `--path`, or `--markdown` is requested).

| Exit Code | Meaning | Agent Action |
| :--- | :--- | :--- |
| `0` | Command succeeded; all checks, gates, and signatures verified. | Parse JSON stdout and proceed. |
| `1` or `2` | Logical check, evaluation gate, or cryptographic verification failed (e.g., tampered receipt, unpinned trust anchor, blocked gate, degraded doctor check). | Inspect `"reason"`, `"problems"`, or `"gates"` in JSON stdout; do **not** treat as pass. |
| `3` | Command could not run (invalid input, missing file, unhandled error). Reported as one JSON object `{"ok": false, "error": "...", "type": "..."}` on stdout. | Fix arguments or set `AETHER_DEBUG=1` for traceback. |

---

## 2. Core Environment Variables

| Variable | Default | Purpose |
| :--- | :--- | :--- |
| `AETHER_DATA_DIR` | `./data` | Root directory for DuckDB (`aether.duckdb`), SQLite WAL/CDC (`oltp/turso_mvcc.db`), snapshots, receipts, and Loom journals. |
| `AETHER_TRUST_STORE` | Per-user config dir | Directory **outside** `AETHER_DATA_DIR` holding pinned ML-DSA-65 public keys and registry anchors. |
| `AETHER_OLTP_BACKEND` | `memory` | OLTP backend: `memory` (SQLite), `sqlite-cdc` (SQLite WAL + `turso_cdc` v2 + write scopes), or `ydb`. |
| `AETHER_LOOM_STUDY` | `default` | Active Loom study when `--study` is omitted. |
| `AETHER_LOOM_SEAL` | `1` | `1` signs every finished Loom run and preview bundle with ML-DSA-65; `0` skips signing. |
| `AETHER_LOOM_DECISION` | `0` | `1` enables `loom.decision` (`Pick`, `Grade`, `YesNo`, `ask`, `aether loom decide`); `0` disables. |
| `AETHER_LOOM_DECISION_REMOTE` | `0` | `0` keeps remote decision endpoints disabled. |
| `AETHER_ENV` | unset | When set to `prod`, refuses plaintext file key custody and educational PQC backends. |

---

## 3. Command Groups

### A. Core SQL, SQLite WAL/CDC, PQC Snapshots & Incremental Delta Sealing
```bash
# Check DuckDB + PQC backend + key custody + trust pin status
aether --data-dir ./data health

# Execute DDL/DML or SELECT queries (returns JSON columns + rows)
aether --data-dir ./data sql "CREATE TABLE events (id INTEGER, label VARCHAR)"
aether --data-dir ./data sql "INSERT INTO events VALUES (1, 'alpha'), (2, 'beta')"
aether --data-dir ./data sql --sandbox --read-only "SELECT * FROM events ORDER BY id"

# One-shot schema & DuckDB vectorized SUMMARIZE digest (including loom.runs, loom.agent_steps, loom.decisions)
aether --data-dir ./data schema --summarize --include-loom

# Export all tables to Parquet, compute SHA3-256 Merkle root, and sign with ML-DSA-65
aether --data-dir ./data commit --snapshot snap-001

# Verify two sealed snapshots and compute table/row diffs via DuckDB EXCEPT ALL
aether --data-dir ./data diff snap-001 snap-002

# Seal an O(delta rows) incremental CDC Merkle delta chained to the latest parent snapshot
aether --data-dir ./data commit --incremental --snapshot snap-delta-002

# Run multi-row ACID transfer on SQLite WAL + CDC v2 store and sync to DuckDB HTAP
aether --data-dir ./data oltp-demo --backend sqlite-cdc
aether --data-dir ./data htap-sync --backend sqlite-cdc

# Pin the signing public key into the external trust store (first time or out-of-band key)
aether --data-dir ./data trust-pin
aether --data-dir ./data trust-status

# Verify snapshot or incremental delta digest integrity + ML-DSA-65 signature
aether --data-dir ./data verify snap-001
aether --data-dir ./data verify snap-delta-002

# Export table to PyArrow Parquet/IPC
aether --data-dir ./data export-arrow events
```

### B. Verifiable MCP Server (`aether mcp`) & Solana / TON / EVM / zkVM State Anchoring
```bash
# List all 33 AST-sandboxed SQL, DuckDB, Memory, Workflow, Schema, Diff, RAG, Crypto, Loom, and Loom Evolve MCP tools
aether --data-dir ./data mcp --list-tools

# Invoke a sandboxed MCP tool directly or run stdio JSON-RPC 2.0 server
aether --data-dir ./data mcp --call current_database
aether --data-dir ./data mcp --call aether_schema_summarize --args '{"summarize":true,"include_loom":true}'
aether --data-dir ./data mcp --call aether_memory_remember --args '{"text":"User prefers TON post-quantum anchors","user_id":"alice","kind":"preference"}'
aether --data-dir ./data mcp --call aether_memory_recall --args '{"query":"TON anchors","user_id":"alice"}'
aether --data-dir ./data mcp --call aether_workflow_run --args '{"task":"Ship TON Mini App memory","user_id":"alice"}'
aether --data-dir ./data mcp --call aether_agent_safety_audit --args '{"user_id":"alice"}'
aether --data-dir ./data mcp --call aether_rsi_mine --args '{"study":"default","min_count":5}'
aether --data-dir ./data mcp --call aether_crypto_simulate_tx --args '{"from_account":"alice","to_account":"bob","value_wei":1000}'
aether --data-dir ./data mcp

# Seal and verify a 128-byte Borsh aether.receipt.v2 (ML-DSA-65 + Ed25519) Solana envelope
aether --data-dir ./data solana-seal snap-001
aether --data-dir ./data solana-verify snap-001
aether --data-dir ./data solana-transfer snap-001 \
  --from-pubkey So11111111111111111111111111111111111111112 \
  --to-pubkey Dest111111111111111111111111111111111111111 \
  --lamports 50000000
```

### B2. Verifiable Agentic Memory (`aether memory` — Mem0 + Letta + Graphiti + DKG + Anamnesis + TON/Base/Solana)
```bash
# Letta-style self-editing core memory blocks (view | set | append | replace)
aether --data-dir ./data memory core set --block persona --text "Autonomous TON & AI Architect" --user alice
aether --data-dir ./data memory core replace --block persona --old-text "Architect" --new-text "Principal Architect" --user alice
aether --data-dir ./data memory core view --user alice

# Mem0-style scoped semantic/episodic/procedural/preference memory + composite hybrid recall
aether --data-dir ./data memory remember "Alice prefers post-quantum TON anchors" --user alice --kind preference
aether --data-dir ./data memory recall "What anchors does Alice prefer?" --user alice

# Graphiti bi-temporal entity-relationship triples + OriginTrail DKG Knowledge Asset Merkle root
aether --data-dir ./data memory graph add --subject alice --predicate lives_in --object Tokyo --user alice
aether --data-dir ./data memory graph query --entity alice --user alice
aether --data-dir ./data memory graph dkg-root --user alice

# Consolidate raw observations into atomic facts & KG edges inside a SpeculativeBranch
aether --data-dir ./data memory consolidate -o "alice works_at Luminara" -o "alice prefers dark_mode" --user alice

# GDPR crypto-shredding (tombstones record + destroys per-record HKDF DEK while preserving SHA3 Merkle commitment)
aether --data-dir ./data memory forget <memory-id> --user alice

# Encrypt memory-bundle/v1 (ML-KEM-768 + ChaCha20-Poly1305), pin to CAS/IPFS, and anchor on TON (136B BOC), Base (EIP-712), and Solana (128B Borsh)
aether --data-dir ./data memory anchor --user alice --chains ton,base,solana
aether --data-dir ./data memory verify-ton <snapshot-id> --network testnet
```

### B3. 5-Layer Durable Agentic Workflow Runtime & Safety Audit (`aether workflow` — LangGraph + Temporal + HITL + Agent-Wiz)
```bash
# Run the 5-role checkpointed workflow (Researcher -> Architect -> Engineer -> QA -> CEO HITL Gate)
aether --data-dir ./data workflow run --task "Deploy verifiable agent memory" --workflow-id wf-prod-01 --user alice

# Inspect checkpoint state, SQLite WAL/CDC watermark, and pending Human-in-the-Loop approval
aether --data-dir ./data workflow status wf-prod-01

# Sign an ML-DSA-65 Human-in-the-Loop approval and auto-resume from durable activity journal
aether --data-dir ./data workflow approve wf-prod-01 --decision approve --reviewer ceo

# Run Agent-Wiz + Langfuse 6-control STRIDE / OWASP Agentic Top-10 safety & observability audit
aether --data-dir ./data workflow safety-audit --workflow-id wf-prod-01 --user alice
```

### C. Stateful Interactive & Batch REPL (`aether repl`)
Use `aether repl` to maintain warm session state (`data_dir`, active Loom `study`, `last_snapshot_id`, `last_run_id`, and undo/redo stack) across multiple commands with `FileLock` session safety:
```bash
aether --data-dir ./data repl --json
```

### D. Loom: Verifiable ML & Agent Lifecycle (`aether loom` / `aether weave`)
```bash
# Run end-to-end verifiable ML lifecycle demo
aether --data-dir ./data loom demo

# Inspect capabilities, sandbox backends, key custody, typed_decisions flag, and local model servers
aether --data-dir ./data loom doctor

# Evaluate closed typed decisions (Pick / Grade / YesNo) over untrusted JSON state (requires AETHER_LOOM_DECISION=1)
AETHER_LOOM_DECISION=1 aether --data-dir ./data loom decide \
  --state '{"ticket":"urgent refund request"}' \
  --questions '{"urgency":{"kind":"grade","instructions":"How urgent?","levels":["low","high","urgent"]}}'

# List studies and runs, show a run card, or compare two runs
aether --data-dir ./data loom studies
aether --data-dir ./data loom runs --study loom-demo
aether --data-dir ./data loom show <run-id>
aether --data-dir ./data loom compare <run-a> <run-b>
aether --data-dir ./data loom verify <run-id>

# Run a script inside an isolated venv or Docker sandbox
aether --data-dir ./data loom run train.py --param lr=0.01 --param epochs=5

# Evaluate a model against a dataset with deterministic scorers and gates
aether --data-dir ./data loom eval qa.jsonl --model support-bot:1 \
  --scorer exact_match --gate "exact_match/mean>=0.80"

# Register, verify, and promote a model package on signed evaluation evidence
aether --data-dir ./data loom register support-bot --flavor pycall --source ./bot_pkg --entry bot:predict
aether --data-dir ./data loom promote support-bot --evidence <eval-run-id>
aether --data-dir ./data loom verify-model support-bot@champion

# Generate self-contained static HTML study report
aether --data-dir ./data loom report loom-demo -o report.html
```

### E. Preview & Trajectory Bundles (`aether loom preview` — `preview-bundle/v1`)
Keep **producer** and **consumer** roles separate:
- **Producer (`aether loom preview ...`):** Generates truthful `preview-bundle/v1` directories (`manifest.json`, `summary.json`, `artifacts/`, and ML-DSA-65 `bundle.receipt.json`) from real Loom journals and DuckDB index data.
- **Consumer (`aether loom preview latest` / `live status` / static web hub):** Reads published bundle state without re-rendering.

```bash
aether --data-dir ./data loom preview recipes
aether --data-dir ./data loom preview capture loom-demo --recipe study-trend
aether --data-dir ./data loom preview latest loom-demo
aether --data-dir ./data loom preview diff <run-a> <run-b>
aether --data-dir ./data loom preview verify <bundle-dir>
```

### F. Loom Evolve: Gated Harness Evolution Engine (`aether loom rsi`)
Closed-loop self-improving agent harness combining Constitutional PQC pinning (`ML-DSA-65`), vectorized DuckDB trace anomaly mining (`kayba-ai`), Darwin-Gödel & MAP-Elites quality-diversity archives (`DGM`), Regularized RSI (`google-research/rrsi`), 3-rung speculative cascade (`SpeculativeBranch`), `AgentFactory` skill crystallization, and `SIA` post-training DPO/SFT export:
```bash
# Pin and verify constitutional mutation boundaries & frozen evaluation surface Merkle root
aether --data-dir ./data loom rsi pin-constitution --study agent-study --mutable "prompts/**,skills/**"
aether --data-dir ./data loom rsi verify-constitution --study agent-study

# Mine 4 failure archetypes (loop, give_up, tool_error, recovery_failure) with Denominator Hygiene
aether --data-dir ./data loom rsi mine --study agent-study --min-count 5

# Run the 3-rung speculative RSI cascade across G generations with cosine edit-budget decay
aether --data-dir ./data loom rsi evolve --study agent-study --generations 3 --budget-max 4 --budget-min 1 --lambda-cost 0.15 --noise-floor 0.01

# Inspect Darwin-Gödel stepping stones, Pareto front, and MAP-Elites niche champions
aether --data-dir ./data loom rsi archive --study agent-study --elites
aether --data-dir ./data loom rsi archive --study agent-study --pareto

# Crystallize verified high-scoring trajectories into an executable ML-DSA-65 signed pycall subagent (--name or --skill-name)
aether --data-dir ./data loom rsi crystallize --study agent-study --skill-name support-subagent --min-score 0.8

# Export SFT & DPO Parquet/JSONL datasets + pass-rate curriculum splits with ML-DSA-65 receipt (-o / --out / --out-dir)
aether --data-dir ./data loom rsi export-posttrain --study agent-study -o ./posttrain_bundle

# Run RRSI ablation pruning over study harness components (or --components ./components.json) to strip zero-gain token bloat
aether --data-dir ./data loom rsi prune --study agent-study
aether --data-dir ./data loom rsi prune --components ./components.json --baseline-score 0.85
```

### G. Verified Backup, Restore & Availability SLO Probes
```bash
aether --data-dir ./data backup create --to ./backups --keep 5
aether backup verify ./backups/<archive>.tar.gz --expect-fingerprint <sha3-hex>
aether backup restore ./backups/<archive>.tar.gz --to ./data-restored --trust-fingerprint <sha3-hex>
aether slo probe --url http://127.0.0.1:18080 --out ./slo-probes.jsonl --count 1
aether slo report ./slo-probes.jsonl
```

### H. Skill Introspection (`aether skill`) & 4-Surface Cross-Platform SDKs
- **Mobile (`bindings/react-native/index.js`)**: `verifySolanaStatementV1`, `verifyEip712ReceiptV1`, `MobileSpeculativeBranch`, `createHardwareCoSignedEnvelope`, `computeDeltaSyncPayload`.
- **Desktop (`bindings/desktop-tauri/index.js` & `loom/ui_tree.py`)**: `SemanticUiTree` (`ui-tree/v1`), `diff_ui_trees`, `verify_pre_action_gate`, `SpeculativeDesktopBranch`.
- **Crypto / Web3 (`adapters/audit/solana.py`, `adapters/audit/ton.py`, `adapters/audit/evm_eip712.py`, `adapters/audit/zk_witness.py`)**: Solana batch anchoring (16 statements/call), TON 136-byte `AETHTON1` BOC memory anchor (`AetherTonAnchorCellV1`) & policy-gated TON transfers, EVM EIP-712 + `ML-DSA-65` hybrid receipts (`AetherEip712ReceiptV1`), pre-sign speculative transaction simulator (`simulate_gated_evm_transaction`), and 152-byte zkVM state transition witnesses (`AetherZkWitnessV1`).
- **Web (`bindings/wasm/aether_verifier.js` & `bindings/wasm/opfs_crdt_sync.js`)**: Browser SHA3-256/Merkle/SQL AST/EIP-712/Solana/TON (`verifyTonAnchorCellV1`) & `memory-bundle/v1` (`verifyMemoryBundleManifestV1`) verifier, `OpfsMerkleCrdtStore`, and `createWebGpuTrajectoryScorer`.
```bash
aether skill              # JSON metadata and command inventory
aether skill --path       # Absolute path to this SKILL.md
aether skill --markdown   # Print full SKILL.md content
aether skill --hub-entry  # Emit AetherFabric Agent Hub / public_registry.json descriptor
```
