@lunora/platform is types and a capability matrix, nothing else. It has no
runtime dependencies and near-zero runtime code: it exists so a second target
implements a contract rather than forking the engine.
Two hosts ship today, each in its own package: @lunora/platform-cloudflare
(Durable Objects, hibernatable WebSockets, DurableObjectNamespace — the
adapters plus the createShardPlatform / createWorkerPlatform composition
root) and @lunora/platform-node (better-sqlite3 and an in-process
registry, experimental, and a registered codegen target). A third gets its own
@lunora/platform-<target> package the same way; hosts are never subpaths here,
because each carries its own provider dependencies and this package must stay
installable anywhere.
import type { ShardHost, SocketHost, PlatformCapabilities } from "@lunora/platform";The contracts
| Contract | What it owns |
|---|---|
ShardHost | One shard's execution slot: runSerialized, transaction, sql, alarms, waitUntil, shardKey |
SocketHost | Hibernatable sockets: accept, getSockets(tag?), handleFor, idFor, optional retagging |
ShardDirectory | Name → stub resolution, with optional jurisdiction pinning |
ShardKvStore | Ordered key-value with prefix scan, which ShardHost deliberately omits |
SchedulerHost | schedule/cancel, at-least-once, optional list/deadLetter, optional runtime cron registration (absent on hosts whose crons are declarative) |
SecretValueHost | put/take/discard for a human-supplied value held for one step; a ref travels, the value does not. No get, list or has, and not a ShardKvStore |
Each is documented at its definition. Two contract notes are worth repeating here because they are behavioural, not type-level, and a host that ignores them compiles fine and fails in production:
- Attachment state must survive host recycling. Hibernation on Cloudflare, a process restart elsewhere. Everything a socket needs after a wake lives in its attachment.
getSockets(tag)must return exactly the tagged sockets. A superset fans updates out to subscriptions that never asked for them, which across tenants is a data leak, so a host without native tagging filters in userland.- Return your transport socket as the
SocketHandle. Identity lives out-of-band onidForprecisely so you can. Fan-out is O(subscribers) andSocketHandleis on that loop, so wrapping costs two extra call frames per socket, measured at +11% to +13% on whisper delivery at 128 and 1024 subscribers. A wrapper also gives one socket two identities, since the runtime's own message and close callbacks hand back the transport object: per-socketWeakMapmemos can then key on either and diverge. Wrapping is permitted, but the host that does it pays for it.
Secret values
SecretValueHost holds a human-supplied value between put and a one-claimant
take. A host never stores the plaintext: the raw layer (SecretValueStore)
mints the ref and asks seal(ref) for the bytes to write, and
encryptingSecretValueHost(store, { key, previousKey }) supplies those bytes as
AES-256-GCM (Advanced Encryption Standard in Galois/Counter Mode) ciphertext. The ref and the scope are bound as additional
authenticated data, so a record moved to another ref, or read under another
scope, does not open. The stored record is { keyId, iv, ciphertext }. The
keyId is the first 8 bytes of SHA-256 over the key, and the IV is fresh for
every put.
- Setup. The key is base64 of exactly 32 bytes, bound as a Worker secret
(
LUNORA_SECRET_VALUE_KEY). Generate it withopenssl rand -base64 32. It never goes invarsorwrangler.jsonc, and it never goes in storage. - Fails closed. A missing or malformed key makes
putandtakethrowSecretValueKeyError. Nothing falls back to storing plaintext. - Unreadable records read as absent. A tampered record, one moved to another
ref or scope, or one sealed under a key that is no longer configured, makes
takereturnundefined. It never throws with the plaintext in the error. A failed take does not bind the claimant, so the real claimant can still take the value once the record opens; the first take that opens it binds the ref. - Rotation. Set
LUNORA_SECRET_VALUE_KEY_PREVIOUSto the current key andLUNORA_SECRET_VALUE_KEYto a new one, then deploy. New values seal under the new key, andtakeopens values under either. Wait until every value sealed under the old key has expired:putcaps a lifetime at 24 hours (SECRET_VALUE_MAX_TTL_MS). Then unsetLUNORA_SECRET_VALUE_KEY_PREVIOUSand deploy.
What point-in-time recovery does. On Cloudflare Durable Objects, point-in-time
recovery (PITR) restores SQL data and key-value put() data to any point in the past 30 days.
The sealed secret records are key-value data, so they are included. The
documented way to start a restore is the object's own code: call
onNextSessionRestoreBookmark with a bookmark, then ctx.abort(). The docs
describe no other trigger, and this page does not claim there is none. PITR is
not available under local dev.
What that means for erasure. Encryption alone does not defeat a restore. A
restored record is still ciphertext, but it opens while the key that sealed it
is still configured. So erasure needs two steps: discard the value, and rotate
the key out (drop it from LUNORA_SECRET_VALUE_KEY_PREVIOUS and every other
binding). Until the old key is gone, a restore to a bookmark before the discard
can bring a value back readable. Cloudflare documents Worker secrets as managed
per Worker, and its rollback page does not say what a rollback does to them, so
this page does not claim how a rollback treats a secret.
Not claimed. This page does not say that a restored record is unreadable on its own, that Cloudflare keeps Worker secrets out of backups, or who can read retained history.
Capabilities
PlatformCapabilities rates each feature "native" | "emulated" | "unsupported".
Codegen intersects it with the app's feature probe and omits ctx.* surfaces the
target cannot serve, with a platform_unsupported_feature diagnostic. emulated
emits as-is.
import { CLOUDFLARE_CAPABILITIES } from "@lunora/platform";Conformance
A host is only correct if it passes the conformance technology compatibility kit (TCK), which is the executable form of these contracts and ships as a subpath of this package so it can never version apart from what it asserts:
import { defineHostContractSuite } from "@lunora/platform/conformance/suite"; // pure — safe in workerd
import { createReferenceHost } from "@lunora/platform/conformance"; // adds the node:sqlite reference hostHost variance is declared through presence-based optional hooks on
ConformanceHost (createSocket, simulateRecycle, awaitAlarmFired,
cronTicks, scheduler) rather than skipped blocks, so a gap shows up in the
suite output instead of vanishing from it.
secretValues is the one optional surface held to the capability matrix. A host
passes its target's matrix as capabilities, and the suite requires the secret
store, its clock and its raw records exactly when that matrix rates
secretValues supported. A supported host that omits them fails, and so does an
unsupported host that offers them. The reference harness omits capabilities
and must provide every surface.
The TCK covers host primitives. It does not yet cover the engine-level
guarantees (optimistic concurrency control (OCC-409), poke ordering,
row-level security (RLS) under a live subscription, scheduler at-least-once). Those are implemented by code still being extracted from
@lunora/do, and they move into the suite as that completes. A passing host
means "the primitives are right", not "the engine will behave".
Adding to the matrix
Any new ctx.* or binding feature states its mapping per target, or its
explicit non-support, in the same change that adds it. That rule lives in
AGENTS.md; the matrix
is only honest if it is updated by the person who knows the answer.
A rating alone gates nothing. @lunora/codegen only acts on a feature it can
detect usage of — a row in CAPABILITY_ROWS mapped to the feature key in
CAPABILITY_TO_FEATURE — and only for the unsupported and undeclared states
(native and emulated emit identically). The full gate-bearing list, and the
keys that are parity reporting only, are in capabilities/types.ts's module header.
API
Reference for the public exports of @lunora/platform. Binding shapes such as
D1DatabaseLike, R2BucketLike and QueueBindingLike are listed in
api-snapshots/platform.api.md.
ShardHost
Type: interface
One shard's execution slot. It has runSerialized, transaction, sql,
alarms, and the optional waitUntil and shardKey.
SocketHost
Type: interface
Hibernatable sockets. It has accept, getSockets(tag?), handleFor, idFor,
newPair and upgradeResponse. setTag and removeTag are optional. A host
that cannot retag omits both, so callers re-accept the socket instead.
SocketHandle
Type: interface
The handle a host returns for an accepted socket. The transport socket is the handle on hosts that return it unchanged.
SOCKET_TAG_BUDGET
Type: { readonly maxTagLength: 256; readonly usableTags: 9 }
The tag limits every host enforces. usableTags is Cloudflare's 10-tag
acceptWebSocket cap minus the identity slot the Cloudflare adapter reserves.
findSocketTagBudgetViolation
Type: (tags?: ReadonlyArray<string>) => string | undefined
Checks tags against SOCKET_TAG_BUDGET. It returns a message when a tag is
over budget, and undefined when the tags fit. Hosts call it first in accept.
ShardDirectory
Type: type
Resolves a shard name to a ShardStub, with optional jurisdiction pinning.
DirectShardDirectory
Type: interface
The directory shape a host implements directly. getByName is required, and
get, idForName and jurisdiction are optional.
resolveShard
Type: (directory: ShardDirectory, name: string, locationHint?: ShardRegionHint) => ShardStub
Resolves a shard by name through a directory. It refuses any name that starts
with LUNORA_ROLE_PREFIX. The locationHint is advisory on every host.
LUNORA_ROLE_PREFIX
Type: "__lunora_do__:"
The instance-name prefix reserved for framework roles that share a shard directory, such as the scheduler. An app shard key cannot use it.
ShardKvStore
Type: interface
An ordered key-value store with prefix scan. ShardHost does not include one.
list takes ShardKvListOptions, which has an optional prefix.
SchedulerHost
Type: interface
Schedules jobs with at-least-once delivery. It has schedule, cancel, and the
optional list, deadLetter and cron. cron is absent on hosts whose crons
are declared rather than registered at runtime.
ScheduleOptions
Type: interface
The options for SchedulerHost.schedule, including the retry settings.
SecretValueHost
Type: interface
Holds a human-supplied value for one take. It has put, take and discard,
and has no get, list or has.
SecretValueStore
Type: interface
The raw record layer that a SecretValueHost wraps. It mints the ref and seals
the record bytes.
encryptingSecretValueHost
Type: (raw: SecretValueStore, options: SecretValueKeyOptions) => SecretValueHost
Wraps a SecretValueStore in AES-256-GCM. options.key is required, and
options.previousKey is accepted during rotation. The key is validated on first
use, so an app that never uses secret values can boot without a key.
SecretValueKeyOptions
Type: { key: string | undefined; previousKey?: string }
The base64 keys for encryptingSecretValueHost. Each key must decode to exactly
32 bytes.
SecretValueKeyError
Type: class, with code set to "SECRET_VALUE_KEY_UNAVAILABLE"
Thrown by put and take when the key is missing or malformed. The constructor
takes reason: "missing" | "malformed".
SECRET_VALUE_MAX_BYTES
Type: number
Default: 8192
The largest value put accepts, counted in UTF-8 bytes.
SecretValueTooLargeError
Type: class
Thrown by SecretValueHost.put when the value is larger than
SECRET_VALUE_MAX_BYTES. assertSecretValueSize throws it.
assertSecretValueSize
Type: (value: string) => void
Throws SecretValueTooLargeError when value is over SECRET_VALUE_MAX_BYTES.
SECRET_VALUE_MAX_TTL_MS
Type: number
Default: 86400000 (24 hours)
The longest lifetime put grants, whatever ttlMs is requested.
clampSecretValueTtl
Type: (ttlMs: number) => number
Clamps a requested lifetime to [1, SECRET_VALUE_MAX_TTL_MS]. It throws a
RangeError when ttlMs is NaN or infinite.
PlatformCapabilities
Type: interface
The capability matrix for one target. Each entry is a Capability whose level is
CapabilityLevel, one of "native", "emulated" or "unsupported".
CLOUDFLARE_CAPABILITIES
Type: PlatformCapabilities
The matrix for the Cloudflare host.
NODE_CAPABILITIES
Type: PlatformCapabilities
The matrix for the Node host, reproduced in the @lunora/platform-node package
page.
CELLD_CAPABILITIES
Type: PlatformCapabilities
The matrix for the celld host.
NOOP_EXECUTION_CONTEXT
Type: ExecutionContextLike
An execution context whose waitUntil and passThroughOnException do nothing.
ConformanceHost
Type: interface
Imported from @lunora/platform/conformance. A host factory that
defineHostContractSuite runs. The optional members are the hooks described under
Conformance.
defineHostContractSuite
Type: (name: string, factory: ConformanceHostFactory, vitest: VitestApi) => void
Imported from @lunora/platform/conformance/suite. Registers the host contract
suite under name. ConformanceHostFactory is () => ConformanceHost | Promise<ConformanceHost>.
createReferenceHost
Type: () => ReferenceHost
Imported from @lunora/platform/conformance. Builds the node:sqlite reference
host for the suite.