augur-schema 0.2.0__tar.gz

augur_schema-0.2.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+
+# Node
+node_modules/
+.next/
+.turbo/
+.pnpm-store/
+.parcel-cache/
+out/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Secrets / env
+.env
+.env.local
+.env.*.local
+
+# Bundles and artifacts (samples may opt back in)
+*.bundle/
+artifacts/
+out/
+tmp/
+
+# Logs (but the sample bundle keeps its own)
+*.log
+!examples/**/*.log

augur_schema-0.2.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# augur-schema changelog
+
+## 0.2.0 (2026-05-23)
+
+First standalone published release. Establishes `augur-schema` as a
+PyPI + npm package consumable by external CUA adapter authors. Rolls up
+all additive changes since `0.1.0` (previously tracked as unreleased
+`0.1.1` and `0.1.2`).
+
+### Packaging
+
+- Published to PyPI as `augur-schema` via Trusted Publisher OIDC from the
+  platform repo. Closes #96.
+- Published to npm as `@augur/schema` in lockstep with the Python version.
+- Schema versioning policy documented in `VERSIONING.md` — semver, breaking
+  changes allowed across `0.x` minors, additive changes bump patch.
+- `CHANGELOG.md` discipline enforced in CI on every schema-touching PR.
+
+### Additive (back-compat) — capture-mode
+
+- `step_trace.schema.json`: new optional `capture_mode` field
+  (per-step override of the manifest's capture mode). Lets producers
+  upgrade or downgrade the active capture mode mid-run (e.g. switch
+  from `metadata` to `screenshots` after the first failed verifier
+  check). Absence inherits the manifest mode. Closes #36.
+
+### Additive (back-compat) — training-data substrate
+
+- **`modelio.schema.json` (new)**: canonical record shape for one
+  model call's full input + output. Loaded under short name
+  `modelio`. Designed to be stored at
+  `modelio/<step_index:04d>-<layer>-<seq>.json`. Closes #56.
+- `step_trace.schema.json`: new optional `costs` object
+  (total_usd, model_usd, gpu_usd, proxy_usd, tokens_in, tokens_out,
+  cache_hit_tokens). Closes part of #58.
+- `step_trace.schema.json`: new optional `latency` object
+  (planner_ms, grounding_ms, dispatch_ms, verifier_ms, recovery_ms,
+  total_ms). Closes part of #58.
+- `step_trace.schema.json` → `verdict`: new optional `score` (0..1),
+  `score_components` (open object), `comparator` (enum:
+  verifier|model-judge|exact-match|human). Closes #59.
+- `debug_session.schema.json`: new optional `costs` object with the
+  same shape as the step-level one. Run-level rollup. Closes part of #58.
+
+## 0.1.0 (2026-05-19)
+
+Initial schema package. Records:
+
+- `manifest.schema.json` — bundle envelope.
+- `trace.schema.json` — combined session + steps document.
+- `debug_session.schema.json` — top-level run record.
+- `step_trace.schema.json` — one step.
+- `observation.schema.json` — screenshot + viewport metadata.
+- `decision_event.schema.json` — planner / verifier / recovery decisions.
+- `replay_fixture.schema.json` — replay seed.
+- `diagnostic_finding.schema.json` — output of the diagnostic rules engine.
+
+Enums:
+
+- `capture_mode.schema.json`
+- `coordinate_space.schema.json`
+- `provenance.schema.json`
+- `failure_class.schema.json` (open string with examples)
+
+Sample bundle: `examples/sample-bundle/` (5 steps, exercises every record).
+
+Per `docs/versioning.md`, breaking changes are allowed across `0.x` minors.

augur_schema-0.2.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: augur-schema
+Version: 0.2.0
+Summary: Augur schema package — canonical JSON Schemas for CUA debugger records.
+Project-URL: Homepage, https://github.com/mercurialsolo/augur
+Project-URL: Issues, https://github.com/mercurialsolo/augur/issues
+Project-URL: Changelog, https://github.com/mercurialsolo/augur/blob/main/packages/schema/CHANGELOG.md
+Author-email: Augur Authors <barada@gmail.com>
+License: Apache-2.0
+Keywords: computer-use-agent,cua,debugger,json-schema,observability,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.22
+Requires-Dist: referencing>=0.35
+Description-Content-Type: text/markdown
+
+# augur-schema
+
+Canonical JSON Schemas for the Augur CUA debugger.
+
+`json/` is the source of truth. Python and TypeScript types are hand-written mirrors
+in `src/augur_schema/` and `ts/` — kept in sync by `tests/test_schema_roundtrip.py`.
+
+Records:
+
+- `manifest.schema.json` — bundle envelope
+- `debug_session.schema.json` — top-level run/session record
+- `step_trace.schema.json` — one step
+- `observation.schema.json` — screenshot + viewport metadata
+- `decision_event.schema.json` — ordered planner/verifier/recovery decisions
+- `replay_fixture.schema.json` — replay seed for a step
+- `diagnostic_finding.schema.json` — output of the diagnostic rules engine
+
+Enums (separate files so they can be `$ref`d):
+
+- `coordinate_space.schema.json`
+- `provenance.schema.json`
+- `capture_mode.schema.json`
+- `failure_class.schema.json`
+
+Schema version: see [`docs/versioning.md`](../../docs/versioning.md). Current: `0.1`.

augur_schema-0.2.0/README.md

@@ -0,0 +1,25 @@
+# augur-schema
+
+Canonical JSON Schemas for the Augur CUA debugger.
+
+`json/` is the source of truth. Python and TypeScript types are hand-written mirrors
+in `src/augur_schema/` and `ts/` — kept in sync by `tests/test_schema_roundtrip.py`.
+
+Records:
+
+- `manifest.schema.json` — bundle envelope
+- `debug_session.schema.json` — top-level run/session record
+- `step_trace.schema.json` — one step
+- `observation.schema.json` — screenshot + viewport metadata
+- `decision_event.schema.json` — ordered planner/verifier/recovery decisions
+- `replay_fixture.schema.json` — replay seed for a step
+- `diagnostic_finding.schema.json` — output of the diagnostic rules engine
+
+Enums (separate files so they can be `$ref`d):
+
+- `coordinate_space.schema.json`
+- `provenance.schema.json`
+- `capture_mode.schema.json`
+- `failure_class.schema.json`
+
+Schema version: see [`docs/versioning.md`](../../docs/versioning.md). Current: `0.1`.

augur_schema-0.2.0/VERSIONING.md

@@ -0,0 +1,91 @@
+# augur-schema versioning policy
+
+This package is the canonical contract between Augur producers (the SDK, third-party
+CUA adapters) and Augur consumers (the server, viewer, CLI, diagnostic rule packs).
+Stability of the schema directly affects the cost of upgrading either side, so
+versioning is treated as a load-bearing decision, not a release-time afterthought.
+
+## Semver discipline
+
+The package follows [semver](https://semver.org/) with one caveat for the pre-1.0
+phase, consistent with semver §4.
+
+- **Pre-1.0** (current): a **minor** bump (`0.x.0 → 0.{x+1}.0`) is allowed to
+  contain breaking changes. A **patch** bump (`0.x.y → 0.x.{y+1}`) is reserved for
+  additive, backward-compatible changes.
+- **Post-1.0**: standard semver. Breaking changes require a **major** bump
+  (`x.y.z → {x+1}.0.0`). Additive changes bump minor.
+
+The Python package (`augur-schema` on PyPI) and the TypeScript package
+(`@augur/schema` on npm) always carry the **same version number** and ship from the
+same git tag (`schema-vX.Y.Z`). Pinning one is equivalent to pinning the other.
+
+## What counts as breaking
+
+Breaking, in either direction:
+
+- **Removed field** on any record (producers depending on emitting it break;
+  consumers depending on reading it break).
+- **Type narrowing** on an existing field (e.g. `string → enum`, `number → integer`).
+- **Required-field addition** to an existing record (producers without it break
+  validation).
+- **Required-field downgrade-then-removal** (counts as removal).
+- **Semantic change** to an existing field's meaning, even if the type is
+  unchanged (e.g. `costs.total_usd` changing from "step cost" to "cumulative
+  cost"). When in doubt, treat semantic changes as breaking.
+- **Enum variant removal**.
+- **Renaming** a record, a field, or an enum variant. Use deprecation, ship the
+  new name as additive, then remove the old in a later breaking bump.
+- **Coordinate-space or unit changes** on numeric fields.
+
+## What counts as additive
+
+Additive, backward-compatible:
+
+- **New optional field** on an existing record.
+- **New enum variant** in an open enum (i.e. one documented as accepting
+  unknown values for forward-compatibility — most Augur enums are open).
+- **New schema file** (a wholly new record type).
+- **Loosening a numeric range** (e.g. `0..1 → 0..2`).
+- **Loosening a required field to optional**.
+
+Additive changes still get a CHANGELOG entry — the policy is "every PR that
+touches `packages/schema/src/augur_schema/json/` updates `CHANGELOG.md`",
+enforced in CI.
+
+## Release flow
+
+1. Schema PR lands on `main` with the change + CHANGELOG entry.
+2. When ready to release, bump version in lockstep:
+   - `packages/schema/pyproject.toml`
+   - `packages/schema/package.json`
+3. Tag: `schema-vX.Y.Z`. Push the tag.
+4. `.github/workflows/release-schema.yml` runs: validates tag/CHANGELOG/pyproject
+   coherence, builds, publishes to PyPI via Trusted Publisher OIDC, creates a
+   GitHub Release with the CHANGELOG entry as the body.
+
+The release workflow refuses to publish if:
+
+- the tag version does not match both `pyproject.toml` and `package.json`;
+- the CHANGELOG has no entry for the tag version;
+- any schema fails to parse;
+- the sample bundle does not validate against the current schemas.
+
+## Pinning guidance for consumers
+
+- **Python**: `augur-schema>=0.2,<0.3` until 1.0. Tight bounds are appropriate
+  during pre-1.0 because breaking changes ship in minor bumps.
+- **TypeScript**: `"@augur/schema": "^0.2.0"` works under npm semver semantics
+  for pre-1.0 (npm treats `^0.x.y` as `>=0.x.y <0.x+1.0`), giving you patch
+  updates without surprise breakage.
+- **Lock files**: commit `uv.lock` / `pnpm-lock.yaml` in consumer repos. Schema
+  upgrades become explicit PRs that can be reviewed.
+
+## Stability promise
+
+- **0.x**: pre-stable. Expect a small number of breaking changes per quarter
+  while the SDK side fills out the Sentry-for-CUA primitive set (see SPEC §2.1).
+- **1.0**: target after the schema additions for primitives #3, #5, #9, and #10
+  have shipped and been exercised by at least one non-Mantis adapter.
+- **Post-1.0**: breaking changes only on major bumps. Deprecation cycles of at
+  least one minor before removal.

augur_schema-0.2.0/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@augur/schema",
+  "version": "0.2.0",
+  "description": "Augur schema package — canonical JSON Schemas for CUA debugger records.",
+  "private": false,
+  "type": "module",
+  "main": "./ts/index.js",
+  "types": "./ts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./ts/index.d.ts",
+      "default": "./ts/index.js"
+    },
+    "./json/*": "./src/augur_schema/json/*"
+  },
+  "files": [
+    "ts/",
+    "src/augur_schema/json/"
+  ],
+  "scripts": {
+    "build": "echo 'schema: json sources only, nothing to build'",
+    "test": "echo 'schema: see Python tests'"
+  }
+}

