Skip to content

docs: state the engine's value model in AGENTS.md - #5133

Merged
ryansolid merged 1 commit into
mainfrom
tembo/agents-engine-model
Nov 20, 2026
Merged

ryansolid merged 1 commit into
mainfrom
tembo/agents-engine-model

Conversation

@ryansolid

Copy link
Copy Markdown
Member

Summary

Adds one section to AGENTS.md, under Engineering Standards: the engine's value model. It says what a node in the signals engine may store, which no single rule states and which lived only in discussion #3905 and the internals log, where fixing agents are not told to look.

The model, as ruled on 2026-11-20:

  • A node has the value the screen shows and one pending value per hold. Holds that overlap on a node merge (F-2, D-33). An ordinary write never forks a node (Idea: let an unrelated write publish during a refresh by forking only the nodes it overlaps #3905, declined).
  • A lane is a hold of its own over the hold it reads ahead of, and only a read ahead the author wrote opens one (F-6). It is the one declared fork.
  • So a node carries at most three values: the screen's, the hold's pending value (also what a guess reverts to, F-11), and one guess a lane has forked off and not yet revealed. That guess shows when its own async lands, even while the hold is open (F-6).
  • Anything else that keeps a value for a node is outside the model. A fix that needs one goes to the maintainer as a JSX component with the screen after each step.
  • Optimistic state is for process, isPending is for data: an app shows work in flight with its own createOptimistic(false) flag or with affects(); the engine does not add state so a guess can come back or announce itself.
  • The three stores that are outside the model today (covers' covered value, kept, screens) are named as debt, not precedent.

Why now. Between 2026-11-10 and 11-20, 90 fixes landed in packages/signals/src; 84 changed no rule, scenario row or seat-table row. Two of the three extra stores came from such fixes (kept with #4337, screens with #4779), each for one scenario, neither reviewed against this model because the model was not written down. A census over the signals and web suites shows a node at rest holds a value beyond the model in only two tested situations, and one of them (#4336's give-back) was never reported by a user.

Docs only. No source, test or behaviour change, so no changeset.

How did you test this change?

Nothing to run: one Markdown file. Checked that every rule id cited in the new section (F-1, F-2, F-6, F-11, D-33) stands in RULES-FUNDAMENTALS.md / RULES-DERIVED.md, and that the three stores named exist at the paths given on main @ 99db9bc.


Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

View on Tembo  Review in Tembo  View Agent Settings

Co-authored-by: tembo[bot] <208362400+tembo-io[bot]@users.noreply.github.com>
@tembo tembo Bot added the tembo Pull request created by Tembo label Nov 20, 2026
@changeset-bot

changeset-bot Bot commented Nov 20, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: f8f6f95

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

Size (brotli, eager entry chunk)

scenario head vs base minified vs base minified vs recorded cap lazy chunks (not counted)
signals: core floor (createSignal/Memo/Effect/Root/flush) 7.50 KB 0 B 0 B −212 B 7.56 KB ✅
signals: + createStore 15.15 KB 0 B 0 B +12 B 15.13 KB ⚠️ over by 18 B, 8 B minified headroom
signals: + isPending/latest 13.41 KB 0 B 0 B 0 B 13.43 KB ✅
signals: + until/refresh (truth readers, no optimism) 8.21 KB 0 B 0 B −49 B 8.23 KB ✅
app: render + one signal (the simple-app floor) 9.75 KB 0 B 0 B −515 B 9.85 KB ✅
app: hydrating (no stores) with Show/For/Loading/Errored/lazy 19.04 KB 0 B 0 B −337 B 19.14 KB ✅ lazy-page.js 0.04 KB
app: hydrating + every store primitive family 35.43 KB 0 B 0 B +13 B 35.45 KB ✅ lazy-page.js 0.04 KB
app: CSR with Show/For/Loading/Errored/lazy 13.77 KB 0 B 0 B −297 B 13.86 KB ✅ lazy-page.js 0.04 KB
app: CSR, observe tier (same app on the observe artifacts) 15.47 KB 0 B 0 B −297 B 15.59 KB ✅ lazy-page.js 0.04 KB
app: CSR, observe tier + attribution engine enabled 30.06 KB 0 B 0 B −375 B 30.22 KB ✅ lazy-page.js 0.04 KB
app: compiled floor (one template, one text hole, one delegated click) 9.93 KB 0 B 0 B −586 B 10.03 KB ✅
app: compiled CSR (JSX todo app: spread/merge/omit, events, class/style, keyed For, Show, Loading + lazy, store) 26.74 KB 0 B 0 B −238 B 26.75 KB ✅ stats.js 0.18 KB
app: compiled hydrating (the same JSX todo app through hydrate(), compiled hydratable) 33.00 KB 0 B 0 B −189 B 33.00 KB ✅ stats.js 0.20 KB
frames: eager client consumer (frames client + transport, lazy codec) 11.78 KB 0 B 0 B +5 B 11.80 KB ✅
page: base server components (hydrating + dynamic + frames + sf reference) 34.20 KB 0 B 0 B −170 B 34.21 KB ✅ assets.js 0.78 KB, decode.js 7.41 KB, lazy-page.js 0.04 KB, regions.js 1.06 KB, trace.js 9.35 KB, wire.js 3.48 KB
page: live server components (base + live/GET + action + isPending/latest) 41.62 KB 0 B 0 B 0 B 41.63 KB ✅ assets.js 0.78 KB, decode.js 7.41 KB, lazy-page.js 0.04 KB, regions.js 1.06 KB, trace.js 9.35 KB, wire.js 3.48 KB
page: compiled base server components (the base page as JSX: templates with class/style/attributes/events, For/Show; no spread) 36.04 KB 0 B 0 B −220 B 36.06 KB ✅ assets.js 0.78 KB, decode.js 7.41 KB, regions.js 1.06 KB, sc-comments.js 0.20 KB, trace.js 9.31 KB, wire.js 3.48 KB
page: compiled live server components (the compiled base page + live/GET + action + isPending/latest) 45.78 KB 0 B 0 B 0 B 45.80 KB ✅ eager (counted): web.js 24.24 KB; assets.js 0.78 KB, decode.js 7.41 KB, regions.js 1.08 KB, sc-comments.js 0.19 KB, trace.js 9.30 KB, wire.js 3.48 KB
page: base + router (base page + @solidjs/router: createRouter, two routes, preload, useNavigate) 41.62 KB 0 B 0 B −175 B 41.75 KB ✅ assets.js 0.78 KB, decode.js 7.41 KB, lazy-page.js 0.04 KB, regions.js 1.06 KB, server.js 1.05 KB, serverForms.js 3.58 KB, trace.js 9.29 KB, wire.js 3.48 KB
page: live + router (live page + @solidjs/router: createRouter, two routes, preload, useNavigate) 51.37 KB 0 B 0 B 0 B 51.41 KB ✅ eager (counted): client.js 29.41 KB; assets.js 0.78 KB, decode.js 7.41 KB, lazy-page.js 0.04 KB, regions.js 1.07 KB, server.js 1.05 KB, serverForms.js 3.30 KB, trace.js 9.31 KB, wire.js 3.50 KB
server: floor (getRequestEvent + isServer) 1.31 KB 0 B 0 B 0 B 1.33 KB ✅
server: renderToString (the server-render floor) 23.60 KB 0 B 0 B 0 B 23.62 KB ✅

⚠️ Over the brotli cap within the minified allowance (passes)

  • signals: + createStore: over brotli cap by 18 B; minified 43,976 B vs 43,964 B recorded with the cap (+12 B) — 8 B of the 20 B minified allowance left; +0 B minified over this PR's base

Bundled with Rolldown (what Vite ships), brotli q11, decimal KB. A scenario fails only when it is over its brotli cap and its minified size is more than 20 B over the minified recorded with the cap; over the cap within that allowance is brotli layout noise and passes with a warning. Caps and their recorded minified in scripts/size/scenarios.js; the floor and page caps in floor-caps.json are frozen (lower only, or Size-Exception: in the PR body). npm run ratchet lowers caps per RC; it never raises one (scripts/size/README.md).

@coveralls

Copy link
Copy Markdown

Coverage Report for CI Build 44796213173

Coverage remained the same at 79.459%

Details

  • Coverage remained the same as the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 1372
Covered Lines: 1152
Line Coverage: 83.97%
Relevant Branches: 1106
Covered Branches: 817
Branch Coverage: 73.87%
Branches in Coverage %: Yes
Coverage Strength: 29.96 hits per line

💛 - Coveralls

@codspeed

codspeed Bot commented Nov 20, 2026

Copy link
Copy Markdown

Merging this PR will improve performance by 31.6%

3 warnings

⚠️ Upgrade your CodSpeed plugin for Node.js 24

@codspeed/* 5.4.0 is only tested on Node.js 18, 20, and 22, so your Node.js 24 measurements may be inaccurate. Upgrade your @codspeed/* packages to 6.0.0 or later.

See affected benchmarks

⚠️ 2 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 1 benchmark with a significant change ran on different hardware

Its base and head results were measured on machines with a different CPU, core count or memory, so the change might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

⚡ 1 improved benchmark
✅ 200 untouched benchmarks
⏩ 5 skipped benchmarks1

Performance Changes

Benchmark BASE HEAD Efficiency
⚡ projection derive: write one NESTED field (reference) 1,245.7 µs 946.6 µs +31.6%

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.


Comparing tembo/agents-engine-model (f8f6f95) with main (99db9bc)

Open in CodSpeed

Footnotes

  1. 5 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

@ryansolid
ryansolid merged commit b944d04 into main Nov 20, 2026
13 of 14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

tembo Pull request created by Tembo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants