Metadata-Version: 2.5
Name: cell-ledger
Version: 0.1.0
Summary: A content-addressed ledger for parameter-space experiments
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: ruamel-yaml>=0.18
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# Cell Ledger

A standalone experiment-grid ledger project.

**Cell Ledger — a content-addressed ledger for parameter-space experiments**

Chinese working title: **experiment-grid ledger** (transliterated)

It serves research work but belongs to no specific research repository. The tool's core objects are:

```text
Family (immutable)
  -> global conditions and open variable axes
  -> Cell (declarable in advance, may stay empty)
  -> multiple independent Reports
```

## Confirmed Design Directions

- The CLI is the core entry point; the local web page is only a viewing component.
- Authoritative records use reviewable text; large artifacts such as checkpoints, deltas, and logs stay external.
- A Family's global conditions cannot be modified after creation; changing global conditions creates a new Family, and a parent can be recorded.
- The same variable Cell allows multiple independent runs (such as reruns after failure); runs never overwrite each other. Appending a new seed declares a new Cell on the seed axis.
- Cell is an independent first-class object; an empty Cell with no Reports can also exist.
- Family, Cell, and Report are stored separately and addressed separately; a Cell computes its identity from `family_hash + typed axis assignments`.
- Each run is an independent fact and never overwrites other runs; failed runs are kept too.
- Family and Report are content-addressed, stored, and hash-named separately.
- A Report's body must record the `family_hash` it belongs to.
- A tag can attach to a Family or a Report, with a detailed name and note; a tag does not modify the body, so it does not change the hash.
- The tool does not automatically decide whether evidence is sufficient; appending a seed value is just a new Cell on an open value domain, with no need to disguise it as part of the original plan.

## Axes and Cells

A Family fixes the **declaration of variable axes**, not a list of every possible value up front. An axis's value domain can grow openly: for example, later adding `K=16` or `optimization_seed=11` just creates a new Cell within the same Family and does not change the existing family hash. Only changing the meaning of an axis, the global conditions, or the training protocol creates a new Family.

**Every dimension that determines a run's scientific identity is an axis**, and together they form the Cartesian product:

```text
axes: K, split_ratio, threshold_group, subset_line, optimization_seed, W0_repeat
```

`optimization_seed` is an ordinary axis: reproducibility requires the seed to be a first-class, addressable coordinate just like any other condition, entering cell_hash and the matrix expansion. The same holds for `W0_repeat`; the axis exists unless the W0 checkpoint is fixed in the Family as a global condition.

A Cell's identity consists of `family_hash` plus typed axis assignments (including the seed). If an axis value references frozen material, use the material's manifest hash instead of just a mutable name.

Statistical aggregation across seeds (mean ± variance) is a **query view**: group by the remaining axes other than the seed; it does not enter the identity model.

## Three-Layer Object Model

### Family

A Family defines an immutable set of research conditions:

- the research question;
- global model, data version, training protocol, and tokenizer;
- declarations of open variable axes;
- `parent_family_hash`;
- notes recorded at creation.

A Family is not modified directly after creation. When global scientific conditions change, create a new Family and record which Family it derives from.

### Cell

A Cell defines one concrete coordinate in the Family's variable space:

```yaml
family_hash: <family_hash>
axes:
  K: 4
  split_ratio: "70/30"
  threshold_group: strict
  subset_line: <subset_manifest_hash>
  optimization_seed: 11
```

The above is a conceptual sketch (map-shaped input syntax). A Cell is an independent, addressable, queryable object. It can be created before any Report runs, so the full matrix can be declared first and then filled in Cell by Cell. An empty Cell is not a failure and not a missing object; it is a declared condition that has not yet produced a Report. For the authoritative on-disk format (envelope + typed axis triples), see DESIGN.md, "Object File Format".

Every dimension that determines a run's identity, including `optimization_seed`, is an axis and enters cell_hash. Multiple runs of the same Cell are independent facts under exactly the same conditions (such as reruns after failure) and never overwrite each other.

A Cell must at least distinguish these states:

```text
declared       declared, no Report yet
running        a run is in progress
completed      at least one successfully sealed Report
failed         has failed or aborted Reports, but no successful one yet
```

Status is a view derived or recorded from the Cell's declaration and its Report set; a rerun must not overwrite historical Reports.

### Report

A Report is the independent fact of one actual run:

