# Chronicle Source Record Contract v1

Status: **proposed for CHR-CORE-001A / #349**

## Purpose

A Chronicle source record is the minimum durable, product-independent representation of material a human intentionally chose to preserve as Chronicle source.

It answers a deliberately narrow question:

> What must remain true about the preserved human source regardless of whether Chronicle is hosted by Genesis, Pocket Chronicle, a future mobile runtime, a service, or another conforming implementation?

This contract does **not** attempt to describe everything that may be known about a thought. Thought formation, triggers, confidence, evidence, relationships, inferred classifications, emotional context, originality, and similar enrichments belong to the [Thought Provenance Model v1](thought-provenance-v1.md) and derivative/relationship contracts.

## Core rule

> Preserve the human source exactly; attribute what is actually known; never manufacture missing provenance; never allow a model, index, summary, classification, or other derivative to become the source owner.

## Canonical source record v1

A conforming logical v1 source record has these fields:

| Field | Required | Meaning |
|---|---:|---|
| `schemaVersion` | yes | Chronicle **logical source-record** schema version. v1 is `1`. This is not a PostgreSQL migration number, SQLite migration number, encryption version, embedding-space version, or product-export version. |
| `id` | yes | Stable UUID identity of this exact source version. It survives storage migration, export/import, re-indexing, provider changes, and runtime changes. |
| `content` | yes | Exact accepted source text. After acceptance, Chronicle must preserve these Unicode characters without trimming, normalization, summarization, rewriting, or model substitution. |
| `captureSource` | yes | How the preserved source was articulated into Chronicle. v1 defines `typed_text` and `voice_transcript`. New meanings require a later Chronicle schema version rather than product-local invention. |
| `sourceCapturedAt` | yes | Time associated with the source articulation/capture event, serialized as UTC RFC 3339 with millisecond precision. It is **not** a claim about when an internal thought first formed unless separately declared as provenance. |
| `createdAt` | yes | Time this source record became durably accepted by the Chronicle runtime, serialized as UTC RFC 3339 with millisecond precision. It may differ from `sourceCapturedAt`. |
| `preservation` | yes | Describes the human decision that made the material canonical source: `explicit_capture` or `explicit_approval`. |
| `preservedBy` | yes | The human actor who intentionally caused the material to become Chronicle source. An identity reference is optional because a local personal runtime can know that a human acted without having an account identifier. |
| `fidelity` | yes | What relationship the stored `content` has to the articulation being preserved: v1 defines `exact_text` and `approved_transcript`. |
| `author` | no | Human authorship attribution when actually known or explicitly declared. Omission means unknown/not represented; it must not be inferred from `preservedBy`. |
| `captureActor` | no | Actor/system responsible for capturing or transforming the articulation before preservation when actually known. Omission means unknown/not represented. |
| `custodyRef` | no | Opaque reference to a Chronicle-level ownership/custody scope when a conforming identity/custody model can supply one. Absence is valid and must not be replaced with a fabricated account/workspace identity. |

The machine-readable shape is defined by `../schemas/source-record-v1.schema.json`.

## Required semantics

### 1. Source identity identifies an exact source version

`id` identifies this exact preserved source version. A correction or superseding version receives a different source ID. Re-indexing, re-embedding, classification, migration, export, import, or encryption changes must not silently create a new source identity.

Correction/supersession relationship semantics remain governed by the Chronicle lifecycle contract; this v1 record deliberately does not encode `entry_kind` or `supersedes_id` as mandatory source fields.

### 2. Content is exact after acceptance

Validation may reject empty or otherwise disallowed input before source creation. Once accepted, the canonical `content` value is the exact source text that was approved for preservation.

A runtime may derive a trimmed string for embedding input, tokenize content for search, encrypt bytes for storage, or serialize text differently on disk. Those operations may not change the canonical logical `content` value.

### 3. Capture time is not thought-formation time

`sourceCapturedAt` describes the source articulation/capture event available to Chronicle. Chronicle must not relabel it as "thought formed at" without separate attributable evidence.

This distinction is intentional. A person may articulate today a thought that arose yesterday, last year, or at an unknown time.

### 4. Creation time means durable Chronicle acceptance

`createdAt` is the time the runtime accepted the source as durable canonical Chronicle material. A runtime must not report successful creation before its durability contract has succeeded.

### 5. Human intentionality is explicit

Chronicle source is not merely material observed by a device or generated by a model. v1 requires a human preservation decision:

- `explicit_capture` — the human directly submitted the source for preservation, such as typed capture.
- `explicit_approval` — material was first captured/transformed and a human explicitly approved the resulting source, such as an approved voice transcript.

Future passive/import workflows may require additional modes, but they must preserve the same rule: observed material does not silently become canonical human source.

### 6. Preserver, author, and capture actor are different concepts

Chronicle must not collapse these roles:

- **preservedBy** — who intentionally caused the record to become canonical Chronicle source;
- **author** — who originated the content, when known;
- **captureActor** — who/what captured or transformed the articulation before preservation, when known.

The same human may occupy all roles, but a runtime must not assert that equivalence without evidence.

Identity references are intentionally optional in v1. Pocket Chronicle can truthfully record a human preservation act without inventing an account. Genesis can associate its authenticated actor through a runtime/custody mapping. A future canonical identity model may strengthen these references without changing the meanings above.

