# Core concepts

## Context items

A `ContextItem` is one typed unit of model input. It combines content with the information needed to make a packing decision: identity, role, provenance, trust, sensitivity, retention, priority, time bounds, and lineage.

Its payload can be Text, canonical JSON, Binary, or Reference. Text, JSON, and Reference are packable in the 0.1 series. Binary is storage and round-trip only.

## Frame, pack, and manifest

- `CognitionFrame` holds context records and an immutable transformation plan.
- `ContextPack` contains the items selected for one model call.
- `PackManifest` explains that decision in machine-readable form.

Calling `filter()`, `select()`, `with_columns()`, `join()`, `sort()`, `limit()`, `dedupe()`, `rank()`, `redact()`, `quarantine()`, or `demote()` returns a new frame. Call `collect()`, `to_records()`, or `pack()` to execute an ordinary frame plan. In the 0.1 series, `group_by().agg()` is the exception and evaluates immediately.

## Provenance, trust, and sensitivity

`sources` records where content came from. Trust and sensitivity are separate assertions: a trusted internal policy can still be restricted, while public web content can be untrusted but non-sensitive.

`untrusted` does not mean automatically blocked. It means the application has not asserted that the content is trusted. Use a boundary policy, `quarantine()`, or a custom `Policy` when untrusted content must be rejected.

## Retention

`required` items cannot be dropped, `preferred` items are considered before optional items, and `optional` items compete by rank, priority, token cost, and a deterministic ID tie-break. Marking an item required is a contract, not a ranking hint.

## Lineage

Transformations preserve content hashes and parent identifiers. Exact deduplication aggregates sources and applies conservative trust, sensitivity, retention, and expiry rules. The resulting manifest records merge decisions and metadata conflicts.

## Determinism

Cognoxium is reproducible for the same **ordered** records, explicit values, settings, token-profile fingerprint, and plugin fingerprints. Selection preserves original conversational order. Reordering the input can therefore reorder the pack.

For strict reproducibility, provide stable `id` and `created_at` values. Constructor defaults use a random UUID and the current time when those fields are absent.