peer-floors: add a sibling-coherence check — a floor that moves generation without its siblings publishes an unresolvable manifest

[drewstone]

The defect

A peer floor that moves a generation is never a single edit. @tangle-network/agent-interface, agent-runtime, agent-knowledge, agent-eval, sandbox, sandbox-ui, and agent-profile-materialize each declare the interface generation they accept. Moving one of them without its siblings publishes a manifest that cannot resolve, and nothing in this repo catches it: pnpm install succeeds, tsc --noEmit is clean, the suite is green, and the break appears only in a consumer's npm install.

src/peer-floors/ already owns the adjacent gate — it audits an installed tree against the floors this package declares, and its own header documents why typecheck cannot see a floor violation. It does not check whether the floors in one manifest are coherent with each other.

Measured evidence, from this repo

Precedent that got it right — #432 (chore(deps): move onto the agent-interface 0.47 line, merged 2026-08-12T22:06:48Z) touched 25 files: package.json, both create-agent-app template manifests, the lockfile, and the docs the pins appear in.

#444 initially did not. Its first two commits moved the interface line in package.json alone. The value audit on head a30eafce came back red:

🔴 Value Audit — redundant-or-flawed

Right and necessary lockstep move (the old interface cap made the published set un-installable), but executed across 2 files where the repo's own doctrine and prior lockstep PR (#432, 25 files) require the pin to move in every place it appears — it leaves the create-agent-app templates below the new floor

Two more commits were needed to clear it — d32749fd chore(create-agent-app): move template pins to the interface 0.53 lockstep and c435f3fc chore(deps): complete the lockstep — sibling peer floors and brand 1.5.0 — after which the audit returned sound. Net cost of the miss: one red audit, two extra commits, and roughly 90 minutes of review round-trips (05:11:58Z red → 06:43:05Z sound).

Why it matters beyond this repo. The same class of miss, one level up, produced a live break the same morning. agent-interface@0.54.0 published 2026-08-16T04:30:11Z; agent-knowledge@8.0.2 moved its interface peer to >=0.54.0 <0.55.0 while agent-runtime@0.135.3 still declared >=0.53.0 <0.54.0. Disjoint ranges, so no interface version satisfies both:

$ npm install --dry-run @tangle-network/agent-runtime@latest @tangle-network/agent-knowledge@latest
npm error   peer @tangle-network/agent-interface@">=0.54.0 <0.55.0" from @tangle-network/agent-knowledge@8.0.2
npm error Conflicting peer dependency: @tangle-network/agent-interface@0.53.0
npm error   peer @tangle-network/agent-interface@">=0.53.0 <0.54.0" from @tangle-network/agent-runtime@0.135.3

A manifest gate that ran on agent-knowledge's release would have failed that commit before it published. See tangle-network/agent-sdk#190 for the release-order half of the same arc.

Proposal — extend src/peer-floors/, do not add a new module

Add a sibling-coherence check on the same subpath and the same agent-app-peer-check bin, beside check.ts and dependency-source.ts. It reads manifests from the registry, not an installed tree, so it answers a different question from the existing gate:

For every first-party peer this manifest declares, does the version at the bottom of that peer's floor itself accept the interface generation this manifest declares?

Concretely, given this repo's own peerDependencies:

1. Read the declared interface range R — for example >=0.53.0 <0.54.0.
2. For each other @tangle-network/* peer, take the floor version (the >= bound) and read that exact published version's own interface range R_sibling.
3. Fail when R ∩ R_sibling = ∅.

That is the exact shape of both failures above:

• chore(deps): adopt interface 0.53 lockstep with runtime 0.135.3 and sandbox 0.27.0 #444, first commit: interface floor moved to >=0.53.0, while the agent-runtime floor still pointed at 0.133.0, whose own interface peer was on the 0.47 line. Empty intersection → fail.
• agent-knowledge@8.0.2: interface peer >=0.54.0 <0.55.0, while its agent-eval floor would have to be a release that accepts 0.54. Any floor below 0.145.16 → empty intersection → fail.

Two properties worth keeping:

• Fail on unreadable, never pass. The existing module already models this with the absent-but-declared verdict — "reported as a failure rather than a pass this did not earn". A registry read that fails must produce the same, not a silent skip.
• Cover the template manifests too. create-agent-app/template/_package.json and create-agent-app/template-chat/_package.json are what chore(deps): adopt interface 0.53 lockstep with runtime 0.135.3 and sandbox 0.27.0 #444's red audit named, and they hold the same pins with no peerDependencies of their own. The check should treat a template pin below this repo's own floor as a violation, which is the drift the existing tests/create-agent-app.test.ts gate covers by assertion and this would cover by rule.

The result: a commit that moves one floor a generation without its siblings fails in the authoring repo, instead of on a consumer's npm install hours later.

[drewstone]

The same class of miss recurred twice in the following two hours

The issue body cites agent-knowledge@8.0.2 moving its interface peer to >=0.54.0 <0.55.0 while agent-runtime@0.135.3 held >=0.53.0 <0.54.0. Two more data points landed after it was filed.

1. agent-interface@0.55.0 published 2026-08-16T06:44:30Z — 2h14m after 0.54.0 — and took latest. agent-knowledge@8.0.2's brand-new <0.55.0 ceiling excluded it immediately, so the package that had just fixed the break became the one blocking npm install @tangle-network/agent-knowledge@latest @tangle-network/agent-interface@latest. Fixed by tangle-network/agent-knowledge#135 (8.0.3, >=0.54.0 <0.56.0).

2. agent-core@0.9.2 published depending on interface 0.55.0 exactly, while agent-eval@0.145.16 pinned 0.54.0 exactly and sandbox@0.27.0 pinned 0.53.0 exactly. Three first-party packages hard-pinning three different generations at the same instant.

At the moment 0.55.0 landed, eight first-party packages declared four generations at once — 0.47, 0.53, 0.54, 0.55 — and latest pointed at the one the fewest of them accepted.

What this adds to the proposal

The check as described compares this manifest's interface range against each first-party peer's floor version. Two refinements the new evidence argues for:

• Cover exact dependencies, not only peerDependencies. agent-core, agent-eval and sandbox each carry "@tangle-network/agent-interface": "<exact>" as a plain dependency. npm nests those rather than failing, so they never produce a clean ERESOLVE — they produce two copies of the schema module in one tree, which is a zod instance-identity hazard rather than an install error. A sibling-coherence check that reads only peers cannot see it.

• Report the WIDTH of the declared window, not only its coherence. Every failure in this arc traces to a one-generation window meeting a publish cadence faster than an adoption wave. A manifest declaring >=X <X+1 for a dependency whose upstream ships a minor every few hours is coherent on the day it is written and broken by the next publish. The gate should be able to say "this window admits exactly one generation of a package that published 3 generations in 26 hours" as a warning, independent of whether the siblings currently agree.

The release-order half is tangle-network/agent-sdk#190. The wave that moved every first-party window to hold the generations it verifies against: tangle-network/agent-runtime#878, tangle-network/agent-knowledge#135, tangle-network/sandbox-ui#254, tangle-network/agent-dev-container#5742.

[drewstone]

I committed this exact defect while filing this issue

Worth recording as the sharpest evidence available, because it is first-hand rather than archaeological.

In tangle-network/sandbox-ui#254 I widened the interface peer from >=0.36.0 <0.54.0 to >=0.36.0 <0.56.0 in package.json, and stopped there. scripts/package-smoke.mjs carries two constants coupled to that range:

const expectedAgentInterfaceRange = ">=0.36.0 <0.54.0";
const expectedAgentInterfaceVersion =
  process.env.SANDBOX_UI_AGENT_INTERFACE_VERSION ?? "0.53.0";

The first is asserted verbatim against the PACKED manifest. Widening package.json alone makes pnpm test:package fail deterministically. Release 0.103.1 (8c012eb) had moved both in the same commit; I did not.

What every other signal said while the defect was in the tree:

check	result
pnpm install	clean, interface 0.53.0 -> 0.55.0
pnpm typecheck	exit 0
pnpm test	Test Files 77 passed (77), Tests 1048 passed (1048)
pnpm test:package	would have failed — and I did not run it

My own PR "Proof" section listed the first three and omitted the fourth. The sound-with-nits audit named that omission as the tell and found the constants. Fixed in 70f8118; pnpm test:package now exits 0.

This is the same shape as the #444 miss and the agent-knowledge 8.0.2 miss, at a third scale: a version range that appears in more than one place, moved in one of them. The three instances differ only in where the second copy lives — a template manifest, a sibling peer floor, a packaging-guard constant.

That argues for widening the proposed check's scope slightly: the gate should locate every occurrence of a first-party version range in the repository — manifests, template manifests, packaging and smoke scripts, and the ecosystem registry where one exists — and fail when they disagree, rather than comparing peer floors alone. agent-dev-container already does a version of this for its own registry (scripts/check-ecosystem.mjs blocked my push there until docs/ecosystem/registry/external.json moved with the manifest), which is a working precedent to copy rather than invent.

Note the asymmetry that makes this worth automating: install, typecheck and the unit suite are the three checks an author runs by reflex, and none of them can see this class of defect. It surfaces only in a packaging step or a consumer's npm install.

[drewstone]

Where the check belongs in the existing test file, and the fixture that proves it works

Agreed with the proposal. Adding the concrete landing site, because src/peer-floors/check.test.ts already sets the bar this check has to clear.

The test home is the self-audit block, not a new file

check.test.ts line 108 already holds:

describe('this package audits itself', () => {
  it('declares support for the current Interface line without claiming the next one', async () => { … })
  it('declares peer floors its own dev install satisfies', async () => { … })
})

That block already reads this repo's own manifest and reasons about the interface line it declares.
Sibling-coherence is the third assertion in that same block — "the floors I declare are satisfiable with each other" — beside "the floors I declare are satisfiable by my install".
It is the same question one level out, so it belongs in the same describe, not in a new module.

Reuse satisfiesRange, do not write a second range engine

check.ts:186 already exports satisfiesRange, and the test at line 24 pins the exact rule this check depends on:

expect(satisfiesRange('0.38.0', '^0.36.0')).toBe(false)

The 0.x minor-lock is the whole reason a generation crossing is unresolvable. The coherence check is then just:

R           = this manifest's interface range
R_sibling   = the interface range declared by each sibling's FLOOR version
fail when   no published interface version satisfies both

A second range implementation would be free to disagree with the one the shipping gate uses, which is how a guard starts reporting false passes.

The calibration bar this file already enforces

Line 61 of the same file:

CALIBRATION. A guard that cannot be shown to FAIL is indistinguishable from one that does nothing — and the shape of this check ("look a version up, skip if you cannot find it") fails OPEN by construction.

A registry-reading check fails open in exactly that way, and harder, because a network read has more ways to return nothing than a filesystem read.
So this check must ship with the same committed-fixture pair the existing gate uses (fixtures/below-floor and fixtures/satisfied, under fixture_modules so the tree is committable).

Use the real break as the failing fixture. Commit the manifests measured on 2026-08-16:

package	version	declared interface range
agent-runtime	0.135.3	>=0.53.0 <0.54.0
agent-knowledge	8.0.2	>=0.54.0 <0.55.0

Empty intersection. The check must reject that pair, and the test must assert the rejection names the generation crossing — the same way it('names the minor-lock in the failure, because that is the fix') at line 87 does today.
A fixture drawn from the actual incident cannot drift into testing a hypothetical.

Keep the registry read out of the test path: pass the sibling manifests in, the way it('declares peer floors its own dev install satisfies') passes the manifest in rather than discovering it. The network belongs in the cli.ts entry point, not in a unit test.

One dependency shape the check must catch that a peer-only scan will miss

agent-eval@0.145.17 declares the interface as an exact regular dependency, not a peer:

$ npm view @tangle-network/agent-eval@0.145.17 dependencies.@tangle-network/agent-interface
0.55.0

A hard exact dependencies pin is what produces Conflicting peer dependency in a consumer's install, and a check that reads only peerDependencies would score that manifest as coherent while it is the thing breaking the tree.
The check should read dependencies and peerDependencies for every @tangle-network/* sibling.

Scope note — this check survives the 1.0 decision, but its trigger rate should collapse

I posted measured evidence on tangle-network/agent-sdk#190 that ten consecutive interface generations (0.45.0 → 0.55.0) removed zero exported symbols, and that agent-runtime@0.135.3 and agent-knowledge@8.0.1 — both capped <0.54.0 — typecheck clean against interface 0.55.0 with skipLibCheck: false.
The recommendation there is 1.0 plus caret ranges, which would retire the single-generation window that makes these crossings frequent.

That does not make this check redundant. It makes it cheap: under ^1.0.0 a genuine major crossing is rare, and this is exactly the gate that should catch it when it happens. Build it, and expect it to stay quiet.