schema

peasant-labs/schema

The canonical data / wire contract for peasant and the village transcript commons: one contract-only Go leaf module that every backend produces and every client consumes.

Use this module whenever code produces, validates, or consumes a peasant-labs wire payload. Go services import the canonical structs and validators directly; TypeScript applications import the matching generated types and Zod schemas. API-aware TypeScript tooling can additionally import type-only paths and operations contracts from @peasant-labs/schema/local-api or @peasant-labs/schema/village-api. Those subpaths describe request and response shapes; they do not perform network requests.

module github.com/peasant-labs/schema

It holds the domain + wire types, the closed-set enums, the publish/pull/push envelopes, the versioned OpenAPI specs, the publish-request validator, the typed fixtures, the generated TypeScript bindings, and the codegen + release-guard tooling. It has no service runtime: no HTTP server, WebSocket hub, transport client, or CLI product. Everything here is contract data, validators, generated specs, fixtures, and the gates that keep them honest.

Why this module exists

The peasant backend, the village backend, and their frontends all speak the same session_detail / publish / pull wire. If each side kept its own copy of those types, the copies would drift, and a silent wire mismatch between a producer and a consumer is exactly the class of bug that is expensive to find.

This module is the single source of truth for that wire. It was extracted from peasant's old nested pkg/schema into a standalone, public, versioned Go module so that:

• One definition, many consumers. The Go types here ARE the contract. peasant emits SessionDetailPayload / PublishRequest; the village validates and stores the same shapes; the frontends render them. Nobody redefines the wire.
• Served ≡ enforced. The village serves its OpenAPI doc from VillageAPISpecJSON(). PublishRequestSchemaJSON() and AnnotationPushRequestSchemaJSON() extract the two operation request schemas from those same embedded bytes; their canonical Go boundaries validate the documented shape before applying typed relational rules. The documented spec and the enforced schema therefore have one source artifact.
• It stays a leaf. The module depends on nothing first-party except bestiary (a sibling), imports no runtime machinery, and a leaf-audit gate keeps its dependency set pinned. That is what lets consumers pin it cheaply (see Pinning).

The data path end-to-end: the contract defines the wire, the peasant and village backends produce it, and transcript-browser (embedded by the two frontends) renders it.

flowchart LR
    schema["schema module<br/>the wire contract"]
    peasant["peasant backend"]
    village["village backend"]
    tb["transcript-browser"]
    pweb["peasant web"]
    vfe["village frontend"]

    schema -->|defines the wire| peasant
    schema -->|defines the wire| village
    peasant -->|SessionDetailPayload| tb
    village -->|SessionDetailPayload| tb
    pweb -->|embeds| tb
    vfe -->|embeds| tb

Coordinates & status

Consumers

Both backends currently pin v0.1.2; their final re-pins happen in separate downstream changes after this release. Because the module is normal go get-pinned, each consumer moves independently, so they can briefly sit on different tags between re-pins; a re-pin is a one-line go.mod change plus go mod tidy.

What's in the contract

The Go source (all package schema in the repo root) is grouped by surface. Every identifier and enum below is a wire type: a JSON-tagged struct or a closed-set string newtype with IsValid() / String() / a JSONSchema() exposer and an All... canonical list.

SchemaVersionResponse.contentCapabilities is a forward-open list used to avoid silently losing optional meaning-, provenance-, or safety-bearing content. observed_model_v1 is the first known token. Clients match exact tokens and refuse unsupported enriched publication before upload; server deployments advertise only behavior they prove end to end. See the authoritative content capability negotiation specification for wire semantics, guarantees, evolution, and contributor policy.

The session-detail payload (the central object)

SessionDetailPayload is the object every producer builds and every renderer consumes. It travels two ways:

• On peasant's local session_detail WebSocket channel, and
• Wrapped in a TranscriptContent envelope as the versioned peasant push wire body (replacing raw provider JSONL with a normalized, self-describing blob).

It carries the session header (Harness, timing, token totals), the ordered []TurnDetail (each with its []ToolCallDetail, optional exact source-observed assistant model, ACP-aligned enrichment, and optional thinking / stop-reason / token fields), an optional SessionScorecard, and the resolved SessionOutcome. The session-level model is the initial root-assistant seed, never the latest or final model; consumers derive sticky effective state from ordered observedModel evidence.

Its composition ([] = has-many; a * pointer = optional):

