Skip to content

one interface per shape: versioned or living, no Run - #225

Merged
adssib merged 3 commits into
mainfrom
pl3-living
Nov 21, 2026
Merged

adssib merged 3 commits into
mainfrom
pl3-living

Conversation

@adssib

@adssib adssib commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Important

Needs a minor release (v0.4.0) after merge. The plugin interface changes (Run, Env.Baselines, plugin.Spec are gone), so the next tag is a minor, run by hand. Agents never release. patch-it's hosted ingestion service switches to it in its own PR, pinned to this branch until the tag exists.

What this changes

No source-specific change: the plugin interface, so living pages work like versioned pairs and Run can go.

1. One interface per shape, Extract shared (core/plugin)

type Plugin interface {
    Name() string
    Extract(ctx, env, from, to Snapshot) (Result, error)
}
type Versioned interface { Plugin; ListVersions(ctx, env) ([]Version, error); ReadAt(ctx, env, v Version) (Snapshot, error) }
type Living    interface { Plugin; Read(ctx, env, last Snapshot) (Snapshot, error) }
  • Every kind is exactly one shape; RegisterProvider refuses a plugin that is both or neither. openapi, changelog, migrationguide, catalog, apisurface are versioned; notices is living.
  • Snapshot gains CompareHash: the hash of the live page as fetched, which a living page's next Read compares with (the content kept is the Wayback snapshot's bytes).
  • notices.Read(ctx, env, last): fetch the page; when it hashes as last did, return last (one GET, no Wayback call); otherwise read it, apply the shape guard against last, cite it with kit.Cite (or the archive fallback when the site answers 401/403), and return a snapshot dated now (Version.ID = RFC 3339). notices.Extract(last, cur) is the notices cur has that last didn't, citing cur. The runner does: cur := Read(last); if cur.CompareHash != last.CompareHash → Extract(last, cur), store events, keep cur.
  • I passed last into Read (the suggestion was Read(ctx, env)): without it, every read would need a Wayback snapshot just to be compared, and the shape guard has nothing to compare with.