```yaml
report_hash: <report_hash>
family_hash: <family_hash>
cell_hash: <cell_hash>
status: completed            # completed | failed | aborted
outputs:
  - [metrics.json, sha256: <artifact_hash>]
```

The above is a conceptual sketch; for the authoritative format (header + body, with status as `outcome.status`), see DESIGN.md. One Cell can own multiple Reports, for example reruns after failure. Adding a new seed is a new Cell on the seed axis; it does not modify the Family and does not overwrite any existing success or failure record.

## Record Model

```text
Family
  └── family_hash
        └── Cell
              └── cell_hash
                    └── Report
                          └── report_hash + family_hash + cell_hash
```

For example, a study may use these as variable axes:

```text
K
split_ratio
threshold_group
subset_line       # axis: references a subset manifest hash
optimization_seed # axis: ordinary axis, participates in the Cartesian product
W0_repeat         # axis, unless the W0 checkpoint is a global condition (fixed globally means no such axis)
```

If `seed=1,2,3` already exist as three Cells under `K=4 / split_ratio=70/30 / threshold_group=strict / subset_line=sha256:bbbb…` and evidence later proves insufficient, just append a new Cell with `seed=11`. There is no need to modify the original Family, and no need to disguise `seed=11` as part of the original plan: the axis value domain grows openly, and the matrix is exactly the set of declared Cells.

## Content-Addressing Rules

family/report hashes are computed from deterministic canonical content:

- field order is fixed;
- collection fields have explicit ordering rules;
- text is UTF-8;
- hash inputs exclude their own filename, generation time, and mutable paths;
- the canonical serialization format and hash algorithm version are written into the object;
- report content includes `family_hash`; family content does not include its own filename.

`parent_family_hash` is a required field on the family object: root Families write an explicit `null`, derived Families write the parent's hash. family/report hashes use a separate envelope to record the algorithm version; canonical content itself excludes its own hash, filename, and generation time. Temporary in-flight records can use a local `run_id`; the immutable `report_hash` is computed only after sealing.

An artifact's identity is determined solely by its artifact hash. Machine paths, mount points, and cache locations do not enter the report's canonical content; a report may additionally store unhashed relative paths or current machine paths as locating hints.

Illustrative storage layout:

```text
.cl/
├── config.yaml
├── families/
│   └── <family_hash>.yaml
├── cells/
│   └── <cell_hash>.yaml
├── reports/
│   └── <report_hash>.yaml
├── tags/
│   └── <tag_hash>.yaml
├── manifests/
│   └── <manifest_hash>.yaml
├── blobs/
│   └── <blob_hash>.yaml
└── runs/                     # local in-flight state, not committed to Git
    └── <run_id>.yaml
```

The CLI assigns a Report to a Family only when the family and cell files exist, recomputed hashes match, and the report's copy of the axes is consistent; otherwise the Report is treated as an orphan **derived view** (at query/verification time, with no persistent marker) and is not automatically assigned to any Family.

A tag is an independent append-only record that can attach to a Family or a Report. The tag record itself has a content hash; appending the same target, name, and note must be idempotent. Revocation uses a new `revoke` tag pointing at the original tag instead of deleting history. Classifications that affect identity and analysis (such as preregistered, pilot, extension, actual run) must be canonical content fields on the report and cannot be expressed by tags alone.

Tags can also attach to a Cell, to mark for example `mainline-candidate`, `appendix`, `blocked`, or a manual note; a Tag does not change the body or hash of the Family, Cell, or Report.

## Frozen Implementation Decisions

Every item on the former "still to freeze before implementation" list has been decided; see DESIGN.md for the normative details:

- canonical serialization format and field type rules: a restricted YAML 1.2 subset on disk (never hashed) plus the hash basis `cjson/1` (a canonical JSON profile without floats, UTF-8 byte-order key sorting, and mandatory write-time round-trip assertions);
- typed cell key schema: a closed 7-type vocabulary (`int / str / enum / bool / ref / int_list / str_list`), no floats, no maps, no nesting; the cell body is the coordinate and the hash input, permanently frozen;
- code version hash definition: the manifest's content-inventory hash is the identity (git-independent, dirty-safe), vcs facts (system/commit/clean) go into the hashed body, and the branch/remote/path/dirty inventory becomes an unhashed annotation;
- data root and record root configuration: the record root is fixed to the in-project `.cl/` directory (like `.git`, located by searching upward from the current directory); `<artifact_root>` is the external artifact area (bucketed by hash prefix, default `<project>/artifacts`, overridable in `.cl/config.yaml`);
- which text records enter Git: inside `.cl/`, `families/`, `cells/`, `reports/`, `tags/`, `manifests/`, `blobs/`, and `config.yaml` go into Git; `.cl/runs/` local state, artifact bytes, and derived files do not.

