# Building a CognitionFrame

## From Python records

`from_records()` accepts mappings or existing `ContextItem` objects. Construction validates payload invariants and computes a canonical content hash before any lazy operation is added.

```{testcode}
import cognoxium as cx

frame = cx.CognitionFrame.from_records([
    {
        "id": "document-42",
        "payload": {"kind": "json", "json": {"answer": 42, "ok": True}},
        "mime_type": "application/json",
        "sources": [{"uri": "db://documents/42", "kind": "database"}],
        "created_at": "2026-01-01T00:00:00Z",
    }
])

item = frame.collect()[0]
print(item.id, item.payload.kind.value, item.trust.value, item.retention.value)
print(len(item.content_hash))
```

```{testoutput}
document-42 json untrusted optional
64
```

## Standard fields

| Field | Accepted record value | v0.1-series default and notes |
| --- | --- | --- |
| `id` | String | Generated UUID when omitted. Supply one for reproducibility. |
| `payload` | String, bytes, JSON-compatible value, payload mapping, or `Payload` | Missing payload becomes empty Text in the 0.1 series; explicit input is strongly recommended. |
| `mime_type` | String | Derived from payload kind. |
| `role` | `system`, `developer`, `user`, `assistant`, `tool` | `user` |
| `sources` | URI string, source mapping, `SourceRef`, or sequence | Empty. External packs reject provenance-free items. |
| `content_hash` | SHA-256 hex string | Computed. A supplied mismatch raises `SchemaError`. |
| `trust` | `trusted`, `untrusted`, `quarantined` | `untrusted` |
| `sensitivity` | `public`, `internal`, `confidential`, `restricted` | `public` |
| `retention` | `required`, `preferred`, `optional` | `optional` |
| `priority` | Number | `0.0` |
| `created_at` | ISO-8601 string or timezone-aware `datetime` | Current UTC time. Supply one for reproducibility. |
| `expires_at` | ISO-8601 string or timezone-aware `datetime` | No expiry |
| `parent_ids` | Sequence of strings | Empty |
| `merged_from_ids` | Sequence of strings | Empty |
| `metadata` | Mapping | Empty; underscore-prefixed keys are reserved for implementation details. |
| `truncatable` | Boolean | `False` |
| `min_tokens` | Non-negative integer | `0`; applies to opt-in Text truncation. |

Naive datetime strings passed through `from_records()` are interpreted as UTC. Constructing `ContextItem` directly requires timezone-aware datetime objects.

## Payload forms

```python
text = cx.Payload.text("hello")
json_payload = cx.Payload.json({"b": 2, "a": 1})
binary = cx.Payload.binary(b"\x00\x01")
reference = cx.Payload.reference(
    "s3://bucket/object",
    digest="sha256:abc",
    size=123,
)
```

- Text hashing normalizes Unicode to NFC and line endings to `\n`.
- JSON is serialized canonically with sorted keys before hashing.
- Binary hashes raw bytes.
- Reference hashes its digest when present, otherwise a normalized URI.
- Payload kind and MIME type are part of the hash.

Binary payloads can be written and restored, but cannot enter a 0.1-series `ContextPack`. See {doc}`roadmap`.

## Files and Arrow-compatible input

```python
frame = cx.CognitionFrame.read_jsonl("context.jsonl")
frame = cx.CognitionFrame.read_ipc("context.arrow")
frame = cx.CognitionFrame.read_parquet("context.parquet")
frame = cx.CognitionFrame.from_arrow(table)
```

Use `write_jsonl()`, `write_ipc()`, and `write_parquet()` for the inverse operations. Arrow IPC, Parquet, `to_arrow()`, and `from_arrow()` require the `arrow` extra. The Arrow payload is a struct containing nullable text, JSON, binary, and reference children plus a non-null kind discriminator.

## Source plugins

A `Source` provides a `load()` method returning records:

```python
class StaticSource:
    id = "static-v1"

    def load(self):
        return [{"id": "one", "payload": "hello", "sources": ["app://static"]}]

frame = cx.CognitionFrame.from_source(StaticSource())
```

External records default to `untrusted`. Set `trusted` only after the application has authenticated the source and is authorized to make that assertion.