Skip to content

feat: every public sheet implements an app-published schema contract - #212

Merged
themightychris merged 8 commits into
developfrom
feat/sheet-contracts
Oct 14, 2026
Merged

themightychris merged 8 commits into
developfrom
feat/sheet-contracts

Conversation

@themightychris

Copy link
Copy Markdown
Member

Implements plans/sheet-contracts.md. This generalizes #203 to every sheet, with this repo as the publisher.

Publishing

  • buildContract() in @cfp/shared turns each sheet's Zod schema (the input side) into a draft-07 gitsheets contract that's open for extension and null-free, with required sorted.
  • The 15 documents are published at contracts/codeforphilly.org/<sheet>/v<N>.json.
  • CI's new check-contracts step fails when a schema change would alter a published version; the fix is to bump that sheet's version.
  • This replaces the unused .gitsheets/schemas/ output.
  • person-evaluations moves to a generated v2. The hand-authored v1 stays published, unchanged.

Adoption (data repo, already pushed in lockstep)

  • empty, fixture and legacy-import adopted every contract from this branch's 7fe6b81 raw URLs, recorded in sources.toml, and every sheet config declares implements.
  • gitsheets contracts verify passes on all three, including legacy-import's full laddr import.
  • Before adoption, every record on published (23k+ across 9 sheets) checked clean against these contracts.

Verification: at boot the API opens every sheet in gitsheets declared mode: identity only, no records read, no structural fallback.

Mirror: apps/api/gitsheets/ now matches empty, including contracts/. Tests check that each mirrored contract hashes identically to its published JSON, and that every sheet declares exactly the version this build publishes.

Found along the way: contracts rejected three invalid test fixtures: a publishedAt field that should be postedAt, a minimal people record, and non-UUID slug-history ids. All three are fixed.

Spec: storage.md → "Schema contracts" (generation, immutability, adoption, verification, the lockstep order); spam-exclusion.md now points at it.

Rollout order: v0.6.0 to production first (the bridge from gitsheets 2.2), then published adopts the contracts together with the release containing this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj

themightychris and others added 8 commits October 13, 2026 23:30
The Zod schemas stay the source of record shape; this repo publishes
them as versioned gitsheets contracts and the data repo adopts them, so
gitsheets enforces shape on every writer, not just the API. Specifies
generation rules, immutability, adoption from a tagged raw URL, boot
verification, and the order of a contract change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
…ockstep

No structural fallback: the API boots only against the exact contract
versions it publishes, and the data repo adopts each version in the
same change that publishes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
…ract

buildContract() turns each sheet's Zod schema (input side) into a
draft-07 gitsheets contract: open, null-free, required sorted. The
generated documents are published at contracts/codeforphilly.org/<sheet>/
v<N>.json, and CI's check-contracts fails when a schema change would
alter a published version. person-evaluations moves to a generated v2;
the hand-authored v1 stays published, unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
Each public sheet must declare exactly the contract version this build
publishes (gitsheets declared mode: identity only, no records read, no
structural fallback). Also fixes a slug-redirect fixture that minted
non-UUID ids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
With contracts enforced on every write, the harness's minimal people
record and the scrub-data blog posts (publishedAt instead of the
schema's postedAt) were rejected. They now write valid records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
apps/api/gitsheets/ now matches codeforphilly-data#empty after it
adopted every published contract: each config declares its contract,
contracts/ holds the canonical documents and sources.toml.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013PxDwrzedwQoijkwbqSGKj
@themightychris
themightychris merged commit 1c339ea into develop Oct 14, 2026
1 check passed
@themightychris
themightychris deleted the feat/sheet-contracts branch October 14, 2026 04:01
themightychris added a commit that referenced this pull request Oct 14, 2026
Every public sheet now implements an app-published contract (#212);
this adds `codeforphilly.org/event-series/v1` for the sheet #211
introduces. The pre-contracts JSON-schema file goes with its generator.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WVK3JSficcyHViXj36opqV
themightychris added a commit that referenced this pull request Oct 14, 2026
Every public sheet now implements an app-published contract (#212);
this adds `codeforphilly.org/event-series/v1` for the sheet #211
introduces. The pre-contracts JSON-schema file goes with its generator.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WVK3JSficcyHViXj36opqV
@themightychris themightychris mentioned this pull request Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant