Skip to content

feat(platform): platform abstraction layer (plan 114) - #190

Merged
prisis merged 123 commits into
alphafrom
feat/platform-abstraction-layer
Jul 30, 2026
Merged

prisis merged 123 commits into
alphafrom
feat/platform-abstraction-layer

Conversation

@prisis

@prisis prisis commented Jul 25, 2026 •

Copy link
Copy Markdown
Member

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:

Package Imports
platform-cloudflare DurableObjectNamespace, DurableObjectState, DurableObjectStub, WebSocket the adapter itself
do DurableObjectStorage the Durable Object class
d1 D1Database provider adapter by definition
workflow cloudflare:workers, cloudflare:workflows provider add-on by definition

Zero 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 *Like projections, 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/do depends on it.
  • @lunora/observability — host-neutral telemetry, logs, metrics, traces, issue grouping.

@lunora/do keeps 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/pokeEnd framing 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.

ShardSqlExec was wrong in both directions. It promised a rowsAffected nothing read and omitted one(), cursor iteration and databaseSize — 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 *Like types 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 (D1DatabaseLike made withSession optional when .global() read-your-writes requires it). The shipping definitions moved in; the barrel is generated from what bindings.ts declares so they cannot silently diverge again.

A native method lost its receiver. toDirectory passed getByName: namespace.getByName by 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 what this is.

ConformanceHost could not observe what a socket was sent — so no delivery guarantee was assertable, and the platform suite's own send leg only checked that send did not throw. A host that silently dropped every frame would have passed. Related: ReferenceSocket.received is 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) and runCodegen({ target }) both accepted one; nothing supplied it. Wiring it up found deploy reading only the flag — so a typo'd lunora.json failed codegen/prepare/dev and shipped fine from deploy — and dev dropping --target when backgrounding, which is the automatic path for an AI agent. Error-level platformDiagnostics also exited 0, which was the root cause the target validation had been patching around.

@lunora/codegen pinned @lunora/platform to 1.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/do no 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/tail are 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.

Package Floor Why
@lunora/shard-engine 46/25/43/46 Extraction moved modules out from under @lunora/do's suite, which still exercises them — as that package's coverage.
@lunora/observability 70/65/68/70 Same, and the residue is function-metrics + issue-explainer, exercised only through ShardDO, whose suites stayed behind.

Both are ratchets set just under measurement, documented in-config.

Verification

@lunora/do 501 + 62 workerd
@lunora/shard-engine 754
@lunora/observability 191, coverage ratchet 76/84/89/89
@lunora/runtime 783
@lunora/codegen 932 (goldens byte-identical)
@lunora/cli 894
@lunora/config 504
@lunora/vite 186
@lunora/platform / platform-cloudflare 36 / 15
repo build: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.ts split — done, and where it stops

shard-do.ts went 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 — the unknown → typed parsers, their argument interfaces, and their validation helpers — now packages/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:

  • Extract-class on telemetry (43 members, 798 lines). The 11 fields it would own — spans, traceSampling, metrics, logs, dispatchSpans, currentRequestTrace, … — are not telemetry-private. handleFetchCloudflare touches nearly all of them, and readAdminWildcardOp, dispatchLifecycle, recordShapeError and handleRecordContainerEvent touch the rest. The extraction would have to publish all 11 through the new collaborator, which is a struct behind an indirection, not encapsulation.
  • Free functions for low-coupling methods. 56 members are ≥15 lines and touch ≤3 other this members (1,651 lines total), and 51 never touch this at 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 / webSocketError also 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 SqlExec and a schema and never touch a Durable Object moved from @lunora/do to @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/src is 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:check reporting 196 declaration-site relocations and zero removals. Test count is conserved exactly: 602 + 653 became 501 + 754, with the six suites that drive a real ShardDO staying in @lunora/do. Git recorded every one of the twelve as a rename at 95–99% similarity.

function-metrics (593 lines) and issue-explainer (300) had no suite of their own — the two largest untested modules in the new package, exercised only through ShardDO. 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 the COALESCE from the accumulator's MIN, 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 imported ContextTracer / ContextMetrics / SpanHandle from @lunora/do after the observability extraction removed them, so lint:types was 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

prisis and others added 30 commits July 25, 2026 16:05
… 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>
prisis added 3 commits July 30, 2026 11:59
`__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.
prisis added 2 commits July 30, 2026 12:59
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.
prisis added 2 commits July 30, 2026 14:08
- `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.
prisis added 2 commits July 30, 2026 14:43
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.
prisis added 6 commits July 30, 2026 18:24
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.
@prisis
prisis merged commit f9a506b into alpha Jul 30, 2026
43 of 44 checks passed
@prisis
prisis deleted the feat/platform-abstraction-layer branch July 30, 2026 20:52
@github-actions

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown
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.
Please note this issue tracker is not a help forum. We recommend using our GitHub Discussions tab for questions.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Sep 8, 2026

This branch was previously deployed

1 inactive deployment
benchmarks — 3210db7a Deployed Jul 30, 2026 by prisis via Benchmarks #1243
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant