agentplane-primitives 0.1.0__tar.gz

agentplane_primitives-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Environments
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Build and packaging
+build/
+dist/
+*.whl
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

agentplane_primitives-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes are recorded here, following [Keep a Changelog](https://keepachangelog.com/)
+and [SemVer](https://semver.org/). Each entry is classified as **compatible** or **breaking** and
+names the migration each consumer needs (see [docs/versioning.md](docs/versioning.md)).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-12
+
+First release. Schema version `0.1`. Everything below is new, so every entry is **compatible**; there
+is nothing to migrate from. Pre-1.0: pin the exact minor (`agentplane-primitives==0.1.*`).
+
+### Added
+- **Entities:** `Trace` (labels are strings, no status of its own), `Span` (`parent_envelope_id`
+  links it to the caller) and `Envelope` with identity fields at the top level and nested
+  `envelope_status`, `input`, `output` and `metadata`; `attempt` and `links` (`retry_of`).
+- **Kinds:** a closed `Kind` enum (`llm`, `tool`). `tool` input and output carry `raw` and an
+  optional `error`; `llm` input and output carry the canonical fields, `raw`, content blocks
+  (`text`, `tool_call`, `reasoning`, `refusal`), `finish_reason` and the fixed cost fields
+  `provider`, `model`, `model_source` and `usage` (five exclusive, additive token buckets).
+- **Enums:** `Kind`, `State`, `Status`, `LinkType`, `FinishReason`, `ModelSource`, `MessageRole`.
+  A new member of any of them is a schema change.
+- **Ids:** `TraceId` (32 hex), `SpanId` and `EnvelopeId` (16 hex), lowercase, never all zero, with
+  random generators.
+- **`traceparent` carrier:** `TraceContext`, `parse_traceparent()` (strict, never raises:
+  anything malformed gives `None`) and `format_traceparent()`. `to_event` and `from_event` are
+  reserved names, documented and not implemented.
+- **Metadata rules:** lowercase dot-separated keys, the reserved `chronicle.` prefix, string-valued
+  trace labels, and the well-known label keys `session_id`, `message_id` and `user_id`.
+- **Schemas:** one committed JSON Schema file per stored entity (`Trace.json`, `Span.json`,
+  `Envelope.json`), generated by `python scripts/generate_schemas.py`; a test fails when they
+  drift from the models.
+- **Versioning:** `schema_version` `"0.1"` on every persisted payload; unknown fields are ignored
+  on read.
+- **Repository:** `src` layout, typed package (`py.typed`), CI, release workflow, dependency
+  updates, contribution and security docs, and ADRs 0001 to 0005 in `docs/adr/`.
+
+**Not in this package:** HTTP request and response wrappers. The control plane owns them and
+reuses these entities as bodies ([ADR 0003](docs/adr/0003-api-models-live-in-control-plane.md)).

agentplane_primitives-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tisha Chawla and Susheem Koul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentplane_primitives-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: agentplane-primitives
+Version: 0.1.0
+Summary: Shared, versioned domain primitives (Trace, Span, Envelope) for the AgentPlane products.
+Project-URL: Homepage, https://github.com/theagentplane/primitives
+Project-URL: Repository, https://github.com/theagentplane/primitives
+Project-URL: Issues, https://github.com/theagentplane/primitives/issues
+Project-URL: Changelog, https://github.com/theagentplane/primitives/blob/main/CHANGELOG.md
+Author: Tisha Chawla, Susheem Koul
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llm,observability,pydantic,schema,tracing
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.6
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# AgentPlane Primitives
+
+**One schema for every agent trace.**<br>
+<sub>Shared, versioned Trace, Span and Envelope models for Chronicle, the control plane and TokenOps.</sub>
+
+[![CI](https://github.com/theagentplane/primitives/actions/workflows/ci.yml/badge.svg)](https://github.com/theagentplane/primitives/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/theagentplane/primitives)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typing-strict-informational.svg)](https://peps.python.org/pep-0561/)
+[![GitHub stars](https://img.shields.io/github/stars/theagentplane/primitives?style=social)](https://github.com/theagentplane/primitives/stargazers)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?logo=linkedin&logoColor=white)](https://www.linkedin.com/company/the-agent-plane/)
+
+<sub>Built by <b><a href="https://www.linkedin.com/in/susheemkoul/">Susheem Koul</a></b> and <b><a href="https://www.linkedin.com/in/tisha-chawla/">Tisha Chawla</a></b></sub>
+
+<br>
+
+[Core features](#-core-features) · [Quickstart](#-quickstart) · [How it fits](#-how-it-fits) · [Scope](#-scope) · [Versioning](#-versioning) · [Development](#-development) · [Support](#-support)
+
+</div>
+
+> ### 🚧 Pre-alpha
+>
+> This release is the repository scaffold. The models land in follow-up releases (see the
+> [roadmap](#-roadmap)). Everything under *Core features* describes the
+> [design](docs/design.md) these releases implement.
+
+## ✨ Core features
+
+Chronicle records what an agent did, the control plane stores and shows it, and TokenOps reads
+it to govern spend. Those three only work together if they agree on the shape of the data.
+This package is that agreement, and nothing else.
+
+| | |
+|---|---|
+| **Three tiers** | A `Trace` is one request across services, a `Span` is one service's handling of it, an `Envelope` is one boundary crossing inside the span. |
+| **One definition, three repos** | Chronicle, the control plane and TokenOps import the same models. None defines its own copy. |
+| **Closed enums** | `kind`, `state`, `status` and the other enumerations are closed sets. A new value is a deliberate schema change. |
+| **Additive-only versioning** | SemVer for the package plus a `schema_version` on every payload. Nothing breaks within a major version. |
+| **W3C `traceparent` carrier** | Parse and format the trace-context header so a trace follows a request across services. |
+| **No I/O, one dependency** | Data and validation only, on pydantic. No network, no disk, no business logic. |
+| **Contract you can read** | Generated JSON Schema, committed and checked in CI, for anything that is not Python. |
+
+## 🚀 Quickstart
+
+Requires Python 3.10+. The package is typed ([PEP 561](https://peps.python.org/pep-0561/)).
+
+```bash
+pip install agentplane-primitives   # once the first release is published
+```
+
+Until then, install from source:
+
+```bash
+git clone https://github.com/theagentplane/primitives.git
+cd primitives
+pip install -e .
+python -c "import agentplane_primitives as p; print(p.__version__)"
+```
+
+### When you need more
+
+| You want to | Go to |
+|---|---|
+| Understand the entities and why there are three tiers | [Design](docs/design.md) |
+| Know what may change between versions | [Versioning policy](docs/versioning.md) |
+| Propose a new field or enum value | [Schema change proposal](https://github.com/theagentplane/primitives/issues/new?template=schema_change.yml) |
+| Add a model | [Contributing](CONTRIBUTING.md) |
+| Publish a release | [Releasing](RELEASING.md) |
+
+## 🧩 How it fits
+
+```mermaid
+flowchart LR
+    P["primitives<br/>Trace · Span · Envelope"]
+    C["Chronicle<br/>edge SDK: record, save, replay"]
+    CP["Control plane<br/>storage, query, visualization"]
+    T["TokenOps<br/>governance"]
+
+    C -->|imports| P
+    CP -->|imports| P
+    T -->|imports| P
+    C -->|"envelopes over HTTP"| CP
+    T -->|"reads cost data"| CP
+```
+
+The control plane owns the schema, and this package is where that schema is defined and shared.
+Chronicle never talks to a database. It sends envelopes to the control plane, which keeps its own
+storage layout and maps from these models.
+
+## 🎯 Scope
+
+| In scope | Out of scope |
+|---|---|
+| `Trace`, `Span`, `Envelope` and their `llm` and `tool` payload variants | Storage, HTTP clients or servers |
+| The `traceparent` carrier, id generation and validation | Business logic (pricing, policy, replay matching) |
+| Enumerations and well-known metadata keys | Visualization or export (the control plane maps to OpenTelemetry) |
+| Committed JSON Schema for every model | HTTP request and response wrappers (the control plane owns them, [ADR 0003](docs/adr/0003-api-models-live-in-control-plane.md)) |
+| | Anything that performs I/O |
+
+## 🔖 Versioning
+
+SemVer for the package, plus a `schema_version` (`major.minor`) on every payload.
+
+- **Additive-only within a major.** New optional fields are allowed. A new enum member is
+  additive for the writer, but older readers reject it, so **consumers upgrade before emitters**.
+- **A breaking change is a new major.** The control plane accepts the current and previous major.
+- **Pre-1.0:** pin the exact minor. From 1.0: `>=1.2,<2`.
+
+Full policy: [docs/versioning.md](docs/versioning.md).
+
+## 🛠 Development
+
+Uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                                   # environment with the dev group
+uv run pytest --cov                       # tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy                               # strict type check
+uv build                                  # sdist and wheel
+```
+
+## 🗺 Roadmap
+
+1. ✅ Repository scaffold
+2. ✅ `Trace`, `Span`, `Envelope`, the `llm` and `tool` payload variants, enums, ids
+3. ✅ The `traceparent` carrier
+4. ✅ Committed JSON Schema and the CI drift check
+5. First release (0.1.0): see [RELEASING.md](RELEASING.md)
+
+## Reference
+
+<details>
+<summary><b>Project structure</b></summary>
+
+```
+src/agentplane_primitives/   # installable package (typed; version in _version.py)
+├── enums/                   # closed lists, one file each: kind, state, status, link type
+├── types/                   # field types: id types, metadata key and label types
+├── models/                  # the models: base class now; Trace, Span, Envelope to come
+├── utils/                   # helper functions: id generation, reserved-key check (traceparent later)
+└── schemas/                 # generated JSON Schema, committed and drift-checked in CI
+                             # (more models and the traceparent carrier arrive in later PRs)
+docs/                        # design notes and the versioning policy
+tests/                       # unit tests
+.github/                     # CI, release, dependency updates, templates
+```
+
+</details>
+
+<details>
+<summary><b>More documentation</b></summary>
+
+- [Design](docs/design.md): the entities and where they are specified
+- [Versioning policy](docs/versioning.md)
+- [Changelog](CHANGELOG.md): every change classified as compatible or breaking
+- [Contributing](CONTRIBUTING.md) - [Releasing](RELEASING.md) - [Security](SECURITY.md)
+
+</details>
+
+## 🛟 Support
+
+| Need | Where |
+|---|---|
+| Bug | [Open an issue](https://github.com/theagentplane/primitives/issues) |
+| Schema change | [Schema change proposal](https://github.com/theagentplane/primitives/issues/new?template=schema_change.yml) |
+| Security issue | [SECURITY.md](SECURITY.md) |
+| Real-time help | [Slack](https://join.slack.com/t/theagentplane/shared_invite/zt-47lqx2xtc-0idr1cuLNJ_JDTgqxDiUsg) |
+| Talk it through | [Office hours](https://calendly.com/theagentplane/theagentplane) |
+
+## Contributors
+
+Thanks to everyone who has contributed.
+
+[![Contributors](https://contrib.rocks/image?repo=theagentplane/primitives)](https://github.com/theagentplane/primitives/graphs/contributors)
+
+---
+
+<div align="center">
+
+[Back to top](#agentplane-primitives)
+
+</div>

agentplane_primitives-0.1.0/README.md

@@ -0,0 +1,185 @@
+<div align="center">
+
+# AgentPlane Primitives
+
+**One schema for every agent trace.**<br>
+<sub>Shared, versioned Trace, Span and Envelope models for Chronicle, the control plane and TokenOps.</sub>
+
+[![CI](https://github.com/theagentplane/primitives/actions/workflows/ci.yml/badge.svg)](https://github.com/theagentplane/primitives/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/theagentplane/primitives)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typing-strict-informational.svg)](https://peps.python.org/pep-0561/)
+[![GitHub stars](https://img.shields.io/github/stars/theagentplane/primitives?style=social)](https://github.com/theagentplane/primitives/stargazers)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?logo=linkedin&logoColor=white)](https://www.linkedin.com/company/the-agent-plane/)
+
+<sub>Built by <b><a href="https://www.linkedin.com/in/susheemkoul/">Susheem Koul</a></b> and <b><a href="https://www.linkedin.com/in/tisha-chawla/">Tisha Chawla</a></b></sub>
+
+<br>
+
+[Core features](#-core-features) · [Quickstart](#-quickstart) · [How it fits](#-how-it-fits) · [Scope](#-scope) · [Versioning](#-versioning) · [Development](#-development) · [Support](#-support)
+
+</div>
+
+> ### 🚧 Pre-alpha
+>
+> This release is the repository scaffold. The models land in follow-up releases (see the
+> [roadmap](#-roadmap)). Everything under *Core features* describes the
+> [design](docs/design.md) these releases implement.
+
+## ✨ Core features
+
+Chronicle records what an agent did, the control plane stores and shows it, and TokenOps reads
+it to govern spend. Those three only work together if they agree on the shape of the data.
+This package is that agreement, and nothing else.
+
+| | |
+|---|---|
+| **Three tiers** | A `Trace` is one request across services, a `Span` is one service's handling of it, an `Envelope` is one boundary crossing inside the span. |
+| **One definition, three repos** | Chronicle, the control plane and TokenOps import the same models. None defines its own copy. |
+| **Closed enums** | `kind`, `state`, `status` and the other enumerations are closed sets. A new value is a deliberate schema change. |
+| **Additive-only versioning** | SemVer for the package plus a `schema_version` on every payload. Nothing breaks within a major version. |
+| **W3C `traceparent` carrier** | Parse and format the trace-context header so a trace follows a request across services. |
+| **No I/O, one dependency** | Data and validation only, on pydantic. No network, no disk, no business logic. |
+| **Contract you can read** | Generated JSON Schema, committed and checked in CI, for anything that is not Python. |
+
+## 🚀 Quickstart
+
+Requires Python 3.10+. The package is typed ([PEP 561](https://peps.python.org/pep-0561/)).
+
+```bash
+pip install agentplane-primitives   # once the first release is published
+```
+
+Until then, install from source:
+
+```bash
+git clone https://github.com/theagentplane/primitives.git
+cd primitives
+pip install -e .
+python -c "import agentplane_primitives as p; print(p.__version__)"
+```
+
+### When you need more
+
+| You want to | Go to |
+|---|---|
+| Understand the entities and why there are three tiers | [Design](docs/design.md) |
+| Know what may change between versions | [Versioning policy](docs/versioning.md) |
+| Propose a new field or enum value | [Schema change proposal](https://github.com/theagentplane/primitives/issues/new?template=schema_change.yml) |
+| Add a model | [Contributing](CONTRIBUTING.md) |
+| Publish a release | [Releasing](RELEASING.md) |
+
+## 🧩 How it fits
+
+```mermaid
+flowchart LR
+    P["primitives<br/>Trace · Span · Envelope"]
+    C["Chronicle<br/>edge SDK: record, save, replay"]
+    CP["Control plane<br/>storage, query, visualization"]
+    T["TokenOps<br/>governance"]
+
+    C -->|imports| P
+    CP -->|imports| P
+    T -->|imports| P
+    C -->|"envelopes over HTTP"| CP
+    T -->|"reads cost data"| CP
+```
+
+The control plane owns the schema, and this package is where that schema is defined and shared.
+Chronicle never talks to a database. It sends envelopes to the control plane, which keeps its own
+storage layout and maps from these models.
+
+## 🎯 Scope
+
+| In scope | Out of scope |
+|---|---|
+| `Trace`, `Span`, `Envelope` and their `llm` and `tool` payload variants | Storage, HTTP clients or servers |
+| The `traceparent` carrier, id generation and validation | Business logic (pricing, policy, replay matching) |
+| Enumerations and well-known metadata keys | Visualization or export (the control plane maps to OpenTelemetry) |
+| Committed JSON Schema for every model | HTTP request and response wrappers (the control plane owns them, [ADR 0003](docs/adr/0003-api-models-live-in-control-plane.md)) |
+| | Anything that performs I/O |
+
+## 🔖 Versioning
+
+SemVer for the package, plus a `schema_version` (`major.minor`) on every payload.
+
+- **Additive-only within a major.** New optional fields are allowed. A new enum member is
+  additive for the writer, but older readers reject it, so **consumers upgrade before emitters**.
+- **A breaking change is a new major.** The control plane accepts the current and previous major.
+- **Pre-1.0:** pin the exact minor. From 1.0: `>=1.2,<2`.
+
+Full policy: [docs/versioning.md](docs/versioning.md).
+
+## 🛠 Development
+
+Uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                                   # environment with the dev group
+uv run pytest --cov                       # tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy                               # strict type check
+uv build                                  # sdist and wheel
+```
+
+## 🗺 Roadmap
+
+1. ✅ Repository scaffold
+2. ✅ `Trace`, `Span`, `Envelope`, the `llm` and `tool` payload variants, enums, ids
+3. ✅ The `traceparent` carrier
+4. ✅ Committed JSON Schema and the CI drift check
+5. First release (0.1.0): see [RELEASING.md](RELEASING.md)
+
+## Reference
+
+<details>
+<summary><b>Project structure</b></summary>
+
+```
+src/agentplane_primitives/   # installable package (typed; version in _version.py)
+├── enums/                   # closed lists, one file each: kind, state, status, link type
+├── types/                   # field types: id types, metadata key and label types
+├── models/                  # the models: base class now; Trace, Span, Envelope to come
+├── utils/                   # helper functions: id generation, reserved-key check (traceparent later)
+└── schemas/                 # generated JSON Schema, committed and drift-checked in CI
+                             # (more models and the traceparent carrier arrive in later PRs)
+docs/                        # design notes and the versioning policy
+tests/                       # unit tests
+.github/                     # CI, release, dependency updates, templates
+```
+
+</details>
+
+<details>
+<summary><b>More documentation</b></summary>
+
+- [Design](docs/design.md): the entities and where they are specified
+- [Versioning policy](docs/versioning.md)
+- [Changelog](CHANGELOG.md): every change classified as compatible or breaking
+- [Contributing](CONTRIBUTING.md) - [Releasing](RELEASING.md) - [Security](SECURITY.md)
+
+</details>
+
+## 🛟 Support
+
+| Need | Where |
+|---|---|
+| Bug | [Open an issue](https://github.com/theagentplane/primitives/issues) |
+| Schema change | [Schema change proposal](https://github.com/theagentplane/primitives/issues/new?template=schema_change.yml) |
+| Security issue | [SECURITY.md](SECURITY.md) |
+| Real-time help | [Slack](https://join.slack.com/t/theagentplane/shared_invite/zt-47lqx2xtc-0idr1cuLNJ_JDTgqxDiUsg) |
+| Talk it through | [Office hours](https://calendly.com/theagentplane/theagentplane) |
+
+## Contributors
+
+Thanks to everyone who has contributed.
+
+[![Contributors](https://contrib.rocks/image?repo=theagentplane/primitives)](https://github.com/theagentplane/primitives/graphs/contributors)
+
+---
+
+<div align="center">
+
+[Back to top](#agentplane-primitives)
+
+</div>

agentplane_primitives-0.1.0/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,55 @@
+# 0001. Record architecture decisions
+
+| Field | Value |
+|---|---|
+| Status | Accepted |
+| Date | 2026-10-05 |
+| Deciders | Susheem Koul, Tisha Chawla |
+
+## Context
+
+Four repositories (chronicle, primitives, control-plane, tokenops) now evolve together and share
+contracts. Decisions are made in conversations, pull request threads and long design documents,
+and the reasoning is hard to find afterwards. New contributors, and AI coding agents working in
+these repositories, have no reliable way to learn why something is built the way it is, so they
+can unknowingly undo a deliberate choice.
+
+## Options considered
+
+### Option A: keep decisions inside design documents and pull requests
+
+- Good: no new process.
+- Bad: reasoning is scattered, mixed with implementation detail, and edited over time, so the
+  record of what was decided and when is lost.
+
+### Option B: one ADR per decision, stored in each repository
+
+- Good: small, dated, reviewable records next to the code; easy for agents to read; history
+  shows what changed and why.
+- Bad: a little writing discipline is needed, and cross-repository decisions need a rule about
+  where they live.
+
+## Decision
+
+We will record architecture decisions as ADRs in `docs/adr/` of each repository, using the
+template in this folder. Cross-repository decisions are recorded in the repository that owns the
+decision and linked from the others. AI coding agents are told to read the ADRs before changing
+architecture and to follow `docs/adr/README.md` when asked to record a decision.
+
+## Consequences
+
+- **Good:** decisions are findable and dated; superseded decisions stay visible.
+- **Bad or risky:** ADRs go stale if nobody writes them, so writing one is part of making a
+  qualifying decision, not a follow-up.
+- **Follow-ups:** backfill ADRs for the decisions already taken in the Chronicle technical
+  design document where they matter most.
+
+## Impact on other repositories
+
+The same folder, template and agent instructions are added to chronicle, primitives,
+control-plane and tokenops.
+
+## Links
+
+- [How to write an ADR](README.md)
+- [Template](template.md)

agentplane_primitives-0.1.0/docs/adr/0002-closed-kind-enum.md

@@ -0,0 +1,60 @@
+# 0002. Define envelope `kind` as a closed enum with two members
+
+| Field | Value |
+|---|---|
+| Status | Accepted |
+| Date | 2026-10-06 |
+| Deciders | Susheem Koul, Tisha Chawla |
+
+## Context
+
+Every envelope has a `kind` that selects the shape of its input and output (design sections 2.3
+and 2.9). In Chronicle 0.5.0, `kind` is a free string, and `router` and `custom` are in use
+alongside `llm` and `tool`. Consumers such as TokenOps read the envelope by kind, and replay
+needs to know how to handle each one. A router is either an LLM call or, if it is a plain
+function, a tool; delegating work to another agent is an outbound call, which is a tool envelope
+(the link between the two services is carried by `traceparent`).
+
+## Options considered
+
+### Option A: keep `kind` a free string
+
+What 0.5.0 does today.
+
+- Good: unchanged from 0.5.0.
+- Bad: it allows values such as `router` and `custom`, which the design retires (section 2.3).
+
+### Option B: closed enum defined in this package
+
+`kind` is `llm` or `tool`. Any other value is rejected at validation.
+
+- Good: a value outside the enum is rejected at validation (section 2.3).
+- Bad: adding a kind is a schema change made in this package (section 2.8).
+
+## Decision
+
+We will define `kind` as a closed enum in this package with the members `llm` and `tool`, and
+reject every other value, including custom and unregistered kinds. `router` and `custom` from
+0.5.0 are retired; both become `tool`.
+
+## Consequences
+
+- **Good:** one definition of `kind`, shared by Chronicle, the control plane and TokenOps.
+- **Bad or risky:** a new kind is additive for the writer, but a reader on an older minor rejects
+  it, so consumers must upgrade before emitters (`docs/versioning.md`). Users cannot invent their
+  own kinds.
+- **Follow-ups:** the input and output variants selected by `kind` arrive with the envelope
+  (tool first, then llm).
+
+## Impact on other repositories
+
+- **chronicle:** declaring a boundary with any other kind fails at declaration time; `router`
+  and `custom` become `tool` (design section 12.3).
+- **control-plane:** validates ingested envelopes against this enum.
+- **tokenops:** `delegate` is removed from its list of observation kinds, leaving `llm | tool`.
+
+## Links
+
+- Design: `docs/rfcs/chronicle-technical-design.md` in chronicle, sections 2.3 and 2.9, decision
+  12.
+- [Versioning policy](../versioning.md)

agentplane_primitives-0.1.0/docs/adr/0003-api-models-live-in-control-plane.md

@@ -0,0 +1,68 @@
+# 0003. Keep HTTP request and response wrappers out of primitives
+
+| Field | Value |
+|---|---|
+| Status | Accepted |
+| Date | 2026-10-06 |
+| Deciders | Susheem Koul, Tisha Chawla |
+
+## Context
+
+The Chronicle technical design (sections 2.8 and 10.1, and the layer table in section 1.1) lists
+"the API request and response models" as part of this package, next to Trace, Span and
+Envelope. Decision 9 of that design says the control plane owns the schema and that Chronicle
+"must not depend on server code".
+
+Trace, Span and Envelope are the records the whole system stores and passes around. They are
+data, not requests. The control plane will use them as the body of its requests and responses,
+while the endpoints, status codes and the rest of the HTTP layer are its own concern.
+
+## Options considered
+
+### Option A: API models stay in primitives (the design as written)
+
+- Good: matches the design as written (sections 1.1, 2.8 and 10.1).
+- Bad: it treats HTTP request and response wrappers as part of the data model, when the
+  maintainers consider Trace, Span and Envelope to be data and not request objects.
+
+### Option B: the control plane owns all API models, and Chronicle depends on primitives through it
+
+- Good: nothing HTTP-specific in primitives.
+- Bad: Chronicle would depend on server code, which conflicts with decision 9 of the design.
+
+### Option C: primitives holds only the entities; the control plane owns the HTTP wrappers
+
+Requests and responses reuse primitives types as their bodies (an upsert-span body is a `Span`; a
+batch of envelopes is a list of `Envelope`). Wrappers that exist only because of the HTTP API
+(the write result and the error body) belong to the control plane. Chronicle imports primitives
+directly.
+
+- Good: primitives stays about the data, and Chronicle depends on primitives directly.
+- Bad: Chronicle must read the write result and error body without a shared model, so it needs a
+  few lines of its own code and a contract test against the control plane.
+
+## Decision
+
+We will take Option C. Primitives defines the entities, ids, enums, metadata rules, the
+`traceparent` carrier and the committed JSON Schema, and no HTTP request or response wrappers.
+
+## Consequences
+
+- **Good:** a smaller package: primitives holds data only.
+- **Bad or risky:** the result and error shapes are defined in one repository and read in
+  another, so drift is possible until a contract test exists. If those shapes grow, moving them
+  into primitives later is an additive change.
+- **Follow-ups:** the planned primitives PR for API models is dropped. The control plane
+  defines the wrappers; Chronicle adds a contract test.
+
+## Impact on other repositories
+
+- **chronicle:** the technical design (sections 1.1, 2.8, 10.1) is updated to match. The client
+  imports primitives for entities and parses the write result and error body itself.
+- **control-plane:** defines the HTTP wrappers and reuses primitives entities as bodies.
+- **tokenops:** none.
+
+## Links
+
+- Design: `docs/rfcs/chronicle-technical-design.md` in chronicle, sections 1.1, 2.8, 10.1 and
+  decision 9.