diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..0459e4a --- /dev/null +++ b/.editorconfig @@ -0,0 +1,18 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.py] +indent_style = space +indent_size = 4 + +[*.{md,yml,yaml,toml,json}] +indent_style = space +indent_size = 2 + +[Makefile] +indent_style = tab diff --git a/.github/workflows/repository-hygiene.yml b/.github/workflows/repository-hygiene.yml new file mode 100644 index 0000000..541a6d1 --- /dev/null +++ b/.github/workflows/repository-hygiene.yml @@ -0,0 +1,20 @@ +name: Repository Hygiene + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + hygiene: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 + with: + python-version: "3.12" + - name: Repository hygiene + run: python scripts/check_repo_hygiene.py diff --git a/README.md b/README.md index 5db6fc6..49c8530 100644 --- a/README.md +++ b/README.md @@ -1,336 +1,279 @@ -# HOWEDO - -**Continuity infrastructure for long-lived and autonomous AI agents.** +![HOWEDO — Reality-aware continuity control plane](docs/assets/howedo-banner.svg) -HOWEDO determines whether an agent can safely continue after the reality it depends on has changed. +# HOWEDO -## Product boundary +**Reality-aware continuity and integrity control plane for long-lived and autonomous AI agents.** -HOWEDO is **not** an agent runtime, workflow engine, memory database, IAM system, sandbox, or observability platform. +[![CI](https://github.com/eimyroot/HOWEDO/actions/workflows/ci.yml/badge.svg)](https://github.com/eimyroot/HOWEDO/actions/workflows/ci.yml) +[![Container](https://github.com/eimyroot/HOWEDO/actions/workflows/container.yml/badge.svg)](https://github.com/eimyroot/HOWEDO/actions/workflows/container.yml) +[![License](https://img.shields.io/badge/license-Apache--2.0-78ffd6)](LICENSE) -It is a vendor-neutral continuity and integrity control plane that evaluates exact state revisions, dependency validity, semantic compatibility, concurrent writes, and recovery validity. +HOWEDO answers one operational question: -## Core decision contract +> **Is the reality this execution depends on still valid enough for the agent to continue?** -Every continuity check resolves to one of: +Persistence can restore what an agent knew. HOWEDO evaluates whether that state, its dependencies, +its semantic assumptions, concurrent-write fences, and recovery binding are still valid **now**. -- `CONTINUE` -- `PAUSE` -- `REVALIDATE` -- `ABORT` -- `RECOVER` +## Operator cockpit -## Core subsystems +HOWEDO ships a lightweight cockpit in the same FastAPI process as the service API. -- **State Registry** — immutable resource identities and revisions. -- **SEMLOCK** — semantic snapshot and compatibility checks. -- **RECALL** — dependency graph and propagated invalidation. -- **CONCUR** — expected-head checks, fencing, and conflict detection. -- **Recovery** — validates restored state against current reality. -- **Decision Engine** — deterministic continuity decisions. -- **Continuity Witness** — reproducible evidence of each decision. - -## R0-R15 baseline - -The current development baseline contains: - -- deterministic continuity kernel and witness contract; -- SEMLOCK semantic drift classification; -- RECALL dependency invalidation; -- CONCUR expected-head and fencing checks; -- recovery validity / safe-resume gating; -- stable `howedo.protocol.v1` schemas; -- optional PostgreSQL reference persistence adapter; -- optional LangGraph OSS runtime adapter; -- optional Temporal OSS Python runtime adapter; -- vendor-neutral `howedo.runtime-adapter.v1` contract; -- executable runtime-adapter conformance kit; -- third-party adapter SDK surface and reference bridges; -- content-addressed `howedo.adapter-conformance-artifact.v1` records; -- core-only conformance artifact verifier and CLI; -- CI-produced evidence artifacts for LangGraph and Temporal reference adapters; -- in-toto Statement v1 binding for exact conformance artifacts; -- core-only attestation builder and semantic verifier CLIs; -- Sigstore keyless reference signing through GitHub Actions OIDC; -- content-addressed `howedo.attestation-trust-policy.v1` consumer policies; -- deterministic `ACCEPT` / `REJECT` attestation trust evaluation; -- Sigstore/Cosign reference crypto-verifier adapter; -- standard in-toto Simple Verification Result v0.2 trust receipts; -- content-addressed `howedo.consumer-trust-profile.v1` relying-party expectations; -- portable `howedo.certification-package.v1` evidence packages; -- independent consumer replay of the R9 → R11 chain, including cryptographically verified GitHub workflow-name claims and pinned consumer-profile digests; -- optional TUF trust-root distribution and rotation for consumer trust profiles; -- content-addressed `howedo.trust-distribution-receipt.v1` update evidence; -- content-addressed `howedo.trust-root-publication-policy.v1` and `howedo.trust-root-publication-manifest.v1` contracts; -- complete public TUF root-history verification plus an offline production root-ceremony / rotation / compromise runbook; -- content-addressed `howedo.release-bundle.v1` binding wheel, sdist, CycloneDX SBOM, exact tag, commit, and tree; -- required CI release-candidate build, clean-install, SBOM, and release-bundle replay on Python 3.12 and 3.13; -- staged draft GitHub Release workflow with provenance/SBOM attestations and a separate fail-closed PyPI Trusted Publishing workflow. - -## Installation profiles - -The core package has no required runtime or cryptography dependencies: - -```bash -pip install howedo-continuity +```text +http://127.0.0.1:8000/ +http://127.0.0.1:8000/cockpit ``` -The adapter contract, conformance kit, artifact verifier, attestation statement builder/verifier, trust policy engine, consumer certification verifier, trust-distribution contract, trust-root publication contract, release-bundle verifier, and SDK helpers are part of core and do not require a runtime vendor SDK or signing library merely to import HOWEDO. Executing TUF cryptographic verification requires the optional `tuf` profile. +The cockpit is intentionally presentation-only. It does not own continuity semantics, persistence, +or runtime control. It calls the same public API that external consumers use. -Optional integrations are isolated extras: +### Run with Docker Compose ```bash -pip install 'howedo-continuity[postgres]' -pip install 'howedo-continuity[langgraph]' -pip install 'howedo-continuity[temporal]' -pip install 'howedo-continuity[tuf]' -pip install 'howedo-continuity[postgres,langgraph,temporal,tuf]' +docker compose up --build ``` -The `release` extra contains build/release tooling for HOWEDO maintainers; it is not a runtime requirement for consumers. - -## Runtime adapter contract - -`howedo.runtime-adapter.v1` defines the narrow interoperability boundary for external runtimes: +Then open: ```text -exact runtime identity - ↓ -capture HOWEDO recovery binding - ↓ -validate against current reality - ↓ -RECOVER only - ↓ -continue exact bound execution +http://127.0.0.1:8000/ ``` -A conforming adapter declares a content-addressed capability manifest and exposes exact identity, capture, validation, and continuation operations. The shared conformance kit verifies the vendor-neutral invariants; runtime-specific fixtures prove exact targeting and real continuation behavior. - -See `docs/runtime-adapter-v1.md`, `docs/third-party-adapters.md`, and `examples/third_party_runtime_adapter.py`. - -## Conformance artifacts - -R9 turns a conformance run into a portable content-addressed JSON record. A saved artifact can be verified without installing LangGraph, Temporal, PostgreSQL, or another runtime SDK: +### Run from Python ```bash -howedo-verify-conformance artifact.json +python -m venv .venv +source .venv/bin/activate +python -m pip install -e '.[api]' +howedo-cockpit ``` -See `docs/adapter-conformance-artifact-v1.md` and `docs/adr/ADR-0010-adapter-conformance-artifact-v1.md`. +Use a non-loopback bind only when you intentionally want to expose the service: -## Signed conformance attestations +```bash +howedo-cockpit --host 0.0.0.0 --port 8000 +``` -R10 binds an exact R9 artifact to an in-toto Statement v1 and uses Sigstore/Cosign with GitHub Actions OIDC as the reference keyless signing path: +Health and API documentation: ```text -R9 artifact - ↓ -in-toto Statement/v1 - ↓ -HOWEDO semantic verification - ↓ -Sigstore keyless signature bundle - ↓ -expected workflow identity verification +GET /health +GET /ready +GET /docs +POST /v1/continuity/check +POST /v1/recovery/check ``` -Core-only commands build and verify the semantic binding: +## Decision contract -```bash -howedo-build-attestation artifact.json artifact.intoto.json -howedo-verify-attestation artifact.json artifact.intoto.json -``` - -See `docs/signed-conformance-attestation-v1.md` and `docs/adr/ADR-0011-signed-conformance-attestation.md`. +Every continuity evaluation resolves to one of five actions: -## Attestation trust policy +| Action | Meaning | +| --- | --- | +| `CONTINUE` | The bound reality is still valid for normal continuation. | +| `PAUSE` | The execution must stop and wait for a safe condition or operator action. | +| `REVALIDATE` | The execution requires a fresh validation step before proceeding. | +| `ABORT` | The bound execution must not continue. | +| `RECOVER` | A validated recovery binding permits safe continuation from a checkpoint. | -R11 evaluates authenticated R10 evidence against a deterministic consumer policy and emits a standard in-toto Simple Verification Result v0.2: +## Architecture ```text -R9 integrity -AND R10 semantic binding -AND external crypto verification -AND HOWEDO trust policy - ↓ -ACCEPT / REJECT - ↓ -in-toto SVR v0.2 +┌─────────────────────────────────────────────────────────────┐ +│ Presentation boundary │ +│ Cockpit · FastAPI · OpenAPI │ +└──────────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────────▼──────────────────────────────┐ +│ Application/service boundary │ +│ Request validation · DTO mapping · stable public endpoints │ +└──────────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────────▼──────────────────────────────┐ +│ Continuity kernel │ +│ STATE · SEMLOCK · RECALL · CONCUR · RECOVERY · DECISION │ +└──────────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────────▼──────────────────────────────┐ +│ Evidence + trust │ +│ Witness · conformance · in-toto · trust policy · TUF │ +└──────────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────────▼──────────────────────────────┐ +│ Adapters │ +│ PostgreSQL · LangGraph · Temporal · future runtime bridges │ +└─────────────────────────────────────────────────────────────┘ ``` -The reference verifier is: - -```bash -howedo-verify-sigstore-trust ... -``` +The architecture rule is strict: **adapters and presentation may invoke HOWEDO semantics; they do +not redefine them.** -The production reference policy accepts only the canonical workflow on `refs/heads/main`; pull requests use a separate test-only policy. +Detailed scaffold and dependency-direction rules are in +[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). -See `docs/attestation-trust-policy-v1.md` and `docs/adr/ADR-0012-attestation-trust-policy.md`. +## Core subsystems -## Consumer certification replay +- **State Registry** — immutable resource identities and exact revisions. +- **SEMLOCK** — semantic snapshot and compatibility checks. +- **RECALL** — dependency graph and propagated invalidation. +- **CONCUR** — expected-head checks, fencing, and conflict detection. +- **Recovery** — safe-resume validation against current reality. +- **Decision Engine** — deterministic continuity decisions. +- **Continuity Witness** — reproducible evidence for each decision. -R12 lets a relying consumer replay the certification chain independently instead of trusting a producer-generated `ACCEPT` as an oracle: +## Minimal API example -```text -portable certification package - ↓ -consumer trust profile - ↓ -file-digest verification - ↓ -R9 + R10 replay - ↓ -Sigstore verification - ↓ -pinned R11 policy identity/digest - ↓ -local R11 policy + SVR replay - ↓ -R11 SVR signature verification - ↓ -ACCEPT / REJECT +```bash +curl -sS http://127.0.0.1:8000/v1/continuity/check \ + -H 'content-type: application/json' \ + -d '{ + "snapshot": [{ + "resource_id": "repo://example", + "revision": "git:abc", + "digest": "sha256:abc" + }], + "current_heads": [{ + "resource_id": "repo://example", + "revision": "git:abc", + "digest": "sha256:abc" + }] + }' ``` -`howedo.consumer-trust-profile.v1` pins relying-party expectations independently of the package. `howedo.certification-package.v1` is transport/index material over authenticated R9/R10/R11 evidence; it is not a new PKI or a producer-controlled trust root. +For exact matching state, the expected action is `CONTINUE` and the response includes a continuity +witness. Unknown, stale, incompatible, or conflicting state is handled by the kernel rather than +silently treated as current. -See `docs/consumer-certification-v1.md` and `docs/adr/ADR-0013-consumer-certification-replay.md`. - -## Trust-root distribution and rotation +## Installation profiles -R13 removes the need to replace a pinned R12 consumer-profile digest manually forever while preserving an independently bootstrapped trust anchor. +The continuity core has no required runtime or cryptography dependencies: -```text -out-of-band trusted TUF root - ↓ -TUF metadata refresh - ├── sequential root rotation - ├── freshness / expiry checks - ├── rollback protection - └── target length + hash verification - ↓ -verified howedo.consumer-trust-profile.v1 target - ↓ -HOWEDO profile validation - ↓ -howedo.trust-distribution-receipt.v1 +```bash +pip install howedo-continuity ``` -The TUF repository URL is not the trust root. The initial TUF root bytes must arrive through an independently trusted bootstrap channel. HOWEDO records their SHA-256 digest, the final trusted TUF root version, exact target hashes, and resulting consumer-profile digest in the update receipt. - -Reference CLI: +Optional integrations are isolated extras: ```bash -howedo-fetch-consumer-trust-profile \ - --bootstrap-root root.json \ - --metadata-dir .howedo/tuf/metadata \ - --metadata-base-url https://example.invalid/metadata/ \ - --target-dir .howedo/tuf/targets \ - --target-base-url https://example.invalid/targets/ \ - --profile-output consumer-profile.json \ - --receipt-output trust-update-receipt.json +pip install 'howedo-continuity[api]' +pip install 'howedo-continuity[postgres]' +pip install 'howedo-continuity[langgraph]' +pip install 'howedo-continuity[temporal]' +pip install 'howedo-continuity[tuf]' ``` -HOWEDO does not implement a TUF-like metadata format, repository server, PKI, or key ceremony. TUF remains an optional distribution/rotation substrate. +Maintainer tooling: -See `docs/adr/ADR-0014-tuf-trust-root-distribution.md`. +```bash +pip install -e '.[dev,api,postgres,langgraph,temporal,tuf,release]' +``` -## Production trust-root publication +## Runtime adapter contract -R14 turns the R13 bootstrap/rotation mechanism into a verifiable public trust-root publication contract without moving production private keys into HOWEDO, GitHub, or CI. +`howedo.runtime-adapter.v1` keeps the interoperability boundary deliberately narrow: ```text -public TUF root history 1..N +exact runtime identity ↓ -root v1 self-threshold verification +capture HOWEDO recovery binding ↓ -N → N+1 old + new threshold verification +validate against current reality ↓ -HOWEDO production publication policy - ├── minimum root key count / threshold - ├── consistent snapshots - ├── disjoint top-level role key IDs - ├── HTTPS publication endpoints - └── minimum remaining root validity +RECOVER only ↓ -content-addressed publication manifest +continue exact bound execution ``` -Reference commands: - -```bash -howedo-build-trust-root-publication ... -howedo-verify-trust-root-publication ... -``` +Implemented reference integrations: -The R14 software publication mechanism is preserved in the R0-R15 development baseline. **Production activation is separate:** a real production root ceremony, production public root v1, publication endpoints, and production TUF repository are not created by normal HOWEDO CI. No production private root key is generated or stored by this repository workflow. +- PostgreSQL persistence adapter; +- LangGraph OSS exact checkpoint binding; +- Temporal OSS exact `namespace + workflow_id + run_id` binding; +- Sigstore/Cosign verification for the reference trust flow; +- The Update Framework (TUF) for optional trust-profile distribution and root rotation. -See `docs/trust-root-publication-v1.md`, `docs/operations/TUF_ROOT_CEREMONY.md`, and `docs/adr/ADR-0015-production-trust-root-publication.md`. +Future adapters can target other runtimes without moving continuity semantics out of the kernel. -## Distribution and release engineering +## Evidence and trust chain -R15 turns the Python codebase into a verifiable release candidate while preserving a fail-closed public-publication boundary. +HOWEDO contains a pre-1.0 engineering chain for: ```text -protected canonical main - ↓ -version tag vX.Y.Z - ↓ -wheel + sdist build once - ↓ -clean wheel installation - ↓ -reproducible CycloneDX 1.6 SBOM - ↓ -howedo.release-bundle.v1 - ↓ -GitHub provenance + SBOM attestations - ↓ -verified assets attached to DRAFT GitHub Release - ↓ -human review + immutable release publication - ↓ -optional PyPI OIDC Trusted Publishing +adapter conformance + ↓ +content-addressed artifact + ↓ +in-toto statement + ↓ +cryptographic verification + ↓ +consumer trust policy + ↓ +independent certification replay + ↓ +optional TUF trust distribution + ↓ +release bundle + SBOM + provenance ``` -Reference release-bundle commands: +Reference CLIs include: ```bash -howedo-build-release-bundle ... -howedo-verify-release-bundle release.json --root dist ... +howedo-verify-conformance +howedo-build-attestation +howedo-verify-attestation +howedo-verify-sigstore-trust +howedo-build-certification-package +howedo-verify-certification-package +howedo-fetch-consumer-trust-profile +howedo-build-trust-root-publication +howedo-verify-trust-root-publication +howedo-build-release-bundle +howedo-verify-release-bundle ``` -The public release boundary is intentionally separate from R15 software completion. Before the first public HOWEDO release, GitHub release immutability must be enabled, package/license terms must be explicitly decided, the package name must be rechecked immediately before publication, the PyPI Trusted Publisher and protected `pypi` environment must be configured, and `HOWEDO_PYPI_PUBLISH_ENABLED=true` must be intentionally activated. No long-lived PyPI token is part of the design. - -See `docs/release-engineering-r15.md` and `docs/adr/ADR-0016-release-engineering.md`. +## Repository quality gates -## Canonical change channel +The canonical repository uses: -Canonical `main` is protected by the active repository ruleset **`HOWEDO canonical main protection`** (ruleset id `20928865`). The ruleset has no bypass actors and requires the exact GitHub Actions checks used by the project before merge. +- protected `main` and pull-request-based change flow; +- CODEOWNERS and an evidence-first PR template; +- Python 3.12/3.13 CI; +- Ruff and pytest; +- release-candidate wheel/sdist verification; +- container build, smoke, provenance, and SBOM workflows; +- deterministic repository-hygiene checks; +- explicit [`SECURITY.md`](SECURITY.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md). -The protected channel requires a pull request, resolved review threads, strict required checks, merge commits, and blocks deletion plus non-fast-forward / force-push updates. `Canonical Channel / provenance` additionally verifies that a resulting `main` head is attributable to a merged PR targeting `main`. +Run the local baseline: -Repository governance is therefore preventive as well as evidence-producing; it is separate from HOWEDO runtime semantics. - -See `docs/governance/CANONICAL_CHANNEL_PROTECTION.md`. +```bash +python -m pip install -e '.[dev,api]' +ruff check . +pytest +python scripts/check_repo_hygiene.py +``` -## Integrations +## Production boundary -**Implemented reference integrations:** +HOWEDO is **pre-1.0 release-candidate engineering**, not a claim of independently audited +production trust infrastructure. -- PostgreSQL — persistence/reference storage adapter. -- LangGraph OSS — exact checkpoint binding and HOWEDO-gated resume through the public LangGraph API. -- Temporal OSS — exact workflow-run binding and HOWEDO-gated signal delivery through the public Temporal Python SDK. -- Sigstore/Cosign — external cryptographic verification for the R10–R12 reference trust flow. -- The Update Framework (TUF) — optional consumer trust-profile bootstrap, distribution, integrity, freshness, root rotation, and public trust-root publication verification substrate. +The repository includes software contracts, verification mechanisms, and operational runbooks. +Production trust-root activation, public package publication, external security review, and any +production deployment authority remain separate gates. -The Temporal adapter deliberately binds `namespace + workflow_id + run_id`. A continuation request is never redirected to an unrelated or successor run merely because it shares the same workflow ID. The bound run must still be `RUNNING`, and HOWEDO recovery validity must resolve to `RECOVER`, before the adapter sends the signal. +See [`docs/RELEASE_READINESS.md`](docs/RELEASE_READINESS.md). -**Future adapters:** OpenAI, AWS AgentCore, custom Python runtimes, CASER, and V-One. +## Documentation map -Adapters never own HOWEDO continuity semantics and are not required dependencies of the core package. +- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — scaffold, layers, dependency direction. +- [`docs/RELEASE_READINESS.md`](docs/RELEASE_READINESS.md) — implemented vs. outstanding gates. +- [`docs/CONSTITUTION.md`](docs/CONSTITUTION.md) — continuity principles and invariants. +- [`docs/adr/`](docs/adr/) — architecture decision records. +- [`docs/operations/`](docs/operations/) — operational trust procedures. +- [`examples/`](examples/) — integration examples. ## Canonical invariant -> Persistence tells you what the agent knew. HOWEDO determines whether it is still valid to act on it. +> **Persistence tells you what the agent knew. HOWEDO determines whether it is still valid to act on it.** diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..b100ae9 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,14 @@ +services: + howedo: + build: + context: . + ports: + - "127.0.0.1:8000:8000" + read_only: true + tmpfs: + - /tmp:size=16m,mode=1777 + cap_drop: + - ALL + security_opt: + - no-new-privileges:true + restart: unless-stopped diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..ec8d938 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,271 @@ +# HOWEDO Architecture + +Status: **canonical scaffold for the pre-1.0 repository** + +This document defines where new code belongs, which direction dependencies may flow, and which +boundaries must remain stable as HOWEDO grows. + +## Architectural objective + +HOWEDO is a continuity and integrity control plane. It is not an agent runtime, workflow engine, +memory database, IAM system, sandbox, or observability platform. + +The primary architectural requirement is therefore separation of **continuity semantics** from +presentation, deployment, persistence, and vendor-runtime integration. + +## Layer model + +### 1. Presentation boundary + +Paths: + +```text +src/howedo/api/ +``` + +Responsibilities: + +- FastAPI HTTP surface; +- request/response transport models; +- operator cockpit; +- OpenAPI exposure; +- transport-level health/readiness. + +Rules: + +- may call application/service functions; +- must not implement continuity decision rules; +- cockpit code must not become a second source of truth; +- browser assets must remain self-contained unless an explicit supply-chain decision says otherwise. + +### 2. Application/service boundary + +Paths: + +```text +src/howedo/api/service.py +src/howedo/api/models.py +``` + +Responsibilities: + +- translate validated transport models into kernel types; +- invoke continuity/recovery services; +- translate kernel results back to stable API responses. + +Rules: + +- no vendor-runtime orchestration; +- no persistence ownership; +- no hidden policy defaults that change kernel semantics. + +### 3. Continuity kernel + +Representative paths: + +```text +src/howedo/domain.py +src/howedo/kernel.py +src/howedo/semlock.py +src/howedo/recall.py +src/howedo/concur.py +src/howedo/recovery.py +src/howedo/protocol.py +``` + +Responsibilities: + +- exact revision identity; +- semantic compatibility; +- dependency invalidation; +- fencing and concurrency safety; +- recovery validity; +- deterministic decisions and evidence. + +Rules: + +- core imports must remain vendor-neutral; +- continuity actions are determined here, not in adapters; +- deterministic evidence contracts are part of the compatibility surface. + +### 4. Evidence, certification, and trust + +Representative paths: + +```text +src/howedo/adapter_conformance.py +src/howedo/adapter_certification.py +src/howedo/attestation.py +src/howedo/consumer_trust.py +src/howedo/certification_package.py +src/howedo/trust_distribution.py +src/howedo/trust_publication.py +src/howedo/release_bundle.py +``` + +Responsibilities: + +- portable conformance evidence; +- in-toto binding; +- trust-policy evaluation; +- independent consumer replay; +- TUF-assisted trust distribution; +- release-bundle integrity. + +Rules: + +- cryptographic verification is distinct from semantic verification; +- producer evidence is not automatically consumer authority; +- production private trust-root keys remain outside the repository and CI. + +### 5. Adapters and storage + +Paths: + +```text +src/howedo/adapters/ +src/howedo/storage/ +``` + +Responsibilities: + +- translate external runtime identity into HOWEDO contracts; +- bind exact runtime/checkpoint identity; +- provide optional persistence implementations. + +Rules: + +- adapters never own HOWEDO continuity semantics; +- runtime continuation is permitted only after the required HOWEDO decision; +- optional vendor SDKs must remain isolated behind extras. + +## Dependency direction + +Preferred dependency flow: + +```text +cockpit / HTTP + ↓ +API service mapping + ↓ +continuity kernel + ↓ +protocol / evidence contracts + +runtime adapter ───────────────→ continuity kernel +storage adapter ───────────────→ storage/kernel contracts +trust verifier ────────────────→ evidence/trust contracts +``` + +Forbidden direction examples: + +```text +kernel → FastAPI +kernel → LangGraph +kernel → Temporal +kernel → PostgreSQL driver +kernel → cockpit HTML/JavaScript +``` + +The core package must remain importable without installing optional runtime, API, database, TUF, or +release-tool dependencies. + +## Repository scaffold + +```text +HOWEDO/ +├── .github/ +│ ├── CODEOWNERS +│ ├── pull_request_template.md +│ └── workflows/ +├── docs/ +│ ├── adr/ +│ ├── governance/ +│ ├── operations/ +│ └── assets/ +├── examples/ +├── policies/ +├── schemas/ +├── scripts/ +├── src/howedo/ +│ ├── adapters/ +│ ├── api/ +│ └── storage/ +└── tests/ + ├── api/ + ├── conformance/ + └── integration/ +``` + +### Placement rule + +Before adding a new top-level directory, answer all three questions: + +1. Why can the content not live in an existing bounded context? +2. What is its ownership and dependency direction? +3. Which automated check proves that the new boundary remains valid? + +If those answers are unclear, do not create the directory. + +## Cockpit boundary + +The cockpit is served at: + +```text +GET / +GET /cockpit +``` + +It is deliberately implemented inside the existing FastAPI deployment to avoid a second build +toolchain, JavaScript package supply chain, deployment artifact, and version-skew boundary. + +The cockpit may: + +- read health/readiness; +- call documented HOWEDO API endpoints; +- visualize deterministic API output; +- link to OpenAPI documentation. + +The cockpit must not: + +- bypass API validation; +- mutate kernel state directly; +- invent a second decision model; +- conceal failed or unavailable checks; +- load third-party browser code without an explicit reviewed decision. + +## Security and operational boundaries + +- Default local cockpit bind: `127.0.0.1`. +- Docker runtime remains non-root. +- The compose profile binds the host port to loopback by default. +- Production deployment authority is an immutable OCI image digest, not a mutable tag. +- A green test or workflow only proves the scope exercised by that check. + +## Quality gates + +Repository changes should satisfy: + +```bash +ruff check . +pytest +python scripts/check_repo_hygiene.py +``` + +The hygiene check verifies required scaffold paths and rejects tracked local/generated artifacts. +It is intentionally narrow: architecture correctness is still enforced by tests, reviews, ADRs, and +dependency discipline rather than by pretending a filename check is a security proof. + +## Change policy + +Use an ADR when a change: + +- moves continuity semantics across a layer boundary; +- introduces a required runtime dependency; +- changes a public protocol or evidence contract; +- changes trust authority or cryptographic verification behavior; +- introduces a new execution/runtime adapter contract; +- changes the production release or trust-root boundary. + +Presentation-only cockpit refinements do not require an ADR unless they change one of those +boundaries. diff --git a/docs/RELEASE_READINESS.md b/docs/RELEASE_READINESS.md index eaf4cd4..bdf5748 100644 --- a/docs/RELEASE_READINESS.md +++ b/docs/RELEASE_READINESS.md @@ -2,32 +2,42 @@ Status: **pre-1.0 / release-candidate engineering** -This document separates implemented repository controls from production trust ceremonies and external assurance. A checked implementation item is not equivalent to an independently audited production guarantee. +This document separates implemented repository controls from production trust ceremonies and +external assurance. A checked implementation item is not equivalent to an independently audited +production guarantee. ## Implemented repository baseline -- Deterministic continuity kernel with `CONTINUE`, `PAUSE`, `REVALIDATE`, `ABORT`, and `RECOVER` decisions. +- Deterministic continuity kernel with `CONTINUE`, `PAUSE`, `REVALIDATE`, `ABORT`, and `RECOVER`. - Continuity Witness evidence contract. - Runtime adapter contract and reference LangGraph/Temporal adapters. -- Conformance artifacts, in-toto attestation binding, trust-policy verification, consumer replay, TUF distribution contracts, trust-root publication contracts, and release-bundle verification. -- R16.1 FastAPI service boundary with health/readiness endpoints and continuity-check API. -- R16.2 hardened OCI runtime definition and GHCR build/publish pipeline using commit-bound tags, immutable image digests, provenance attestation, SBOM generation, non-root runtime, dropped capabilities, read-only verification, and health/API smoke checks. -- Apache-2.0 repository license and explicit security policy. +- Conformance artifacts, in-toto attestation binding, trust-policy verification, consumer replay, + TUF distribution contracts, trust-root publication contracts, and release-bundle verification. +- R16.1 FastAPI service boundary with health/readiness and continuity/recovery endpoints. +- R16.2 hardened OCI runtime and GHCR pipeline with non-root execution, digest-bound deployment, + provenance, SBOM generation, health/API smoke checks, and read-only verification. +- R16.3 self-contained operator cockpit served by the existing FastAPI process, browser hardening + headers, a loopback-first local launch path, canonical scaffold documentation, and deterministic + repository-hygiene checks. +- Apache-2.0 repository license, security policy, CODEOWNERS, contribution policy, and PR evidence + template. ## Mandatory gates before first public PyPI production release -The following are operational decisions or external actions and MUST NOT be represented as completed until evidence exists: +The following are operational decisions or external actions and MUST NOT be represented as completed +until evidence exists: 1. Confirm the public package name `howedo-continuity` is final and uncontested. 2. Enable PyPI Trusted Publishing only for the intended production environment and canonical workflow. 3. Produce a release candidate from a protected canonical commit and preserve the exact release-bundle evidence. 4. Verify wheel/sdist clean installation and the complete release verification matrix in GitHub Actions. -5. Verify that package metadata resolves to `https://github.com/eimyroot/HOWEDO` and includes the Apache-2.0 license. +5. Verify package metadata, repository links, and Apache-2.0 license material in the built artifacts. 6. Keep any publish-enablement switch fail-closed until the release owner explicitly authorizes publication. ## Mandatory gates before production TUF trust-root activation -The repository contains contracts and runbooks; this does not mean a production trust root currently exists. +The repository contains contracts and runbooks; this does not mean a production trust root currently +exists. Before production activation: @@ -42,14 +52,16 @@ Before production activation: Before describing HOWEDO as independently verified production trust/security infrastructure: -1. Complete a line-level review of the Decision Engine, SEMLOCK, RECALL/CONCUR interactions, recovery fencing, attestation verification, TUF rotation, and release workflows. -2. Obtain at least one independent security review from a person who did not author the implementation under review. +1. Complete a line-level review of the Decision Engine, SEMLOCK, RECALL/CONCUR interactions, + recovery fencing, attestation verification, TUF rotation, and release workflows. +2. Obtain at least one independent security review from a person who did not author the implementation. 3. Track findings to closure with reproducible regression tests. -4. Publish a reference deployment/case study demonstrating a real stale-state or dependency-drift incident that HOWEDO detects and handles safely. +4. Publish a reference deployment/case study demonstrating a real stale-state or dependency-drift + incident that HOWEDO detects and handles safely. ## Deployment authority -For OCI deployment, mutable tags such as `main` are convenience aliases only. The deployment authority is: +For OCI deployment, mutable tags such as `main` are convenience aliases only. Deployment authority is: ```text ghcr.io/eimyroot/howedo@sha256: @@ -57,6 +69,18 @@ ghcr.io/eimyroot/howedo@sha256: The digest must be produced by the canonical build and recorded as release/deployment evidence. +## Cockpit deployment boundary + +The cockpit does not introduce a separate frontend deployment. It is served by the same FastAPI +application and therefore shares the service deployment authority. + +Local examples bind to loopback by default. Exposing the cockpit outside localhost is an explicit +operator decision and must be paired with the deployment's network, authentication, TLS, and ingress +controls. The cockpit itself is not an IAM layer. + ## Current interpretation -HOWEDO can be treated as a serious pre-1.0 continuity/security engineering project with a substantial implemented verification surface. Production trust claims remain conditional on the operational trust-root ceremony, release activation, and independent review gates above. +HOWEDO can be treated as a serious pre-1.0 continuity/security engineering project with a substantial +implemented verification surface and a runnable operator interface. Production trust claims remain +conditional on the trust-root ceremony, release activation, production deployment controls, and +independent review gates above. diff --git a/docs/assets/howedo-banner.svg b/docs/assets/howedo-banner.svg new file mode 100644 index 0000000..6ca2854 --- /dev/null +++ b/docs/assets/howedo-banner.svg @@ -0,0 +1,57 @@ + + HOWEDO + Reality-aware continuity control plane for autonomous AI agents. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HOWEDO + REALITY-AWARE CONTINUITY CONTROL PLANE + Validate state · semantics · dependencies · fences · recovery before autonomous execution continues. + + + + CONTINUE + + PAUSE + + RECOVER + + + + + + diff --git a/pyproject.toml b/pyproject.toml index 8dfc694..760a6de 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,9 +14,11 @@ dependencies = [] [project.urls] Repository = "https://github.com/eimyroot/HOWEDO" +Documentation = "https://github.com/eimyroot/HOWEDO/blob/main/docs/ARCHITECTURE.md" Issues = "https://github.com/eimyroot/HOWEDO/issues" [project.scripts] +howedo-cockpit = "howedo.api.cli:main" howedo-verify-conformance = "howedo.certification_cli:main" howedo-build-attestation = "howedo.attestation_cli:build_main" howedo-verify-attestation = "howedo.attestation_cli:verify_main" diff --git a/scripts/check_repo_hygiene.py b/scripts/check_repo_hygiene.py new file mode 100644 index 0000000..f74df1d --- /dev/null +++ b/scripts/check_repo_hygiene.py @@ -0,0 +1,80 @@ +from __future__ import annotations + +import subprocess +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +REQUIRED_PATHS = ( + ".github/CODEOWNERS", + ".github/pull_request_template.md", + ".github/workflows/ci.yml", + ".gitignore", + "CONTRIBUTING.md", + "Dockerfile", + "LICENSE", + "README.md", + "SECURITY.md", + "docs/ARCHITECTURE.md", + "docs/adr", + "pyproject.toml", + "src/howedo", + "tests", +) + +FORBIDDEN_DIRECTORY_NAMES = { + ".mypy_cache", + ".pytest_cache", + ".ruff_cache", + ".venv", + "__pycache__", + "build", + "dist", + "node_modules", + "venv", +} + +FORBIDDEN_FILE_NAMES = { + ".DS_Store", +} + + +def tracked_paths() -> tuple[str, ...]: + result = subprocess.run( + ["git", "ls-files", "-z"], + cwd=ROOT, + check=True, + capture_output=True, + text=True, + ) + return tuple(path for path in result.stdout.split("\0") if path) + + +def main() -> int: + errors: list[str] = [] + + for relative in REQUIRED_PATHS: + if not (ROOT / relative).exists(): + errors.append(f"missing required path: {relative}") + + for relative in tracked_paths(): + path = Path(relative) + if path.name in FORBIDDEN_FILE_NAMES: + errors.append(f"tracked generated/local file: {relative}") + if path.suffix == ".pyc": + errors.append(f"tracked bytecode file: {relative}") + if any(part in FORBIDDEN_DIRECTORY_NAMES for part in path.parts): + errors.append(f"tracked generated/local directory content: {relative}") + + if errors: + print("repository hygiene: FAIL") + for error in errors: + print(f"- {error}") + return 1 + + print(f"repository hygiene: PASS ({len(tracked_paths())} tracked paths inspected)") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/howedo/api/app.py b/src/howedo/api/app.py index aa25795..b621004 100644 --- a/src/howedo/api/app.py +++ b/src/howedo/api/app.py @@ -1,7 +1,9 @@ from __future__ import annotations from fastapi import FastAPI, HTTPException +from fastapi.responses import HTMLResponse +from .cockpit import render_cockpit from .models import ( ContinuityCheckRequest, ContinuityCheckResponse, @@ -11,14 +13,35 @@ ) from .service import check_continuity, check_recovery +_COCKPIT_HEADERS = { + "Content-Security-Policy": ( + "default-src 'none'; " + "style-src 'unsafe-inline'; " + "script-src 'unsafe-inline'; " + "connect-src 'self'; " + "img-src 'self' data:; " + "base-uri 'none'; " + "form-action 'none'; " + "frame-ancestors 'none'" + ), + "Referrer-Policy": "no-referrer", + "X-Content-Type-Options": "nosniff", + "X-Frame-Options": "DENY", +} + def create_app() -> FastAPI: app = FastAPI( title="HOWEDO", version="v1", - description="Deployable API boundary for the HOWEDO continuity kernel.", + description="Deployable API and cockpit boundary for the HOWEDO continuity kernel.", ) + @app.get("/", response_class=HTMLResponse, include_in_schema=False) + @app.get("/cockpit", response_class=HTMLResponse, include_in_schema=False) + def cockpit() -> HTMLResponse: + return HTMLResponse(content=render_cockpit(), headers=_COCKPIT_HEADERS) + @app.get( "/health", response_model=HealthResponse, diff --git a/src/howedo/api/cli.py b/src/howedo/api/cli.py new file mode 100644 index 0000000..eb775f0 --- /dev/null +++ b/src/howedo/api/cli.py @@ -0,0 +1,36 @@ +from __future__ import annotations + +import argparse + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="howedo-cockpit", + description="Run the HOWEDO API and operator cockpit.", + ) + parser.add_argument("--host", default="127.0.0.1") + parser.add_argument("--port", default=8000, type=int) + return parser + + +def main() -> None: + args = build_parser().parse_args() + + try: + import uvicorn + except ImportError as exc: + raise SystemExit( + "The cockpit requires the API profile. " + "Install it with: pip install 'howedo-continuity[api]'" + ) from exc + + uvicorn.run( + "howedo.api.app:app", + host=args.host, + port=args.port, + access_log=False, + ) + + +if __name__ == "__main__": + main() diff --git a/src/howedo/api/cockpit.py b/src/howedo/api/cockpit.py new file mode 100644 index 0000000..83b414f --- /dev/null +++ b/src/howedo/api/cockpit.py @@ -0,0 +1,302 @@ +from __future__ import annotations + +COCKPIT_HTML = """ + + + + + + HOWEDO · Continuity Cockpit + + + +
+
+
HOWEDO
+
checking runtime
+
+ +
+
Continuity control plane · R16.3
+

