@occasiolabs/occasio 0.8.1

package/policy-templates/dev-default.yml

@@ -0,0 +1,84 @@
+# yaml-language-server: $schema=https://occasio.ai/schemas/occasio-policy.schema.json
+# Occasio policy — dev-default template (generated by: occasio policy init)
+#
+# Default posture: governance on, blocking on, no path restrictions.
+# All flags are at their built-in defaults; the tools: block is shown
+# commented for reference. Edit this file to customise. Changes take
+# effect immediately on the next tool call (no proxy restart).
+#
+#   occasio policy show       — view the active policy with annotations
+#   occasio policy validate   — check this file for errors before using it
+#   occasio policy init --template strict   — switch to a locked-down preset
+#   occasio policy init --template finance  — switch to the finance-oriented preset
+version: 1
+
+# ── Global flags ──────────────────────────────────────────────────────────────
+
+# Block the request when a tool result contains a recognised secret pattern.
+# The model never sees the secret; a policy-refusal response is returned instead.
+block_secrets_in_tool_results: true
+
+# Redact secrets in-place (replace with [REDACTED]) rather than blocking outright.
+# To use: set this to true and set block_secrets_in_tool_results to false.
+redact_secrets_in_tool_results: false
+
+# Distil long tool outputs (file reads, grep results) before sending to the
+# model. Reduces token cost; the full raw output is still saved locally.
+distill_tool_results: false
+
+# Block outbound requests once the session spend reaches the --budget limit.
+block_requests_over_budget: true
+
+# ── Per-tool routing (optional) ───────────────────────────────────────────────
+# Uncomment the tools: block below to override routing for specific tools.
+#
+# IMPORTANT: when tools: is present it replaces the built-in defaults entirely.
+# Any tool not listed here will PASS to the cloud. List every tool you want
+# to keep running locally.
+#
+# Available actions:
+#   LOCAL      — execute locally, result never leaves your machine
+#   TRANSFORM  — execute locally, then apply a shaping step before sending
+#   PASS       — skip local execution, let the cloud handle it
+#
+# Available transforms: redact-secrets, distill-output
+# Chaining: set both redact_secrets_in_tool_results and distill_tool_results
+# to true to apply redact → distil automatically on all LOCAL tools.
+#
+# tools:
+#
+#   # Distil grep output to send only matched lines, not the full corpus:
+#   grep:
+#     action: TRANSFORM
+#     transform: distill-output
+#
+#   # Redact secrets from file reads (replaces recognised patterns):
+#   read_file:
+#     action: TRANSFORM
+#     transform: redact-secrets
+#
+#   # Always route shell commands locally (default behaviour, shown for reference):
+#   shell_bash:
+#     action: LOCAL
+#     classifier: bash-allowlist
+
+# ── Path-based access control (optional) ──────────────────────────────────────
+# Block or allow filesystem paths regardless of tool routing. Applies to
+# read_file, find_files, and grep. Path entries may use ~ for the user home
+# directory; comparisons are case-insensitive on Windows.
+#
+# deny_paths:
+#   - ~/.ssh
+#   - ~/.aws
+#   - ~/.config/gcloud
+#
+# allow_paths:
+#   - ~/projects
+
+# ── Custom deny patterns (optional) ───────────────────────────────────────────
+# Extend the built-in secret scanner with your own regexes. Patterns are
+# JavaScript RegExps; escape backslashes for YAML.
+#
+# deny_patterns:
+#   internal-jwt:    "eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+"
+#   internal-ticket: "INC-[0-9]{6,}"

package/policy-templates/finance.yml

