Repository navigation
Epic: 1.0.0 — the stability bar #56
Description
Outcome
1.0.0 means something specific: the extension interfaces lose
@experimental, and breaking the deliberately supported integration contract
requires a major version. Compatible additions may still ship in minors.
Why now
It is not scheduled and this epic does not schedule it. It exists so that
"before 1.0" stops being a phrase and starts being a list.
Everything about the current state is explicitly pre-1.0:
README.mdleads with "early, solo-maintained, extension interfaces marked
@experimentaluntil 1.0".- ROADMAP binding decision 7 is exactly one sentence: "Extension interfaces are
@experimentaluntil 1.0." - All nineteen packages version in lockstep through a changesets
fixedgroup,
whichCONTRIBUTING.mdcalls "a deliberate pre-1.0 solo-maintainer tradeoff,
not an oversight".
So 1.0.0 is not a feature milestone. It is the point at which several deliberate
tradeoffs stop being available.
Shared context
What the milestone actually commits to:
docs/integration-contract.mdis already binding. Additive machine-contract changes ship in minors. Before 1.0, breaks require a prior maintainer ruling, thebreakinglabel and a changeset naming the break, and ship in minors; from 1.0, breaks require a major. Contract changes require aCONTRACT:commit and same-commit contract update. The current contract includes CLI--jsonshapes, MCP tool names and schemas,schema_version, frontmatter semantics, the documented client/server wire protocol and the explicitly selected supported HTTP methods, payloads and behavior. See contract versioning, including docs: decide what 1.0 freezes where the contract document does not say #343 Q5 delivered by docs: clarify wire protocol compatibility and versioning #538/CONTRACT: docs(protocol): clarify compatibility and versioning #670, and the supported HTTP specification with its boundary decision delivered under Q6 by docs: inventory and define the supported HTTP API before 1.0 #539/CONTRACT: define the supported HTTP API and internal route inventory #704. 1.0 does not make everyCONTRACT:commit a breaking change.- The seams lose
@experimental. Embeddings, completions, rerankers, agent runners,
agent backends, speech, tool renderers, content renderers, skill emitters and site adapters. A published
provider should survive a minor bump after that.
SiteAdapter adoption is delivered by scrape: migrate job boards to the shared SiteAdapter contract and runner #545/CONTRACT: migrate jobs boards to the shared site adapter runner #706: all ten jobs boards use the
shared contract and runner while retaining evidence-derived outcomes and
domain policy. The adoption decision records the approved pre-1.0 migration.
It remains experimental. packages: curate public exports and align the 1.0 stability contract #534 delivered the public-export boundary through CONTRACT: refactor(packages): curate public exports and align the 1.0 stability contract #1052 (825cd044e550b2cef5d7f2ddad2b7251f73d762a), recorded indocs/decisions/public-export-boundary.md. The remaining third-party backend/tool-renderer parity work is tracked by the attached epic Epic: a third-party backend or tool renderer can do what the first-party ones do using supported API #1345; delivery of the export boundary does not complete that conformance outcome or freeze the seams. - The lockstep group is reconsidered, or defended. Lockstep is honest for
nineteen packages nobody depends on independently. It is a different
proposition once a provider author pins one of them.
Constraints and non-goals
- 1.0 is not a promise of stability for anything not in the contract document.
If something should be stable, it goes in the document before the version
moves. - No new seams to "round out" the set — ROADMAP binding decision 2, and the
not-pluggable list indocs/extending/README.mdis final. - Out: a feature checklist. Nothing gets added because 1.0 "needs" it.
Breakdown
The surface audit #319 is complete. Its findings and the #343 rulings produced the attached native sub-issues, which own interface cleanup, supported-surface classification, contract proof and durable records. Use their current bodies and dependencies for implementation; the epic itself is not a coding task. Completion of the audit does not satisfy the publication and compatibility bar below.
The bar is real: this repository has already had to change a shipped machine
surface several times, each time through a CONTRACT: commit. 1.0 is the point
at which that stops being cheap.
Definition of done
A published version where a third-party provider written against the previous
minor still compiles and still passes the interface's contract test — and where
the contract document is something the maintainer would be willing to be held
to.
Updated 2026-09-30 triage: folded the completed audit and existing contract-versioning rules into the brief. No 1.0 schedule, lockstep change or immediate interface freeze is selected.
Updated 2026-10-01: corrected the current package count to fifteen, matching the changesets fixed group, and included the already-shipped Reranker seam in the summary, matching ROADMAP and docs/extending/README.md. Historical audit figures stay pinned to their original commits. The existing maintainer ruling keeps this epic without agent-ready; its publication/compatibility definition of done is still open.
2026-10-01 triage: refreshed the current lockstep count to sixteen from .changeset/config.json and CONTRIBUTING.md at 0a6389cf3f30341db7093e195637cf08a0f27e6a. Historical audit counts retain their dated provenance. Publication/third-party compatibility, existing child prerequisites and the epic-not-ready ruling are unchanged.
2026-10-10 factual review: refreshed both current lockstep-count references to eighteen, verified against the package manifests and .changeset/config.json at main 17a6f84ad5b9029961c5225414b66e82edab3328. Dated historical counts remain unchanged. No release, lockstep policy change, schedule or epic readiness is selected.
2026-10-16 triage at main 80e028d84b7686d6cf864d8166029b1142de8756: verified the nineteen-package fixed group and the delivered experimental content-renderer seam. Preserved historical counts, the unscheduled 1.0 compatibility bar and epic-not-ready status; no release or interface freeze is selected.
2026-10-22 triage at main 01e084918a17f8724bb203d7ad532d996398273c: corrected the obsolete future #534 handoff using its verified merged delivery and current public-export decision. #1345 remains the native extension-parity follow-up. The nineteen-package fixed group, unscheduled 1.0 compatibility bar and epic-not-ready status are unchanged.
Activity
schlessera commentedon Sep 22, 2026
Code audit against main
b220652e60d6(2026-09-22).The stability audit is still needed, but two parts of the baseline should be explicit:
integration-contract.md:305. The issue's “today only a discussion, after 1.0 a major” framing does not match those documents. Reconcile the written policy before making 1.0 the point at which it first becomes binding.@experimentalannotations will miss documented interfaces. docs/extending/README.md:77 also names the browserAsrClientand the scrapingSiteAdapter; their declarations do not carry individual@experimentaltags. Use the documented/exported surface inventory as well as annotation searches.No versioning or stability-policy change was made by this audit.
docs: pre-1.0, an additive contract change ships in a minor (#184)
schlessera commentedon Sep 25, 2026
State on 2026-09-25. The breakdown's first step, the audit, is filed as #319 and attached. Its output becomes this epic's remaining sub-issues.
The 2026-09-22 audit comment's first point no longer holds:
docs/integration-contract.md:3-14now says a breaking change ships in a minor before 1.0, with thebreakinglabel and a maintainer ruling, and needs a major from 1.0 (docs/decisions/contract-versioning.md). That matches this epic's framing. Its second point, thatAsrClientandSiteAdapterare documented seams with no@experimentaltag, is carried into #319's scope.64 remaining items
schlessera commentedon Oct 3, 2026
2026-10-03 — #693 has a complete scoped health/SSE implementation in draft PR #926, signed head
bedf362b18e15bdfdfdd7b731a414ba72b047e1d, with 213 scoped tests, declaration/mutation proof and approved minor/contract migration documentation. Ten of eleven current-head CI jobs and contract passed; the sole failure is an unchanged inbox-budget fixture whose fixed October 1 seed expires against the wall-time runtime. Ready native #736 child #927 owns that harness repair. #693 now recordsBlocked by #927, exact refresh/current-head/base completion evidence and a released claim. No merge, public API publication or epic completion is claimed.schlessera commentedon Oct 3, 2026
2026-10-03: #702 has its approved nullable result/candidate declaration correction and runtime/declaration/mutation proof in draft #928. It preserves the existing CLI/MCP/HTTP values, built-in provider request text and retrieval goldens. It remains open pending required final-head CI and shared fixture blocker #927; the canonical dependency is in the child body. Resume after #927 is delivered by rebasing and validating the new PR head before merge. No 1.0 schedule or interface-freeze policy changes.
schlessera commentedon Oct 3, 2026
2026-10-03 — #911's approved peer/context record and design are prepared in draft PR #936, head
c4a059e86428f4134faf10812803adda06ebdb77. The four documentation files cover both #696 rulings, alternatives, all nine operations/reachable types, jobs/root/failure preservation, migration process and implementation verification handoffs. Local 123-test documentation group, typecheck/lint and all 44 inspected citation ranges pass. Exact-head CI has 10/11 jobs passing plus contract; the sole failure is unchanged #927's admission-clock fixture. #911 now declares canonicalBlocked by #927, retains scoped readiness, releases its claim and preserves its draft. No record delivery/merge, runtime migration, SQL retirement, 1.0 freeze or publication is claimed. Resume #911 after the clock repair and passing refreshed-head CI; #696 consumes the verified merged record before completing its own reconciliation, including the recorded #343 Q7 summary correction. Existing implementation dependencies remain.schlessera commentedon Oct 3, 2026
2026-10-03 child outcome: #693 is closed by PR #926, squash
ab55924eb53e0702d2f0d763d88146c5b7d85d5e, verified on main with the tested tree. The approved direct health-type correction and SSE sync helper repair have real-handler, reservation/draining, byte-framing, incomplete-outcome and emitted-declaration coverage. Refreshed local coverage passes 230 tests; all eleven current-head CI jobs and refreshed contract pass after #927's independent clock-fixture repair.The public health break follows the maintainer's selected A migration: minor pre-1.0 changeset naming the break, CONTRACT commit/update and migration notes. Former health-version readers use authenticated status explicitly. No release was versioned or published. The native sub-issue list records this completion; the remaining #56 children and its third-party compatibility/publication definition of done remain open.
schlessera commentedon Oct 3, 2026
2026-10-03 child handoff: #702's approved nullable-declaration correction is preserved in refreshed draft #928, head
b1fc988fb76d76695a510f65ac9265b4bdd0d205, based on mainab55924eb53e0702d2f0d763d88146c5b7d85d5e. Local 378-test coverage, build/typecheck/lint/declarations, all four restored combined consumer-probe mutation failures and minor-only changeset validation are recorded. All three full CI test shards, packaging and contract pass.Required current-head CI is 10/11 green: the unchanged mixed-picker image-preview assertion fails before its upload assertion in browser shard 1. #940 records that distinct observation and missing measurements; #702 now explicitly waits on it, keeps Refs/draft, and releases its resumption claim. The original nullable values, rankings and migration ruling are preserved. No #702 merge or #56 completion is claimed.
schlessera commentedon Oct 4, 2026
2026-10-04 — #911's approved peer/context record remains prepared in draft #936, refreshed head
1f185a10830719aa113cb7facf38de3d26d27c02, after #927's repair. Fresh 123 documentation tests, sixteen builds, typecheck/lint and 48 inspected anchored references (28 unique ranges) pass. Current-head CI finishes 10/11 green: all 9,350 unit tests and browser shard 2 pass; browser shard 1 fails the first dark/320px Configure Jobs assertion (#955) and dark/1440px whole-test timeout (#853). Both light cases and all 54 subjects pass. The four-file documentation diff changes no browser/UI implementation or harness; no retry or gate weakening was used.#911 stays open, draft and canonically blocked by #955/#853; its claim is released. The approved policy is not yet a delivered record. #696 retains its #911 prerequisite and its own reconciliation, including the previously recorded obsolete #343 Q7 summary. #697/#699/#700/#534/#537/#701 retain their implementation criteria and SQL-retirement prerequisites. This handoff completes no runtime migration, epic, 1.0 freeze or publication.
schlessera commentedon Oct 4, 2026
2026-10-04 child handoff: #854's complete configured-input membership, hint validation, module ownership/user override and related query repair is recreated in draft #976, signed head
1f481ab3e07e4cc90036753d2ed14c1643ac472a. Fresh runtime, 211-test local, eight restored guard-mutation, build/typecheck/lint/leakage and core-patch release receipts pass; canonical-key scope remains separately owned by #876/#890.Current-head CI finishes 10/11 green with all 9,369 unit tests and browser shard 2 passing. Browser shard 1 repeats #955's first dark/320px Configure Jobs matcher failure. #854 retains every original criterion, uses draft/Refs and canonical Blocked by #955, releases its claim and requires fresh required-CI/live-base verification and normal merge after the blocker repair. Signing access is restored; no #854 merge, compatibility/publication milestone or #56 completion is claimed.
schlessera commentedon Oct 6, 2026
Readiness, 2026-10-06: removed
agent-readyper the maintainer's ruling that epics never carry it (see the epic ruling on #56). Work is picked up through this epic's child issues.schlessera commentedon Oct 22, 2026
2026-10-22 triage: #534 is delivered by #1052, squash
825cd044e550b2cef5d7f2ddad2b7251f73d762a(verified ancestor of inspected main01e084918a17f8724bb203d7ad532d996398273c). Corrected the obsolete future export-curation handoff in the body; the supported/internal boundary is recorded in docs/decisions/public-export-boundary.md. Native #1345 still owns the remaining third-party extension parity and conformance outcome. No 1.0 schedule, interface freeze, new runtime proof or readiness change is claimed.