### 7. Fidelity is source provenance, not a quality score

`fidelity` states how the preserved content relates to the articulation:

- `exact_text` — the human directly supplied the preserved text and Chronicle preserves it exactly after acceptance.
- `approved_transcript` — the content is a transcript that the human explicitly approved as the source representation.

This field does not claim semantic perfection, transcription accuracy, truth, confidence, or originality.

### 8. Missing provenance stays missing

Optional provenance fields are omitted when unknown or unavailable. Chronicle must not fill them from guesses, model inference, product defaults, or convenient equivalence assumptions.

Machine-inferred provenance belongs to a derivative assertion with its own provenance, not inside the canonical source record as if observed or human-declared fact.

### 9. Source durability cannot depend on derivatives

Embeddings, classifications, summaries, interpretations, extracted preferences, search indexes, Ask answers, and model context are not required source fields. Their absence or failure cannot invalidate, erase, or reject an otherwise valid Chronicle source after source durability succeeds.

### 10. Physical storage is outside this contract

A conforming runtime may store canonical fields as plaintext columns, encrypted blobs, normalized physical tables, an object document, or another representation consistent with Chronicle security contracts. Physical schemas may contain implementation metadata not present in this logical record.

A physical representation is conforming only if it can reproduce the canonical logical record without semantic reinterpretation.

## Current-runtime mapping

### Genesis / server Chronicle

| Genesis field/behavior | Chronicle v1 mapping | Notes |
|---|---|---|
| `chronicle_entries.id` | `id` | Direct stable identity. |
| `content` | `content` | Already preserved byte-for-byte after non-empty validation; trimmed content used for embedding is derivative input, not source mutation. |
| `capture_source` | `captureSource` | `typed_text` and `voice_transcript` map directly. |
| `source_captured_at` | `sourceCapturedAt` | Direct semantic match. |
| `created_at` | `createdAt` | Direct semantic match for durable record creation. |
| authenticated `created_by` actor | `preservedBy.identityRef` when mapped through a Chronicle identity/custody reference scheme | Genesis currently knows a server user ID; the raw database ID is not declared a universal Chronicle identity by this contract. |
| typed capture | `preservation = explicit_capture`, `fidelity = exact_text` | Direct. |
| approved voice transcript | `preservation = explicit_approval`, `fidelity = approved_transcript` | Voice-specific provider/model/edit metadata remains provenance outside the minimum source record and should be carried by CHR-CORE-001B-compatible provenance. |
| `workspace_id` | runtime custody mapping; possible future `custodyRef` | A workspace is a Genesis tenancy mechanism, not a universal Chronicle field. |
| `entry_kind`, `supersedes_id` | deferred lifecycle relationship | Existing behavior is not discarded; canonical supersession semantics are handled separately. |
| `updated_at`, `updated_by`, `approved_at` | runtime/lifecycle/provenance metadata | Not required by the minimum v1 logical source record. |
| embeddings/searchability | no source field | Derived capability only. |

### Pocket Chronicle 0.1

| Pocket field/behavior | Chronicle v1 mapping | Notes |
|---|---|---|
| `chronicle_sources.id` | `id` | Direct stable UUID identity. |
| decrypted `encrypted_content` | `content` | Encryption is physical protection; logical source is exact decrypted content. |
| `capture_source` | `captureSource` | 0.1 supports only `typed_text`, which is a valid subset of v1 capability. |
| `source_captured_at_ms` | `sourceCapturedAt` | Serialize milliseconds as canonical UTC RFC 3339 milliseconds. |
| `created_at_ms` | `createdAt` | Serialize milliseconds as canonical UTC RFC 3339 milliseconds. |
| typed capture action | `preservation = explicit_capture`, `preservedBy.actorType = human`, `fidelity = exact_text` | No account ID is required or invented. |
| `source_schema_version` | maps conceptually to `schemaVersion` after convergence | Pocket's current value is a product/local physical source schema version; CHR-CORE establishes the product-independent logical meaning going forward. |
| `content_encryption_version` | no source field | Physical crypto/version metadata belongs to storage/security adapter semantics. |
| local app/device custody | `custodyRef` omitted until canonical identity/custody representation exists | No fake account/workspace is introduced. |

## Explicit non-fields

The following are **not** canonical source fields merely because a runtime can calculate or infer them:

- embedding vectors or embedding model;
- classification/topic;
- generated summary;
- confidence or certainty;
- inferred emotion;
- inferred intent;
- originality score;
- inferred trigger;
- inferred relationships/preferences/profile;
- search rank/similarity;
- model/provider session memory;
- ciphertext, nonce, key ID, or encryption-library metadata;
- PostgreSQL/SQLite row or migration identifiers.

Some of these may become Chronicle provenance, relationships, derivatives, or adapter metadata. They do not become human source by proximity.

## Versioning rule

A change requires a new Chronicle logical source-record schema version when it changes the meaning of an existing field, makes a previously optional semantic fact mandatory, introduces a new mandatory semantic distinction, or adds a new canonical enumeration meaning that older conforming runtimes could misinterpret.

Physical migrations and additive runtime metadata do not by themselves change `schemaVersion`.

## Conformance principle

A runtime conforms to source-record v1 when it can accept/produce the canonical logical record and demonstrate the invariants in `../conformance/source-record-v1.md`, regardless of its database, language, encryption implementation, network topology, or optional model capabilities.