@@ -0,0 +1,61 @@
+# yaml-language-server: $schema=https://occasio.ai/schemas/occasio-policy.schema.json
+# Occasio policy — finance template
+#
+# Posture for finance / banking environments where the regulated data
+# surface includes account numbers, SWIFT/BIC identifiers, and locale-
+# specific PII patterns the built-in scanner does not cover.
+#
+# This template ADDS deny_patterns on top of the dev-default posture; it
+# does not lock paths down. Pair with a strict allow_paths list if the
+# deployment also requires project-scoped access.
+#
+# Compliance reference: docs/compliance-mapping.md (DRAFT) maps the
+# stanzas in this file to SOC 2 CC controls.
+version: 1
+
+# ── Global flags ──────────────────────────────────────────────────────────────
+block_secrets_in_tool_results: true
+redact_secrets_in_tool_results: false
+distill_tool_results: true
+block_requests_over_budget: true
+
+# ── Path-based access control ─────────────────────────────────────────────────
+# Deny common credential locations. Add organisation-specific paths
+# (key vaults, signed-config stores) as needed.
+deny_paths:
+  - ~/.ssh
+  - ~/.aws
+  - ~/.config/gcloud
+  - ~/.gnupg
+
+# allow_paths intentionally left empty (deny_paths is still enforced).
+# Set this to your repo roots if you want to restrict reads further.
+# allow_paths:
+#   - ~/projects
+
+# ── Custom deny patterns ──────────────────────────────────────────────────────
+# Each pattern below is a JavaScript regex. Tested against tool output;
+# a match triggers BLOCK (or REDACT if redact_secrets_in_tool_results is on).
+deny_patterns:
+  # SWIFT / BIC code (8 or 11 chars, ISO 9362). Covers most outbound
+  # international wire-transfer artefacts that might appear in logs or
+  # generated documents.
+  swift-bic: "\\b[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?\\b"
+
+  # IBAN (International Bank Account Number, ISO 13616). Length varies by
+  # country (15–34 chars); this regex captures the common shape conservatively.
+  iban: "\\b[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}\\b"
+
+  # US Social Security Number (xxx-xx-xxxx). Conservative — matches the
+  # canonical hyphenated form only, to keep false positives down.
+  ssn-us: "\\b[0-9]{3}-[0-9]{2}-[0-9]{4}\\b"
+
+  # Internal change / incident ticket IDs (typical Jira/ServiceNow shapes).
+  # Customise per-org; ticket IDs in tool output are often associated
+  # with sensitive change context.
+  internal-ticket: "(INC|CHG|RITM)-[0-9]{6,}"
+
+  # Internal JWT format (Anthropic / Auth0 / generic three-segment token).
+  # The built-in scanner already catches many JWTs; this is an extra
+  # belt-and-braces match for organisation-specific tokens.
+  jwt: "eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+"

package/policy-templates/strict.yml

@@ -0,0 +1,49 @@
+# yaml-language-server: $schema=https://occasio.ai/schemas/occasio-policy.schema.json
+# Occasio policy — strict template
+#
+# Locked-down posture for deployments where the agent should only ever
+# touch a small, declared set of project paths and never see credentials
+# of any kind.
+#
+# Before activating: review the allow_paths list — the default below
+# allows ONLY ~/projects. Anything outside that prefix is blocked, even
+# read_file calls. On Windows, paths are matched case-insensitively;
+# both POSIX (~/.ssh) and Windows-style (C:\Users\…\.ssh) deny entries
+# are honoured.
+#
+#   occasio policy show       — confirm the active policy
+#   occasio policy validate   — lint this file
+version: 1
+
+# ── Global flags ──────────────────────────────────────────────────────────────
+block_secrets_in_tool_results: true
+redact_secrets_in_tool_results: false
+distill_tool_results: true
+block_requests_over_budget: true
+
+# ── Path-based access control ─────────────────────────────────────────────────
+# Deny common credential / config locations. The list intentionally covers
+# the same prefixes on both Linux/macOS (~) and Windows (C:\Users\<you>\…),
+# so the same template works across the team without per-platform edits.
+deny_paths:
+  - ~/.ssh
+  - ~/.aws
+  - ~/.config/gcloud
+  - ~/.gnupg
+  - ~/.kube
+  - ~/.docker
+  - ~/.netrc
+
+# Allow ONLY this prefix. Anything outside is blocked. Widen this for your
+# project layout — for example, add ~/work, ~/code, or specific repos.
+# An empty allow_paths list disables the allowlist (deny_paths still applies).
+allow_paths:
+  - ~/projects
+
+# ── Custom deny patterns ──────────────────────────────────────────────────────
+# Conservative additions to the built-in scanner. The patterns below cover
+# common internal token / ticket shapes that a generic secret scanner would
+# miss. Extend per-org as needed.
+deny_patterns:
+  internal-jwt:    "eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+"
+  internal-ticket: "INC-[0-9]{6,}"

