@cooplux/datum

Local-first reference-data manager — init, add, validate, query, version, and status for CSV/JSON lookup tables, with Frictionless-style schema validation and content-hash (SRI sha256) fixity.

Reference data at rest only — computes no rates, makes no underwriting/pricing/ compliance/accuracy claims. datum stores and schema-validates tables; it decides nothing and certifies nothing. Validation receipts are labeled schema-shape + hash conformance only. The "CoopLux Ultra-Luxury Underwriting OS" is brand poetry; every functional surface here is literal.

Part of the CoopLux constellation (cli, plux, datum, enfilade, praxis).

Install / use

npx @cooplux/datum init            # scaffold datum.json + a generic reference set
# or
npm i -g @cooplux/datum && datum --help

Node ≥ 20. Zero network, zero process-spawn, zero credentials — chalk + commander only.

Commands

• datum init [dir] [--example <name>] — scaffold a datum.json and a neutral generic reference set (country, currency, and a shipping_zone decision table). Underwriting flavor is opt-in: datum init --example underwriting (still pure reference data). Refuses to clobber an existing datum.json.
• datum add <name> <file> [--format csv|json] [--decision] [--hit-policy unique] — register a CSV/JSON file as a new set. Schema is inferred as string fields (tighten by editing datum.json); content hash recorded.
• datum validate [set] [--json] [--force] — verify fixity + schema + rows and write datum-receipt.json (cooplux.datum.receipt.v1).
• datum query <set> [-w field=value ...] [--limit n] [--json] [--force] — query a set. Fixity is verified first; decision tables enforce their hitPolicy.
• datum version <set> [--list] [--json] [--force] — snapshot a set into .versions/; the content hash is the version identity. --list re-verifies snapshots (tampering self-detects).
• datum status [--json] — fixity health + set overview + dbt-seed boundary warnings.

Fixity — verified on every read

The SRI content hash of each set's canonicalized backing file is recorded in datum.json. query, validate, version, and status re-hash the file and compare. On mismatch datum fails closed (refuses to emit drifted data) with a loud warning; --force downgrades to loud-warn-and-continue and marks the data UNVERIFIED.

Hashing is over a canonical form (sorted-key JSON / normalized-LF CSV with a single trailing newline), so a Windows CRLF checkout or a JSON key reordering does not cry wolf. The recorded hash is also the version identity, so a tampered .versions/ snapshot self-detects.

Schema (Frictionless-style)

Field type: string | integer | number | boolean | date | enum. Constraints: required, unique, minimum, maximum, pattern, plus enum values. Schemas compile once per set and are reused across every row.

Decision-table sets carry a DMN hitPolicy (v0.2.0: unique — a query matching more than one row is an error).

Configuration

| Variable / flag | Purpose | Default | | --- | --- | --- | | --manifest <file> / DATUM_MANIFEST | path to datum.json | ./datum.json | | DATUM_AUTHOR | author recorded in version snapshots | OS username |

Conventions

Manifest tag cooplux.datum.manifest.v1; receipt tag cooplux.datum.receipt.v1 (datum-receipt.json in cwd + version snapshots). Env prefix DATUM_. One content-hash dialect across the family: SRI sha256-<base64> over canonicalized content. See ATTRIBUTIONS/NOTICE.md for the specs emulated (Frictionless, DMN, SLSA/in-toto, Dolt, SRI).

License

MIT © Dane Anthony Cooper