From 3632735cafc03c3fbb3503db7f7aceba3be0216b Mon Sep 17 00:00:00 2001 From: "David (rabbidave)" Date: Mon, 3 Aug 2026 14:46:56 -0500 Subject: [PATCH 1/3] spec_change: agent_id as the correlation key for OCSF ai_agent.instance_uid Section 5.3.1 already binds agent_id to "the authenticated workload subject for the current session" for gateway runtime-session binding. This makes the same binding explicit and normative for OCSF-emitting runtime-evidence producers: when such a producer emits an ai_agent- bearing event (e.g. Agent Inventory Info [5050]) for a manifest-governed session, ai_agent.instance_uid MUST equal this manifest's agent_id. Verification results gain an optional runtime_correlation_key field (section 5.2) that echoes agent_id back, so a runtime-evidence consumer doesn't need to re-parse the manifest to get the join key. fields_verified is untouched -- it stays boot-time-only per section 7.2; this does not make the manifest a runtime monitor. Worked example uses real output from the reference implementation (rabbidave/ws4-secure-design-agentic-systems@1e35ab5): AgentIdentity now feeds a proper OCSF ai_agent object (uid/instance_uid/version/charter/ token_fingerprint) instead of the flat, model-conflated agent_uid that implementation used before. Does not split agent_id into separate stable/instance fields -- flagged as an open question for reviewers rather than decided here. Closes #269. --- CHANGELOG.md | 4 ++ spec/agent-manifest-spec-v0.2.md | 64 ++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 045351e..0433805 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to Agent Manifest are documented here. Format follows [Keep ## [Unreleased] +### Added + +**[SPEC]** **`agent_id` is now the normative correlation key for OCSF `ai_agent.instance_uid`** (section 3.1), and verification results carry it back as `runtime_correlation_key` (section 5.2). Closes #269. Section 5.3.1 already bound `agent_id` to "the authenticated workload subject for the current session" for gateway runtime binding; this extends the same scope to OCSF-emitting runtime-evidence producers (e.g. the `agent-state` KV-fingerprint chain, `rabbidave/ws4-secure-design-agentic-systems@1e35ab5`) so a verifier can join runtime evidence to a manifest without a second identity mechanism. Does not change `fields_verified`, which stays boot-time-only per section 7.2; does not split `agent_id` into separate stable/instance fields, though a future revision may if the current overload proves to be a problem in practice. + ### Changed **[SPEC][SDK] BREAKING: the `@context` URI moves to `https://manifest.agentrust-io.com/v0.2/context.json`**, and the specification is republished as v0.2 ([`spec/agent-manifest-spec-v0.2.md`](spec/agent-manifest-spec-v0.2.md), [ADR-0012](docs/adr/0012-context-uri-moved-to-controlled-domain.md)). The v0.1 URI `https://agentmanifest.agentrust.io/v0.1/context.json` named `agentrust.io`, a domain this project has never controlled: registered to a third party behind Domains By Proxy, paid through mid-2027, and it has never resolved. Every manifest issued to date was therefore identified under somebody else's name, which is untenable in an identity specification. diff --git a/spec/agent-manifest-spec-v0.2.md b/spec/agent-manifest-spec-v0.2.md index ac2cc4e..e8826bd 100644 --- a/spec/agent-manifest-spec-v0.2.md +++ b/spec/agent-manifest-spec-v0.2.md @@ -236,6 +236,11 @@ All fields annotated as UUID v7 MUST conform to RFC 9562 Section 5.7. The string The `agent_id` path structure `/agent//` shown in examples is a convention, not a requirement. Trust domain must be lowercase `[a-z0-9._-]`; path segments may use `[a-zA-Z0-9._-]`. UUID v7 instance identifiers (hyphens permitted in path segments) are valid. Example: `spiffe://trust.example/agent/payments-processor/01926b4c-1234-7abc-9def-000000000001`. + +`agent_id` already serves as the runtime-session subject-binding value in section 5.3.1 item 3 ("the authenticated workload subject for the current session equals the manifest `agent_id`"). This section makes that same binding explicit for OCSF-emitting runtime-evidence producers: when such a producer emits an `ai_agent`-bearing OCSF event (e.g. `Agent Inventory Info [5050]`) for a session governed by this manifest, the value populated into `ai_agent.instance_uid` MUST equal this manifest's `agent_id`. `ai_agent.instance_uid` is scoped to "a specific running instance or session" (OCSF `objects/ai_agent.json`) — the same scope `agent_id` already carries per 5.3.1, not a new concept. `ai_agent.version`/`ai_agent.charter`, if present, are not part of this binding: both are static across a session and are not suitable join keys for per-event correlation. + +This section does not require `agent_id`'s optional `/agent//` path segment (above) to itself carry the instance scope — only that the resolved `agent_id` string, however structured, equals the emitted `instance_uid`. A future revision MAY split `agent_id` into a stable and an instance-scoped field if implementation experience shows the overload is a problem; this section does not propose that split. + The `@context` URL `https://manifest.agentrust-io.com/v0.2/context.json` is provisional for the v0.2 draft period. The CoSAI WS4 working stream will assign the canonical URL prior to v1.0 ratification, and implementations MUST support the canonical CoSAI-assigned URL when it is assigned. @@ -1147,6 +1152,7 @@ Conformance level requirements: "pack_hash": "sha256:<64-hex-chars>", "pack_uri": "" }, + "runtime_correlation_key": "", "verification_signature": "" } ``` @@ -1161,6 +1167,64 @@ Conformance level requirements: `INCOMPATIBLE_VERSION` is returned when the verifier does not support the manifest's declared `version`. See section 2.2 for version negotiation rules. + +`runtime_correlation_key` echoes `agent_id` back in the verification result so a runtime-evidence consumer does not need to re-parse the manifest just to obtain the join key defined in section 3.1. It is set whenever `agent_id` is present (i.e. always, since `agent_id` is REQUIRED) and is otherwise informational — it does not affect `result` or any `fields_verified` entry, since runtime evidence is out of scope for what this verification call attests (section 7.2). A verifier that has no runtime-evidence consumers MAY omit populating downstream consumption of this field, but the field itself is always present given `agent_id` always is. + +Worked example — a manifest, the OCSF runtime evidence a producer emits against it (per the correlation rule in section 3.1), and the resulting verification result: + +```jsonc +// Manifest excerpt (section 3.1) +{ + "manifest_id": "01926b4c-79a0-7f3e-9c21-4e0f0a1b2c3d", + "agent_id": "spiffe://trust.example/agent/payments-processor/01926b4c-1234-7abc-9def-000000000001", + "version": "0.1", + "issuer": "spiffe://trust.example/manifest-authority", + "issued_at": "2026-08-03T14:00:00Z", + "expires_at": "2026-11-01T14:00:00Z" +} + +// Runtime evidence: an OCSF Agent Inventory Info [5050] event, unmodified +// output of the reference implementation at +// rabbidave/ws4-secure-design-agentic-systems@1e35ab5 (ocsf_mapping.to_ocsf_event) +{ + "class_uid": 5050, + "class_name": "Agent Inventory Info", + "ai_agent": { + "uid": "spiffe://trust.example/agent/payments-processor/01926b4c-1234-7abc-9def-000000000001", + "instance_uid": "spiffe://trust.example/agent/payments-processor/01926b4c-1234-7abc-9def-000000000001", + // ^ MUST equal manifest.agent_id above -- the binding section 3.1 defines. + "version": "2.3.1", + "charter": null, + "token_fingerprint": { + "algorithm_id": 3, "algorithm": "SHA-256", + "value": "e7a0585389f573fcfc3b744a81cb791b2a325240066731cd8a8c10fb710c28ea" + } + }, + "session_uid": "spiffe://trust.example/agent/payments-processor/01926b4c-1234-7abc-9def-000000000001", + "context": { + "kv_state_fingerprint": { + "algorithm_id": 3, "algorithm": "SHA-256", + "value": "c96021ce1c548d3723ffe318e1167d5b85d9901f0a3dd4439eed090ba75ddc08" + } + }, + "prev_inventory": { "algorithm_id": 3, "algorithm": "SHA-256", "value": "00...00" }, + "inventory": { "algorithm_id": 3, "algorithm": "SHA-256", "value": "a877499302eef959999656c486b081a5a5f977c03d6876a295de0e89b15dce72" } +} + +// Verification result (section 5.2), with the correlation key surfaced +{ + "verification_id": "01926b4d-0001-7000-8000-000000000001", + "manifest_id": "01926b4c-79a0-7f3e-9c21-4e0f0a1b2c3d", + "result": "VALID", + "attestation_verified": false, + "fields_verified": { "...": "unchanged -- boot-time artifacts only, per section 7.2" }, + "runtime_correlation_key": "spiffe://trust.example/agent/payments-processor/01926b4c-1234-7abc-9def-000000000001" + // A runtime-evidence consumer joins this manifest's evidence stream by + // matching Agent Inventory Info events where ai_agent.instance_uid + // equals this value -- no re-derivation from the manifest needed. +} +``` + ##### 5.2.1 Evidence Pack Format An evidence pack is a JSON document with the following structure: From f4c3e7b9bacff8ffed9b5799bd0a6dd59cb155e5 Mon Sep 17 00:00:00 2001 From: David Pierce Date: Tue, 11 Aug 2026 08:19:05 +0000 Subject: [PATCH 2/3] Soften worked-example comment: frame as candidate shape pending ocsf-schema#1724, not settled fact --- spec/agent-manifest-spec-v0.2.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/spec/agent-manifest-spec-v0.2.md b/spec/agent-manifest-spec-v0.2.md index 8319cc3..aa4c49a 100644 --- a/spec/agent-manifest-spec-v0.2.md +++ b/spec/agent-manifest-spec-v0.2.md @@ -1210,9 +1210,10 @@ Worked example — a manifest, the OCSF runtime evidence a producer emits agains "expires_at": "2026-11-01T14:00:00Z" } -// Runtime evidence: an OCSF Agent Inventory Info [5050] event, unmodified -// output of the reference implementation at -// rabbidave/ws4-secure-design-agentic-systems@1e35ab5 (ocsf_mapping.to_ocsf_event) +// Runtime evidence: a candidate OCSF Agent Inventory Info [5050] event shape, +// pending class assignment upstream (see ocsf/ocsf-schema#1724). Reflects the +// reference implementation at rabbidave/ws4-secure-design-agentic-systems@1e35ab5 +// (ocsf_mapping.to_ocsf_event) — the working contribution this proposal is based on. { "class_uid": 5050, "class_name": "Agent Inventory Info", From 69ba9fb147c5b7b1194e29ff2572615d70203b73 Mon Sep 17 00:00:00 2001 From: Imran Siddique Date: Fri, 14 Aug 2026 09:29:15 -0700 Subject: [PATCH 3/3] docs: link OCSF agent inventory proposal --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b4defa..f971944 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -62,7 +62,7 @@ The digest covers every file in the bundle, including ones the adapter does not **[SPEC] Section 6.4 is an informative crosswalk to OCSF runtime evidence** (#269). There was no defined join key between a manifest and the OCSF events emitted under it, so a consumer holding both could not tell they described the same agent without an out-of-band convention, and implementers were left to invent a second identity mechanism for a job this specification already does. The new section records the intended correspondence and deliberately requires nothing. -Three things it gets right that a normative version could not yet: it is written against the **`ai_operation` profile**, which is what actually contributes `ai_agent`, rather than against an event class (the `Agent Inventory Info [5050]` class proposed for this does not exist in OCSF — there is no `agent_inventory_info.json` and no occurrence of `5050` anywhere in `ocsf-schema`); it maps `ai_agent.uid` to the durable identity and `instance_uid` to the session-scoped one, which is what OCSF's own definitions ask for, instead of collapsing both onto `agent_id`; and it notes that `session_uid` is not an `ai_agent` attribute at all. +Three things it gets right that a normative version could not yet: it is written against the **`ai_operation` profile**, which is what actually contributes `ai_agent`, rather than against an event class (the `Agent Inventory Info [5050]` class proposed for this does not exist in OCSF as of this writing; a Discovery-category class for agent trust-base inventory is now proposed upstream at `ocsf/ocsf-schema#1724`); it maps `ai_agent.uid` to the durable identity and `instance_uid` to the session-scoped one, which is what OCSF's own definitions ask for, instead of collapsing both onto `agent_id`; and it notes that `session_uid` is not an `ai_agent` attribute at all. It stays informative because `agent_id` is one field serving both roles, and section 3.1 says the `/agent//` path is "a convention, not a requirement" — so a conformant `agent_id` may be stable and carry no instance scope. Requiring it to populate `instance_uid`, which OCSF defines as explicitly distinct from the stable `uid`, would force a stable identifier into the non-stable field and cost a consumer the ability to separate "every run of this agent" from "this run". Resolving that means deciding whether `agent_id` splits, which belongs in CoSAI WS4 alongside the canonical `@context` URL that section 3.1 already defers there.