packstruct docs

Family status dialect

packstruct adopted the family status dialect (family-status@1) so every member of the struct family can read every other member’s adversarial verdicts without a server, a dashboard product, or any trust beyond “the committing repo’s own CI ran its own battery”.

The contract, in three rules:

  1. every member serves a machine-readable status.json at the fixed path /status.json on its site;
  2. that file is generated, never hand-edited, by the member’s own web build, straight from the committed ledgers;
  3. every member’s status page reads the others’ files and renders their numbers (or their absence) honestly.

Humans read /status; agents and machines read /status.json. Both get the same numbers, because both read the same generated file.

The dialect: family-status@1

One JSON object per repo. schema is 1 and contract is the string family-status@1 - a reader that sees either field missing or renamed refuses and shows “not serving the dialect”, never a guessed row.

field shape meaning
schema 1 the dialect’s schema pin, additive-first
contract "family-status@1" the contract name a reader matches
repo string the GitHub repo the file describes
site URL the member’s own status page (where a human reads it)
docs URL the doc page explaining the member’s legs
asOf short sha the commit the generator last saw (worktree when no git context - never a fake sha)
legs array one row per adversarial leg, below
packs array one row per committed pack, below

A leg row:

field shape meaning
leg string the leg’s slug (crashtest, refusal-matrix in packstruct’s file)
verdict "PASS" or "RED" derived from the ledger rows: every case REFUSED, PASSED, or BOUNDED is a pass; anything else degrades the leg to RED
cases integer ledger row count for that leg
counts object verdict-tallied row counts, straight from the rows
ledger path the committed ledger file the numbers came from, repo-relative

A pack row:

field shape meaning
name string the pack slug (SPEC v1: kebab-case, equals the directory)
spec "packstruct@1" the grammar every family pack loads under
manifest path the pack’s pack.json, repo-relative
cases integer this pack’s ledger row count

That last table is the “understand each other’s packs” clause: because every family pack lives at packs/public/<name>/pack.json under the packstruct@1 grammar with ids namespaced by pack slug, a member’s packs array is directly readable by any other member with no bespoke understanding - the same normalization packstruct itself enforces.

packstruct’s legs

The refusal rules (what a reader may assume)

How packstruct serves it