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

CardEventBus

Process-wide fan-out bus. Subscribers are registered once at startup (from ALC_CARD_SINKS) and stored behind a Mutex so that tests can swap them out via replace_subscribers_for_test without losing the singleton identity.

Comparison

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

FileCardStore

File-backed implementation of CardStore.

FileCardSubscriber

A subscriber that mirrors events to a local directory using the same two-tier layout as FileCardStore:

FindQuery

Query parameters for find.

LastError

Most recent delivery failure for a single subscriber. Exposed via SubscriberHealthRow.last_error in the alc_stats JSON snapshot.

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.

PerSubscriber

Per-subscriber counter state. Held inside SubscriberStats under a Mutex; snapshot clones the fields into an owned SubscriberHealthRow while the lock is held, so the lock window stays short.

SamplesQuery

Query parameters for read_samples.

SinkBackfillReport

Result of a card_sink_backfill run. One row per card the tool touched (classified as pushed / skipped / failed / pushed_samples). The failed entries carry the error message so an operator can triage read-only mounts etc.

SubscriberHealthRow

Snapshot row for a single subscriber, serialized directly into the alc_stats JSON output as one element of the card_sinks array.

SubscriberStats

Process-wide per-subscriber statistics, keyed by subscriber URI (the value returned by CardSubscriber::describe).

Summary

Summary row for alc.card.list().

Enums

CardEvent

A Card-level event emitted from the write path.

CardEventKind

Lightweight discriminant for CardEvent. Used as a HashMap key in SubscriberStats so that ok/err counters can be tracked per event kind without holding the full payload.

CmpOp

Single comparison operator.

LineageDirection

Walk direction for lineage.

Predicate

Parsed predicate tree.

Constants

SCHEMA_VERSION

Traits

CardStore

Storage backend for Cards.

CardSubscriber

A downstream backend that receives CardEvents in best-effort, serial fan-out order.

Functions

alias_list

List aliases, optionally filtered by pkg.

alias_list_with_store

List aliases from store. See alias_list for the default-store variant.

alias_set

Bind (or rebind) an alias to a Card.

alias_set_with_store

Bind an alias in store. See alias_set for the default-store variant.

aliases_to_json

append

Append new top-level fields to an existing Card.

append_with_store

Append to a Card in store. See append for the default-store variant.

card_sink_backfill

Backfill one subscriber (sink URI) from the primary store.

card_sink_backfill_with_store

card_sink_backfill with an injectable CardStore. Tests drive this directly against a tempdir-backed FileCardStore to avoid touching the user’s real ~/.algocline/cards/.

create

Main create entry. Returns (card_id, absolute_path).

create_with_store

Create a new Card backed by store. See create for the default-store variant.

eval_predicate

Evaluate a predicate tree against a full Card JSON.

event_bus

Return the process-wide CardEventBus singleton, initializing it on the first call from the ALC_CARD_SINKS environment variable.

find

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

find_with_store

Filter/sort Cards from store. See find for the default-store variant.

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.

get_by_alias_with_store

Resolve an alias in store. See get_by_alias for the default-store variant.

get_with_store

Read a Card from store. See get for the default-store variant.

import_from_dir

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

import_from_dir_with_store

Import Card files into store. See import_from_dir for the default-store variant.

init_event_bus

Eagerly initialize the bus. Idempotent and safe to call multiple times; intended for startup hooks (main.rs) so that subscriber registration tracing::info! lines are emitted at boot rather than on the first Card write.

lineage

Walk the lineage tree from q.card_id.

lineage_to_json

Render a LineageResult as JSON for the service layer.

lineage_with_store

Walk the lineage tree in store. See lineage for the default-store variant.

list

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

list_with_store

List cards from store. See list for the default-store variant.

parse_order_by

Parse an order_by JSON value. Accepts:

parse_where

Parse a where JSON value into a Predicate.

publish

Convenience wrapper: publish through the singleton.

read_samples

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

read_samples_with_store

Read samples from store. See read_samples for the default-store variant.

subscriber_stats_snapshot

Public entry point: snapshot of all process-wide subscriber stats. Wrapper around event_bus().stats().snapshot() so that downstream crates (notably algocline-app) do not need a handle to the CardEventBus singleton.

summaries_to_json

write_samples

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

write_samples_with_store

Write samples via store. See write_samples for the default-store variant.