packstruct docs

The pack catalog

The normative contract lives in SPEC v1 and the Entry profiles page. This page is the live catalog: what ships in packs/public/, and which family hosts load the same grammar. The branded version is at packstruct.creadev.org/packs.

A pack is a directory under packs/public/<name>/ carrying a frozen pack.json (schemaVersion 1, kebab-case name matching the directory, a relative entry that must exist, optional armedByKey, optional requires) plus the entry module it names.

What ships here

packstruct carries one pack of its own, and it attacks the linter. packstruct-lint-shapes holds four attacks, one contract each:

Attack Profile What it proves
hostile-manifest-fuzz scenario Every malformed pack.json answers in-bounds: parseable verdict JSON, violations carried with {pack,norm,message}, exit 0/1, never 5xx, never a deep stack trace.
entry-path-containment scenario Entry values escaping the pack dir (traversal, absolute, file URL, null byte) are flagged by the entry norm, and an outside file that happens to exist never silences the refusal.
over-strict-drift-canary scenario Spec-allowed shapes (extra manifest keys, empty armedByKey) are never over-strictly flagged. The linter is strict only against spec norms.
clean-pack-canary scenario The happy path stays clean: a well-formed pack lints exit 0, so a green run is earned, not assumed.

A new EXPLOITED verdict, or a regression of any recorded row, fails CI.

The family hosts

One manifest surface, two execution profiles. A host declares which profile it loads; the manifest never forks. Every host below lints its packs through the same packstruct lint --deep.

Host Profile Packs What it loads packs for
crashtest scenario 9 Hostile scenarios against a transport, isolated; the dogfood double every member’s crashtest.config.js drives.
vant scenario 24 The agent OS measures its own defenses: kernel, mcp, relay, brain, and walls, 290 declared ids.
gistory scenario 1 The chain-relay dialect pack attacks the push/pull sync surface in-process.
prestruct scenario 1 prestruct-proxy attacks the HTTP render proxy pair (VPS + Worker) over the real wire.
poststruct check 12 Pure-reading verifiers over files on disk: one shape pack per SSG, plus eyes-reference.
govstruct check 14 The source-consistency profile: check packs over its own tree, plus a hostile member-block lane over govstruct lint.
eyestruct check 6 The capture and canon lanes (eye-shapes, eye-text-leg, eye-ci-gate, eye-adapter, eye-bundle, eye-spa-dist).
monoforge check 1 forge-shapes verifies a stamped tree ships its receipt and holds the truth-slot law.

See the Showcase page for the full crosslink board, including the dogfood pack that attacks the linter itself.

Running a packdir

npx packstruct lint packs/ --deep     # manifest + entry + id-census grammar
npx packstruct lint packs/ --json     # machine-readable verdict
npx packstruct audit-conformance .    # verify a host loader honors the spec

The conformance harness runs bundled verdict-claiming fixture packs against a host’s own loader command and checks pass/fail as promised, so the implements: packstruct@1 pin is verifiable rather than honorary. See the Conformance harness page for the case list.