package/schemas/agent-attestation-v1.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/occasiolabs/occasio/spec/agent-attestation/v1",
+  "title": "Occasio Agent Behavioral Attestation v1",
+  "description": "Self-contained, schema-validated commitment to a slice of a Occasio tamper-evident audit chain. Summarises what an AI coding agent did during one governed session (run_id) — every tool call's decision, blocked attempts, redacted secrets, the active policy's digest, and the first/last hashes of the chain segment that backs the claim. Intended to be later wrapped in an in-toto Statement envelope and signed via Sigstore keyless. v1 carries an unsigned variant (signature: null); subsequent versions populate the signature object.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "predicate_type",
+    "subject",
+    "agent",
+    "policy",
+    "execution_summary",
+    "audit_chain",
+    "signature"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "predicate_type": {
+      "type": "string",
+      "const": "https://github.com/occasiolabs/occasio/spec/agent-attestation/v1"
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run_id"],
+      "properties": {
+        "run_id": {
+          "type": "string",
+          "description": "UUID of the Occasio proxy run that produced the attested events."
+        },
+        "git_commit": {
+          "type": ["string", "null"],
+          "description": "Reserved for v1.1 — populated when the attestation is bound to a single git commit (set by GitHub Action in Phase 2)."
+        },
+        "files_changed": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Reserved for v1.1 — paths modified by the agent during this run."
+        }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["platform", "model", "session_id", "started_at", "ended_at", "wall_time_s"],
+      "properties": {
+        "platform": {
+          "type": "string",
+          "description": "Adapter that produced these events (e.g. 'claude-code', 'cline', 'mcp')."
+        },
+        "model": {
+          "type": ["string", "null"],
+          "description": "Model ID derived from request rows in the chain slice, if available."
+        },
+        "session_id": {
+          "type": ["string", "null"]
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "ended_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "wall_time_s": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file_hash", "file_path", "source", "version", "rules_digest"],
+      "properties": {
+        "file_hash": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "SHA-256 of the active policy.yml file bytes (sentinel 0*64 if no file was present)."
+        },
+        "file_path": {
+          "type": ["string", "null"]
+        },
+        "source": {
+          "type": "string",
+          "enum": ["user", "default", "unknown", "inferred"],
+          "description": "How the file_hash was determined. 'user'/'default'/'unknown' all reflect a policy_loaded event observed inside the run slice. 'inferred' means no such event was found and file_hash was computed from the policy file's current on-disk bytes at attest time — which may differ from what was active during the run. Verifiers SHOULD treat 'inferred' as weaker evidence."
+        },
+        "version": {
+          "type": ["integer", "null"]
+        },
+        "rules_digest": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "deny_paths_count":    { "type": "integer", "minimum": 0 },
+            "deny_patterns_count": { "type": "integer", "minimum": 0 },
+            "block_secrets":       { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "execution_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tool_calls", "local", "passed", "blocked", "transformed", "secrets_redacted", "blocked_events"],
+      "properties": {
+        "tool_calls":      { "type": "integer", "minimum": 0 },
+        "local":           { "type": "integer", "minimum": 0 },
+        "passed":          { "type": "integer", "minimum": 0 },
+        "blocked":         { "type": "integer", "minimum": 0 },
+        "transformed":     { "type": "integer", "minimum": 0 },
+        "secrets_redacted":{ "type": "integer", "minimum": 0 },
+        "blocked_events": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["tool", "rule", "at_offset_s"],
+            "properties": {
+              "tool":        { "type": "string" },
+              "target":      { "type": ["string", "null"] },
+              "rule":        { "type": "string" },
+              "at_offset_s": { "type": "integer", "minimum": 0 }
+            }
+          }
+        }
+      }
+    },
+    "audit_chain": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["genesis", "first_hash", "last_hash", "event_count", "chain_file", "verifier_url"],
+      "properties": {
+        "genesis": {
+          "type": "string",
+          "const": "0000000000000000000000000000000000000000000000000000000000000000"
+        },
+        "first_hash": {
+          "type": ["string", "null"],
+          "description": "Hash field of the first attested row (null when event_count == 0).",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "last_hash": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "event_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "chain_file": {
+          "type": "string"
+        },
+        "verifier_url": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    },
+    "signature": {
+      "description": "Sigstore keyless / cosign signature. v1 Phase-0 attestations are unsigned (null); Phase 1 populates the object.",
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "identity", "signed_at"],
+          "properties": {
+            "type":             { "type": "string", "enum": ["sigstore-cosign-keyless"] },
+            "identity":         { "type": "string" },
+            "rekor_entry":      { "type": ["string", "null"], "format": "uri" },
+            "signed_at":        { "type": "string", "format": "date-time" },
+            "envelope_sha256":  { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+          }
+        }
+      ]
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/schemas/occasio-policy.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://occasio.ai/schemas/occasio-policy.schema.json",
+  "title": "Occasio Policy",
+  "description": "Schema for ~/.occasio/policy.yml — the single document that governs how Occasio handles tool calls and tool results. Authoritative reference: src/policy/loader.js (parser) and src/policy/validate.js (linter). Stable across v0.6.x.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "description": "Policy schema version. Currently 1.",
+      "const": 1
+    },
+    "block_secrets_in_tool_results": {
+      "type": "boolean",
+      "description": "Block the request when a tool result contains a recognised secret pattern. The model never sees the secret; a synthetic refusal is returned instead."
+    },
+    "redact_secrets_in_tool_results": {
+      "type": "boolean",
+      "description": "Replace recognised secrets with [REDACTED] in-place rather than blocking outright. Mutually intended with block_secrets_in_tool_results=false."
+    },
+    "distill_tool_results": {
+      "type": "boolean",
+      "description": "Distil long tool outputs (file reads, grep results) before sending to the model. Reduces token cost; the full raw output is still saved locally."
+    },
+    "block_requests_over_budget": {
+      "type": "boolean",
+      "description": "Block outbound requests once the session spend reaches the --budget limit. Returns HTTP 402 without invoking the model."
+    },
+    "tools": {
+      "type": "object",
+      "description": "Per-tool routing. When present, REPLACES the built-in defaults entirely — every tool not listed here will PASS to the cloud. Use sparingly; the defaults are usually what you want.",
+      "additionalProperties": {
+        "$ref": "#/$defs/toolEntry"
+      }
+    },
+    "deny_paths": {
+      "type": "array",
+      "description": "Filesystem prefixes denied for read_file, find_files, and grep. Comparisons are on the symlink-resolved absolute path; case-insensitive on Windows. ~ is expanded to the user's home directory.",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "allow_paths": {
+      "type": "array",
+      "description": "Filesystem prefixes allowed for read_file, find_files, and grep. When non-empty, access is restricted to these prefixes; anything outside is blocked. Empty (the default) means no allowlist.",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "deny_patterns": {
+      "type": "object",
+      "description": "Custom regex patterns that, when matched in a tool result, are treated like secret-scanner hits — blocked or redacted depending on the global flags. Each entry is label: \"regex-string\".",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1,
+        "description": "JavaScript-flavored regular expression source (without leading/trailing slashes)."
+      }
+    }
+  },
+  "$defs": {
+    "toolEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action"],
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["PASS", "LOCAL", "TRANSFORM"],
+          "description": "What the dispatcher does with this tool call. PASS forwards to the cloud; LOCAL executes on the user's machine; TRANSFORM executes locally then applies a shaping step."
+        },
+        "transform": {
+          "type": "string",
+          "description": "Required when action is TRANSFORM. Built-in values: redact-secrets, distill-output. Other names are forward-compatible but only execute if the dispatcher knows about them.",
+          "minLength": 1
+        },
+        "executor": {
+          "type": "string",
+          "description": "Optional executor name. Default: native.",
+          "minLength": 1
+        },
+        "classifier": {
+          "type": "string",
+          "description": "Optional input-validation classifier. Built-in values: read-input-validator, glob-input-validator, grep-input-validator, todo-write-validator, todo-read-validator, bash-allowlist, powershell-allowlist.",
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "description": "Optional reason string surfaced in audit rows when this entry's action fires.",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "action": { "const": "TRANSFORM" } }, "required": ["action"] },
+          "then": { "required": ["transform"] }
+        }
+      ]
+    }
+  }
+}

