Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Integrity & audit commands

These commands use physics-inspired names (nucleate, evolve, decay, spore, …). New to the vocabulary? See The physics vocabulary.

cs verify

Verify — walk a molecule's event hash chain (plumbing v2)

Usage: cs verify [OPTIONS] [MOLECULE_ID]

EXAMPLES: cs verify # walk the event hash chain cs verify --strict # also replay gates

Proof-of-work chain integrity check.

Arguments:

  • <MOLECULE_ID> — Molecule ID (or prefix) whose proof-of-work chain should be verified.

    Optional when --federation is set — the federation provenance scan is a fleet-wide audit and does not target a single molecule.

Options:

  • --no-replay — Skip gate replay (shell/native step re-execution). Artifact hash check and event chain check still run

  • --step <N> — Verify the briefing seal for a specific zero-based step index.

    When omitted, the most recent briefing seal (if any) is checked against the current briefing.md. When specified, the corresponding entry from MoleculeData::briefing_seals is used. If no seal exists for the requested step, the check is reported as SKIP (inconclusive), never as FAIL.

  • --federation — Scan the fleet-wide event log for cross-galaxy events missing federation provenance (ADR-105, I9' machinery).

    When set, walks <state_dir>/events.jsonl and reports every cross-galaxy event whose federation_provenance is None:

    • MergeDispatched / MergeCompleted whose molecule_id or branch carries a foreign galaxy alias (Oracle B subject-mark per ADR-105 §D3). - ChronicleAdded whose cites_galaxies mentions a non-cosmon peer (Oracle B'' delegation-dispatched per ADR-105 §D3). - AdrInscribed whose cites_galaxies mentions a non-cosmon peer (same Oracle B'' channel for ADR-grade citations).

    Missing provenance is a hard FAIL — the federation discipline is detect-on-write, cs verify --federation is the audit oracle.

    The flag stacks with molecule_id: when both are given, the scan is restricted to the molecule's local events.jsonl. When molecule_id is omitted, the fleet-wide log is scanned.

  • --legacy-tolerate-before <DATE> — Tolerate cross-galaxy events emitted before a specific date that lack federation provenance.

    Format: ISO8601 date (e.g. 2026-05-19). Events whose envelope timestamp is strictly before the date are downgraded from FAIL to SKIP with a tracing::warn!-equivalent detail line. Only meaningful in combination with --federation.

    Default: not set — every cross-galaxy event without provenance is a hard FAIL. ADR-105 §"Backfill discipline" recommends option (a) (backfill the field by reading the existing citation format); this flag is option (b), the legacy-tolerate escape hatch for the migration window.

  • --invariants — Check structural state-machine invariants over molecule rows.

    Currently a single invariant is enforced: archived ⇒ status.is_terminal() — an archived molecule must carry a terminal status (Completed or Collapsed). A row with {archived: true, status: running} is a ghost: it was torn down out-of-band (e.g. cs done --force on a never-completed molecule) without terminalizing its status, so it keeps rendering as live work.

    Detection only — cs verify --invariants never mutates state; it exits non-zero when any violation is found. To heal the on-disk rows (rewrite status → Collapsed), run cs reconcile --heal-invariants.

    Like --federation, the flag stacks with molecule_id: with a molecule given, only that row is checked; without one, every molecule in the fleet is swept (the galaxy-wide audit).

cs verify-trace

verify-trace — replay events.jsonl against the scheduler spec (Phase 3 CI gate)

Usage: cs verify-trace [OPTIONS] <TRACE>

Arguments:
  • <TRACE> — Path to the events.jsonl trace. Use - to read from stdin
Options:
  • --skip-unknown — Tolerate lines whose shape is not recognised by EventV2 or the legacy migration helper — they are counted and skipped instead of failing the whole replay. Required when replaying historical fleet logs that pre-date the canonical schema

cs verify-graph

verify-graph — Tarjan SCC check on the subgraph induced by a typed relation (substrate, ADR-016)

Usage: cs verify-graph [OPTIONS]

EXAMPLES: cs verify-graph --relation blocks # check the Blocks subgraph for cycles cs verify-graph --relation refines # check Refines (cycles permitted, reported as WARN) cs verify-graph --all # every registered relation cs verify-graph --all --json # NDJSON, one row per relation

Tarjan SCC check on the subgraph induced by a typed MoleculeLink relation. Substrate primitive for the organization-twin programme. Read-only — does not mutate state.

Exit code: 0 every DAG-required relation is acyclic 1 at least one DAG-required relation contained a cycle Cycles in non-DAG-required relations (e.g. refines) are reported but do not flip the exit code.

Options:
  • --relation <KIND> — Single relation to check (e.g. blocks, decay-product, merged-from, refines, refutes). Mutually exclusive with --all
  • --all — Check every registered relation kind in turn

cs spec-audit

spec-audit — ledger audit against the TLA+ spec (catches c1cb bypass_merge)

Usage: cs spec-audit [OPTIONS]

EXAMPLES: cs spec-audit # default: cosmon-run × events.jsonl cs spec-audit --fleet default # explicit fleet (advisory today) cs spec-audit --events path/to/events.jsonl cs spec-audit --json # NDJSON drift report cs spec-audit --no-git-probe # skip the c1cb merge-topology probe

Multi-spec: cs spec-audit --spec mycelial-gate --events .cosmon/state/attestor-events.jsonl cs spec-audit --spec attestor-graph --events .cosmon/state/attestor-events.jsonl cs spec-audit --spec witness-freshness --events .cosmon/state/attestor-events.jsonl cs spec-audit --spec noogram/specs/MycelialGate.tla # path also accepted

Ledger audit: replays events through the TLA+ spec and flags drifts. For --spec cosmon-run (default), drifts include c1cb bypass_merge and disabled-action-fired. For the noogram specs, drifts are emitted as spec_invariant_violation with stable (spec, invariant) tags — see crates/cosmon-core/src/attestor_audit.rs for the full taxonomy and docs/specs/attestor-events.schema.json for the AttestorEventV1 NDJSON schema. One-shot, not a daemon. Exit 0 if clean, 1 if any drift is found.

Options:

  • --fleet <FLEET> — Fleet id whose ledger should be audited. Defaults to the fleet resolved from the walk-up config (default for single-fleet projects). The fleet id is advisory today — the canonical events.jsonl lives at .cosmon/state/events.jsonl regardless of fleet — but the flag is accepted so future multi-ledger layouts stay backward-compatible

  • --spec <SPEC> — Which spec to audit against. Defaults to cosmon-run (historical behaviour). Other accepted values: mycelial-gate, attestor-graph, witness-freshness. A path to a .tla file is also accepted; the basename (snake/Camel-case normalised) is looked up in the registry

    Default value: cosmon-run

  • --events <PATH> — Explicit path to the events file to audit. Overrides --fleet and the walk-up state-dir discovery. The expected format depends on --spec:

    • cosmon-run → .cosmon/state/events.jsonl (EventV2 envelopes). * Noogram specs → .cosmon/state/attestor-events.jsonl (AttestorEventV1 envelopes, see cosmon/docs/specs/attestor-events.schema.json).

  • --repo <PATH> — Repository whose branch topology should be probed for the c1cb out-of-band check. Defaults to the current working directory. Pass --no-git-probe to disable the probe entirely (useful when git is not available, e.g. inside CI sandboxes). Only meaningful when --spec cosmon-run

  • --no-git-probe — Disable the git-topology probe. When set, the audit still flags disabled-action-fired drifts but does not emit bypass_merge findings. The switch exists so the audit stays useful in environments without git (containers, strict sandboxes). Only meaningful when --spec cosmon-run

  • --target-ref <REF> — Target branch for the merge-topology probe. Defaults to origin/main; pass main to check the local branch when no remote tracking is configured. Only meaningful when --spec cosmon-run

    Default value: origin/main

cs release-audit

release-audit — dry-run drift detector for the public distribution (analogue of reconcile --check)

Usage: cs release-audit [OPTIONS]

EXAMPLES: cs release-audit --dry-run # simulate the release chain on the live tree cs release-audit --dry-run --json # machine report for CI / jq cs release-audit --repo /path/to/clone # audit an explicit repo root

Dry-run drift detector for the public cosmon distribution — the release-side analogue of cs reconcile --check.

PRIMARY MEMBRANE — deny-by-default allowlist (ADR-127). Ship nothing except positively-cleared paths: every tracked, non-purged path must carry a per-path permit in .cosmon/release-allowlist.toml, or it is a path-not-permitted regression. A new confidential file is caught BY CONSTRUCTION (new = unpermitted = refused), instead of slipping past a frozen denylist. Content-bound permits (with a blake3 seal) go permit-stale when the file changes — cleanliness-now, not freshness-at-t0. The membrane is ARMED by the presence of the allowlist file; absent it, the audit runs in legacy denylist mode and says so LOUDLY (a warning, never a silent pass). Bless paths with scripts/release/ bless-allowlist.sh (a separate tool — the audit stays read-only).

CONTENT BACKSTOP — the legacy detectors still run on permitted files:

  • a private-sibling path dependency reappeared (the claudion vendoring case);
  • a client name reintroduced in a tracked path the rename chain misses;
  • a structural string the chain does not scrub (operator homeserver, etc.);
  • a live instance oidc-identity.toml re-tracked under a non-purged path. The confidential detector literals live in the PRIVATE, purged-from-release .cosmon/release-rules.toml (Bucket-3) — not in the shipped source, so the detector is no longer its own leak. Absent that file the backstop is inert and the audit warns.

Exit 0 if the distribution is clean, 1 if it would regress. One-shot, not a daemon; reports, does not remediate. See ADR-127.

The audited repo may exempt structural strings that are intentionally public in it (e.g. a maintainer-contact domain) via .cosmon/release-audit.toml, each with a mandatory justification — the same exemption list its own forbid-strings CI gate should read, so both referees agree.

Options:
  • --dry-run — Simulate the release-resync transformation chain against the live working tree (no scratch clone) and report regressions. This is currently the only mode; the flag is accepted so the documented invocation cs release-audit --dry-run is exact
  • --repo <PATH> — Repository root to audit. Defaults to the toplevel discovered by git rev-parse --show-toplevel from the current directory

cs notarize

Notarize — issue or verify an operator-signed attestation for a molecule (ADR-056)

Usage: cs notarize [OPTIONS] [MOLECULE_ID] [COMMAND]

Subcommands:
  • issue — Issue a new seal — build the commitment, sign with Ed25519, write mint.json
  • verify — Verify an existing seal — full Ed25519 + canonical commitment bytes
Arguments:
  • <MOLECULE_ID> — Legacy: molecule ID (or prefix) to notarize. Equivalent to cs notarize issue <MOLECULE_ID>
Options:
  • --dry-run — Legacy: skip signing — compute and print the commitment only
  • --key <PATH> — Legacy: path to an Ed25519 secret-key file
  • --cosmon-version <COSMON_VERSION> — Legacy: override cosmon_version in the commitment

cs notarize issue

Issue a new seal — build the commitment, sign with Ed25519, write mint.json

Usage: cs notarize issue [OPTIONS] <MOLECULE_ID>

Arguments:
  • <MOLECULE_ID> — Molecule ID (or prefix) to notarize
Options:
  • --dry-run — Skip signing — compute and print the commitment only. Default when --key is not provided
  • --key <PATH> — Path to an Ed25519 secret-key file (raw 32 bytes or 64-char lowercase hex). Required for a real notarization
  • --cosmon-version <COSMON_VERSION> — Override cosmon_version in the commitment (defaults to the crate-level CARGO_PKG_VERSION). Mostly useful for tests

cs notarize verify

Verify an existing seal — full Ed25519 + canonical commitment bytes

Usage: cs notarize verify <PATH>

Arguments:
  • <PATH> — Path to a seal JSON file (e.g. <mol_dir>/mint.json or theater/pitch-*/notary/slides.notarization.json)

cs witness

Witness — Layer-2 witness-quorum seal for stress-test molecules (ADR-085 §3)

Usage: cs witness <COMMAND>

EXAMPLES: cs witness attest # default prior path: <mol_dir>/prior.md cs witness attest --prior-path prior.md # explicit prior file cs witness attest --witness-id ci-bot # deterministic identity (LaunchAgent/CI) cs witness attest --json # NDJSON for scripting

Layer-2 witness-quorum seal for stress-test molecules (ADR-085 §3). A separate cosmon agent reads the prior file's bytes, computes its BLAKE3 hash, and emits a SealAttested event distinct from the molecule's tackler session. Refuses if the molecule's class is not stress-test, or if the witness identity matches the tackler's session_name (cheap structural-independence check).

SEE ALSO: cs notarize (operator Ed25519 attestation, ADR-056).

Subcommands:
  • attest — Attest a stress-test molecule's prior seal — emit SealAttested

cs witness attest

Attest a stress-test molecule's prior seal — emit SealAttested

Usage: cs witness attest [OPTIONS] <MOLECULE_ID>

Arguments:
  • <MOLECULE_ID> — Molecule ID (or prefix) to attest. Must be a stress-test class molecule (ADR-085 §1); standard-class molecules are refused so a witness cannot accidentally lend weight to a tactical deliberation
Options:
  • --prior-path <PATH> — Path to the operator-sealed prior. Defaults to <molecule_dir>/prior.md. The witness opens this file, computes its BLAKE3 hash, and records that hash in the EventV2::SealAttested::prior_b3 field. The witness never inspects the file's content beyond the bytes-to-hash transformation.
  • --witness-id <ID> — Override the witness identity. Defaults to the [cosmon_runtime::resolve_witness_id] heuristic ($TMUX first, then <host>-<pid>). Useful for LaunchAgent / CI invocations that want a deterministic identity

cs key

Key — manage the operator's Ed25519 notary key (generate, show)

Usage: cs key <COMMAND>

EXAMPLES: cs key generate # ~/.config/cosmon/operator.key (0600) cs key generate --output /tmp/dev.key # alternate destination cs key generate --force # overwrite an existing key cs key show # print pubkey hex of the default key

Generates a fresh Ed25519 secret (32 bytes of OS randomness, 64-char lowercase hex) at the path cs notarize --key already expects. Silent rotation is forbidden: without --force the command refuses to clobber an existing key file. For retirement / successor publication, see ADR-060 (cs rotate-key, deferred post-S4).

SEE ALSO: cs notarize (sign a molecule under the operator key), docs/guides/notary-operator-guide.md, ADR-056, ADR-060.

Subcommands:
  • generate — Generate a fresh Ed25519 operator key (32 bytes OS randomness, hex-encoded)
  • show — Print the public key (and its path) for an existing operator key file

cs key generate

Generate a fresh Ed25519 operator key (32 bytes OS randomness, hex-encoded)

Usage: cs key generate [OPTIONS]

Options:
  • --output <PATH> — Destination path. Defaults to ~/.config/cosmon/operator.key
  • --force — Overwrite an existing key file. Without this flag, refuses to clobber any pre-existing key — silent rotation is forbidden (ADR-060 §Alternatives-rejected)

cs key show

Print the public key (and its path) for an existing operator key file

Usage: cs key show [OPTIONS]

Options:
  • --key <PATH> — Path to the operator key file. Defaults to ~/.config/cosmon/operator.key