Module card 

Card storage — immutable run-result snapshots.

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.

v0 schema (frozen)

REQUIRED fields: schema_version, card_id, created_at, [pkg].name. Everything else is OPTIONAL and auto-injected where possible.

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?)	Query with sort / filter / 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 offset/limit paging

Structs

Alias

FindQuery

Query parameters for find. All filters are optional.

Summary

Summary row for alc.card.list().

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).

find

Filter/sort Cards across the store.

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}/.

list

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

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).