Module card 

Card storage — immutable run-result snapshots.

A Card is a frozen record of a strategy run: identity, parameters, model, scenario, aggregate stats, and (optionally) per-case detail. Cards are immutable — once written they are never modified, only annotated via additive append. Mutable aliases point to a Card and can be rebound freely.

Design principles

1. Minimal REQUIRED, maximal OPTIONAL — v0 needs only 4 fields; lightweight “ran this pkg” records and heavy optimize snapshots share the same schema.
2. Immutable append-only — no overwrite, no delete. New data is added via append (new top-level keys only) or by creating a new Card with a fresh card_id.
3. Two-tier storage — TOML for human-readable aggregate, JSONL sidecar for machine-parseable per-case detail.
4. File-primary — files are the source of truth; in-memory state is cache. Cards can be copied, diffed, and version-controlled.

Storage layout (two-tier)

Tier	File	Content
Tier 1	~/.algocline/cards/{pkg}/{card_id}.toml	Aggregate scalars, decisions, identity, params
Tier 2	~/.algocline/cards/{pkg}/{card_id}.samples.jsonl	Per-case raw data (JSONL, write-once)

Tier 1 holds a shareable summary (a few KB). Tier 2 holds per-case detail ��� the engine does not interpret its columns; packages define their own schema.

Alias table: ~/.algocline/cards/_aliases.toml (global).

card_id naming

{pkg}_{model_short}_{compact_ts}_{hash6}

• compact_ts: YYYYMMDDTHHMMSS in UTC
• hash6: first 6 hex chars of DJB2 param fingerprint
• Example: cot_opus46_20260412T061500_a3f9c1

v0 schema (frozen)

REQUIRED (minimum valid Card)

Field	Type	Example
schema_version	string	"card/v0"
card_id	string	"cot_opus46_20260412T061500_a3f9c1"
created_at	string (RFC 3339)	"2026-04-12T06:15:00Z"
[pkg].name	string	"cot"

OPTIONAL (auto-injected where possible)

Section	Fields
[pkg]	version, category, source, source_ref, source_sha
[runtime]	alc_version, lua_version, host_os, git_sha
[model]	provider, id, id_short, cutoff
[params]	Free-form ctx snapshot; param_fingerprint for DJB2 hash
[strategy_params]	Strategy-tunable parameters surfaced for sweeps / optimizers (e.g. alpha, temperature, depth). Free-form, but where-queryable as a first-class section
[scenario]	name, source, case_count, grader
[stats]	pass_rate, mean_score, std, median, min, max, n
[stats.by_bucket]	Disaggregated sub-bucket stats (array of tables)
[cost]	llm_calls, input_tokens, output_tokens, elapsed_ms, usd_estimate
[optimize]	target, search, rounds_used, top_k (for optimize Cards)
[metadata]	Free-form escape hatch. Recognized lineage conventions: prior_card_id (parent Card id), prior_relation (relation kind, e.g. "sweep_variant", "reflection_of", "derived_from")

Lua API (alc.card.*)

Function	Description
create(table)	Write new Card (Tier 1). Returns { card_id, path }
get(card_id)	Read Card by id. Returns table or nil
list(filter?)	List Cards as summaries (newest first)
find(query?)	Prisma-style where DSL + dotted-path order_by + offset/limit
append(card_id, fields)	Additive-only annotation (new keys only)
alias_set(name, card_id, opts?)	Pin mutable alias
alias_list(filter?)	List aliases
get_by_alias(name)	Resolve alias → full Card
write_samples(card_id, samples)	Write Tier 2 sidecar (write-once)
read_samples(card_id, opts?)	Read Tier 2 with where filtering + offset/limit paging
lineage(query)	Walk ancestry/descendants via metadata.prior_card_id

Structs

Alias

Comparison

One parsed comparison: path points at a nested field, op + value describe how to compare it.

FindQuery

Query parameters for find.

LineageEdge

One edge in the lineage result (child → parent, always).

LineageNode

One node in the lineage result.

LineageQuery

Query parameters for lineage.

LineageResult

Full lineage walk result.

OrderKey

Parsed sort key: path with optional descending flag.

SamplesQuery

Query parameters for read_samples.

Summary

Summary row for alc.card.list().

Enums

CmpOp

Single comparison operator.

LineageDirection

Walk direction for lineage.

Predicate

Parsed predicate tree.

Constants

SCHEMA_VERSION

Functions

alias_list

List aliases, optionally filtered by pkg.

alias_set

Bind (or rebind) an alias to a Card.

aliases_to_json

append

Append new top-level fields to an existing Card.

create

Main create entry. Returns (card_id, absolute_path).

eval_predicate

Evaluate a predicate tree against a full Card JSON.

find

Filter/sort Cards across the store using the where DSL.

get

Read a Card by id. Returns None if not found.

get_by_alias

Resolve an alias name to its bound Card and return the full Card JSON.

import_from_dir

Import Card files from source_dir into ~/.algocline/cards/{pkg}/.

lineage

Walk the lineage tree from q.card_id.

lineage_to_json

Render a LineageResult as JSON for the service layer.

list

List cards. pkg_filter = Some("name") restricts to that pkg subdir.

parse_order_by

Parse an order_by JSON value. Accepts:

parse_where

Parse a where JSON value into a Predicate.

read_samples

Read per-case samples from {card_id}.samples.jsonl.

summaries_to_json

write_samples

Write per-case samples to {card_id}.samples.jsonl (write-once).