Repository navigation
feat(platform): platform abstraction layer (plan 114) - #190
Merged
Merged
Conversation
…e unused platform dep
… engine moves Centralizes TableDefinitionLike, DatabaseWriterLike, SchemaLike, QueryArgs, QueryPage, WithInput, RelationDefinitionLike, trigger-family types, aggregate/rank/pagination types, and helpers in @lunora/shard-engine/src/schema-types.ts. @lunora/do now imports these projections and re-exports trigger types from the engine package. SystemDatabaseReader stays DO-specific in system-reader.ts. Tests and repo-wide lint:types pass.
Moves query-args.ts and its unit tests to @lunora/shard-engine; updates do imports and index re-exports to pull from the engine package. Tests and repo-wide lint:types pass.
Moves rank.ts to @lunora/shard-engine; updates do imports, tests, and benches to pull from the engine package. Tests and repo-wide lint:types pass.
Moves aggregates.ts to @lunora/shard-engine; updates do imports, tests, and benches to pull from the engine package. Tests and repo-wide lint:types pass.
…engine Moves relations.ts and relation-predicates.ts to @lunora/shard-engine; updates do imports, tests, and re-exports to pull from the engine package. Tests and repo-wide lint:types pass.
…rd-engine Moves aggregate-sql.ts and aggregate-tally.ts to @lunora/shard-engine; moves aggregate-sql unit tests; updates do imports and re-exports. @lunora/do tests and @lunora/shard-engine tests pass.
Records that query/planning engine files are now in @lunora/shard-engine and the remaining @lunora/do files are Cloudflare/DO-specific.
Addresses CodeRabbit review on PR #182. - `ShardDirectory` becomes a union of `DirectShardDirectory` (name lookup) and `TwoStepShardDirectory` (`idForName` + `get`). The docs already described these as alternatives, but the interface required all three members, so a name-only registry had to stub out methods it has no concept of. Adds `resolveShard` so callers do not narrow by hand. - `ShardJurisdiction` widens as its doc comment claims, so a new Cloudflare jurisdiction is not a compile error here. - `SocketHost.getSockets(tag)` must now filter exactly. Permitting a host to ignore the tag and return every socket turns a tagged fan-out into a cross-tenant broadcast; hosts that cannot filter omit `setTag` instead. - `ShardAlarms.set` documented `null` clearing that its signature rejected; the doc now points at `delete()`. - Cloudflare capability matrix reports `crossShardFanout` and `mail` as emulated: both are Lunora-implemented over primitives (coordinator tier, Resend), not first-class platform products. - Conformance README example passes the required Vitest API argument. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The files moved out of `@lunora/do` during the engine extraction landed without a lint pass, leaving `eslint . --max-warnings=0` red for the package: re-exports written as import-then-export rather than `export…from`, unsorted imports, and unescaped `<` in JSDoc. All autofixable and behaviour-preserving. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Tagging was modelled as a single mutable tier: `setTag` after accept, its presence declaring that `getSockets(tag)` filters exactly. Cloudflare cannot honour that — DO tags freeze at `acceptWebSocket` — so the only conforming Cloudflare host was one that omitted `setTag` and therefore gave up tagged fan-out entirely, despite the platform supporting it natively. Split the two capabilities that were conflated. `accept` now takes durable `tags` every host must honour, and `setTag`/`removeTag` become the optional "tags are mutable" tier. A host with frozen tags can now route by tag and still be honest about what it cannot do. The TCK gains matching structure so it can run against hosts that are not the reference one: `alarms.get()` is awaited (the contract allows async), and host variance is expressed as presence-based hooks — `createSocket`, `simulateRecycle`/`restoreSocket`, `awaitAlarmFired`, and an optional `scheduler` — each reported as its own result rather than a silently skipped block. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`cloudflare-host.ts` implements `ShardHost`, `SocketHost`, and
`ShardDirectory` over `DurableObjectState`/`DurableObjectNamespace`, and
`ShardDO` now reaches the runtime through them instead of `state.*`:
- `runInTransaction` composes `runSerialized` around `transaction` — the
same `blockConcurrencyWhile` + `storage.transaction` pair as before,
expressed in contract terms. There is deliberately no raw BEGIN/COMMIT
fallback: workerd forbids it inside a Durable Object.
- the WebSocket upgrade goes through `socketHost.accept`, which accepts
and stamps the attachment back-to-back so no frame can reach an
unstamped socket.
- `ShardRunner` owns the `handleFetch`/`handleAlarm` seam; the
Cloudflare lifecycle is injected as host handlers until the router
itself moves into the engine.
`SocketHandle.id` is stable across hibernation: Cloudflare exposes no
native socket identifier that survives recycling, so the adapter mints
an id tag at accept and reads it back via `state.getTags`. `setTag` and
`removeTag` are omitted rather than stubbed, because DO tags are frozen
once accepted.
The conformance TCK now runs against these adapters in real workerd,
which closes plan 114's phase-1 gate ("TCK green on both hosts"). It
injects an `it` that wraps each body in `runInDurableObject`, so the
factory gets a genuine `DurableObjectState` rather than a double.
Verified load-bearing by mutation: dropping the tag filter or the
transaction call fails exactly the tests that should fail.
`handleFetchCloudflare` moved below the public WebSocket handlers and is
`protected` — it is the host-implementation hook a host-specific
subclass overrides, like `runInTransaction` beside it. Pure code motion;
the class's member set is unchanged apart from the five new seam
members.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Left over from the engine extraction: imports of `@lunora/shard-engine` split across several statements, unsorted import blocks, and re-exports written as import-then-export. All autofixable and behaviour-preserving; `eslint . --max-warnings=0` is green for the package again. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`realLunoraPackages` read `package.json` from every directory under `packages/`, so any non-package residue in a working tree — a half-scaffolded package, a `node_modules`-only leftover from an aborted install — threw and took the whole suite down before a single assertion ran. Skip directories with no manifest. This cannot mask a regression: a renamed or deleted package still disappears from the set and still trips the assertion that every template's Lunora dependency names a real one. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Restructure Next Steps into Done/Open (the tail had two overlapping number runs, 7-10 followed by 7-9), and record what the re-bind actually established versus what it did not. Adds the gap it surfaced: `SessionDO` is built entirely on the KV-style `storage.put`/`get`/`delete`/`list` surface, which `ShardHost` does not cover, so it is the one Durable Object that cannot be re-bound until a `ShardKvStore` contract exists. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Two members the engine needs before socket enumeration can leave the provider type behind: `SocketHandle.bufferedAmount` — `awaitWsDrain` paces delivery off the outbound queue depth, and nothing on the handle exposed it. A second host could accept sockets but never apply backpressure to a slow subscriber. Optional, because not every transport reports a queue depth; absent keeps the pre-backpressure behaviour rather than stalling. `SocketHost.handleFor(socket)` — enumeration yields handles while the runtime's message and close callbacks yield raw sockets, and nothing bridged the two. Any code comparing them (excluding a sender from its own broadcast) was forced back onto the provider socket. Required, not optional: returning `undefined` for an unknown socket is a valid answer, omitting the method is not. The engine's delivery helpers are retyped on the minimal surface they actually use — `FrameSink` (a `send`), `DrainableSink` (an optional `bufferedAmount`) — so a runtime socket and a `SocketHandle` both satisfy them. That is what lets the call sites migrate one at a time instead of in a single cut across 126 `WebSocket` references. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Accept went through the host but all eight enumeration sites still called `state.getWebSockets()`, so a non-Cloudflare host could receive connections and then be unable to broadcast to them. Three sites move: the two admin-introspection collectors, which only read attachments, and the whisper fan-out, which bridges its sender through `handleFor` and compares by handle id instead of socket identity. `readAttachment` is retyped on the attachment surface rather than `WebSocket`, so it accepts either. Five stay: `broadcastDelta`, `refreshSubscriptions`, `pokeShapeSubscribers`, `pollGlobalShapes`, and the relay-hub adapter. Their loop bodies hand the socket to `runSocketPool` and ~20 `WebSocket`-typed private helpers, so moving them is the same retyping exercise as extracting the router — not an independent change. The Cloudflare handle gains `bufferedAmount` (read through to the runtime socket) and the host gains `handleFor`, which falls back to rebuilding a handle from the durable id tag for a socket that predates this wake. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds the socket-enumeration status (three of eight sites moved, why the other five are coupled to the router extraction) and the two contract members that unblocked it. Also records a gap I had left implicit: the `__bench__` suites run under CodSpeed instrumentation and emit no local timings, and none of them exercise `runInTransaction` — the path that gained closure hops. Plan 114's perf-regression watch is still open. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`ShardHost` models the reactive engine — serialization, local SQL,
transactions, alarms. A Durable Object that keeps plain records instead
of running the engine needs ordered key lookup and prefix scans, and
routing it through `ShardHost.sql` would hand it a SQL dialect it does
not want. `ShardKvStore` (get/put/delete/list({prefix})) is that missing
surface, kept a separate contract so a host can implement one, the
other, or both.
The TCK gains a `ShardKvStore` block — read-back, idempotent delete, and
an exact prefix scan — and the reference host implements it over a Map
with a structured-clone on write, matching a real serializing store's
isolation. Reported as a gap, like the scheduler, when a host omits it.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
SessionDO was the one Durable Object still built entirely on `state.storage.*` — the KV surface `ShardHost` does not cover — so it could not run on a non-Cloudflare host. It now depends on `ShardKvStore` plus the shared `ShardAlarms`, both built by new adapters in `cloudflare-host.ts` (`createShardKvStore`, and `createShardAlarms` factored out of `createShardHost`). The same session logic now runs on any host that supplies a KV store. The adapters are structural, so the plain-object doubles the unit tests pass still satisfy them; the one capability the doubles may lack — `list` — is probed before the GC sweep routes through the contract, so that path stays a no-op there rather than throwing. The GC sweep and alarm arming had no coverage (the doubles exercised only create/get/revoke), so this adds a Map-backed double with the `list`/alarm surface and two tests: expired-record sweep with re-arm, and single-alarm-arm-on-create. The Cloudflare adapter is also run through the KV block of the workerd TCK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`@lunora/runtime` carried its own `resolveShard`/`applyJurisdiction` over a structural `ShardNamespaceLike`, duplicating the `ShardDirectory` contract `@lunora/platform` defines — and three call sites hand-rolled `namespace.get(idFromName(...))` on top of that. So the contract had no production consumer at all; only the TCK exercised it. `resolveShard` now adapts the Cloudflare-shaped namespace to a `ShardDirectory` and delegates to the contract's own `resolveShard`, and the three hand-rolled sites (scheduler completion, dynamic shard registry, health probe) route through it. The historical preference — `getByName` when present, else `idFromName` + `get` — is preserved, but now lives in one place. A mutation that forces the two-step branch fails the resolve-shard suite, so the preference is genuinely under test. Runtime adapts locally rather than importing `@lunora/do`'s `createShardDirectory`, which takes a real `DurableObjectNamespace`: runtime resolves structural doubles, and depending on the Cloudflare host package would be the wrong edge. It gains a direct dependency on the zero-dep `@lunora/platform` contract instead. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`__bench__/reactive-cache.bench.ts` has never run: the package had a bench file but no `vitest.bench.config.ts` and no `test:bench` script, unlike `@lunora/do` and `@lunora/observability`. Matters more now that twelve modules moved into this package.
…ction-layer # Conflicts: # packages/codegen/package.json # packages/d1/package.json # packages/do/package.json # packages/hyperdrive/package.json # packages/sql-store/package.json # packages/testing/package.json # pnpm-lock.yaml
Both inherited from #236 ("bundle search-core"), which merged into alpha with `Lint (eslint)` and `Lint (api surface)` red: - `@lunora/search-core` is `private: true` and packem now inlines it into `@lunora/server`'s dist, so it correctly sits in devDependencies — but `import/no-extraneous-dependencies` cannot see the bundling and flagged `src/schema.ts`. Scoped exemption with the reason. - `SearchLanguage` / `SearchStrategy` stopped being tracked re-exports and became inlined declarations, so the server and lunora snapshots drifted. Also ignores `vitest.bench.config.ts` in `@lunora/shard-engine`'s eslint config, matching `@lunora/do`'s — it is not in any tsconfig, so type-aware linting cannot parse it.
The two largest untested modules in the package: 593 and 300 lines with no suite of their own. 56 tests across the durable accumulator's fold rules (MIN over a NULL-seeded column, last-error stickiness, per-distinct scan and index attribution, the attacker-reachable path cap, bucket flooring and per-path retention) and the explainer's caps, grounding, degraded arms, prompt fencing and inference deadline.
The COALESCE in the accumulator's MIN only matters when a row already exists with a null minimum — reachable via a legacy or path-only row — and dropping it survived the first suite. Covered now; all twelve mutations across both modules are caught. Both modules measure 100% on every metric, taking the package from 70/65/68/70 to 90.09/77.72/85.95/90.10. Ratchet raised to sit just under that, verified to fail all four thresholds if the new suites are removed.
- `lunorash/platform` subpath (§8.4), wired into the umbrella's re-export parity test so it cannot silently drop its barrel. - `@lunora/d1`'s src no longer imports `@cloudflare/workers-types` (§5.1's ambient scrub): the two drizzle-driver casts target drizzle's own `AnyD1Database`. The tsconfig keeps the ambient types for the test tier alone — the workerd suite uses Cloudflare's typed `Response.json<T>()` overload — with a breadcrumb recording why. - `plans/TEMPLATE.md` with the mandatory **Platform parity** section (§5.6). The section had nowhere to live: `plans/` had an index and no template. `plans/README.md` now points new plans at it. - Plan 114 records status for §5.1, §5.2 and §5.6, which had none — including where the `shard-do.ts` split stops and the two measurements that say why, so it is not re-attempted blind.
… into feat/platform-abstraction-layer
Fan-out is O(subscribers) and `SocketHandle` sits on that loop: whisper delivery, shape pokes and delta delivery all walk every socket calling `deserializeAttachment` then `send`. `CloudflareSocketHandle` forwarded both to the runtime socket, so each one cost two extra call frames per socket — measured at +1.11 ns/socket against a per-socket body of only ~6-7 ns, i.e. +11% at 128 subscribers and +13% at 1024 on whisper fan-out, with fixed per-frame cost unchanged. The wrapper existed for one reason: to carry `id`, which is read a handful of times and never inside the loops. So identity moves out-of-band to `SocketHost.idFor` and hosts return their transport socket unchanged. Cloudflare already had the machinery — the durable `lunora-socket:` accept-time tag plus the `fallbackIds` WeakMap. This also collapses the dual identity the wrapper created: enumeration yielded handles while `webSocketMessage`/`webSocketClose` yield the transport socket, so per-socket WeakMap memos could key on either and diverge. With one object, `handleFor` is an ownership test rather than a translation, and `liveHandles` + the `mappedByTag` memo that existed purely to avoid re-mapping N sockets to N wrappers per broadcast are gone. `ShardRunner.socketFor` stays — the contract still permits a wrapping host, and for that host it is what reconciles the identities — but it is per frame, never per socket. Verified: platform 36, platform-cloudflare 15, shard-engine 754, do 501, and the workerd gate at 563 including the hibernation legs, which is the real regression net for socket identity across a recycle.
`@lunora/platform`'s doc still listed `SocketHost` without `idFor` and said nothing about returning the transport socket as the handle — now a third behavioural note, since a host that wraps compiles fine and is simply slower with a split identity. `shard-engine`, `observability` and `platform-cloudflare` shipped as published packages with no `docs/`, against a 47-of-51 convention, so they appeared in the packages index with no page behind them. Each now has one, plus the `packages-metadata.json` feature entries the docs generator was warning about (including `notify`, whose warning predates this branch — its `docs/` folder is still missing and is not mine to invent). Two new category slugs (`platform`, `observability`) get titles, colors and an ordering hint rather than relying on the humanized fallback. Also adds `apps/docs/src/content/changelogs/` to `.prettierignore`: it is git-ignored generated output, but prettier does not read .gitignore, so running the docs build locally failed the repo prettier gate.
`recordAuthEvent` and `isDevEnvironment` were imported as values but only
ever referenced from `{@link}` tags, which satisfies `no-unused-vars`
without being a real use — so both gates stayed green while the imports
were dead. Reported by github-code-quality.
The links become code refs rather than being deleted: they point at
helpers in other packages, and leaving `{@link}` on an unimported symbol
trips `jsdoc/no-undefined-types`. Swept the other 30 files whose imports
this branch rewrote by script — no others of this class.
Also adds the `@lunora/notify` docs page, the last published package
without one, so all 51 now have docs.
The observability extraction moved 52 names out of `@lunora/do`, and 50 of them left `lunorash` with them — reachable only by adding `@lunora/observability` as a direct dependency, which is the one thing an umbrella user installed the umbrella to avoid. With this subpath the migration is a path swap (`lunorash/do` -> `lunorash/observability`) and the umbrella's public surface is whole again: zero names missing against alpha.
114 §5.5 gates the emitted `ctx.*` surface on the target but not the emitted host entry: `emit.ts` writes the `ShardDO` subclass and worker entry target-blind, and `lunorash` depends on `@lunora/do` — hence `@lunora/platform-cloudflare` — unconditionally. So an `aws` target today would still emit a Durable Object and still install the Cloudflare host. Not a packaging bug: per D2 `@lunora/do` IS the Cloudflare host, so making its own host optional is incoherent. The switch belongs where D1 put it — codegen emits the host entry per target, and an AWS project never pulls `@lunora/do`. Deliberately unbuilt until plan 115 phase 1 supplies a second host, since with one host it is a seam nothing exercises. Recorded in both plans because neither said it and 115 phase 1 is where it bites.
They were always one arc — 114 the provider-neutral half, 115 the AWS implementation consuming its seams — and every cross-reference had to be maintained in both. That is how the host-entry gap ended up recorded in neither until it was found by asking how a user switches provider. `plans/114-multi-provider-platform.md` keeps the abstraction work as §§0–5 and appends the AWS target as §§6–9, with one merged phase table (0–4 shipped, 5–10 ahead), one risk list and one open-questions list split by which half they belong to. §§0–5 keep their numbering deliberately: `@lunora/do`, `@lunora/d1` and `@lunora/config` cite `plan 114 §5.1/§5.2/§5.3` in source comments, and all three still resolve. Also corrects AGENTS.md, which still claimed there is deliberately no `@lunora/platform-cloudflare` package — this branch created it.
"Should @lunora/bindings move into @lunora/platform-cloudflare?" has a measurable answer, so the plan now states the measurement rather than the opinion: bindings, storage, browser, hyperdrive, scheduler, d1 and queue have ZERO real provider imports in src — they are facades over the *Like contracts, which is what §8 already assumes (ctx.kv becomes DynamoDB behind KVNamespaceLike). Only @lunora/container carries real provider code, and it already isolates it behind the /do subpath. The rule: provider differences go through *Like injection plus the capability matrix (D3); a package carrying real provider code isolates it behind a subpath. The line is whether app code imports it — apps depend on @lunora/bindings by name, so moving it breaks them and forces every new host to reimplement the facade instead of supplying a binding. §5.3 also records what actually shipped for the config split — stays put — and names it as D6's one open edge: cloudflare-driver.ts sits in a neutral package with no subpath boundary. Left unsplit on the same reasoning that defers the host-entry switch, with phase 8 cross-linked to revisit it once @lunora/aws gives the split a second consumer.
…dflare Closes D6's one open edge: provider code sat in a nominally neutral package with no subpath boundary — the arrangement D6 rejects everywhere else. Ten modules move to `src/cloudflare/`: the wrangler validator, path and secret-variable readers, the three reconcilers, remote bindings, the Workers-cache probe, the alchemy translator and the Cloudflare driver. They keep their public names — the barrel preserves the aliases the root index applied (`ReconcileCronsResult`, `CLOUDFLARE_DRIVER`), so only the import path changes. Binding *inference* deliberately stays at the root, per §5.3's own line: inference is provider-neutral, emission is wrangler-shaped. The neutral root keeps `ResourceGraph`, `DeployDriver`, the driver registry, project config and target resolution, and `.dev.vars` — 168 exports with zero wrangler names left on it, verified against the built d.ts. Consumers repointed: 13 files across `@lunora/cli` and `@lunora/vite`, plus the playground smoke test. Suites unchanged at config 504, cli 894, vite 186.
HIGH — @lunora/search-core is `private: true` and 404s on the registry, but shard-engine, sql-store and do declared it in `dependencies`. packem externalizes dependencies and inlines everything else, so all three shipped an unresolvable bare import AND a manifest npm cannot install. Moved to devDependencies (the pattern @lunora/server and @lunora/d1 already use); verified all three dists now inline it. `do` dropped it entirely — its src never imported it. MEDIUM — readFunctionMetricBuckets had no LIMIT on either arm, and `getMetrics` calls the all-paths arm on every Studio Metrics load: ~144k rows and ~60MB for 100 active functions in a ~128MB isolate. Now bounded, selected newest-first so the cut drops the oldest history, then reversed to keep the oldest-first order a chart plots. readFunctionMetricIndexHits bounded too, for the same stated policy. MEDIUM — the UNTRUSTED_FENCE comment claimed the caps made the marker unforgeable. They do not: it is 38 chars against caps of 2000 and 200, so attacker-shaped error text could close the block early and continue where Lunora's curated guidance appears. Every fenced field is now stripped of the marker, and the comment says what actually holds the boundary. Socket host: `fallbackIds` is checked before `hasIdTag` so the per-frame path is an O(1) WeakMap hit rather than a `getTags` host call; `idFor` no longer records minted ids into that map (a read must not launder a refused socket into ownership) and no longer throws on a socket the runtime has forgotten. Tests: 6 mutations across the new fixes all caught, including the three a reviewer proved the previous suites missed — index-hit keying on table or index alone, and a path cap that guarded only the accumulator. Also: no-secrets suppression removed from admin-rpc-args.ts entirely rather than re-bounded (backticks were inflating the entropy score, so rewording cleared it); the redundant file-scoped eslint exemption in @lunora/server dropped in favour of alpha's narrower inline one; AdvisorProcedure exported from the engine barrel after the alpha merge; stale @lunora/errors pin, stale README samples and three comments describing the deleted wrapper corrected.
Contributor
|
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Separates the Lunora engine from the Cloudflare host, so a second target implements a contract rather than forking the codebase. Plan 114, phases 0–5, plus three follow-ups that merged in (#216, #218, #225, #232, #233).
The headline
Six real Cloudflare imports remain across every package's
src/, in exactly the four packages that should have them:platform-cloudflareDurableObjectNamespace,DurableObjectState,DurableObjectStub,WebSocketdoDurableObjectStoraged1D1Databaseworkflowcloudflare:workers,cloudflare:workflowsZero in
shard-engine,platform,observability,runtime,server,sql-store,config,codegen,client,testing,hyperdrive. (Other packages mention Cloudflare in comments and error strings — "mentions" and "depends on" are different claims, and only the second one matters.)Four new packages
@lunora/platform— the contracts. Zero dependencies:ShardHost,SocketHost,ShardDirectory,ShardKvStore,SchedulerHost, the canonical binding*Likeprojections,PlatformCapabilities. A behavioural TCK ships at/conformance.@lunora/shard-engine— the host-neutral reactive engine, extracted from@lunora/do.@lunora/platform-cloudflare— the Cloudflare adapters. Depends only on the contracts, and@lunora/dodepends on it.@lunora/observability— host-neutral telemetry, logs, metrics, traces, issue grouping.@lunora/dokeeps the Durable Object classes and the code that genuinely needs them.Conformance is the reason to believe any of this
Two suites, each run against two hosts — an in-memory reference and real workerd through the composition root:
@lunora/platform/conformance— 20 legs on what a host must provide: serialized mutations, transaction rollback, cursor read shapes, durable alarms, socket accept/send/close, attachment round-trip across recycle, deterministic shard placement, scheduler enqueue/cancel and dead-letter invariants.@lunora/shard-engine/conformance— 10 legs on what the engine does with them: OCC snapshot-CAS → 409 with no retry,pokeStart/pokePart/pokeEndframing under one poke id, per-socket cursor resume, and RLS identity under live subscription.That last one is the sharpest. A cohort multicast computes one delta under the anonymous identity and ships it to every subscriber — correct only while a shape is identity-blind. The suite pins the uniformity gate from both directions, so neither leg passes on a gate that simply refuses everything.
Findings worth reviewer attention
Several are the same defect wearing different clothes: an abstraction nothing exercised was wrong, and only wiring it up said so.
ShardSqlExecwas wrong in both directions. It promised arowsAffectednothing read and omittedone(), cursor iteration anddatabaseSize— all of which the engine uses. A second host could have satisfied that type and failed at runtime.The canonical binding projections had no consumers. 17
*Liketypes nothing imported, while four packages kept their own — and the packages' copies were the correct ones, because platform's were written from the Cloudflare docs rather than from use (D1DatabaseLikemadewithSessionoptional when.global()read-your-writes requires it). The shipping definitions moved in; the barrel is generated from whatbindings.tsdeclares so they cannot silently diverge again.A native method lost its receiver.
toDirectorypassedgetByName: namespace.getByNameby reference.DurableObjectNamespace's methods are native and need their own receiver, so workerd rejected every shard resolution with "Illegal invocation", surfacing as a bare{ code: 'INTERNAL' }. It type-checked and passed every unit test, because those doubles are closures and closures do not care whatthisis.ConformanceHostcould not observe what a socket was sent — so no delivery guarantee was assertable, and the platform suite's own send leg only checked thatsenddid not throw. A host that silently dropped every frame would have passed. Related:ReferenceSocket.receivedis typed(string | ArrayBuffer)[]but the send path encoded unconditionally, making the string arm unreachable. Write-only state does not get type-checked by use.The deploy target was selectable in machinery only.
resolveDeployDriver(target)andrunCodegen({ target })both accepted one; nothing supplied it. Wiring it up founddeployreading only the flag — so a typo'dlunora.jsonfailedcodegen/prepare/devand shipped fine fromdeploy— anddevdropping--targetwhen backgrounding, which is the automatic path for an AI agent. Error-levelplatformDiagnosticsalso exited 0, which was the root cause the target validation had been patching around.@lunora/codegenpinned@lunora/platformto1.0.0-alpha.1— a version that does not exist on the registry. Masked by workspace overrides; it would have frozen the published dependency forever.Two deliberate breaks
@lunora/dono longer re-exports observability — 52 exports removed, 357 → 305. Re-exporting would put the Cloudflare package in the middle of a dependency it does not own, and make a second host reach telemetry through Cloudflare. Nothing in the repo imported them that way and codegen references none, so no generated code changes; the exposure is external.DriverToolchain.secretList/secretPut/tailare optional — an IaC-backed target declares secrets as resources inside its program and has no CLI step. Absent now means "no command for that", which the CLI reports rather than skipping.@lunora/do's own frozen surface held through every extraction: 357 exported names, unchanged, until the deliberate removal above.Two coverage floors
Flagged because a lowered gate should be a review decision, not a config footnote.
@lunora/shard-engine@lunora/do's suite, which still exercises them — as that package's coverage.@lunora/observabilityfunction-metrics+issue-explainer, exercised only throughShardDO, whose suites stayed behind.Both are ratchets set just under measurement, documented in-config.
Verification
@lunora/do@lunora/shard-engine@lunora/observability@lunora/runtime@lunora/codegen@lunora/cli@lunora/config@lunora/vite@lunora/platform/platform-cloudflarebuild:packages(53 projects),lint:types,lint:eslint,lint:prettier,lint:package-json,api:check(43 snapshots)The platform family is registered with the API-surface guard — a contracts-only package's surface is the product.
What this does not do
The
shard-do.tssplit — done, and where it stopsshard-do.tswent 9,703 → 8,562 lines. What came out is the block that was genuinely a separate thing: ~1,100 lines of admin-RPC argument parsing — theunknown→ typed parsers, their argument interfaces, and their validation helpers — nowpackages/do/src/admin-rpc-args.ts. Move-only, no logic edits, which is the sequence plan 114 §5.2 prescribed ("move-only refactor first, then the host-interface cut").It stops there, and the measurements say why. What remains is one class with 273 members averaging 18 lines, the largest being 319. There is no oversized method to break up. Two candidate cuts were measured and rejected on the evidence:
spans,traceSampling,metrics,logs,dispatchSpans,currentRequestTrace, … — are not telemetry-private.handleFetchCloudflaretouches nearly all of them, andreadAdminWildcardOp,dispatchLifecycle,recordShapeErrorandhandleRecordContainerEventtouch the rest. The extraction would have to publish all 11 through the new collaborator, which is a struct behind an indirection, not encapsulation.thismembers (1,651 lines total), and 51 never touchthisat all — but 37 of those are the 3-line abstract hooks a codegen subclass overrides, so they must stay on the class. The honest remainder is ~200 lines, scattered across unrelated concerns.handleFetchCloudflare/handleAlarmCloudflare/webSocketClose/webSocketErroralso cannot leave: the platform invokes them on the instance, so they are the DO's lifecycle surface by definition. The file is large because a request entry point legitimately reaches the telemetry, admin and subscription state — which is a case for the host-interface cut §5.2 named as the second step, not for more moving.The host-neutral lines are out
All ~2,800 of them. Twelve modules that take a
SqlExecand a schema and never touch a Durable Object moved from@lunora/doto@lunora/shard-engine: admin export/import, data migrations, PITR, the SQL console, settings, the TTL sweep, the four external-source ingest modules, and the mail and queue catchers.@lunora/do/srcis now 11,693 lines against the engine's 19,031.@lunora/do's frozen surface is byte-identical across the whole change — 305 names, diffed name-for-name against the pre-move build,api:checkreporting 196 declaration-site relocations and zero removals. Test count is conserved exactly:602 + 653became501 + 754, with the six suites that drive a realShardDOstaying in@lunora/do. Git recorded every one of the twelve as a rename at 95–99% similarity.function-metrics(593 lines) andissue-explainer(300) had no suite of their own — the two largest untested modules in the new package, exercised only throughShardDO. Both now have one and both measure 100% on all four metrics, taking the package from 70/65/68/70 to 90.09/77.72/85.95/90.10. The placeholder coverage ratchet is raised to sit just under that, and verified to fail all four thresholds if the new suites are removed. All twelve mutations tried across the two modules are caught — the twelfth (dropping theCOALESCEfrom the accumulator'sMIN, which only matters for a row that already has a null minimum) survived the first pass and drove one more test.One regression surfaced and is fixed:
@lunora/testing's telemetry drift guard still importedContextTracer/ContextMetrics/SpanHandlefrom@lunora/doafter the observability extraction removed them, solint:typeswas failing on this branch. It now imports from@lunora/observability.No non-Cloudflare host exists. By the repo's own rule — one adapter is a hypothetical seam — the split is verified by construction rather than by a port. The strongest evidence it is real is that the conformance suites, run against two hosts, caught the four defects above that inspection had missed. That is better than nothing and weaker than plan 115.
🤖 Generated with Claude Code
https://claude.ai/code/session_0137KKKmGRyB69XgLzMaFgSh