Agent-Control-Standard · afogel · May 6, 2026 · May 6, 2026 · May 6, 2026 · May 6, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
 .idea/
 .git/
 book/
+site/
+references/
 .DS_Store
diff --git a/docs/acs.md b/docs/acs.md
@@ -1,21 +1,21 @@
 # Agent Control Standard
 
-The Agent Control Standard (ACS) provides specification for building [trustworthy agents](./README.md).
-Agents that implement ACS can be deployed with higher trust.
-They are instrumentable, traceable and inspectable.
-They are an open book 
+The Agent Control Standard (ACS) is a wire-format specification that lets a separate **Guardian Agent** permit, deny, or modify what an AI agent does — in real time, with a verifiable audit trail.
 
-They have a dynamic bill-of-material, a clear audit trail and hard inline-controls.
+Agents that implement ACS are instrumentable (Guardians can intervene at runtime), traceable (every step emits an OpenTelemetry span and an OCSF event), and inspectable (a dynamic Agent Bill of Materials enumerates models, MCP servers, A2A peers, tools, knowledge sources, and memory stores).
 
-Trustworthiness of agents builds upon the foundation of existing standards (MCP and A2A), but provides value regardless. 
-It build upon cybersecurity and observability standards including OpenTelemetry, OCSF, CycloneDX, SPDX and SWID.
+ACS extends existing standards rather than reinventing them: JSON-RPC 2.0 for the wire format, OpenTelemetry and OCSF for observability, CycloneDX / SPDX / SWID for the AgBOM, MCP and A2A intact for tool and peer communication.
 
-ACS makes agents trustworthy.
+## What v0.1.0 ships
 
