Absolutely — here’s a complete README.md for your repository, designed for immediate publication and integration with Codex or other AI dev agents. It explains the project goals, architecture, build setup, and contribution model.

---

# 🧩 Compositional WebAssembly System

**Spec:** [`SPEC.md`](./SPEC.md)  
**Version:** `@1.0.0`  
**Maintainer:** Zachary Whitley  
**License:** Apache 2.0 (recommended)

---

## Overview

The **Compositional WebAssembly System** provides a reproducible, secure, and portable way to **compose, execute, and attest** WebAssembly components.

It defines a family of **WIT interfaces**, **canonical serialization formats**, and **runtime policies** that make complex component graphs deterministic and composable across hosts, runtimes, and registries.

The goal is to create a “*Guice for WebAssembly*” — dependency injection for Wasm components — backed by canonical formats and verifiable trust.

---

## Features

✅ **Canonical WIT + CBOR**
- Deterministic hashing and serialization.
- Reproducible component identity and shape verification.

🔐 **Pluggable Trust & Secrets**
- PKCS#11, Vault, HSM, and SigStore integrations.
- Token-based secret delivery with secure indirection.

⚙️ **Compositional Execution**
- Build multi-component graphs declaratively.
- Execute directly or emit a composed artifact.

🪪 **Reproducibility & Attestation**
- Every composition produces a verifiable digest.
- Optional audit and attestation for provenance and compliance.

📊 **Observability**
- Structured logs and metrics (`std:metrics`).
- Optional audit trails (`std:audit`) and host attestation (`std:attest`).

🧱 **Pluggable Backends**
- Modular interfaces for storage (`blobs`), trust, and secrets.
- Host policies determine execution, determinism, and resource limits.

---

## Architecture

### Worlds & Interfaces

| Package | Purpose |
|----------|----------|
| `sys:compose` | Core composition world (`plan`, `emit`, `exec`, `blobs`, `trust`, `events`). |
| `canon:wit` | Canonical WIT normalization and ID hashing. |
| `canon:cbor` | Deterministic CBOR profile. |
| `std:secrets` | Token-based secret system with pluggable backends. |
| `std:metrics` | Optional runtime metrics world. |
| `std:audit` | Optional audit and provenance recording. |
| `std:attest` | Optional attestation proofs (TPM/TEE/SigStore). |

### Canonicalization

| Format | Purpose |
|---------|----------|
| **Canonical WIT** | Structural hashing for interfaces, worlds, packages. |
| **Canonical CBOR** | Deterministic serialization for plans and artifacts. |

---

## Quick Start

### 1. Install toolchain

```bash
# Recommended tools
cargo install wasm-tools
cargo install wasmtime

2. Build the canonicalization libraries

cd canon-wit
cargo build --release

cd ../canon-cbor
cargo build --release

3. Validate and emit a composition plan

composectl plan validate examples/hello-plan.cbor
composectl emit build examples/hello-plan.cbor -o build/hello.wasm

4. Execute directly

composectl exec run build/hello.wasm

5. Serve an HTTP world

composectl exec serve examples/http-plan.cbor --port 8080

---

Directory Layout

.
├── SPEC.md                 # Technical specification
├── README.md               # This file
├── wit/
│   ├── sys-compose/        # Core WIT definitions
│   ├── canon-wit/          # Canonical WIT package
│   ├── canon-cbor/         # Canonical CBOR profile
│   ├── std-secrets/        # Secrets store WIT
│   ├── std-metrics/        # Metrics WIT
│   ├── std-audit/          # Audit WIT
│   └── std-attest/         # Attestation WIT
├── hosts/
│   ├── wasmtime/           # Reference host implementation
│   └── ...
├── tools/
│   └── composectl/         # CLI utilities
├── conformance/
│   ├── vectors/            # Canonical test vectors
│   └── runner/             # Executable conformance tests
└── examples/
    ├── hello-cli/          # Example CLI component
    └── hello-http/         # Example HTTP component

---

Development Milestones

1. Canonicalization Layer

   • canon:cbor and canon:wit with test vectors.

2. Core Compositor

   • Implement plan, emit, and exec with incremental validation.

3. Trust and Secrets

   • PKCS#11 backend, SigStore verifier, Vault adapter.

4. Policy and Tenancy

   • Capability filtering, required/optional enforcement, tenant scopes.

5. Observability

   • std:metrics and std:audit integration.

6. Conformance and Distribution

   • Static vectors, executable suite, OCI packaging.

---

Caching & Determinism

Key	Composition	Description
Emit key	H(plan + digests + "emit:v1")	Artifact reproducibility
Exec key	H(plan + digests + host/policy/fingerprint)	Safe runtime reuse

---

Security and Policy

• Secrets are never serialized; only token handles flow through CBOR.
• Capabilities are deny-by-default, explicitly requested and filtered.
• Trust verification is pluggable; hosts may enforce mandatory signature checks.

---

Conformance

Run the conformance suite to verify host compliance:

cargo test --all
cargo run -p conformance-runner -- run --json artifacts/conformance-summary.json

The second command shells out to composectl plan validate for each canonical fixture and produces a machine-readable summary. Outputs include:

• Pass/fail summary
• Metrics & event logs
• Signed attestation report (if host supports std:attest)
• JSON summary (artifacts/conformance-summary.json) containing stdout/stderr for each fixture

---

Distribution

Artifacts and WIT packages are distributed via both:

• Git: signed tags (v1.0.0)
• OCI: oci://registry.example.com/wit/sys/compose:v1.0.0

Media type: application/vnd.wit.bundle.v1+tar

---

License

Apache License 2.0 (recommended for interoperability).

---

Author

Zachary Whitley https://github.com/zacharywhitley Project Maintainer and Spec Author

---

Status

🧠 Draft Implementation in Progress Follow the milestones in SPEC.md and CODEx_TASKS.md once generated.

---

“Deterministic when required, flexible when allowed.” — Design principle of the Compositional WebAssembly System

---