augur_schema-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "augur-schema"
+version = "0.2.0"
+description = "Augur schema package — canonical JSON Schemas for CUA debugger records."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Augur Authors", email = "barada@gmail.com" },
+]
+keywords = [
+    "cua",
+    "computer-use-agent",
+    "debugger",
+    "schema",
+    "json-schema",
+    "observability",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "jsonschema>=4.22",
+    "referencing>=0.35",
+]
+
+[project.urls]
+Homepage = "https://github.com/mercurialsolo/augur"
+Issues = "https://github.com/mercurialsolo/augur/issues"
+Changelog = "https://github.com/mercurialsolo/augur/blob/main/packages/schema/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/augur_schema"]
+
+[tool.hatch.build.targets.wheel.shared-data]
+# JSON schemas ship with the package; no extra include rules needed because
+# they live under src/augur_schema/json/.

augur_schema-0.2.0/src/augur_schema/__init__.py

@@ -0,0 +1,23 @@
+"""Augur schema package.
+
+Canonical JSON Schemas live under `augur_schema/json/`. This module exposes
+loaders and a small validation helper.
+"""
+
+from augur_schema._loader import (
+    SCHEMA_VERSION,
+    SchemaError,
+    list_schemas,
+    load_schema,
+    schemas_dir,
+    validator_for,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "SchemaError",
+    "list_schemas",
+    "load_schema",
+    "schemas_dir",
+    "validator_for",
+]