-!!! info "Work in progress"
-    This page is currently under development.
-
-    **Want to contribute?** Check out the [GitHub issue](https://github.com/Agent-Control-Standard/ACS/issues/53) and join the discussion!
+- **ACS-Core** (mandatory baseline) — capability-negotiation handshake, JSON-RPC envelope, 16 native lifecycle hooks (`sessionStart`/`End`, `agentTrigger`, `userMessage`, `agentResponse`, `turnStart`/`End`, `toolCallRequest`/`Result`, `knowledgeRetrieval`, `memoryContextRetrieval`, `memoryStore`, `preCompact`/`postCompact`, `subagentStart`/`Stop`), wrapped MCP, five dispositions (`allow`, `deny`, `modify`, `ask`, `defer`), SessionContext with rolling SHA-256 chain hash, optional Intent with immutability rule, replay protection, and `system/ping` liveness.
+- **ACS-Trace** profile — OpenTelemetry semconv mapping + OCSF event-class mapping, with decisions emitted as span events on the parent step span.
+- **ACS-Inspect** / **ACS-Inspect-Dynamic** profiles — canonical AgBOM with `agbom/snapshot` and `agbom/changed`, deterministic CycloneDX / SPDX / SWID derivations.
+- **ACS-Provenance** profile — field-level `Provenance` objects with `origin`, `source_id`, `derived_from`, and an OPTIONAL wire-format `trust` enum that obeys the monotonicity rule.
+- **ACS-Crypto** profile — crypto-agile signature registry: HMAC-SHA256 baseline, ML-DSA-65 / SLH-DSA-128s for PQC, hybrid composites for transitional deployments.
+- **ACS-Audit** profile — `request_hash` on every ContextEntry so the chain commits to request content, not just step metadata.
+
+See [Conformance Profiles](./spec/conformance.md) for what each profile requires.
 
 ## Trustworthy agents are
 

diff --git a/docs/spec/conformance.md b/docs/spec/conformance.md
@@ -0,0 +1,85 @@
+# Conformance Profiles
+
+ACS v0.1.0 conformance is tiered. Every conformant deployment implements **ACS-Core** — the mandatory baseline below. Trace event emission, AgBOM serialization, field-level provenance, cryptographic signatures, and strengthened audit chains are organized as **profiles** that deployments declare independently in the [handshake](./instrument/specification.md#4-capability-negotiation-handshake).
+
+The profile system lets a small harness ship a useful subset of ACS quickly, while a more capable deployment can layer on observability, supply-chain inventory, or cryptographic integrity without changing the wire format.
+
+## Profile declaration
+
+Profiles are declared in the handshake. ClientHello includes `profiles_supported: string[]`; ServerHello includes `profiles_accepted: string[]`. Profile names are the lowercase hyphenated forms below: `acs-core`, `acs-trace`, `acs-inspect`, `acs-inspect-dynamic`, `acs-provenance`, `acs-crypto`, `acs-audit`.
+
+A Guardian MAY refuse a session if the client does not declare a profile the Guardian's policy requires (e.g. a Guardian whose policy needs provenance MAY refuse a client that does not declare `acs-provenance`).
+
+## ACS-Core (mandatory baseline)
+
+A v0.1.0-conformant deployment MUST implement ACS-Core. ACS-Core comprises:
+
+- **Handshake** — `handshake/hello` with ClientHello/ServerHello ([Specification §4](./instrument/specification.md#4-capability-negotiation-handshake)).
+- **Request/response envelope** — JSON-RPC 2.0 with ACS extensions ([§3](./instrument/specification.md#3-wire-format)). `request_id`, `timestamp`, `acs_version`, `metadata` required on every request.
+- **Hook taxonomy** — At minimum: `sessionStart`, `userMessage` or `agentTrigger`, `toolCallRequest`, `toolCallResult`, `agentResponse`, `sessionEnd`. Additional hooks (`turnStart`/`turnEnd`, `preCompact`/`postCompact`, `subagentStart`/`subagentStop`, `knowledgeRetrieval`, `memoryContextRetrieval`, `memoryStore`) are normatively defined and SHOULD be implemented when the harness can observe the corresponding event; they are capability-negotiated via the handshake.
+- **Dispositions** — All five (ALLOW, DENY, MODIFY, ASK, DEFER) with required fields per [§6](./instrument/specification.md#6-disposition-vocabulary).
+- **SessionContext and Intent** — `session_id`, `chain_hash` (rolling SHA-256), append-only ContextEntry chain ([§8](./instrument/specification.md#8-sessioncontext-and-intent)). Intent is optional but normative when IBAC is the enforcement paradigm.
+- **Replay protection** — `request_id` (UUID) and `timestamp` on every request; Guardians MUST reject replays per [§10.3](./instrument/specification.md#103-replay-protection).
+- **Liveness** — `system/ping` ([§13](./instrument/specification.md#13-liveness-system-methods)).
+- **Wrapped MCP** — `protocols/MCP/*` ([Hooks](./instrument/hooks.md#protocolsmcp)).
+
+ACS-Core does NOT require: field-level Provenance objects, Trace event emission, AgBOM, cryptographic signatures, or `request_hash` on ContextEntry (`request_hash` remains SHOULD).
+
+## ACS-Trace
+
+Adds deterministic Trace event emission per [Trace Events](./trace/events.md). A deployment claiming ACS-Trace MUST:
+
+1. Emit at least one of {OTel, OCSF} for every supported ACS step, with the required attributes populated.
+2. Record decisions as Trace events.
+3. Carry provenance facts forward onto Trace events.
+
+Required for deployments that need cross-vendor observability or SIEM integration. Trace events MUST NOT block enforcement.
+
+## ACS-Inspect
+
+Adds AgBOM snapshot emission per [Inspect](./inspect/README.md). A deployment claiming ACS-Inspect MUST:
+
+1. Emit `agbom/snapshot` once per session before content-bearing hooks fire.
+2. Have the Guardian serialize the canonical AgBOM into at least one of {CycloneDX 1.6, SPDX 3.0, SWID} on request.
+
+Required when Guardian policy depends on component inventory.
+
+### ACS-Inspect-Dynamic (extends ACS-Inspect)
+
+Adds `agbom/changed` emission on every mid-session component mutation, with audit-chain integration. Required for deployments where agents hot-swap models, tools, or MCP servers.
+
+## ACS-Provenance
+
+Adds field-level Provenance objects ([§7](./instrument/specification.md#7-provenance)) to data-bearing fields. A deployment claiming ACS-Provenance MUST populate `provenance_id`, `origin`, and (when applicable) `derived_from` on Provenance-bearing fields.
+
+The wire-format `trust` enum is OPTIONAL in v0.1; the v0.1 expected practice is for Guardians to derive trust from `origin` + `source_id` against local policy without populating the field. Vendor Guardian implementations that elect to populate `trust` on the wire MUST enforce the monotonicity rule on `agent_generated` trust and SHOULD use the default channel-to-trust mapping ([§7.2](./instrument/specification.md#72-default-channel-to-trust-mapping)) so cross-deployment audits remain portable.
+
+Required for FIDES, CaMeL, and AARM-style enforcement paradigms (which depend on the trust *concept* — whether materialized on the wire or derived in policy). Not required for pure IBAC.
+
+## ACS-Crypto
+
+Adds cryptographic signature support beyond the baseline's replay-protection fields. A deployment claiming ACS-Crypto MUST support at least `ML-DSA-65` (RECOMMENDED primary) and SHOULD support `SLH-DSA-128s` as an algorithmic-diversity backup. Hybrid composites (`ML-DSA-65+ECDSA-P256`, `ML-DSA-65+RSA-PSS-SHA256`) are OPTIONAL for transitional deployments.
+
+Baseline deployments without ACS-Crypto MAY use `HMAC-SHA256` for integrity or rely on transport-level security; neither is required by ACS-Core.
+
+Policy-author identity is distinct from both Observed Agent identity and Guardian identity. v0.1 keeps policy-author authorization and trust schemes deployment-defined, but `policy_references[].policy_version` gives replay and ledger-backed deployments a stable pointer to the policy state that was evaluated. A future Policy Attestation profile is expected to bind policy references to verifiable author signatures using algorithms from the ACS-Crypto registry while leaving the deployment trust scheme (for example SPIFFE, OIDC, DID, organizational PKI, or quorum signing) out of the core wire contract.
+
+## ACS-Audit
+
+Strengthens the audit chain beyond ACS-Core's baseline. A deployment claiming ACS-Audit MUST populate `request_hash` (lowercase-hex SHA-256 of JCS-canonicalized request params) on every ContextEntry, ensuring the chain commits to request content, not just step metadata. ACS-Audit deployments SHOULD also populate `timestamp` and `provenance_summary` on every ContextEntry.
+
+## Profile combinations
+
+Profiles compose. A deployment that wants full observability and supply-chain inventory but not cryptographic signatures declares `["acs-core", "acs-trace", "acs-inspect", "acs-provenance"]`. A high-assurance deployment declares all of `["acs-core", "acs-trace", "acs-inspect", "acs-inspect-dynamic", "acs-provenance", "acs-crypto", "acs-audit"]`. A minimal IDE harness declares `["acs-core"]` only.
+
+## Quick reference
+
+| Profile | What it adds | When to claim |
+|---|---|---|
+| `acs-core` | Handshake, envelope, hook taxonomy, dispositions, SessionContext, Intent, replay protection, ping | Always (mandatory) |
+| `acs-trace` | OTel + OCSF event emission per step | Cross-vendor observability or SIEM integration |
+| `acs-inspect` | `agbom/snapshot` + canonical AgBOM serialization | Policy depends on component inventory |
+| `acs-inspect-dynamic` | `agbom/changed` on mutation | Agent hot-swaps components mid-session |
+| `acs-provenance` | Field-level Provenance objects | Enforcing FIDES, CaMeL, or AARM-style information-flow paradigms |
+| `acs-crypto` | ML-DSA-65 / SLH-DSA-128s signatures | Cryptographic integrity beyond shared-secret HMAC |
+| `acs-audit` | `request_hash` on every ContextEntry | Chain must commit to request content |
diff --git a/docs/spec/inspect/README.md b/docs/spec/inspect/README.md
@@ -1,45 +1,77 @@
-# Agent Control Standard - Inspect with AgBOM
-
-As AI agents become more sophisticated, transparent insight into their architecture, behavior, and security posture becomes critical. The Agent Bill of Materials (AgBOM) addresses this need by providing a structured, dynamic inventory of all components comprising an agent system including tools, models, capabilities, and dependencies. This concept aligns with growing calls for AI system transparency and supply chain integrity, particularly within regulated or enterprise environments.
-
-!!! info "AgBOM Extends Industry Standards"
-    We already have great Bill-of-Material standards, so ACS doesn't introduce a new one. Instead, it extends existing industry-proven standards: CycloneDX, SPDX, and SWID to support AI agent-specific components.
-
-## What Is AgBOM?
-AgBOM, short for Agent Bill-of-Materials, is a comprehensive inventory that captures metadata about every component in an AI agent system. Its core purpose is to enable inspectability, allowing developers, auditors, and stakeholders to determine:
-- What tools, models, and capabilities are embedded within an agent
-- Who authored each component
-- What version and configuration is currently deployed
-- What external services and data sources are accessed
-
-This visibility supports better security tracing, version tracking, and regulatory compliance. AgBOM must dynamically adapt to reflect the rapid iteration and evolution of agent architectures, especially in real-time or distributed environments.
-
-## Desired Outcome
-The end result of generating an AgBOM is a standardized, machine-readable artifact that outlines the full software composition of the agent.
-To support industry-wide adoption and interoperability, AgBOM supports output in the following standard formats:
-
-| BOM standard | AgBOM Spec | Status |
-|--|--|--|
-| [CycloneDX](https://cyclonedx.org/) | [AgBOM with CycloneDX](./extend_cyclonedx.md) | Working draft |
-| [SPDX](https://spdx.dev/) | [AgBOM with SPDX](./extend_spdx.md) | [Help wanted](https://github.com/Agent-Control-Standard/ACS/issues/20) |
-| [SWID](https://csrc.nist.gov/Projects/Software-Identification-SWID) | [AgBOM with SWID](./extend_swid.md) | [Help wanted](https://github.com/Agent-Control-Standard/ACS/issues/21) |
-
-### AgBOM entities and parameters:
-
-| Entity | Parameters |
-|--|--|
-| Standard Packages | Name, Description, Version |
-| Models | Name, Version, Description, Endpoint, Context Window, Args |
-| Capabilities | Agent Card Definitions (per A2A), list of discovered Agents, list of MCP servers and parameters (protocolVersion, capabilities, serverInfo)  |
-| Knowledge | Name, Description, Schema, Search type, Search args  |
-| Memory | Name, Description, Type, Size, Search args, Window size, Path |
-| Tools | Name, Description, Scheme, Endpoint (local/directly-attached and MCP) |
-
-### Triggers for AgBOM Update
-
-- Agent discovered, removed or changed capabilities
-- MCP server discovered, removed or changed capabilities
-- Knowledge discovered, removed or changed capabilities
-- Tool discovered, removed or changed capabilities
-- Memory discovered, removed or changed capabilities
-- Model discovered, removed or changed capabilities
+# Inspect — AgBOM
+
+AI agents add and remove capabilities at runtime: a model swap mid-session, a hot-loaded MCP server, a new A2A peer, a knowledge source registered after `sessionStart`. Without inspectability, every Guardian policy that depends on what the agent *is* (rather than only what it *does*) becomes unverifiable.
+
+The **Agent Bill of Materials (AgBOM)** is a queryable, dynamic inventory of the components an Observed Agent uses: Models, MCP servers, A2A peers, Tools, Knowledge sources, Memory stores, and Agent capabilities.
+
+!!! info "AgBOM extends industry standards"
+    ACS doesn't introduce a new BOM format. The canonical AgBOM is a structured component graph; CycloneDX, SPDX, and SWID outputs are deterministic derivations of the same graph.
+
+AgBOM emission is the subject of the **ACS-Inspect** [conformance profile](../conformance.md#acs-inspect). When Guardian policy depends on component inventory (e.g. banning a model or tool at the boundary), the deployment MUST implement ACS-Inspect.
+
+## Wire methods
+
+The `agbom/*` namespace is reserved by [Specification §3](../instrument/specification.md#3-wire-format). Two methods are defined in v0.1.0:
+
+| Method | Direction | Trigger |
+|---|---|---|
+| `agbom/snapshot` | Observed → Guardian | Once after `sessionStart`, before any content-bearing hook; and after any handshake renegotiation. Carries the full AgBOM. |
+| `agbom/changed` | Observed → Guardian | Whenever a component is added, removed, or version-changed mid-session. Carries either a full snapshot or a diff (`added[]`, `removed[]`, `changed[]`). |
+
+Both methods follow the standard ACS request envelope and are written into the SessionContext audit chain — AgBOM mutation is part of the security-relevant history of the session. Decisions are normally `allow`; Guardians MAY return `deny` to refuse a session whose component graph contains a banned component, or to block a hot-swap.
+
+`agbom/changed` is part of the **ACS-Inspect-Dynamic** profile extension. Deployments that claim only **ACS-Inspect** emit a single snapshot and do not track mid-session mutations.
+
+## Canonical schema
+
+Every component graph is expressed in the canonical AgBOM document ([`agbom/document.json`](https://github.com/afogel/ACS_official/blob/dev/specification/v0.1.0/agbom/document.json)). Components are typed; the type set in v0.1.0 is:
+
+| Type | Required fields | Optional fields |
+|---|---|---|
+| `model` | `id`, `name`, `version`, `provider`, `endpoint` (URI), `context_window` | `args` (model-config snapshot) |
+| `mcp_server` | `id`, `name`, `version`, `endpoint` (URI), `tools[]` | — |
+| `a2a_peer` | `id`, `endpoint` (URI), `protocol_version` | `agent_card_ref` (URI to peer's Agent Card if known) |
+| `tool` | `id`, `name`, `version`, `provider`, `capability` (abstract: `filesystem.delete`, `network.egress`, `process.execute`, …) | — |
+| `knowledge_source` | `id`, `name`, `source_type` (`vector_db`/`search_index`/`knowledge_base`/`web_search`/`other`) | `endpoint` (URI), `schema_ref` (URI) |
+| `memory_store` | `id`, `name`, `scope` (`session`/`user`/`tenant`/`global`), `store_type` | `path` (URI), `window_size` |
+| `agent_capability` | `id`, `name`, `description` | `tools[]`, `mcp_servers[]`, `a2a_peers[]` |
+
+The full per-component schema is [`agbom/component.json`](https://github.com/afogel/ACS_official/blob/dev/specification/v0.1.0/agbom/component.json).
+
+Every component SHOULD carry `registration_provenance` (who declared it — framework / configuration / runtime discovery) so AgBOM mutations are traceable in the same lineage system as data flow. Deployments claiming **ACS-Provenance** MUST populate `registration_provenance` on every component.
+
+## Output format mappings
+
+The canonical document is the source of truth; serialized output is a deterministic derivation. The mapping rules live in [`inspect/format-mapping.json`](https://github.com/afogel/ACS_official/blob/dev/specification/v0.1.0/inspect/format-mapping.json).
+
+| Standard | ACS extension | Status |
+|---|---|---|
+| [CycloneDX 1.6](https://cyclonedx.org/) | [Extending CycloneDX](./extend_cyclonedx.md) | Working draft |
+| [SPDX 3.0](https://spdx.dev/) | [Extending SPDX](./extend_spdx.md) | Working draft |
+| [SWID](https://csrc.nist.gov/Projects/Software-Identification-SWID) | [Extending SWID](./extend_swid.md) | Working draft |
+
+A Guardian MAY request a specific serialization in the handshake's AgBOM negotiation (`agbom_serializations_supported` in ServerHello); the canonical form is always the source of truth and the serializations are derivations.
+
+## ACS-Inspect conformance bar
+
+A deployment claiming **ACS-Inspect** MUST:
+
+1. Emit `agbom/snapshot` once per session, before content-bearing hooks fire.
+2. Have the Guardian accept `agbom/snapshot`, write it into the SessionContext audit chain, and serialize the canonical AgBOM into at least one of {CycloneDX 1.6, SPDX 3.0, SWID} on request.
+
+A deployment claiming **ACS-Inspect-Dynamic** additionally MUST:
+
+3. Emit `agbom/changed` on every mutation to the component graph.
+4. Write those mutations into the audit chain.
+
+Without -Dynamic, a deployment that hot-swaps components silently is not Inspect-conformant for that session — the Guardian's view of the agent diverges from runtime reality.
+
+## Triggers for AgBOM updates
+
+- Model added, removed, or version-changed.
+- MCP server discovered, removed, or version-changed.
+- A2A peer registered or deregistered.
+- Tool registered, removed, or capability-changed.
+- Knowledge source connected or disconnected.
+- Memory store attached or detached.
+- Agent capability declared or revoked.