Skip to content

feat(memory): add structured provenance metadata #141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BunsDev merged 1 commit into from
Jul 7, 2026
Merged

feat(memory): add structured provenance metadata #141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,8 +161,10 @@ Auto-extracted memories are approval-gated in hosted review mode. By default,
hosted sessions write reviewable JSON candidates under
`.coven-code/memory-candidates/` instead of appending directly to durable
`.coven-code/AGENTS.md` memory. Each candidate records content, category,
confidence, provenance, source trust, proposed scope, proposed visibility,
status, and any rejection reason.
confidence, structured provenance, source trust, proposed scope, proposed
visibility, status, and any rejection reason. Auto-extracted provenance records
the session id, source kind, creator, and best-effort repository and commit
references; it does not store secret values.

Trusted deployments can opt into direct durable writes only when the source
trust meets the configured threshold:
Expand Down Expand Up @@ -373,8 +375,9 @@ Frontmatter fields:
| `scope` | Intended scope, such as `user`, `tenant`, `installation`, `repo`, `branch`, or `pr`. |
| `trust` | Source trust. Hosted review enforces this against `hostedReview.memoryTrustThreshold`. Supported values include `system_policy`, `maintainer_approved`, `default_branch_code`, `model_inferred`, `contributor_input`, `fork_input`, and `unknown`. |
| `visibility` | Intended review visibility: `public_review`, `private_review`, or `security_private`. Hosted public reviews exclude `security_private` memory by default. |
| `source` | Provenance source kind, for example `manual`, `github_pr`, `github_pr_review`, or `session_memory_extraction`. |
| `source` | Provenance source kind, for example `manual`, `github_pr`, `github_pr_review`, or `session-memory-extraction`. |
| `source_ref` | Source reference such as `owner/repo#123`, a commit SHA, or another non-secret audit handle. |
| `source_repo`, `source_commit`, `source_actor` | Optional structured provenance for repository slug, commit SHA, and source actor. Store references only, not secret values. |
| `expires_at` | Optional expiry date in `YYYY-MM-DD` format. Expired hosted memory is ignored. |
| `retention_class` | Optional lifecycle class such as `standard`, `short_lived`, `security`, or `legal_hold`. |
| `redacted_at` | Marks content as redacted. Hosted review keeps the metadata visible but replaces the body with a redaction stub. |
Expand Down
40 changes: 28 additions & 12 deletions docs/headless-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# coven-code Headless Execution Contract

**Contract version: `2`** - Status: **Locked** (V2 / structured review output)
**Contract version: `3`** - Status: **Locked** (V3 / memory provenance in review artifacts)

This document is the single source of truth for the interface between
`coven-github` (the GitHub ingress adapter) and `coven-code` (the execution
Expand Down Expand Up @@ -64,7 +64,7 @@ The adapter is the **producer**; the runtime is the **consumer**. The brief is

```json
{
"contract_version": "2",
"contract_version": "3",
"trigger": "issue_assigned",
"repo": {
"owner": "OpenCoven",
Expand Down Expand Up @@ -96,7 +96,7 @@ The adapter is the **producer**; the runtime is the **consumer**. The brief is

| Field | Type | Notes |
|---|---|---|
| `contract_version` | string | MUST be `"2"`. Consumers MUST reject a brief whose major version they do not implement. |
| `contract_version` | string | MUST be `"3"`. Consumers MUST reject a brief whose major version they do not implement. |
| `trigger` | string enum | `issue_assigned` \| `pr_review_comment` \| `issue_mention`. |
| `repo.owner` | string | |
| `repo.name` | string | |
Expand Down Expand Up @@ -132,7 +132,7 @@ the file MAY be absent.

```json
{
"contract_version": "2",
"contract_version": "3",
"status": "success",
"branch": "cody/fix-issue-42",
"commits": [
Expand All @@ -157,7 +157,18 @@ the file MAY be absent.
"id": "mem_review_policy",
"trust": "maintainer-approved",
"visibility": "public_review",
"scope": "managed"
"scope": "managed",
"source": "session-memory-extraction",
"source_ref": null,
"source_repo": "OpenCoven/coven-code",
"source_commit": "0123456789abcdef0123456789abcdef01234567",
"source_actor": "BunsDev",
"session_id": "sess-artifact",
"transcript_ref": "sha256:abc123",
"created_by": "coven-code",
"provenance": [
"session:sess-artifact;source:session-memory-extraction;repo:OpenCoven/coven-code;commit:0123456"
]
}
]
}
Expand All @@ -170,7 +181,7 @@ the file MAY be absent.