classDiagram
    class SessionDetailPayload {
        Harness harness
        int totalTokens
        int turnCount
        int toolCallCount
        SessionOutcome outcome
    }
    class TurnDetail {
        int index
        Role role
        string content
        ObservedModelID observedModel
        EntryType entryType
        StopReason stopReason
    }
    class ToolCallDetail {
        string name
        string arguments
        string result
        ToolCallKind toolKind
    }
    class ChildSessionRef {
        string id
        string project
    }
    class SessionScorecard {
        float specQualityScore
        float m2TokenOutcomeRatio
        int m4ConsecutiveErrorMax
    }
    SessionDetailPayload "1" *-- "many" TurnDetail : turns
    SessionDetailPayload "1" *-- "many" ChildSessionRef : childSessions
    SessionDetailPayload "1" o-- "0..1" SessionScorecard : scorecard
    TurnDetail "1" *-- "many" ToolCallDetail : toolCalls

The enum field types (Role, EntryType, StopReason, ToolCallKind, SessionOutcome, FileChangeStatus, and DiffLineKind) are schema newtypes; Harness is re-exported from bestiary. File-change statuses retain the Git wire tokens M, A, D, and R; diff-line kinds retain context, add, and del.

A trimmed excerpt of the top-level shape (local_api.go):

type SessionDetailPayload struct {
    Harness       Harness           `json:"harness"`
    Turns         []TurnDetail      `json:"turns"`
    ChildSessions []ChildSessionRef `json:"childSessions,omitempty"`
    Outcome       SessionOutcome    `json:"outcome,omitempty"`
    Scorecard     *SessionScorecard `json:"scorecard,omitempty"`
    // + session header: timing, token totals, turn/tool-call counts
}

The License surface

The content-license menu is owned by this contract (types.go), so producers, enforcers, and UIs all read one closed set:

The publish/pull wire carries it as an optional license field (PublishRequest, PullTranscriptInfo); the generated JSON-Schema's license enum is derived from AllLicenses, so widening the menu flows through the schema automatically. village enforces it; peasant mirrors it in two SQLite CHECK constraints.

Generated OpenAPI specs (generated/)

go run ./cmd/schema-gen renders the Go source into OpenAPI 3.1 specs, committed as byte-frozen goldens (JSON + YAML) plus standalone PublishRequest and AnnotationPushRequest JSON Schemas (draft 2020-12). Three OpenAPI spec families and two standalone JSON Schemas are emitted from the builders in openapi/:

The current specs are read back into the binary via //go:embed generated. Three version-aware accessors expose the bytes so consumers follow the go.mod pin without vendoring their own copy:

• VillageAPISpecJSON(): the current village API spec (village serves it as GET /openapi.json).
• PublishRequestSchemaJSON(): the current PublishRequest JSON-Schema (the single byte-source ValidatePublishRequest compiles and the village enforces through).
• AnnotationPushRequestSchemaJSON(): the current annotation-push operation schema. ValidateAnnotationPushRequest compiles it, decodes the request, and applies the runtime entry-target rule endIndex > entryIndex that standard JSON Schema cannot represent.

All three derive their filename from the version constant in versions.go, so a version bump re-points them in lockstep: consumers need no change.

Versioned specs & frozen goldens

Released spec versions are immutable. The rule is bump, don't mutate: you never add or change surface on an already-shipped spec in place. You bump the relevant version constant in versions.go (minor for additive surface, major for a breaking change), regenerate, and commit: the new version is emitted while every prior version stays byte-frozen exactly as shipped.

flowchart TD
    change["a surface change<br/>(additive or breaking)"]
    bump["bump the version constant<br/>versions.go (minor / major)"]
    regen["go run ./cmd/schema-gen"]
    current["new current spec in generated/<br/>codegen-freshness gate"]
    frozen["every prior version byte-frozen<br/>retired-versions immutability guard<br/>(retired_specs_test.go)"]
    change --> bump --> regen
    regen --> current
    regen --> frozen

Two gates enforce this (both run in make check via cmd/schema-gen):

• Codegen-freshness gate: the committed artifacts under generated/ (and the generated redaction fixture) must be byte-identical to what the generator emits from the Go source. A stale or hand-edited current spec fails the build; the fix is go run ./cmd/schema-gen + commit. (make freshness is the git-diff backstop for the same invariant.)
• Retired-versions immutability guard (cmd/schema-gen/retired_specs_test.go): every retired version is content-hash-pinned (sha256 of its committed bytes) in a registry and asserted present-and-frozen. It fails loudly on both an in-place edit (hash mismatch) and a deletion (missing file): the exact gap the freshness gate can't see, because freshness only diffs versions the generator still emits. A version is moved into the registry at the moment it is frozen (the same change that bumps the live constant past it), so there is never a window where a retired spec is mutable-and-unguarded. A permanent negative-control self-test proves the guard actually fires.