Know when an AI agent must not continue.

+

+ HOWEDO validates whether the state, dependencies, semantics, fences, and recovery + assumptions behind an execution are still valid before the execution proceeds. +

+
+ + Open API docs + OpenAPI JSON +
+
+ +
+
+
Runtime boundary
+
Fail closed
+

Unverifiable or stale execution assumptions do not silently become valid.

+
+
+
Evidence
+
Witnessed
+

Every continuity decision can carry deterministic, reproducible evidence.

+
+
+
Integration model
+
Vendor-neutral
+

The kernel stays independent from the agent runtime and persistence vendor.

+
+ +
+
Decision contract
+
+ CONTINUE + PAUSE + REVALIDATE + ABORT + RECOVER +
+
+ +
+
Continuity pipeline
+
+
STATEExact identities and revisions
+
SEMLOCKSemantic compatibility
+
RECALLDependency invalidation
+
CONCURHeads, fences, conflicts
+
DECIDEAction + witness
+
+
+ +
+
Operator endpoints
+

/health
/ready
/docs

+

The cockpit is presentation only. Continuity semantics remain in the kernel.

+
+ +
+
Live proof output
+
+ The demo posts an exact-state snapshot to /v1/continuity/check. +
+ 
Press “Run continuity proof” to execute a real API decision.
+
+
+ +
+ Persistence tells you what the agent knew. HOWEDO determines whether it is still valid to act on it. +
+
+ + + + +""" + + +def render_cockpit() -> str: + return COCKPIT_HTML diff --git a/tests/api/test_cockpit.py b/tests/api/test_cockpit.py new file mode 100644 index 0000000..1c27469 --- /dev/null +++ b/tests/api/test_cockpit.py @@ -0,0 +1,33 @@ +import pytest + +pytest.importorskip("fastapi") +pytest.importorskip("httpx") + +from fastapi.testclient import TestClient + +from howedo.api.app import create_app + + +def client() -> TestClient: + return TestClient(create_app()) + + +def test_root_serves_operator_cockpit() -> None: + response = client().get("/") + + assert response.status_code == 200 + assert response.headers["content-type"].startswith("text/html") + assert "HOWEDO" in response.text + assert "Continuity Cockpit" in response.text + assert "/v1/continuity/check" in response.text + + +def test_cockpit_alias_has_browser_hardening_headers() -> None: + response = client().get("/cockpit") + + assert response.status_code == 200 + assert response.headers["x-content-type-options"] == "nosniff" + assert response.headers["x-frame-options"] == "DENY" + assert response.headers["referrer-policy"] == "no-referrer" + assert "default-src 'none'" in response.headers["content-security-policy"] + assert "connect-src 'self'" in response.headers["content-security-policy"]