FS.GG.Coord.Cli 0.82.0

FS.GG.Coord.Cli — the typed coordination engine

The schedulability model behind fsgg-coord, as one total function.

This is not a user-facing tool. scripts/fsgg-coord is the client you run; this is the engine it shells out to. You will normally never invoke it by hand.

What it is for

scripts/fsgg-coord was 4,000 lines of bash modelling a concurrent, transactional, budget-constrained domain in a substrate with no types, no Result, no atomicity, and whose default failure mode was to fail open — an error, an empty result, and a legitimate "no" were the same value. The defect record follows from the substrate: "is this item startable?" was computed in five places and agreed in none (#485), and the fail-open family (#266) has 51 children.

ADR-0034 moves that domain to a typed F# core. There is no bool in a verdict:

type Verdict<'a> = Green of 'a | Red of string list | NoVerdict of reason: string

type Schedulability =
    | Startable
    | WrongStatus of BoardStatus        // NoStatus is its own case, not a Backlog
    | IssueClosed                       // the issue outranks the board column
    | NoTouchSet                        // an OMISSION
    | DeliberatelyNoTouchSet            // `Paths: none` — a DECISION. Not the same fact.
    | UnusableTouchSet of tokens: string list
    | BlockedBy of Blocker list         // resolved = CLOSED *or MERGED*
    | HeldBy of WorkerId
    | HeldByLiveWork of WorkerId * pr: int   // the lease lapsed; the WORK did not
    | OverlapsInFlight of (string * string) list
    | Undetermined of reason: string    // "I could not decide." NEVER green, never a silent skip.

It reads nothing

The engine performs no IO. No board, no issues, no network, no token. The client has already paid for the board scan and the claim markers by the time it decides, so it hands that state over on stdin and the engine decides from it:

fsgg-coord-engine decide < snapshot.json      # → a typed verdict per candidate, as JSON
fsgg-coord-engine decide --text < snapshot.json

That is what makes the engine pure and reproducible: the verdict is a total function of the snapshot, so the same board state always decides the same way, and a test can state the answer rather than stand a live fixture up — no second scan of the 5,000 pt/hr budget the whole fleet shares (#418).

It is the client now

scripts/fsgg-coord is the ADR-0034 §4.4 shim (ADR-0040 Phase D): it resolves this compiled engine and execs it, passing argv through unchanged. The ~7,000-line bash implementation, and the shadow that once ran both engines side by side and returned bash's answer, are gone — this engine is the one and only coordination client.

Exit codes

These are the engine's, not the client's — the client translates them.

An unreachable answer is not a negative one. That rule is the whole point.

Telemetry, qualification, and roadmap closure (0.82.0)

The engine owns the deterministic telemetry boundary. telemetry usage collect codex|claude emits the stable runtime-usage CSV (or canonical JSONL), including exact model and coherent tool versions; --append retains one CSV header and ignores an already-recorded response identity. telemetry lifecycle export-comments|seal-successor|validate elects GitHub-comment order, seals the SHA-256 chain, and requires immutable --usage and optional --history-report receipts before measured terminal evidence is accepted. telemetry summarize, telemetry critique validate, and telemetry feedback validate are read-only. telemetry qualification validate|run validates or executes the closed exact-checkout qualification contract. telemetry qualification obligation render|verify emits the existing guarded, current-head fsgg:delivery-obligation(s) grammar or verifies a strict GitHub PR comment readback through the same delivery parser, with URL and comment id agreement; it introduces no second marker authority.

roadmap close inspect|render|verify consumes an evidence manifest whose relative artifact paths bind an accepted unit receipt, delivery receipt, schema-v3 critique, schema-v2 feedback report and audit, feedback binding, cycle update, and one or more check receipts. Every machine receipt is canonical and self-digested; all unit, head, cycle, report, audit, claim, and check identities are joined before rendering. render prints only a candidate document. verify additionally requires --source-roadmap, authenticates its --source-digest, and proves that the candidate changed no bytes outside the marked unit block.

Version 0.81.0 established the publish-before-adopt boundary. Current callers and cycle-ledger provider validation use these compiled commands directly; the frozen Python differential corpus remains an independent test oracle, while no Python compatibility helper is packaged or invoked at runtime.

License

MIT