The exact retired inventory and hashes live in cmd/schema-gen/testdata/retired_specs.yaml. The still-generated current versions (Village API, PublishRequest, and AnnotationPushRequest 0.12.0, Peasant Local API 0.7.0, and Types 0.10.0) live under the freshness gate instead. When a Village API version is frozen, register both JSON-only request schemas alongside the OpenAPI golden in that manifest.

The versioning procedure itself is codified in the versions.go doc comments, the "Regeneration & gates" section of CONTRIBUTING.md, and the release ceremony in docs/release-runbook.md; there is no separate versioning document.

How pinning works

Because the contract is a normal published, tagged Go module, a consumer pins one version:

go get github.com/peasant-labs/schema@v0.1.0

That single pin replaces the old model of vendoring an in-tree copy of the types. It also structurally retires the cross-repo cost that model carried: there is no vendorHash / private-module-auth tax to fold first-party schema source into a consumer's build. The Nix buildGoModule vendorHash covers only the third-party module graph, and a no-local-replace rule (proven by TestVendorHashStableOnFirstPartyEdit) forbids the local-path replace directive that would fold first-party source into the vendor graph, so a schema edit can never drift a consumer's hash.

The ceremony (in effect): a contract change lands as its own schema-repo PR + tag first, and only then do the consumer PRs that re-pin to the new tag land. The wire is defined once, published once, and adopted deliberately. Never edited in two repos at once. Because the village both serves and enforces from the same pinned module bytes, its served spec and its enforcement can't drift from each other or from the tag.

Contract gates

The advisory posting runs in a write-scoped companion workflow (go-apidiff-comment.yml) so the read-only Tests workflow can be reused as a gate. Alongside these, make check runs the codegen-freshness gate, the retired-versions immutability guard, the leaf-audit, the vendorHash-stability proof, and the synthetic-break tests that prove the oasdiff / go-apidiff gates actually fire.

TypeScript bindings

The typescript/ directory is the source of the @peasant-labs/schema package, first shipped with the module's v0.1.0-rc6 tag. It mirrors the Go contract architecture:

• the package root is the canonical Types 0.10 projection of the complete public Go wire/domain catalog, including Zod runtime schemas and Go-shaped closed sets and guards;
• /local-api and /village-api retain type-only OpenAPI paths and operations namespaces for consumers that need endpoint request/response contracts; shared payloads resolve to the canonical root identities;
• /types remains a deprecated compatibility re-export of the canonical root;
• no HTTP or WebSocket transport client SDK is generated;
• /testcase owns generic validation behavior and a strict YAML decoder;
• /fixtures/quality and /fixtures/timeline provide typed access to generated data from the same canonical YAML corpora consumed by Go.

The Go source and generated OpenAPI catalogs remain authoritative. Hey API's Zod plugin derives root TypeScript definitions and runtime schemas without enabling its SDK/client plugins. openapi-typescript derives the type-only Local/Village operation contracts. Canonical shared payload names preserve their root identity.

