docs(data): teach the contract convention and the generated manifest in the data guide by trueadm · Pull Request #2642 · octanejs/octane

trueadm · 2026-11-14T01:25:07Z

Summary

Last part of step 3 of the octane/data contract convention: the data guide now teaches the convention that #2605, #2624 and #2630 built.

website/src/content/docs/data.mdx:
- Every example imports from ./contracts.data.ts.
- The receipt read is now declared in the contract module, so code that runs no longer declares contracts.
- The windowOf factory takes Shelf.books.view instead of the contract.
- The cross-tab example imports contracts from octane/data/manifest instead of building the list by hand.
- A new section, "Let the build check your contracts", covers the rules, what each build reports, dev warnings, octane analyze, data: true/false, and a table of the manifest's exports.
docs/data.md: octane/data/manifest is added to the entry points, with a paragraph pointing to the check.
website/public/llms.txt: a "build check" bullet, and the corrected import path.
Compiler: journal.writes now counts as a contract site, so a journal can still list a subset of writes inline (journal: { writes: [addBook, setRead], receipt }). The guide teaches that form, and it was an ESCAPE before. The catalog, a test and a patch changeset are included.

Validation

website/tests/data-docs.test.ts (reference table against the real exports), strong-diagnostics-catalog, data-contracts.test.ts (new writes site)
pnpm sync, pnpm format:files:check
Full pnpm test: left to CI.
perf-review: not applicable. The only code change is one property name in the per-module analysis.
concise-code: +105 −50, almost all docs. Alternative considered: teach the manifest's writes only. Rejected, because choosing which writes to journal is a documented feature, and keeping it costs one word in the compiler.

Risk / follow-ups

The guide's code blocks are not built, so I checked them against the rules by reading them. No test enforces this.

Provenance

An agent produced this diff (agent-authored)

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

Note

Low Risk
Almost entirely documentation; the compiler change is a single property site with a matching unit test.

Overview
Documents the *.data.ts contract convention and generated octane/data/manifest across the data guide, reference docs, strong-mode diagnostics, and LLM index. Examples now import from contracts.data.ts, and new sections explain build-time contract checks and manifest exports (contracts, writes, identity).

The only runtime/compiler change treats journal.writes like other contract sites (e.g. feeds, journal.receipt), so an inline list such as journal: { writes: [addBook, setRead], receipt } is analyzed instead of tripping OCTANE_DATA_CONTRACT_ESCAPE. Diagnostic catalogs, tests, and a patch changeset are updated to match.

^{Reviewed by Cursor Bugbot for commit 9d17fdb. Bugbot is set up for automated code reviews on this repo. Configure here.}

…in the data guide

cloudflare-workers-and-pages · 2026-11-14T01:29:57Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	octane-website-mcp	`9d17fdb`	Commit Preview URL Branch Preview URL	Nov 14 2026, 01:40 AM

github-actions · 2026-11-14T01:32:28Z

Benchmark report

🟢 No byte growth, no added work, and no timing changes beyond ±3%.

Compares 0e8d8eefd, the merge commit's first parent (main has moved 2 commit(s) past the pull request's recorded base 521d58d16) with c92570c7f on the same runner. Any increase in a js-framework work counter fails this check; byte changes are a report. Wall time is a report: base and head samples alternate in one browser, and an operation is called slower or faster only when the 95% confidence interval of its ratio excludes ±3%. Workflow run

js-framework: 1k/10k row operations

target	operation	base ms	head ms	head/base	95% CI
octane-jsx	select_lots	0.853	0.834	−4.4%	−5.2% … −3.6%	🟢 faster

All 20 timed operations (19 without a verdict)