augur_schema-0.2.0/src/augur_schema/_loader.py

@@ -0,0 +1,102 @@
+"""Schema loader.
+
+The JSON Schemas are the source of truth. This loader caches them and
+returns a `jsonschema` validator that resolves cross-schema `$ref`s against
+the on-disk schema directory.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+
+SCHEMA_VERSION = "0.1"
+
+# Map short names → schema filenames. Keep names stable; consumers depend on them.
+_SCHEMA_FILES: dict[str, str] = {
+    "manifest": "manifest.schema.json",
+    "trace": "trace.schema.json",
+    "debug_session": "debug_session.schema.json",
+    "step_trace": "step_trace.schema.json",
+    "observation": "observation.schema.json",
+    "decision_event": "decision_event.schema.json",
+    "replay_fixture": "replay_fixture.schema.json",
+    "prior_steps": "prior_steps.schema.json",
+    "modelio": "modelio.schema.json",
+    "preference": "preference.schema.json",
+    "diagnostic_finding": "diagnostic_finding.schema.json",
+    "coordinate_space": "coordinate_space.schema.json",
+    "provenance": "provenance.schema.json",
+    "capture_mode": "capture_mode.schema.json",
+    "failure_class": "failure_class.schema.json",
+}
+
+
+class SchemaError(Exception):
+    """Wraps schema lookup and validation failures."""
+
+
+def schemas_dir() -> Path:
+    """Return the on-disk path to the bundled JSON Schemas."""
+    return Path(resources.files("augur_schema") / "json")  # type: ignore[arg-type]
+
+
+def list_schemas() -> list[str]:
+    """Return the supported schema short names."""
+    return sorted(_SCHEMA_FILES)
+
+
+@cache
+def load_schema(name: str) -> dict[str, Any]:
+    """Load a schema by short name (e.g. `manifest`) or filename."""
+    filename = _SCHEMA_FILES.get(name, name)
+    path = schemas_dir() / filename
+    if not path.exists():
+        raise SchemaError(f"unknown schema: {name!r}")
+    with path.open() as f:
+        loaded: dict[str, Any] = json.load(f)
+    return loaded
+
+
+@cache
+def _registry() -> Registry:
+    """Registry that lets cross-schema `$ref`s resolve against bundled files.
+
+    Schemas use relative refs like `coordinate_space.schema.json`. Draft 2020-12
+    resolves those against the base URI of the containing schema's `$id`. We
+    pre-register every schema under both its `$id` and its plain filename so
+    relative refs work no matter which one a producer used.
+    """
+    resources_list: list[tuple[str, Resource[Any]]] = []
+    for short, filename in _SCHEMA_FILES.items():
+        schema = load_schema(short)
+        resource = DRAFT202012.create_resource(schema)
+        if "$id" in schema:
+            resources_list.append((schema["$id"], resource))
+        resources_list.append((filename, resource))
+    return Registry().with_resources(resources_list)
+
+
+def validator_for(name: str) -> Draft202012Validator:
+    """Return a Draft 2020-12 validator for the named schema."""
+    schema = load_schema(name)
+    return Draft202012Validator(schema, registry=_registry())
+
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "SchemaError",
+    "ValidationError",
+    "list_schemas",
+    "load_schema",
+    "schemas_dir",
+    "validator_for",
+]

augur_schema-0.2.0/src/augur_schema/json/__init__.py

@@ -0,0 +1 @@
+"""JSON Schemas (data). Imported via importlib.resources, not as Python."""

augur_schema-0.2.0/src/augur_schema/json/capture_mode.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/capture_mode.schema.json",
+  "title": "CaptureMode",
+  "description": "Augur capture mode (spec §7). Ordered from least to most coverage.",
+  "type": "string",
+  "enum": [
+    "off",
+    "metadata",
+    "trace",
+    "screenshots",
+    "video",
+    "model_io",
+    "dispatch",
+    "replay",
+    "full"
+  ]
+}

augur_schema-0.2.0/src/augur_schema/json/coordinate_space.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/coordinate_space.schema.json",
+  "title": "CoordinateSpace",
+  "description": "Coordinate space registry (spec §4, §9, issue #9). Every coordinate MUST be tagged with one of these spaces so viewers can render overlays correctly across viewport sizes and device pixel ratios.",
+  "type": "string",
+  "enum": [
+    "viewport_css_px",
+    "device_px",
+    "screenshot_px",
+    "dom_client_rect"
+  ],
+  "x-conversions": {
+    "note": "Conversion rules are non-normative here. See packages/sdk-python/src/augur_sdk/coordinates.py for the reference impl.",
+    "viewport_css_px<->device_px": "multiply by device_scale_factor on the source observation",
+    "viewport_css_px<->screenshot_px": "screenshots are captured at viewport scale by default; otherwise multiply by screenshot_scale",
+    "dom_client_rect": "Diagnostic-only space. MUST be paired with provenance=dom. Never a runtime input (spec §4)."
+  }
+}

augur_schema-0.2.0/src/augur_schema/json/debug_session.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/debug_session.schema.json",
+  "title": "DebugSession",
+  "description": "One CUA run from the debugger's point of view. Spec §8.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "debug_session_id",
+    "run_id",
+    "client",
+    "capture_mode",
+    "started_at",
+    "status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Augur schema version that this record conforms to. See docs/versioning.md.",
+      "pattern": "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$"
+    },
+    "debug_session_id": {
+      "type": "string",
+      "pattern": "^dbg_[A-Za-z0-9_\\-]+$"
+    },
+    "run_id": {
+      "type": "string",
+      "description": "Adapter-supplied run id. Often `run_<uuid>` but the format is not enforced."
+    },
+    "client": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string", "description": "Adapter name, e.g. `mantis`."},
+        "version": {"type": "string"},
+        "git_sha": {"type": "string"}
+      }
+    },
+    "capture_mode": {"$ref": "capture_mode.schema.json"},
+    "started_at": {"type": "string", "format": "date-time"},
+    "ended_at": {"type": ["string", "null"], "format": "date-time"},
+    "status": {
+      "type": "string",
+      "enum": ["running", "succeeded", "failed", "cancelled", "halted"]
+    },
+    "artifact_root": {
+      "type": "string",
+      "description": "URI to the artifact root. file:// for local bundles, s3:// or https:// otherwise."
+    },
+    "trace_uri": {"type": "string"},
+    "live": {
+      "type": ["object", "null"],
+      "description": "Live attach endpoints. Only populated while the run is active (spec §7, Phase 4).",
+      "additionalProperties": false,
+      "properties": {
+        "status_url": {"type": "string"},
+        "video_url": {"type": "string"},
+        "reasoning_url": {"type": "string"}
+      }
+    },
+    "tags": {
+      "type": "object",
+      "additionalProperties": {"type": "string"},
+      "description": "Free-form key/value tags (tenant, environment, plan signature, etc.)."
+    },
+    "costs": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Run-level cost rollup. Producers MAY also stamp `cost_usd` as a string in `tags` for back-compat with the runs-list display path; servers/viewers prefer this structured form when present. Closes #58.",
+      "properties": {
+        "total_usd":        {"type": "number", "minimum": 0},
+        "model_usd":        {"type": "number", "minimum": 0},
+        "gpu_usd":          {"type": "number", "minimum": 0},
+        "proxy_usd":        {"type": "number", "minimum": 0},
+        "tokens_in":        {"type": "integer", "minimum": 0},
+        "tokens_out":       {"type": "integer", "minimum": 0},
+        "cache_hit_tokens": {"type": "integer", "minimum": 0}
+      }
+    }
+  }
+}

augur_schema-0.2.0/src/augur_schema/json/decision_event.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/decision_event.schema.json",
+  "title": "DecisionEvent",
+  "description": "An ordered record from planner, verifier, recovery, routing, or dispatch layers (spec §8). Stored one-per-line in JSONL files under events/.",
+  "type": "object",
+  "required": ["ts", "layer", "kind", "summary"],
+  "additionalProperties": false,
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 UTC timestamp."
+    },
+    "step_index": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional — events MAY be associated with a step or stand alone."
+    },
+    "layer": {
+      "type": "string",
+      "enum": [
+        "planner",
+        "grounding",
+        "model",
+        "dispatch",
+        "verifier",
+        "step_recovery",
+        "routing",
+        "runner",
+        "adapter"
+      ]
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["decision", "observation", "error", "info", "metric"]
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-line human summary. The detail object carries the structured payload."
+    },
+    "detail": {
+      "type": "object",
+      "description": "Layer-specific structured payload. Schema is intentionally open here; adapters MAY define their own shapes.",
+      "additionalProperties": true
+    }
+  }
+}