Object files uniformly use a two-layer structure: header (`envelope` + `id` + `annotations`, not hashed) + body (the sole hash input); algorithm/canonical/schema versions are recorded in the envelope, and sealed objects are never rewritten.

## Research-Repository Boundary

This project only records and views experimental facts. A concrete research repository owns its own model, training, data processing, and experiment programs, and supplies configuration, code, data, and artifact hashes to the Reports.

For now, no study-specific training logic is implemented here, and no research repository is embedded as a subdirectory of this project.

## Quick Start (0.1.0)

Install in editable mode from the repository root, then walk through a minimal closed loop in an empty directory (everything after `#` is explanation and real output):

```bash
pip install -e .          # run from the cell-ledger repository root

cell-ledger init          # create the .cl/ ledger in the current directory
# initialized ledger at /tmp/opencode/m7-smoke/.cl

cell-ledger family new --def - <<'YAML'   # read the family definition from stdin (syntax in DESIGN, "CLI Input Files")
type: family
name: split-threshold-k
question: effect of threshold policy on K-way splitting
parent_family_hash: null
global:
  model: wide-resnet
  tokenizer: bert-base-uncased
  protocol: "adamw lr=1e-3, 100ep, early-stop=5"
axes:
  - {name: K, type: int, doc: width multiplier}
  - {name: optimization_seed, type: int, doc: torch manual seed}
  - {name: split_ratio, type: str, doc: train/val split label}
  - {name: threshold_group, type: enum, values: [loose, strict]}
YAML
# family sha256:2f91ca9c6f0fa89df4708db4fabb81ccf38f31c6baebe8ad14b2ec406202b896

FAM=sha256:2f91ca9c6f0fa89df4708db4fabb81ccf38f31c6baebe8ad14b2ec406202b896
CELL=$(cell-ledger cell declare --family $FAM --axes K=4,optimization_seed=1,split_ratio=70/30,threshold_group=strict | cut -d' ' -f2)
# cell sha256:a10db041fe4015e9128e8db1b995999b79ae642d1f474dcd61c61b0d8885d7e7
RUN=$(cell-ledger report begin --cell $CELL | cut -d' ' -f2)   # open a run draft .cl/runs/<run_id>.yaml
# run run_7397c9209dfc (run_id randomly generated)

mkdir -p out && printf '{"final_loss": 0.0234, "best_epoch": 37}\n' > out/metrics.json   # simulate training output

cat > seal.yaml <<'YAML'                   # seal manifest: output files and small conclusions
outputs:
  - [metrics.json, out/metrics.json]
summary: {final_loss: "0.0234", best_epoch: 37}
YAML
cell-ledger report seal $RUN --status completed --artifacts seal.yaml   # seal into an immutable report
# report sha256:f718a43a2cbca17be23e384297e78ac1a2197031c3401f8267cf9ea847badbc6

cell-ledger cell list                     # status view: flips to completed automatically after seal
# a10db041fe40  K=4,optimization_seed=1,split_ratio=70/30,threshold_group=strict  completed  1

cell-ledger tag add --target cell/$CELL --name mainline-candidate   # append a tag; body and hash unchanged
# tag sha256:9b9770b99641d57a746d8b0140892870e8c6b6a10f494109629d6210ef4909ee

cell-ledger verify --full                 # recompute all hashes, verify bucketed artifact bytes
# ok family 2f91ca9c6f0f
# ok cell a10db041fe40
# ok report f718a43a2cbc
# ok tag 9b9770b99641
# ok manifest ba1e8c74adb9
# verified 5 objects
# --full: 1 artifacts checked
```

seal automatically collects a code manifest from the current directory and records it in the ledger. The family/cell definitions in the example above reproduce the same hashes; the run_id and the report and manifest hashes vary with the run time and directory contents. For the precise semantics of every command, see DESIGN.md, "Command Surface".
