# Agent context v1

**Status:** v1, stabilizing. Until the first known external consumer appears or 2026-10-01, whichever happens first, compatibility is best-effort. From that trigger onward, `reviewable-artifacts/agent-context/v1` is additive-only.

## Consumer contract

- A snapshot is immutable. Its JSON and Markdown exports do not change after creation.
- Within v1, new fields may be added; existing fields and their meanings are not removed or changed.
- This is curated review context, not an execution request. Regeneration happens outside Reviewable Artifacts.

## Entities

- **Snapshot:** an immutable materialization of thread conclusions and source revisions.
- **Included thread:** a thread in `requested_changes`, `constraints`, or `context`.
- **Omitted thread:** an identifier and disposition retained for traceability, without message text.
- **Target reference:** a portable reference resolved through the projection document; see [Stable anchors](stable-anchors.md).

## Top-level fields

| Field | Meaning |
| --- | --- |
| `schema` | Exact schema identifier: `reviewable-artifacts/agent-context/v1`. |
| `snapshot` | Snapshot identity, creation time, and immutable marker. |
| `artifact_ref` | Reviewed artifact identity and storage references. |
| `version_ref` | Exact artifact version reviewed by this snapshot. |
| `projection_ref` | Review projection identity and kind. |
| `review_session_ref` | Review session identity. |
| `execution_boundary` | Explicit declaration that regeneration is external. |
| `summary` | Counts across all source threads. |
| `requested_changes` | Included `change_request` conclusions. |
| `constraints` | Included `preserve` conclusions. |
| `context` | Included `context` conclusions. |
| `unresolved_blocker_ids` | Included blocking threads not in `resolved` lifecycle status. |
| `omitted_threads` | Every non-included thread as an id/disposition reference. |

## Reference fields

| Field | Meaning |
| --- | --- |
| `snapshot.id` | Immutable consolidation id. |
| `snapshot.created_at` | ISO-8601 creation timestamp. |
| `snapshot.immutable` | Always `true` for this schema. |
| `artifact_ref.id` | Artifact id. |
| `artifact_ref.title` | Artifact title at snapshot creation. |
| `artifact_ref.source_ref` | Source filename or source reference. |
| `artifact_ref.storage_mode` | Artifact storage mode. |
| `artifact_ref.snapshot_ref` | Artifact content snapshot reference, or `null`. |
| `version_ref.id` | Reviewed version id. Use it to detect post-snapshot artifact drift. |
| `version_ref.parent_version_id` | Parent version id, or `null`. |
| `version_ref.label` | Version label. |
| `version_ref.snapshot_ref` | Version content snapshot reference, or `null`. |
| `projection_ref.id` | Projection id. |
| `projection_ref.kind` | Projection kind. |
| `review_session_ref.id` | Review session id. |
| `execution_boundary.regeneration` | `external`. |
| `execution_boundary.provider` | Always `null`; provider selection is outside the platform. |
| `execution_boundary.executable_job` | Always `null`; no executable job is supplied. |
| `summary.total_threads` | Number of source threads considered. |
| `summary.included_count` | Number of records across the three included sections. |
| `summary.omitted_count` | Number of omitted thread references. |
| `summary.unresolved_blocking_count` | Included blocking records not yet resolved. |

## Included-record fields

Every object in `requested_changes[]`, `constraints[]`, and `context[]` has this shape.

| Field | Meaning |
| --- | --- |
| `thread_id` | Source thread id. |
| `thread_revision` | Exact source thread revision materialized in the snapshot. |
| `target_ref.id` | Projection target id. |
| `target_ref.adapter` | Projection adapter. |
| `target_ref.slide_id` | Slide id for slide projections, otherwise `null`. |
| `target_ref.group_id` | Group id when present, otherwise `null`. |
| `target_ref.element_id` | Element id when present, otherwise `null`. |
| `target_ref.text_hash` | Target text hash; empty when unavailable. |
| `target_label` | Human-readable target label captured at consolidation. |
| `severity` | Reserved, non-normative metadata. |
| `feedback_type` | Reserved, non-normative metadata. |
| `lifecycle_status` | Source lifecycle status at consolidation. |
| `disposition` | Included disposition: `change_request`, `preserve`, or `context`. |
| `accepted_conclusion` | Normalized accepted conclusion text. |
| `source_message_refs` | Ordered source-message references, without message bodies. |
| `source_message_refs[].id` | Source message id. |
| `source_message_refs[].revision` | Source message revision. |
| `source_message_refs[].server_order` | Source message order. |
| `source_message_refs[].deleted` | Whether the source message is deleted. |

**Consumer note:** `feedback_type` and `severity` are reserved/non-normative. Consumers must not branch, rank, filter, or otherwise derive behavior from them. Their semantics may change in a future revision.

## Omitted references

| Field | Meaning |
| --- | --- |
| `unresolved_blocker_ids[]` | Thread id of an included unresolved blocking record. |
| `omitted_threads[].id` | Omitted source thread id. |
| `omitted_threads[].disposition` | Source disposition retained for audit. |