target	operation	base ms	head ms	head/base	95% CI
octane-tsrx	run	2.450	2.450	−3.8%	−3.8% … ±0.0%	⚪ within noise
octane-tsrx	replace	5.292	5.092	−0.0%	−5.3% … +4.6%	⚪ within noise
octane-tsrx	add	2.108	2.092	±0.0%	−4.4% … +4.8%	⚪ within noise
octane-tsrx	update	0.086	0.086	−0.0%	−1.2% … +1.0%	⚪ within noise
octane-tsrx	select	0.005	0.005	−0.3%	−2.1% … +1.1%	⚪ within noise
octane-tsrx	swap	0.017	0.016	−2.4%	−3.3% … −1.3%	⚪ within noise
octane-tsrx	remove	0.014	0.014	−0.4%	−3.5% … +3.8%	⚪ within noise
octane-tsrx	runlots	21.258	21.917	+0.5%	−5.1% … +8.0%	⚪ within noise
octane-tsrx	select_lots	0.005	0.005	−0.3%	−2.1% … +0.5%	⚪ within noise
octane-tsrx	clear	42.708	42.825	−0.5%	−1.2% … +1.6%	⚪ within noise
octane-jsx	run	3.267	3.242	−0.0%	−3.1% … +1.5%	⚪ within noise
octane-jsx	replace	5.475	5.567	+2.5%	+1.7% … +6.5%	⚪ within noise
octane-jsx	add	2.742	2.792	±0.0%	−3.5% … +3.6%	⚪ within noise
octane-jsx	update	0.157	0.153	−1.3%	−3.7% … ±0.0%	⚪ within noise
octane-jsx	select	0.080	0.080	−1.0%	−3.0% … +1.1%	⚪ within noise
octane-jsx	swap	0.121	0.122	−1.3%	−1.9% … ±0.0%	⚪ within noise
octane-jsx	remove	0.110	0.107	±0.0%	−2.2% … +2.0%	⚪ within noise
octane-jsx	runlots	23.383	23.600	−0.2%	−2.9% … +3.0%	⚪ within noise
octane-jsx	select_lots	0.853	0.834	−4.4%	−5.2% … −3.6%	🟢 faster
octane-jsx	clear	43.042	42.692	+0.5%	−2.3% … +1.9%	⚪ within noise

All 64 work counters are unchanged.

Application bundle size (bytes)

No changes across 111 measured values.

Public-import reachability bundles (bytes)

No changes across 141 measured values.

cloudflare-workers-and-pages · 2026-11-14T01:36:30Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	octane-website	`9d17fdb`	Commit Preview URL Branch Preview URL	Nov 14 2026, 01:41 AM

…fest replacing hand-kept lists Builds on #2642's contract-check section: the four rules with accepted and rejected examples, the .map/for…of loop form, and the shelf session before and after octane/data/manifest. Restores #2642's docs/data.md and llms.txt, which already cover these.

… manifest replaces (#2644) * docs(data): document the octane/data contract check and generated manifest * docs(data): number the contract rules with examples and show the manifest replacing hand-kept lists Builds on #2642's contract-check section: the four rules with accepted and rejected examples, the .map/for…of loop form, and the shelf session before and after octane/data/manifest. Restores #2642's docs/data.md and llms.txt, which already cover these.

docs(data): teach the contract convention and the generated manifest …

3bf9813

…in the data guide

trueadm marked this pull request as ready for review November 14, 2026 01:25

github-actions Bot added agent-authored Diff or issue body substantially produced by an AI agent docs PR: documentation only labels Nov 14, 2026

docs(data): add the contract-check sections to the docs search index

9d17fdb

trueadm merged commit 9a756ff into main Nov 14, 2026
32 checks passed

trueadm deleted the docs/data-guide-contract-convention branch November 14, 2026 08:16

trueadm mentioned this pull request Nov 14, 2026

docs(data): number the contract rules with examples and show what the manifest replaces #2644

Merged

7 of 8 tasks

Navigation Menu

Repository navigation

docs(data): teach the contract convention and the generated manifest in the data guide - #2642

docs(data): teach the contract convention and the generated manifest in the data guide#2642
trueadm merged 2 commits into
mainfrom
docs/data-guide-contract-convention

trueadm commented Nov 14, 2026 •

edited by cursor Bot

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Nov 14, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 14, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Nov 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

trueadm commented Nov 14, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Risk / follow-ups

Provenance

Uh oh!

cloudflare-workers-and-pages Bot commented Nov 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

github-actions Bot commented Nov 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmark report

js-framework: 1k/10k row operations

Application bundle size (bytes)

Public-import reachability bundles (bytes)

Uh oh!

cloudflare-workers-and-pages Bot commented Nov 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

trueadm commented Nov 14, 2026 •

edited by cursor Bot

Loading

cloudflare-workers-and-pages Bot commented Nov 14, 2026 •

edited

Loading

github-actions Bot commented Nov 14, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Nov 14, 2026 •

edited

Loading