Skip to content
DocspackagesDocumentation

@lunora/platform

The host contracts every Lunora target implements — ShardHost, SocketHost, ShardDirectory, ShardKvStore, SchedulerHost — plus the capability matrix codegen reads.

PackagesPlatform

@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

ContractWhat it owns
ShardHostOne shard's execution slot: runSerialized, transaction, sql, alarms, waitUntil, shardKey
SocketHostHibernatable sockets: accept, getSockets(tag?), handleFor, idFor, optional retagging
ShardDirectoryName → stub resolution, with optional jurisdiction pinning
ShardKvStoreOrdered key-value with prefix scan, which ShardHost deliberately omits
SchedulerHostschedule/cancel, at-least-once, optional list/deadLetter, optional runtime cron registration (absent on hosts whose crons are declarative)
SecretValueHostput/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 on idFor precisely so you can. Fan-out is O(subscribers) and SocketHandle is 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-socket WeakMap memos 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 with openssl rand -base64 32. It never goes in vars or wrangler.jsonc, and it never goes in storage.
  • Fails closed. A missing or malformed key makes put and take throw SecretValueKeyError. 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 take return undefined. 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_PREVIOUS to the current key and LUNORA_SECRET_VALUE_KEY to a new one, then deploy. New values seal under the new key, and take opens values under either. Wait until every value sealed under the old key has expired: put caps a lifetime at 24 hours (SECRET_VALUE_MAX_TTL_MS). Then unset LUNORA_SECRET_VALUE_KEY_PREVIOUS and 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 host

Host 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.