2. Deleted (no shims): Plugin.Run on all six kinds, Env.Baselines, BaselineReader, plugin.Spec, plugin.Baseline, Result.Label and Result.Baselines, kit.Unchanged, migrationguide.Guide.Current (+ both readers'), changelog's runLog and Log.CommitsURL, notices' ListVersions/ReadAt (Web Archive captures as versions), versions.WaybackCaptures and versions.WaybackAt (no caller left), the VersionLister/Reader/Extractor sub-interfaces; in the test kit kittest.Ingest, IngestWith, Run, Sink.SaveSpec/LastSpec and Mem's baselines; two unused fixtures (commits-c0f99ca9.json, commits-day.json).

3. Test kit, both shapes (core/kit/kittest): Versions(t, env, p, from, to) (ReadAt both, Extract), Extracted(t, env, p, from, to) (snapshots the test built), Page(t, env, p) (a living page's first read; a second read must return the kept snapshot and store nothing). Each extracts twice and fails on anything new. Non-failing steps for error tests: Pair, Extract, ReadPage.

4. plugin.ErrNothingToRead: a wrap-able sentinel for a release or page with no part a reader can use. Returned (wrapped) by the changelog (no heading for the release), both migration-guide readers (not this major's guide, no section, no table, an empty table), and the notices readers (no table). A table that isn't the expected one stays a plain error. Tests use errors.Is.

5. Contract (patch-it#58): contract/fixtures/ resynced from patch-it main (change-events-v2-ids.json, change-events-v2-from-to.json added, change-events-invalid.json deleted, the rest rewritten to ids). core/event: rule 13 (previous_version required on api_operation/package_release: event.PairType), rule 14 (api matches the contract's provider/source pattern), supersedes gone. Every fixture file is now validated (not only two), and every invalid case is refused. make check PATCH_IT=<patch-it main> passes.

6. Docs and scaffolding: docs/writing-a-plugin.md §4 (both shapes, ErrNothingToRead) and §6 (the kit), docs/which-kind.md (which kinds are which shape), docs/how-it-works.md, AGENTS.md layout; cmd/new-plugin templates use kittest.Versions/Extracted/Page (the scaffold test builds, vets and tests a source of every kind and reader).

Golden proof

Every golden compared before/after with a script (api, fingerprint and every other field included):

goldens
byte-identical all 12 core/normalize files, all 11 openapi, notices/{openai,anthropic}-models, github-actions, google-vertex-ai-models (27 of 37)
only id changed apisurface/openai-1.1.2 (0 → 1, 2): its test returned Extract's events directly; it now goes through kittest.Versions and the store like every other golden, so ingest's conformance test can replay it byte for byte
only previous_version added, nothing else differs changelog/textual-0.86.0 (0.85.2), urllib3-2.0.0 (1.26.15), mongodb-atlas (2026-11-09); migrationguide/anthropic-1.0.0 (0.75.0), numpy-2.0.0 (1.26.4), newrelic-11.0.0 (10.17.0), posthog-8.0.0 (7.91.4); notices/cloudflare-api, salesforce (2026-11-14T12:00:00Z)

Why the 9 gain previous_version: they are api_operation/package_release events, which rule 13 now refuses without previous_version. They used to come from Run extracting the pinned release against nothing; now each is a real pair from the release before (from PyPI, or the commit before in mongodb/openapi). Fingerprints don't hash previous_version, so every fingerprint is unchanged.

Checklist

  • Metadata complete in the registration. Not applicable: no source added or changed.
  • Every commit is signed off
  • Golden tests: rewritten onto the two shapes; content proven above
  • testdata/README.md: the two deleted fixtures' row removed
  • Drop tests: unchanged, now run through the same helpers
  • providers/*.md: cloudflare.md, salesforce.md (what previous_version is for a notice), convex.md, supabase.md (no "daily ingest")
  • Fetches only through env.Get / core/kit/
  • make check PATCH_IT=<patch-it main> passes (go1.27.1, incl. its gofmt; go test -race)
  • Nothing private

Calls I made (please check)

  • previous_version on dated api_operation notices (Cloudflare, Salesforce). The merged contract requires it on every api_operation, but these are dated notices read from a page with no releases. I set it to the dated read the page was compared with (the read before; on a first read, the read itself), so the events are valid and nothing is dropped. The client's gate treats both as dated APIs and doesn't read the field. If you'd rather the contract said "a change found by comparing two versions" instead of listing types, that's a patch-it change; the code here would follow it.
  • A pinned changelog / migration guide golden names the release before without reading it (kittest.Extracted): those Extracts read only the newer release's own section. The MongoDB JSON changelog's golden names the real commit before (f49749a6, 2026-11-09) without reading it, so every change in the saved file is extracted; for that, its Extract subtracts the older side's findings only when it has content.
  • Notices lose their Web Archive history (ListVersions over captures): a kind is exactly one shape. A living page's past is no longer backfilled from captures; it starts at its first read. versions.WaybackCaptures/WaybackAt are deleted with it (I19.9 can bring a Wayback-at-date helper back with a caller).
  • ErrNothingToRead on the notices readers too ("page has no table"): for a living page the runner still treats any error as a failure; the sentinel says why.

Related PRs

Part of #179.

🤖 Generated with Claude Code

A plugin is plugin.Versioned (ListVersions, ReadAt) or plugin.Living
(Read), never both, and every change is what Extract finds between two
snapshots. notices is the one living kind: Read fetches the page, keeps
the snapshot when it hashes the same, and cites a Wayback snapshot
otherwise. Run, Env.Baselines, plugin.Spec, plugin.Baseline,
kit.Unchanged, Result.Label and the Wayback version helpers are gone.

plugin.ErrNothingToRead marks a release or page with no part a reader
can use. core/event applies the contract's rules 13 and 14 and drops
supersedes; contract/fixtures resynced from patch-it main.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 1m 30s —— View job


✅ Ready to merge. The interface split is clean, every kind has exactly one shape and RegisterProvider enforces that, all checks I ran pass, and the PR body explains every golden change.

Rules

Rule Status Evidence
Plugin list (Rule 1) ✅ n/a No source added or changed. No hand-kept list came back. provider.go:226 shape() refuses a plugin that is both shapes or neither.
Provider pages ✅ cloudflare.md and salesforce.md now say what previous_version means for a notice. convex.md and supabase.md no longer mention a "daily ingest".
Golden tests and quotes ✅ Only 10 goldens change, and each one only adds previous_version. Fingerprints don't hash that field (event.go:176), so they are unchanged. The body explains why the new output is right (rule 13). Two unused fixtures are deleted along with their testdata/README.md row.
Drop tests ✅ Unchanged; they now run through kittest.Versions, Extracted and Page.
Fetch only via env ✅ No new net/http, filesystem or database access. notices.Read fetches through env.Get and kit.Cite.
Contract fixtures ✅ Resynced from patch-it after patch-it#58 merged, so they were not changed here first.
Nothing private ✅ Nothing private in the code, docs or PR body. Leak guard is clean.

Bugs

None found. Points I checked:

  • Unchanged pages are skipped: notices.Read returns last when the page hashes the same, so the runner's CompareHash check skips Extract.
  • Old notices are not re-emitted: the dedupe in Extract keys on Fingerprint, which doesn't include source_url. A new Wayback URL therefore doesn't bring old notices back. living_test.go covers this.
  • The shape guard still works: it now compares against last.Content.
  • The LatestTag fallback in openapi.ListVersions is unused: every OpenAPI adapter implements Versions, so losing Run's baseline path costs nothing.

Verified

  • ✅ go build ./...: clean
  • ✅ go vet ./...: clean
  • ✅ gofmt -l .: prints nothing
  • ✅ go test -race ./...: every package passes, including cmd/new-plugin's scaffold test
  • ✅ python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • ⚠️ Not run: make check, make todos, make imports and make nethttp. This environment needs approval for make, so CI_go will be the check for those.

Non-blocking (optional)

  1. ErrNothingToRead can hide a real breakage. changelog/parse.go:131 returns it for "no heading for release" and members.parseRST for "no section". For an old release, being skipped is right. But if a changelog or guide is restructured, every new release will also be skipped quietly, where today it fails loudly. You may want the ingestion side to alert when a source's newest release is skipped, or when many releases in a row are.
  2. First pairs are dropped silently. On a versioned source, an Extract(zero, v) pair for api_operation or package_release events now puts every event in Rejected (rule 13), for example the JSON changelog's first commit. That is consistent with precision over recall, but one line in writing-a-plugin.md §4 saying the runner starts at the first real pair would save the next author some confusion.
  3. Stale comment: plugins/openapi/adapter/adapter.go:15 still says "the baseline's (plugin.Spec) job", and plugin.Spec no longer exists.
  4. Salesforce (ArchiveWhenBlocked): every read still takes a fresh Wayback capture before the hash check, because the live page is blocked. That was already the case before this PR. Only worth a look if the Wayback calls start costing too much.

Your four "calls I made" look reasonable to me, especially passing last into Read: it avoids a Wayback snapshot on every read and gives the shape guard something to compare against. Thanks for the careful golden proof.

@adssib
adssib merged commit ccd2748 into main Nov 21, 2026
4 checks passed
@adssib
adssib deleted the pl3-living branch November 21, 2026 01:41
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