The package is published to npm as @peasant-labs/schema. The committed typescript/package.json stays 0.0.0-development + private: true as the local safety; the release pipeline (release.yml's npm-publish job, behind the same guard → nix-vendor-hash → contract-gates gates as the GitHub Release, and authenticated via npm Trusted Publishing / OIDC rather than a stored token) stamps the real version from the tag and publishes at release time. The published version follows the schema module release tag, not the individual Village, local, or types document versions: an -rcN tag publishes under the npm dist-tag next, a final vX.Y.Z under latest. See docs/release-runbook.md for the npm publication ceremony (the one-time GitHub environment + npm Trusted Publisher setup) and troubleshooting. The old @peasant-labs/types package is deprecated rather than migrated: do not add new handwritten wire interfaces there.

Develop, build, regenerate

Everything is provisioned through Nix: the flake devShell is the dev-dependency manifest (Go has no dev/prod dependency split). You do not install Go or any tool globally.

Prerequisites: Nix with flakes enabled, and (recommended) direnv with nix-direnv.

# Option A: direnv (recommended)
cd <this-worktree>
direnv allow          # loads the flake devShell on cd; the committed .envrc is `use flake .`

# Option B: nix develop
nix develop           # drops you into the Go 1.26 dev shell

Inside the shell (go, gopls, golangci-lint, oasdiff, go-apidiff, vacuum, actionlint, Node, pnpm, ... on PATH):

pnpm --dir typescript install --frozen-lockfile --ignore-scripts # install the exact locked generator/toolchain
make check                            # Go + TypeScript generation, tests, and package gates
                                      #   (incl. leaf-audit, freshness, immutability, and the synthetic-break tests)
make gates BASE_REF=origin/develop    # breaking-change gates vs a base ref (oasdiff + go-apidiff + vacuum)
make schema                           # regenerate OpenAPI/Redoc and TypeScript contract outputs
nix build                             # hermetic buildGoModule (cmd/schema-gen + cmd/release-guard)

The Go test packages remain runnable with a bare Go toolchain. Full make check also needs the locked Node dependencies because freshness regenerates the TypeScript package. If they are absent, the gate names the exact pnpm install command. After any change to the Go schema source, regenerate and commit both generated/ and the generated TypeScript sources; freshness enforces byte-identity.

The leaf rule

The module's go.mod direct require set must stay a subset of the allowed contract dependencies, enforced by TestLeafAudit_GoModRequiresAreAllowed:

github.com/dayvidpham/bestiary
github.com/google/go-github/v88          # runtime seam for cmd/release-guard's GitHub API, not a dev tool
github.com/santhosh-tekuri/jsonschema/v5
github.com/swaggest/jsonschema-go
github.com/swaggest/openapi-go
golang.org/x/crypto
gopkg.in/yaml.v3

Dev/CI tools (oasdiff, go-apidiff, vacuum, linters) live in the flake devTools, never in go.mod. See CONTRIBUTING.md for the leaf-audit and no-local-replace (vendorHash-stability) rules and the go.work workflow for co-developing consumers against a local worktree before a version is cut.

Testing

The suite keeps the contract honest rather than exercising a runtime: the committed specs stay byte-identical to the Go source, released spec versions stay frozen, a breaking wire change is caught before it ships, and the module stays a dependency leaf. Three layers do this: the contract gates (codegen freshness, retired-version immutability, the oasdiff / vacuum / go-apidiff gates, the leaf-purity audit, and the vendor-hash guard, each with a real test plus a synthetic-break meta-gate that proves it fires); unit tests alongside every source (closed enums, JSON shapes, validator behaviour); and typed fixture families under testdata/. The whole suite runs with a bare go toolchain, the tool-gated tests skipping when oasdiff / go-apidiff / vacuum are absent.

Case corpora live in fixtures, not inline. When a test drives a set of cases, the cases live in a testdata/*.yaml corpus loaded through one idiom: a typed struct with yaml: tags, a //go:embed of the file, a yaml.Unmarshal, a small Load...Fixtures loader, and a row-count guard that fails loudly on an empty or mis-keyed corpus (so an iterating test can never pass on no cases). New corpora adopt the canonical testcase standard (a generic Case[I, E] / Corpus[I, E] with closed-set classification and provenance + mutation metadata, a pure loader, and its *testing.T seams split into testcase/assert), so each case also records why it exists and the single change it embodies. Fixtures that split into heterogeneous behavioral arms use the segmented form: a typed struct of named per-arm Corpus fields, each guarded by RequireMin + RequireValid. A contract change then updates one corpus instead of N inline tables, and a new test follows this by default. The corpora sit under testdata/ (annotations, contract, publish, pull, quality, session-detail, sync), internal/release/testdata/ (grammar, workflow), and cmd/release-guard/testdata/github.

See TESTING.md for the full strategy and the test behind each gate.

Releasing

Releases are cut by merging a PR titled release(vX.Y.Z[-rcN]): <summary> into develop. Never by hand-tagging. The title/tag grammar and final-release guard live once in internal/release, exposed through cmd/release-guard, the single canonical release-gating tool (built on go-github; it also serves peasant via a per-repo .github/release-guard.policy.yml). On merge, the release workflow mints the annotated tag and publishes a GitHub Release (prerelease for -rcN) with the generated/ OpenAPI specs attached as assets.

The maintainer-approval assertion in the release PR is deferred to the public flip (a single active maintainer plus GitHub's no-self-approval rule make it unsatisfiable today); the release-guard check-approval guard code stays live and tested, re-enabled alongside branch protection at the flip. The full operator guide (secrets, the GitHub App, the ceremony, and the public-flip checklist) is in docs/release-runbook.md.

Repository layout

License

Apache-2.0, see LICENSE.