## Example snapshot

Generated locally on 2026-07-23 by starting the application against a temporary SQLite database, running `npm run seed:demo`, then downloading its JSON consolidation export. It contains no capabilities or other secrets.

```json
{
  "schema": "reviewable-artifacts/agent-context/v1",
  "snapshot": {
    "id": "con_1be687f7-da74-4f01-be01-28c67c35",
    "created_at": "2026-07-23T10:14:28.822Z",
    "immutable": true
  },
  "artifact_ref": {
    "id": "art_b3ad2f4e-4212-4ec2-9303-b4b16c62",
    "title": "Northstar Q3 Growth Review",
    "source_ref": "demo-report.html",
    "storage_mode": "managed_snapshot",
    "snapshot_ref": "sha256:3cd916eb01b2c83303a0dc9c0231d5834a911c2a63a0896f311eedef34bf03e7"
  },
  "version_ref": {
    "id": "ver_d163f0d6-a220-45ba-b8ee-5dbffb98",
    "parent_version_id": null,
    "label": "v1",
    "snapshot_ref": "sha256:3cd916eb01b2c83303a0dc9c0231d5834a911c2a63a0896f311eedef34bf03e7"
  },
  "projection_ref": {
    "id": "prj_646136bc-ff68-4b01-a179-2ab74727",
    "kind": "html"
  },
  "review_session_ref": {
    "id": "rev_736fd0d5-a5fc-49e8-a1d9-6aa9c99a"
  },
  "execution_boundary": {
    "regeneration": "external",
    "provider": null,
    "executable_job": null
  },
  "summary": {
    "total_threads": 5,
    "included_count": 3,
    "omitted_count": 2,
    "unresolved_blocking_count": 0
  },
  "requested_changes": [
    {
      "thread_id": "thr_aec90d4a-824d-4b55-994c-f8dab29a",
      "thread_revision": 2,
      "target_ref": {
        "id": "executive-summary",
        "adapter": "html",
        "slide_id": null,
        "group_id": null,
        "element_id": null,
        "text_hash": "1j7o5ix"
      },
      "target_label": "Executive summary Demand is healthy; activation is now the highest-lever",
      "severity": "important",
      "feedback_type": "logic",
      "lifecycle_status": "resolved",
      "disposition": "change_request",
      "accepted_conclusion": "Make activation the explicit 30-day operating priority, while preserving the current acquisition mix.",
      "source_message_refs": [
        {
          "id": "msg_11298e8e-066d-43c3-bad6-1aa3cf48",
          "revision": 1,
          "server_order": 1,
          "deleted": false
        },
        {
          "id": "msg_68368b8a-9d0f-4768-9725-42e85eb0",
          "revision": 1,
          "server_order": 2,
          "deleted": false
        }
      ]
    }
  ],
  "constraints": [
    {
      "thread_id": "thr_2ef7f1f2-8806-4aee-a151-a7b1328f",
      "thread_revision": 2,
      "target_ref": {
        "id": "channel-performance",
        "adapter": "html",
        "slide_id": null,
        "group_id": null,
        "element_id": null,
        "text_hash": "1cjq8ct"
      },
      "target_label": "Channel performance Partner-sourced pipeline is the efficient growth eng",
      "severity": "minor",
      "feedback_type": "brand",
      "lifecycle_status": "resolved",
      "disposition": "preserve",
      "accepted_conclusion": "Preserve the partner-channel conclusion and its efficient-growth framing in the executive narrative.",
      "source_message_refs": [
        {
          "id": "msg_d034cd48-63e5-448d-99a0-cfcb1afc",
          "revision": 1,
          "server_order": 1,
          "deleted": false
        }
      ]
    }
  ],
  "context": [
    {
      "thread_id": "thr_19885017-1523-4c35-bc89-7ca2cb53",
      "thread_revision": 2,
      "target_ref": {
        "id": "next-steps",
        "adapter": "html",
        "slide_id": null,
        "group_id": null,
        "element_id": null,
        "text_hash": "rakd0n"
      },
      "target_label": "30-day plan Actions, owners, and decision checkpoints Week 1 Instrument ",
      "severity": "minor",
      "feedback_type": "logic",
      "lifecycle_status": "resolved",
      "disposition": "context",
      "accepted_conclusion": "Use the August activation cohort and CAC-payback data as the documented gate for revisiting paid-search spend.",
      "source_message_refs": [
        {
          "id": "msg_966041b6-1036-40a0-8c5e-16470199",
          "revision": 1,
          "server_order": 1,
          "deleted": false
        }
      ]
    }
  ],
  "unresolved_blocker_ids": [],
  "omitted_threads": [
    {
      "id": "thr_8478b26c-0871-4ca1-8166-0872f55f",
      "disposition": "omit"
    },
    {
      "id": "thr_080a25d6-c320-49d4-9d44-df88b567",
      "disposition": "omit"
    }
  ]
}
```