| Field | Type | Notes |
|---|---|---|
| `contract_version` | string | MUST be `"2"`. Producers MUST emit it. |
| `contract_version` | string | MUST be `"3"`. Producers MUST emit it. |
| `status` | string enum | `success` \| `failure` \| `partial` \| `needs_input`. See [3.3](#33-status). |
| `branch` | string \| null | Branch the runtime pushed. `null` when no branch was created. The adapter only opens a PR when `branch` is set **and** `commits` is non-empty. |
| `commits` | array | `{ "sha": string, "message": string }`. MAY be empty. |
Expand All @@ -181,9 +192,9 @@ the file MAY be absent.
| `exit_reason` | string enum \| null | `null` on success; otherwise the terminal cause. See [3.4](#34-exit_reason). |

> **Drift note (supersedes `COVEN-GITHUB.md`):** the prose result envelope listed
> an `events` array. Progress/event streaming is **not** part of the v2 result
> an `events` array. Progress/event streaming is **not** part of the v3 result
> envelope — it is deferred to M2 and will travel over a separate channel. The
> v2 envelope carries terminal task state only. Producers MUST NOT rely on
> v3 envelope carries terminal task state only. Producers MUST NOT rely on
> `events` being read.

### 3.2 `review`
Expand All @@ -202,7 +213,7 @@ the intended code. It is required on every result. Non-review tasks MUST set
| `tests_run` | array | Commands run while reviewing, with `passed`, `failed`, `not_run`, or `unknown` status. |
| `no_findings_reason` | string \| null | File-backed explanation for a clean review. MAY be `null` for degraded/partial output when `evidence_status` and `limitations` explain why a substantive clean-review conclusion was not possible. |
| `limitations` | string[] | Evidence gaps, skipped checks, or other caveats. |
| `memory` | object | Memory audit report: `domains_loaded` (hosted memory domains eligible for this review, e.g. `default-branch`; empty for local runs) and `entries` (every loaded memory entry with its stable `id`, effective `trust` label after hosted caps/floors, optional `visibility`, and load `scope`). Lets the consumer audit which memory inputs could have influenced findings and cross-check `memory_refs` citations. |
| `memory` | object | Memory audit report: `domains_loaded` (hosted memory domains eligible for this review, e.g. `default-branch`; empty for local runs) and `entries` (every loaded memory entry with its stable `id`, effective `trust` label after hosted caps/floors, optional `visibility`, load `scope`, structured file-level provenance fields such as `source`, `source_ref`, `source_repo`, `source_commit`, `session_id`, and `created_by`, plus compact per-entry `provenance` strings found in durable memory content). Lets the consumer audit which memory inputs could have influenced findings and cross-check `memory_refs` citations. |

Each finding carries `severity`, `file`, optional `line`, `title`, `body`, and
optional `recommendation`. Valid severities are `info`, `low`, `medium`, `high`,
Expand Down Expand Up @@ -259,7 +270,7 @@ A process **killed by signal**, or one that **times out** (the adapter enforces

## 5. Security invariants

These are non-negotiable for v2:
These are non-negotiable for v3:

1. The session brief is **tokenless**. Serializing a brief MUST NOT produce an
`auth` field, a `"token"` field, or a credential-bearing `clone_url`
Expand All @@ -284,11 +295,16 @@ The contract is versioned by the single `contract_version` string, which tracks
the version.
- A change that adds a **required** field, removes a field, renames a field,
changes a type, or changes exit-code/status semantics is **breaking** and MUST
bump `contract_version` to `"2"`, update both schemas and fixtures, and ship a
migration note here.
bump `contract_version` to the next major version, update both schemas and
fixtures, and ship a migration note here.
- Consumers MUST reject a payload whose major version they do not implement,
rather than silently mis-parsing it.

Migration note for v3: `review.memory.entries[]` now includes structured
file-level provenance fields and compact per-entry provenance strings alongside
memory ids and effective trust labels. Consumers that validate result envelopes
must accept the new required nullable provenance fields and `provenance` arrays.

---

## 7. Conformance artifacts
Expand Down
Loading