package/spec/agent-attestation/v1/README.md

@@ -0,0 +1,137 @@
+# AI-Agent Behavioral Attestation v1
+
+**Predicate type URI:** `https://github.com/occasiolabs/occasio/spec/agent-attestation/v1`
+
+**Status:** Draft 1 (v1.0.0). Tracked at [`schemas/agent-attestation-v1.json`](../../../schemas/agent-attestation-v1.json).
+
+**License:** Apache-2.0.
+
+> **Note on URI resolvability.** The predicate type URI above is currently a stable identifier rather than a fetchable resource — a `GET` against it will not return this spec document. (Standard practice for predicate URIs varies: SLSA Provenance and CycloneDX URIs resolve to content today; this one will resolve once a static-site mirror is published at the canonical URL. The identifier is reserved and will not move.) Consumers must compare the URI as a string, not dereference it.
+
+## What this predicate claims
+
+A signed cryptographic statement about **what an AI coding agent did during a single bounded session**, including every governed tool call, every blocked attempt, every transform applied to a tool result, and the active policy that produced those decisions — all bound to a tamper-evident audit chain.
+
+The predicate answers the question **"What did the AI agent actually do while producing this artifact?"** — which is orthogonal to, and complementary with:
+
+- **SLSA Provenance** (what build process produced the artifact)
+- **CycloneDX ML-BOM / AIBOM** (what model + training data sit in the AI system)
+
+None of those predicate types describe **runtime behavioral integrity**: which files were read, which were blocked, which secrets were redacted, which policy was enforcing the call. This predicate fills that gap.
+
+## Use cases
+
+- A pull request opened by an AI coding agent ships an attestation as a GitHub Check. A reviewer sees `47 tool calls · 2 blocked · 1 secret redacted` before merge.
+- A SOC2 auditor receives signed attestations covering every AI-assisted change in the audit period and re-walks the chain offline using an independent verifier.
+- An enterprise mandates that every vendor's AI-agent contribution carries a behavioral attestation conformant to this predicate type.
+
+## Envelope
+
+This predicate is intended to be wrapped in an [in-toto Statement v1](https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md) and signed via [Sigstore](https://www.sigstore.dev/) (keyless, GitHub OIDC). The Statement carries:
+
+```jsonc
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "predicateType": "https://github.com/occasiolabs/occasio/spec/agent-attestation/v1",
+  "subject": [{
+    "name":   "occasio:run:<uuid>",
+    "digest": { "sha256": "<last_hash from the run's audit chain slice>" }
+  }],
+  "predicate": { /* the v1 object below */ }
+}
+```
+
+The `subject.digest.sha256` is the `last_hash` of the audit-chain slice attested by this predicate. Because the chain hash-links every event back to the GENESIS sentinel via `prev_hash → hash`, signing this single hash transitively commits to every event in the slice.
+
+## Predicate fields (v1.0.0)
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `schema_version` | string | yes | `"1.0.0"` |
+| `predicate_type` | string | yes | Constant: predicate URI above |
+| `subject.run_id` | string | yes | UUID identifying the agent session |
+| `subject.git_commit` | string \| null | no | Set in CI when the attestation is bound to a commit |
+| `subject.files_changed` | string[] | no | Paths modified during the run |
+| `agent.platform` | string | yes | e.g. `claude-code`, `cline`, `mcp` |
+| `agent.model` | string \| null | yes | Model ID, if surfaced by the adapter |
+| `agent.session_id` | string \| null | yes | Adapter-level session ID |
+| `agent.started_at` | RFC 3339 | yes | First event in slice |
+| `agent.ended_at` | RFC 3339 | yes | Last event in slice |
+| `agent.wall_time_s` | integer | yes | Elapsed seconds |
+| `policy.file_hash` | hex-64 | yes | SHA-256 of the active policy.yml bytes (or `0`*64 when no file) |
+| `policy.file_path` | string \| null | yes | Path on the producer's machine |
+| `policy.source` | enum | yes | `user`, `default`, `unknown`, or `inferred` (see below) |
+| `policy.version` | integer \| null | yes | Policy file `version:` field |
+| `policy.rules_digest` | object | yes | `deny_paths_count`, `deny_patterns_count`, `block_secrets` |
+| `execution_summary.tool_calls` | integer | yes | Total in slice (excluding policy events) |
+| `execution_summary.local` | integer | yes | `LOCAL` decisions |
+| `execution_summary.passed` | integer | yes | `PASS` decisions |
+| `execution_summary.blocked` | integer | yes | `BLOCK` decisions |
+| `execution_summary.transformed` | integer | yes | `TRANSFORM` decisions |
+| `execution_summary.secrets_redacted` | integer | yes | Σ secrets redacted across slice |
+| `execution_summary.blocked_events` | array | no | One entry per BLOCK with `tool`, `target`, `rule`, `at_offset_s` |
+| `audit_chain.genesis` | hex-64 | yes | Constant: 64 zeros |
+| `audit_chain.first_hash` | hex-64 \| null | yes | Hash of first row in slice |
+| `audit_chain.last_hash` | hex-64 \| null | yes | Hash of last row in slice |
+| `audit_chain.event_count` | integer | yes | Number of rows in slice |
+| `audit_chain.chain_file` | string | yes | Path to the chain file (advisory) |
+| `audit_chain.verifier_url` | URI | yes | Where to fetch the independent verifier |
+| `signature` | object \| null | yes | `null` for unsigned; populated when Sigstore-signed |
+| `generated_at` | RFC 3339 | no | Producer timestamp |
+
+The full JSON Schema (Draft-07) is the authoritative source: [`schemas/agent-attestation-v1.json`](../../../schemas/agent-attestation-v1.json).
+
+### `policy.source` values
+
+- `user` — a `policy_loaded` event was observed inside the run slice and the active policy came from a user-supplied file.
+- `default` — a `policy_loaded` event was observed and the producer was running on its built-in default policy.
+- `unknown` — a `policy_loaded` event was observed but its `policy_source` field was not set.
+- `inferred` — **no `policy_loaded` event was found in the slice.** The producer fell back to hashing the policy file's bytes *at attest time*, which may have been edited after the run ended. Verifiers SHOULD treat `inferred` as weaker evidence than the other three and surface this distinction to the user.
+
+## Verification model
+
+A consumer of an attestation must perform three independent checks, in order, all of which must pass:
+
+1. **Sigstore signature.** Verify the Sigstore Bundle's certificate chain (Fulcio root) and inclusion proof (Rekor transparency log). This proves *who* produced the predicate.
+2. **Predicate ↔ payload equivalence.** Re-decode the DSSE envelope inside the Sigstore Bundle, parse its payload as an in-toto Statement, and compare its `predicate` (modulo the `signature` metadata field) byte-for-byte with the attestation JSON in hand. This proves *that the predicate file has not been swapped*.
+3. **Audit chain integrity.** Re-walk the `chain_file` end-to-end using the canonical SHA-256 walker, and confirm that `first_hash` and `last_hash` appear in that chain in the correct relative order. This proves *the predicate reflects events that actually happened*.
+
+Each check is a hard requirement. A consumer that skips any of them is not verifying this predicate.
+
+Reference verifiers are available in two languages:
+- **Node:** `occasio attest verify` (all three steps in one call).
+- **Python:** [`docs/attest_verify.py`](../../../docs/attest_verify.py) (stdlib + optional `sigstore-python`; reuses [`docs/audit_walker.py`](../../../docs/audit_walker.py) for the chain step). See [`docs/python-verifier.md`](../../../docs/python-verifier.md).
+
+**Cross-language invariant.** Both verifiers produce byte-identical canonical forms of the predicate and identical pass/fail decisions for the audit-chain step on the same payload, including for predicate-tampered and chain-tampered inputs. Both canonicalize implementations explicitly reject non-integer numbers so a future schema addition cannot silently introduce divergence. The test suite asserts this under `xlang:` and `xlang-float:` cases.
+
+**Sigstore signature step.** Uses the standard DSSE-wrapped in-toto Statement format. Independently verifiable by any [sigstore-conformant](https://www.sigstore.dev/) tool — `cosign verify-blob`, `sigstore-js`, or `sigstore-python`. The reference test suite mocks the signing path for determinism; a real-OIDC signed-and-verified round-trip requires a GitHub Actions environment with `permissions: id-token: write` and is exercised by the reference Action when used in CI.
+
+## Compatibility and stability
+
+- **Breaking changes** to required fields require a new predicate URI (`/v2`, etc.).
+- **Additive changes** (new optional fields) are permitted in `v1.x` and do not bump the URI.
+- The predicate URI in this spec is **canonical and stable**. It will not be moved or re-pointed.
+- Consumers MUST refuse to verify attestations whose `predicate_type` does not match exactly.
+
+## Relationship to other specifications
+
+| Spec | Relationship |
+|---|---|
+| [in-toto Attestation Framework](https://github.com/in-toto/attestation) | Carrier envelope. This predicate type is a v1 in-toto Statement payload. |
+| [SLSA Provenance](https://slsa.dev/spec/v1.0/provenance) | Complementary. SLSA describes builds; this predicate describes AI-agent runtime behavior. |
+| [CycloneDX ML-BOM / OWASP AIBOM](https://cyclonedx.org/capabilities/mlbom/) | Complementary. ML-BOM describes models/data; this predicate describes session-level agent actions. |
+| [Sigstore](https://www.sigstore.dev/) | Signing transport. Reference implementation uses Sigstore keyless via GitHub OIDC. |
+
+## Open questions (tracked for v1.1 / v2)
+
+- **Multi-commit attestations.** Today the attestation binds to a single `run_id`. A natural extension: one attestation per PR covering N commits from M runs. v1.1 will likely add `subject.git_commits[]` and a way to merge slices.
+- **Policy provenance.** Today `policy.file_hash` commits to the file bytes. We do not carry the *origin* of the policy (was it committed to a repo? signed by a security team?). v1.1 may add `policy.attestation_url` for nested signed claims.
+- **Event-level disclosure.** Today the chain-file path is advisory; the chain itself is not bundled. A v1.x option may add an embedded compressed chain slice for fully offline verification, at a size cost.
+
+## Reference implementation
+
+The producing CLI, full verifier, JSON Schema, and an independent Python audit-chain walker live in [`occasiolabs/occasio`](https://github.com/occasiolabs/occasio). The reference Sigstore-signed attestations from that repo's own CI runs serve as conformance examples (Phase 3 of the rollout plan).
+
+## Authors and contributions
+
+Apache-2.0 licensed. Issues and pull requests at [`occasiolabs/occasio`](https://github.com/occasiolabs/occasio). Predicate-type submissions to the [in-toto attestation registry](https://github.com/in-toto/attestation) tracking once production usage and external adopters reach the registry's bar.