@lunora/platform 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/conformance/index.d.mts

@@ -1,2 +1,2 @@
 export { type C as ConformanceHost, type a as ConformanceHostFactory, type R as ReferenceHost, type VitestApi, c as createReferenceHost, defineHostContractSuite } from "./suite.mjs";
-import "../packem_shared/socket-host.d-Cq5uVbiH.mjs";
+import "../packem_shared/socket-host.d-dVPE86WP.mjs";

package/dist/conformance/index.d.ts

@@ -1,2 +1,2 @@
 export { type C as ConformanceHost, type a as ConformanceHostFactory, type R as ReferenceHost, type VitestApi, c as createReferenceHost, defineHostContractSuite } from "./suite.js";
-import "../packem_shared/socket-host.d-Cq5uVbiH.js";
+import "../packem_shared/socket-host.d-dVPE86WP.js";

package/dist/conformance/index.mjs

@@ -1 +1 @@
-import{createReferenceHost as o}from"../packem_shared/createReferenceHost-GO8Hp4ft.mjs";import{defineHostContractSuite as f}from"./suite.mjs";export{o as createReferenceHost,f as defineHostContractSuite};
+import{createReferenceHost as o}from"../packem_shared/createReferenceHost-Cvx-Socp.mjs";import{defineHostContractSuite as f}from"./suite.mjs";export{o as createReferenceHost,f as defineHostContractSuite};

package/dist/conformance/suite.d.mts

@@ -1,4 +1,4 @@
-import { f as ShardDirectory, j as ShardKvStore, n as SocketHandle, c as SchedulerHost, g as ShardHost, o as SocketHost } from "../packem_shared/socket-host.d-Cq5uVbiH.mjs";
+import { e as ShardDirectory, i as ShardKvStore, n as SocketHandle, c as SchedulerHost, f as ShardHost, o as SocketHost } from "../packem_shared/socket-host.d-dVPE86WP.mjs";
 /**
  * A conformance host bundles all four platform contracts so a single factory
  * can stand up a complete, isolated test environment.
@@ -12,6 +12,15 @@ interface ConformanceHost {
    * contract — platform delivery is the platform's test, not the adapter's.
    */
   awaitAlarmFired?: (target: number) => Promise<void>;
+  /**
+   * Resolve once the host has actually dispatched a scheduled job — invoked
+   * its delivery path, not merely expired the timer. Optional, but NOT for a
+   * host that declares `scheduler.deadLetter`: that member is the
+   * at-least-once claim, and a host that cannot show the TCK a dispatch is
+   * claiming what the suite cannot check.
+   * @returns `true` when the job was dispatched at least once.
+   */
+  awaitJobDispatched?: (id: string) => Promise<boolean>;
   /** Optional cleanup hook (close DBs, release timers). */
   cleanup?: () => void;
   /**
@@ -23,6 +32,22 @@ interface ConformanceHost {
   createSocket?: () => unknown;
   /** The shard directory under test. */
   directory: ShardDirectory;
+  /**
+   * Terminally dispose this host instance, as opposed to {@link
+   * ConformanceHost.cleanup}, which some hosts (Cloudflare's DO-backed
+   * `cleanup`) use as a per-test reset rather than a true teardown — the DO's
+   * storage has no explicit close a test can drive, so `cleanup` there just
+   * disarms the pending alarm and drops socket references for the next run.
+   *
+   * Optional: only a host with a real terminal dispose implements it. Where
+   * it exists, the suite calls it once and then asserts every surface that
+   * documents a post-close behaviour (`ShardHost.alarms`,
+   * `SchedulerHost.schedule`, `SocketHost.accept`/`setTag`/`removeTag`) fails
+   * closed with a `"platform closed: …"` error — the same "report the gap
+   * instead of asserting a false close" pattern `scheduler`/`kv` already use
+   * for hosts that don't implement a surface at all.
+   */
+  disposeTerminally?: () => void;
   /**
    * The durable key-value store under test. Optional: a host that implements
    * only the reactive-engine half (`ShardHost`) has no KV surface to offer,
@@ -111,22 +136,5 @@ type VitestApi = {
   expect: typeof import("vitest").expect;
   it: typeof import("vitest").it;
 };
-/**
- * Define the host-contract conformance suite for the given factory.
- *
- * The suite asserts the provider-neutral behaviors that every Lunora host must
- * provide: single-writer serialization, durable transactions, local SQL,
- * durable alarms, socket accept/send/close, attachment round-trip across
- * recycle, deterministic shard placement, and durable scheduling.
- *
- * Usage:
- *
- * ```ts
- * import { describe, expect, it } from "vitest";
- * import { createReferenceHost, defineHostContractSuite } from "@lunora/platform/conformance";
- *
- * defineHostContractSuite("reference", createReferenceHost, { describe, expect, it });
- * ```
- */
 declare const defineHostContractSuite: (name: string, factory: ConformanceHostFactory, vitest: VitestApi) => void;
 export { ConformanceHost as C, ReferenceHost as R, type VitestApi, ConformanceHostFactory as a, createReferenceHost as c, defineHostContractSuite };

package/dist/conformance/suite.d.ts

@@ -1,4 +1,4 @@
-import { f as ShardDirectory, j as ShardKvStore, n as SocketHandle, c as SchedulerHost, g as ShardHost, o as SocketHost } from "../packem_shared/socket-host.d-Cq5uVbiH.js";
+import { e as ShardDirectory, i as ShardKvStore, n as SocketHandle, c as SchedulerHost, f as ShardHost, o as SocketHost } from "../packem_shared/socket-host.d-dVPE86WP.js";
 /**
  * A conformance host bundles all four platform contracts so a single factory
  * can stand up a complete, isolated test environment.
@@ -12,6 +12,15 @@ interface ConformanceHost {
    * contract — platform delivery is the platform's test, not the adapter's.
    */
   awaitAlarmFired?: (target: number) => Promise<void>;
+  /**
+   * Resolve once the host has actually dispatched a scheduled job — invoked
+   * its delivery path, not merely expired the timer. Optional, but NOT for a
+   * host that declares `scheduler.deadLetter`: that member is the
+   * at-least-once claim, and a host that cannot show the TCK a dispatch is
+   * claiming what the suite cannot check.
+   * @returns `true` when the job was dispatched at least once.
+   */
+  awaitJobDispatched?: (id: string) => Promise<boolean>;
   /** Optional cleanup hook (close DBs, release timers). */
   cleanup?: () => void;
   /**
@@ -23,6 +32,22 @@ interface ConformanceHost {
   createSocket?: () => unknown;
   /** The shard directory under test. */
   directory: ShardDirectory;
+  /**
+   * Terminally dispose this host instance, as opposed to {@link
+   * ConformanceHost.cleanup}, which some hosts (Cloudflare's DO-backed
+   * `cleanup`) use as a per-test reset rather than a true teardown — the DO's
+   * storage has no explicit close a test can drive, so `cleanup` there just
+   * disarms the pending alarm and drops socket references for the next run.
+   *
+   * Optional: only a host with a real terminal dispose implements it. Where
+   * it exists, the suite calls it once and then asserts every surface that
+   * documents a post-close behaviour (`ShardHost.alarms`,
+   * `SchedulerHost.schedule`, `SocketHost.accept`/`setTag`/`removeTag`) fails
+   * closed with a `"platform closed: …"` error — the same "report the gap
+   * instead of asserting a false close" pattern `scheduler`/`kv` already use
+   * for hosts that don't implement a surface at all.
+   */
+  disposeTerminally?: () => void;
   /**
    * The durable key-value store under test. Optional: a host that implements
    * only the reactive-engine half (`ShardHost`) has no KV surface to offer,
@@ -111,22 +136,5 @@ type VitestApi = {
   expect: typeof import("vitest").expect;
   it: typeof import("vitest").it;
 };
-/**
- * Define the host-contract conformance suite for the given factory.
- *
- * The suite asserts the provider-neutral behaviors that every Lunora host must
- * provide: single-writer serialization, durable transactions, local SQL,
- * durable alarms, socket accept/send/close, attachment round-trip across
- * recycle, deterministic shard placement, and durable scheduling.
- *
- * Usage:
- *
- * ```ts
- * import { describe, expect, it } from "vitest";
- * import { createReferenceHost, defineHostContractSuite } from "@lunora/platform/conformance";
- *
- * defineHostContractSuite("reference", createReferenceHost, { describe, expect, it });
- * ```
- */
 declare const defineHostContractSuite: (name: string, factory: ConformanceHostFactory, vitest: VitestApi) => void;
 export { ConformanceHost as C, ReferenceHost as R, type VitestApi, ConformanceHostFactory as a, createReferenceHost as c, defineHostContractSuite };

package/dist/conformance/suite.mjs

@@ -1 +1 @@
-import{resolveShard as l}from"../packem_shared/resolveShard-uGhAKuTB.mjs";const m=(u,h,w)=>{const{describe:d,expect:t,it:o}=w;d(`host contract: ${u}`,()=>{const r=async()=>h(),n=e=>e.createSocket?.()??{};d("ShardHost",()=>{o("serializes mutations so no two closures interleave",async()=>{t.assertions(1);const e=await r(),a=[];await Promise.all([e.shard.runSerialized(async()=>{a.push("a-start"),await new Promise(c=>{setTimeout(c,10)}),a.push("a-end")}),e.shard.runSerialized(async()=>{a.push("b-start"),await new Promise(c=>{setTimeout(c,5)}),a.push("b-end")})]);const s=a.join("").includes("a-starta-end"),i=a.join("").includes("b-startb-end");t(s&&i).toBe(!0),e.cleanup?.()}),o("rolls back a transaction that throws",async()=>{t.assertions(2);const e=await r();await e.shard.transaction(async()=>{e.shard.sql.exec("CREATE TABLE IF NOT EXISTS rollback_test (id INTEGER PRIMARY KEY)"),e.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (1)")}),await t(e.shard.transaction(async()=>{throw e.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (2)"),new Error("boom")})).rejects.toThrow("boom");const a=e.shard.sql.exec("SELECT id FROM rollback_test WHERE id = 2").toArray();t(a).toHaveLength(0),e.cleanup?.()}),o("observes its own writes inside a transaction",async()=>{t.assertions(1);const e=await r(),a=await e.shard.transaction(async()=>(e.shard.sql.exec("CREATE TABLE IF NOT EXISTS ryw_test (id INTEGER PRIMARY KEY, value TEXT)"),e.shard.sql.exec("INSERT INTO ryw_test (id, value) VALUES (1, 'hello')"),e.shard.sql.exec("SELECT value FROM ryw_test WHERE id = 1").toArray()[0]?.value));t(a).toBe("hello"),e.cleanup?.()}),o("returns a cursor that buffers, yields one row, and iterates",async()=>{t.assertions(3);const e=await r();await e.shard.transaction(async()=>{e.shard.sql.exec("CREATE TABLE IF NOT EXISTS cursor_test (id INTEGER PRIMARY KEY)"),e.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (1)"),e.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (2)")}),t(e.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id").toArray()).toHaveLength(2),t(e.shard.sql.exec("SELECT id FROM cursor_test WHERE id = 1").one()).toEqual({id:1}),t([...e.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id")]).toHaveLength(2),e.cleanup?.()}),o("reports a pending alarm, and clears it once fired",async()=>{t.assertions(2);const e=await r(),a=Date.now()+50;if(await e.shard.alarms.set(a),t(await e.shard.alarms.get()).toBe(a),e.awaitAlarmFired===void 0){t(await e.shard.alarms.get()).toBe(a),e.cleanup?.();return}await e.awaitAlarmFired(a),t(await e.shard.alarms.get()).toBeNull(),e.cleanup?.()}),o("deletes a pending alarm",async()=>{t.assertions(1);const e=await r();await e.shard.alarms.set(Date.now()+1e4),await e.shard.alarms.delete(),t(await e.shard.alarms.get()).toBeNull(),e.cleanup?.()})}),d("SocketHost",()=>{o("accepts a socket and can send/close",async()=>{const e=await r(),a=e.socket.accept(n(e),{user:"ada"});t(e.socket.idFor(a)).toBeDefined(),a.send("hello"),t(e.socket.getSockets().map(s=>e.socket.idFor(s))).toContain(e.socket.idFor(a)),e.readFrames!==void 0&&t(e.readFrames(a)).toStrictEqual(["hello"]),t(()=>{a.close(1e3,"done")}).not.toThrow(),e.cleanup?.()}),o("round-trips an attachment on a live socket",async()=>{t.assertions(1);const e=await r(),a={roomId:"room-1",roles:["admin"]},s=e.socket.accept(n(e),a);t(s.deserializeAttachment()).toEqual(a),e.cleanup?.()}),o("round-trips attachments across a recycle",async()=>{t.assertions(1);const e=await r();if(e.simulateRecycle===void 0||e.restoreSocket===void 0){t(!0).toBe(!0),e.cleanup?.();return}const a={roomId:"room-1",roles:["admin"]},s=e.socket.accept(n(e),a);e.simulateRecycle();const i=e.restoreSocket(e.socket.idFor(s),a);t(i.deserializeAttachment()).toEqual(a),e.cleanup?.()}),o("keeps idFor stable across repeated calls within a wake",async()=>{t.assertions(1);const e=await r(),a=e.socket.accept(n(e),{}),s=e.socket.idFor(a),i=e.socket.idFor(a);t(i).toBe(s),e.cleanup?.()}),o("keeps idFor stable across a recycle",async()=>{t.assertions(1);const e=await r();if(e.simulateRecycle===void 0||e.restoreSocket===void 0){t(!0).toBe(!0),e.cleanup?.();return}const a={roomId:"room-1",roles:["admin"]},s=e.socket.accept(n(e),a),i=e.socket.idFor(s);e.simulateRecycle();const c=e.restoreSocket(i,a);t(e.socket.idFor(c)).toBe(i),e.cleanup?.()}),o("returns exactly the sockets carrying an accept-time tag",async()=>{t.assertions(4);const e=await r(),a=e.socket.accept(n(e),{},["room-a"]),s=e.socket.accept(n(e),{},["room-b"]),i=e.socket.accept(n(e),{}),c=p=>e.socket.idFor(p);t(e.socket.getSockets("room-a").map(c)).toStrictEqual([c(a)]),t(e.socket.getSockets("room-b").map(c)).toStrictEqual([c(s)]),t(e.socket.getSockets("room-c").map(c)).toStrictEqual([]),t(e.socket.getSockets().map(c)).toContain(c(i)),e.cleanup?.()}),o("resolves a raw socket back to its handle",async()=>{t.assertions(2);const e=await r(),a=n(e),s=e.socket.accept(a,{}),i=e.socket.handleFor(a);t(i!==void 0&&e.socket.idFor(i)).toBe(e.socket.idFor(s)),t(e.socket.handleFor(n(e))).toBeUndefined(),e.cleanup?.()}),o("reports a plausible outbound queue depth, if any",async()=>{t.assertions(1);const e=await r(),a=e.socket.accept(n(e),{}),{bufferedAmount:s}=a;t(s===void 0||typeof s=="number"&&s>=0).toBe(!0),e.cleanup?.()}),o("retags a live socket when the host declares mutable tags",async()=>{t.assertions(2);const e=await r();if(e.socket.setTag===void 0){t(e.socket.removeTag).toBeUndefined(),t(!0).toBe(!0),e.cleanup?.();return}const a=e.socket.accept(n(e),{});e.socket.setTag(a,"room-a"),t(e.socket.getSockets("room-a").map(s=>e.socket.idFor(s))).toStrictEqual([e.socket.idFor(a)]),e.socket.removeTag?.(a,"room-a"),t(e.socket.getSockets("room-a").map(s=>e.socket.idFor(s))).toStrictEqual([]),e.cleanup?.()})}),d("ShardDirectory",()=>{o("resolves shard keys deterministically",async()=>{t.assertions(1);const e=await r(),a=await l(e.directory,"tenant-42").fetch(new Request("http://localhost/")),s=await l(e.directory,"tenant-42").fetch(new Request("http://localhost/"));await t(a.text()).resolves.toBe(await s.text()),e.cleanup?.()}),o("dispatches fetch to a resolved stub",async()=>{t.assertions(1);const e=await r(),a=await l(e.directory,"tenant-42").fetch(new Request("http://localhost/"));t(a).toBeInstanceOf(Response),e.cleanup?.()})}),d("SchedulerHost",()=>{o("schedules a job for a future timestamp",async()=>{t.assertions(2);const e=await r();if(e.scheduler===void 0){t(e.scheduler).toBeUndefined(),t(!0).toBe(!0),e.cleanup?.();return}const a=Date.now(),s=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:50});t(s.scheduledFor).toBeGreaterThanOrEqual(a+50),t(s.id).toBeDefined(),e.cleanup?.()}),o("cancels a scheduled job",async()=>{t.assertions(1);const e=await r();if(e.scheduler===void 0){t(e.scheduler).toBeUndefined(),e.cleanup?.();return}const a=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4}),s=await e.scheduler.cancel(a.id);t(s).toBe(!0),e.cleanup?.()}),o("reports a second cancel of the same job as false",async()=>{t.assertions(2);const e=await r();if(e.scheduler===void 0){t(e.scheduler).toBeUndefined(),t(!0).toBe(!0),e.cleanup?.();return}const a=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4});t(await e.scheduler.cancel(a.id)).toBe(!0),t(await e.scheduler.cancel(a.id)).toBe(!1),e.cleanup?.()}),o("gives two identical schedules independently cancellable ids",async()=>{t.assertions(3);const e=await r();if(e.scheduler===void 0){t(e.scheduler).toBeUndefined(),t(!0).toBe(!0),t(!0).toBe(!0),e.cleanup?.();return}const a=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:1e4}),s=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:1e4});t(s.id).not.toBe(a.id),t(await e.scheduler.cancel(a.id)).toBe(!0),t(await e.scheduler.cancel(s.id)).toBe(!0),e.cleanup?.()}),o("lists a pending job with a zero attempt count",async()=>{t.assertions(2);const e=await r();if(e.scheduler?.list===void 0){t(e.scheduler?.list).toBeUndefined(),t(!0).toBe(!0),e.cleanup?.();return}const a=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:1e4}),s=(await e.scheduler.list()).find(i=>i.id===a.id);t(s?.functionPath).toBe("tasks/remind"),t(s?.attempts).toBe(0),e.cleanup?.()}),o("keeps the pending and dead-letter listings disjoint",async()=>{t.assertions(2);const e=await r();if(e.scheduler?.list===void 0||e.scheduler.deadLetter===void 0||e.simulateDeadLetter===void 0){t(e.simulateDeadLetter).toBeUndefined(),t(!0).toBe(!0),e.cleanup?.();return}const a=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4});await e.simulateDeadLetter(a.id);const s=await e.scheduler.list(),i=await e.scheduler.deadLetter.list();t(s.some(c=>c.id===a.id)).toBe(!1),t(i.some(c=>c.id===a.id)).toBe(!0),e.cleanup?.()}),o("returns a requeued job to the pending set with a fresh budget",async()=>{t.assertions(4);const e=await r();if(e.scheduler?.list===void 0||e.scheduler.deadLetter===void 0||e.simulateDeadLetter===void 0){t(e.simulateDeadLetter).toBeUndefined(),t(!0).toBe(!0),t(!0).toBe(!0),t(!0).toBe(!0),e.cleanup?.();return}const a=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4});await e.simulateDeadLetter(a.id),t(await e.scheduler.deadLetter.requeue(a.id)).toBe(!0);const s=(await e.scheduler.list()).find(c=>c.id===a.id);t(s).toBeDefined(),t(s?.attempts).toBe(0);const i=await e.scheduler.deadLetter.list();t(i.some(c=>c.id===a.id)).toBe(!1),e.cleanup?.()}),o("reports a requeue of an unparked job as false",async()=>{t.assertions(1);const e=await r();if(e.scheduler?.deadLetter===void 0){t(e.scheduler?.deadLetter).toBeUndefined(),e.cleanup?.();return}t(await e.scheduler.deadLetter.requeue("job-does-not-exist")).toBe(!1),e.cleanup?.()})}),d("ShardKvStore",()=>{o("reads back a written value",async()=>{t.assertions(2);const e=await r();if(e.kv===void 0){t(e.kv).toBeUndefined(),t(!0).toBe(!0),e.cleanup?.();return}await e.kv.put("s:token-1",{userId:"ada"}),t(await e.kv.get("s:token-1")).toEqual({userId:"ada"}),t(await e.kv.get("s:missing")).toBeUndefined(),e.cleanup?.()}),o("deletes a key idempotently",async()=>{t.assertions(3);const e=await r();if(e.kv===void 0){t(e.kv).toBeUndefined(),t(!0).toBe(!0),t(!0).toBe(!0),e.cleanup?.();return}await e.kv.put("k",1),t(await e.kv.delete("k")).toBe(!0),t(await e.kv.delete("k")).toBe(!1),t(await e.kv.get("k")).toBeUndefined(),e.cleanup?.()}),o("enumerates exactly the keys under a prefix",async()=>{t.assertions(2);const e=await r();if(e.kv===void 0){t(e.kv).toBeUndefined(),t(!0).toBe(!0),e.cleanup?.();return}await e.kv.put("s:a",1),await e.kv.put("s:b",2),await e.kv.put("other",3);const a=await e.kv.list({prefix:"s:"}),s=await e.kv.list();t([...a.keys()].toSorted((i,c)=>i.localeCompare(c))).toStrictEqual(["s:a","s:b"]),t(s.size).toBe(3),e.cleanup?.()})})})};export{m as defineHostContractSuite};
+import{resolveShard as k}from"../packem_shared/resolveShard-BzKOUEO4.mjs";const f=/platform closed/u,b=(d,v,S)=>{const{describe:u,expect:t,it:c}=S;u(`host contract: ${d}`,()=>{const p=async()=>v(),l=a=>a.createSocket?.()??{},o=async a=>{const e=await p();try{await a(e)}finally{e.cleanup?.()}};u("ShardHost",()=>{c("serializes mutations so no two closures interleave",async()=>{t.assertions(1),await o(async a=>{const e=[];await Promise.all([a.shard.runSerialized(async()=>{e.push("a-start"),await new Promise(i=>{setTimeout(i,10)}),e.push("a-end")}),a.shard.runSerialized(async()=>{e.push("b-start"),await new Promise(i=>{setTimeout(i,5)}),e.push("b-end")})]);const s=e.join("").includes("a-starta-end"),r=e.join("").includes("b-startb-end");t(s&&r).toBe(!0)})}),c("rolls back a transaction that throws",async()=>{t.assertions(2),await o(async a=>{await a.shard.transaction(async()=>{a.shard.sql.exec("CREATE TABLE IF NOT EXISTS rollback_test (id INTEGER PRIMARY KEY)"),a.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (1)")}),await t(a.shard.transaction(async()=>{throw a.shard.sql.exec("INSERT INTO rollback_test (id) VALUES (2)"),new Error("boom")})).rejects.toThrow("boom");const e=a.shard.sql.exec("SELECT id FROM rollback_test WHERE id = 2").toArray();t(e).toHaveLength(0)})}),c("rejects with the value the closure threw, and stays usable",async()=>{t.assertions(3),await o(async a=>{const e=Object.assign(new Error("closure failed"),{code:"NOT_FOUND",status:404});await t(a.shard.transaction(()=>Promise.reject(e))).rejects.toBe(e),await t(a.shard.runSerialized(()=>Promise.reject(e))).rejects.toBe(e),await t(a.shard.runSerialized(async()=>a.shard.transaction(async()=>"still here"))).resolves.toBe("still here")})}),c("observes its own writes inside a transaction",async()=>{t.assertions(1),await o(async a=>{const e=await a.shard.transaction(async()=>(a.shard.sql.exec("CREATE TABLE IF NOT EXISTS ryw_test (id INTEGER PRIMARY KEY, value TEXT)"),a.shard.sql.exec("INSERT INTO ryw_test (id, value) VALUES (1, 'hello')"),a.shard.sql.exec("SELECT value FROM ryw_test WHERE id = 1").toArray()[0]?.value));t(e).toBe("hello")})}),c("keeps overlapping transactions atomic",async()=>{t.assertions(2),await o(async a=>{a.shard.sql.exec("CREATE TABLE IF NOT EXISTS overlap_test (id TEXT PRIMARY KEY)");const e=a.shard.transaction(async()=>{a.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('A')"),await new Promise(i=>{setTimeout(i,20)}),a.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('B')")}),s=a.shard.transaction(async()=>{a.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('C')")});await Promise.all([e,s]);const r=a.shard.sql.exec("SELECT id FROM overlap_test ORDER BY id").toArray();t(r.map(i=>i.id)).toStrictEqual(["A","B","C"]),await t(a.shard.transaction(async()=>{throw a.shard.sql.exec("INSERT INTO overlap_test (id) VALUES ('D')"),new Error("boom")})).rejects.toThrow("boom")})}),c("returns a cursor that buffers, yields one row, and iterates",async()=>{t.assertions(3),await o(async a=>{await a.shard.transaction(async()=>{a.shard.sql.exec("CREATE TABLE IF NOT EXISTS cursor_test (id INTEGER PRIMARY KEY)"),a.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (1)"),a.shard.sql.exec("INSERT INTO cursor_test (id) VALUES (2)")}),t(a.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id").toArray()).toHaveLength(2),t(a.shard.sql.exec("SELECT id FROM cursor_test WHERE id = 1").one()).toEqual({id:1}),t([...a.shard.sql.exec("SELECT id FROM cursor_test ORDER BY id")]).toHaveLength(2)})}),c("reports a pending alarm, and clears it once fired",async()=>{t.assertions(2),await o(async a=>{const e=Date.now()+50;if(await a.shard.alarms.set(e),t(await a.shard.alarms.get()).toBe(e),a.awaitAlarmFired===void 0){t(await a.shard.alarms.get()).toBe(e);return}await a.awaitAlarmFired(e),t(await a.shard.alarms.get()).toBeNull()})}),c("deletes a pending alarm",async()=>{t.assertions(1),await o(async a=>{await a.shard.alarms.set(Date.now()+1e4),await a.shard.alarms.delete(),t(await a.shard.alarms.get()).toBeNull()})})}),u("SocketHost",()=>{c("accepts a socket and can send/close",async()=>{await o(async a=>{const e=a.socket.accept(l(a),{user:"ada"});t(a.socket.idFor(e)).toBeDefined(),e.send("hello"),t(a.socket.getSockets().map(s=>a.socket.idFor(s))).toContain(a.socket.idFor(e)),a.readFrames!==void 0&&t(a.readFrames(e)).toStrictEqual(["hello"]),t(()=>{e.close(1e3,"done")}).not.toThrow()})}),c("round-trips an attachment on a live socket",async()=>{t.assertions(1),await o(async a=>{const e={roomId:"room-1",roles:["admin"]},s=a.socket.accept(l(a),e);t(s.deserializeAttachment()).toEqual(e)})}),c("round-trips attachments across a recycle",async a=>{await o(async e=>{if(e.simulateRecycle===void 0||e.restoreSocket===void 0){a.skip(`${d} does not implement simulateRecycle/restoreSocket`);return}t.assertions(1);const s={roomId:"room-1",roles:["admin"]},r=e.socket.accept(l(e),s);e.simulateRecycle();const i=e.restoreSocket(e.socket.idFor(r),s);t(i.deserializeAttachment()).toEqual(s)})}),c("keeps idFor stable across repeated calls within a wake",async()=>{t.assertions(1),await o(async a=>{const e=a.socket.accept(l(a),{}),s=a.socket.idFor(e),r=a.socket.idFor(e);t(r).toBe(s)})}),c("keeps idFor stable across a recycle",async a=>{await o(async e=>{if(e.simulateRecycle===void 0||e.restoreSocket===void 0){a.skip(`${d} does not implement simulateRecycle/restoreSocket`);return}t.assertions(1);const s={roomId:"room-1",roles:["admin"]},r=e.socket.accept(l(e),s),i=e.socket.idFor(r);e.simulateRecycle();const n=e.restoreSocket(i,s);t(e.socket.idFor(n)).toBe(i)})}),c("returns exactly the sockets carrying an accept-time tag",async()=>{t.assertions(4),await o(async a=>{const e=a.socket.accept(l(a),{},["room-a"]),s=a.socket.accept(l(a),{},["room-b"]),r=a.socket.accept(l(a),{}),i=n=>a.socket.idFor(n);t(a.socket.getSockets("room-a").map(i)).toStrictEqual([i(e)]),t(a.socket.getSockets("room-b").map(i)).toStrictEqual([i(s)]),t(a.socket.getSockets("room-c").map(i)).toStrictEqual([]),t(a.socket.getSockets().map(i)).toContain(i(r))})}),c("accepts the portable budget of nine caller tags",async()=>{t.assertions(9);const a=await p(),e=Array.from({length:9},(i,n)=>`tag-${String(n)}`),s=a.socket.accept(l(a),{},e),r=i=>a.socket.idFor(i);for(const i of e)t(a.socket.getSockets(i).map(r)).toStrictEqual([r(s)]);a.cleanup?.()}),c("resolves a raw socket back to its handle",async()=>{t.assertions(2),await o(async a=>{const e=l(a),s=a.socket.accept(e,{}),r=a.socket.handleFor(e);t(r!==void 0&&a.socket.idFor(r)).toBe(a.socket.idFor(s)),t(a.socket.handleFor(l(a))).toBeUndefined()})}),c("reports a plausible outbound queue depth, if any",async()=>{t.assertions(1),await o(async a=>{const e=a.socket.accept(l(a),{}),{bufferedAmount:s}=e;t(s===void 0||typeof s=="number"&&s>=0).toBe(!0)})}),c("retags a live socket when the host declares mutable tags",async a=>{await o(async e=>{if(e.socket.setTag===void 0){a.skip(`${d} does not implement mutable socket tags (setTag)`);return}t.assertions(2);const s=e.socket.accept(l(e),{});e.socket.setTag(s,"room-a"),t(e.socket.getSockets("room-a").map(r=>e.socket.idFor(r))).toStrictEqual([e.socket.idFor(s)]),e.socket.removeTag?.(s,"room-a"),t(e.socket.getSockets("room-a").map(r=>e.socket.idFor(r))).toStrictEqual([])})})}),u("ShardDirectory",()=>{c("resolves shard keys deterministically",async()=>{t.assertions(1),await o(async a=>{const e=await k(a.directory,"tenant-42").fetch(new Request("http://localhost/")),s=await k(a.directory,"tenant-42").fetch(new Request("http://localhost/"));await t(e.text()).resolves.toBe(await s.text())})}),c("dispatches fetch to a resolved stub",async()=>{t.assertions(1),await o(async a=>{const s=await k(a.directory,"tenant-42").fetch(new Request("http://localhost/"));t(s).toBeInstanceOf(Response)})})}),u("SchedulerHost",()=>{c("schedules a job for a future timestamp",async a=>{await o(async e=>{if(e.scheduler===void 0){a.skip(`${d} does not implement SchedulerHost`);return}t.assertions(2);const s=Date.now(),r=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:50});t(r.scheduledFor).toBeGreaterThanOrEqual(s+50),t(r.id).toBeDefined()})}),c("dispatches a scheduled job at least once",async a=>{await o(async e=>{if(e.scheduler===void 0){a.skip(`${d} does not implement SchedulerHost`);return}const s=e.scheduler.deadLetter!==void 0;if(!s&&e.awaitJobDispatched===void 0){a.skip(`${d} does not claim at-least-once delivery (no deadLetter) and supplies no awaitJobDispatched hook`);return}if(s&&t(e.awaitJobDispatched).toBeDefined(),e.awaitJobDispatched===void 0)return;const r=e.scheduler.list!==void 0;t.assertions(1+(s?1:0)+(r?1:0));const i=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:30});if(await t(e.awaitJobDispatched(i.id)).resolves.toBe(!0),r){const n=await e.scheduler.list?.();t(n?.some(w=>w.id===i.id)).toBe(!1)}})}),c("cancels a scheduled job",async a=>{await o(async e=>{if(e.scheduler===void 0){a.skip(`${d} does not implement SchedulerHost`);return}t.assertions(1);const s=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4}),r=await e.scheduler.cancel(s.id);t(r).toBe(!0)})}),c("reports a second cancel of the same job as false",async a=>{await o(async e=>{if(e.scheduler===void 0){a.skip(`${d} does not implement SchedulerHost`);return}t.assertions(2);const s=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4});t(await e.scheduler.cancel(s.id)).toBe(!0),t(await e.scheduler.cancel(s.id)).toBe(!1)})}),c("gives two identical schedules independently cancellable ids",async a=>{await o(async e=>{if(e.scheduler===void 0){a.skip(`${d} does not implement SchedulerHost`);return}t.assertions(3);const s=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:1e4}),r=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:1e4});t(r.id).not.toBe(s.id),t(await e.scheduler.cancel(s.id)).toBe(!0),t(await e.scheduler.cancel(r.id)).toBe(!0)})}),c("lists a pending job with a zero attempt count",async a=>{await o(async e=>{if(e.scheduler?.list===void 0){a.skip(`${d} does not implement SchedulerHost.list`);return}t.assertions(2);const s=await e.scheduler.schedule("tasks/remind",{user:"ada"},{delayMs:1e4}),i=(await e.scheduler.list()).find(n=>n.id===s.id);t(i?.functionPath).toBe("tasks/remind"),t(i?.attempts).toBe(0)})}),c("keeps the pending and dead-letter listings disjoint",async a=>{await o(async e=>{if(e.scheduler?.list===void 0||e.scheduler.deadLetter===void 0||e.simulateDeadLetter===void 0){a.skip(`${d} does not implement scheduler.list/deadLetter/simulateDeadLetter`);return}t.assertions(2);const s=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4});await e.simulateDeadLetter(s.id);const r=await e.scheduler.list(),i=await e.scheduler.deadLetter.list();t(r.some(n=>n.id===s.id)).toBe(!1),t(i.some(n=>n.id===s.id)).toBe(!0)})}),c("returns a requeued job to the pending set with a fresh budget",async a=>{await o(async e=>{if(e.scheduler?.list===void 0||e.scheduler.deadLetter===void 0||e.simulateDeadLetter===void 0){a.skip(`${d} does not implement scheduler.list/deadLetter/simulateDeadLetter`);return}t.assertions(4);const s=await e.scheduler.schedule("tasks/remind",{},{delayMs:1e4});await e.simulateDeadLetter(s.id),t(await e.scheduler.deadLetter.requeue(s.id)).toBe(!0);const i=(await e.scheduler.list()).find(w=>w.id===s.id);t(i).toBeDefined(),t(i?.attempts).toBe(0);const n=await e.scheduler.deadLetter.list();t(n.some(w=>w.id===s.id)).toBe(!1)})}),c("reports a requeue of an unparked job as false",async a=>{await o(async e=>{if(e.scheduler?.deadLetter===void 0){a.skip(`${d} does not implement scheduler.deadLetter`);return}t.assertions(1),t(await e.scheduler.deadLetter.requeue("job-does-not-exist")).toBe(!1)})})}),u("ShardKvStore",()=>{c("reads back a written value",async a=>{await o(async e=>{if(e.kv===void 0){a.skip(`${d} does not implement ShardKvStore`);return}t.assertions(2),await e.kv.put("s:token-1",{userId:"ada"}),t(await e.kv.get("s:token-1")).toEqual({userId:"ada"}),t(await e.kv.get("s:missing")).toBeUndefined()})}),c("deletes a key idempotently",async a=>{await o(async e=>{if(e.kv===void 0){a.skip(`${d} does not implement ShardKvStore`);return}t.assertions(3),await e.kv.put("k",1),t(await e.kv.delete("k")).toBe(!0),t(await e.kv.delete("k")).toBe(!1),t(await e.kv.get("k")).toBeUndefined()})}),c("enumerates exactly the keys under a prefix",async a=>{await o(async e=>{if(e.kv===void 0){a.skip(`${d} does not implement ShardKvStore`);return}t.assertions(2),await e.kv.put("s:a",1),await e.kv.put("s:b",2),await e.kv.put("other",3);const s=await e.kv.list({prefix:"s:"}),r=await e.kv.list();t([...s.keys()].toSorted((i,n)=>i.localeCompare(n))).toStrictEqual(["s:a","s:b"]),t(r.size).toBe(3)})})}),u("post-dispose",()=>{c("fails closed on every documented surface once the host is terminally disposed",async a=>{const e=await p();if(e.disposeTerminally===void 0){a.skip(`${d} has no terminal dispose the suite can drive from inside a test`);return}const{removeTag:s,setTag:r}=e.socket,{scheduler:i}=e,n=e.socket.accept(l(e),{}),w=l(e);e.disposeTerminally();const E=async m=>{await t(async()=>{await m()}).rejects.toThrow(f)},y=[()=>e.shard.alarms.set(Date.now()+1e3),()=>e.shard.alarms.delete(),()=>e.socket.accept(w,{}),...r===void 0?[]:[()=>{r(n,"room-a")}],...s===void 0?[]:[()=>{s(n,"room-a")}],...i===void 0?[]:[()=>i.schedule("tasks/remind",{},{delayMs:10})]];t.assertions(y.length);for(const m of y)await E(m)})})})};export{b as defineHostContractSuite};

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-export { type D as DirectShardDirectory, type S as ScheduleOptions, type a as ScheduledJob, type b as ScheduledJobStatus, type c as SchedulerHost, type d as ShardAlarms, type e as ShardAsyncSqlExec, type f as ShardDirectory, type g as ShardHost, type h as ShardJurisdiction, type i as ShardKvListOptions, type j as ShardKvStore, type k as ShardSqlCursor, type l as ShardSqlExec, type m as ShardStub, type n as SocketHandle, type o as SocketHost, type p as SqlRow, type T as TwoStepShardDirectory, r as resolveShard } from "./packem_shared/socket-host.d-Cq5uVbiH.mjs";
+export { type D as DirectShardDirectory, type S as ScheduleOptions, type a as ScheduledJob, type b as ScheduledJobStatus, type c as SchedulerHost, type d as ShardAlarms, type e as ShardDirectory, type f as ShardHost, type g as ShardJurisdiction, type h as ShardKvListOptions, type i as ShardKvStore, type j as ShardRegionHint, type k as ShardSqlCursor, type l as ShardSqlExec, type m as ShardStub, type n as SocketHandle, type o as SocketHost, type p as SqlRow, type T as TwoStepShardDirectory, r as resolveShard } from "./packem_shared/socket-host.d-dVPE86WP.mjs";
 /**
  * The subset of the Cloudflare `ExecutionContext` the Lunora worker entry and
  * the framework mount seams rely on — `waitUntil` for fire-and-forget work that
@@ -22,6 +22,13 @@ export { type D as DirectShardDirectory, type S as ScheduleOptions, type a as Sc
  * fall back to {@link NOOP_EXECUTION_CONTEXT}.
  */
 interface ExecutionContextLike {
+  /**
+   * Present only when Cloudflare Access authenticated the request against a
+   * policy attached to the **Worker** (rather than to a hostname). `undefined`
+   * on every unauthenticated request, so its presence is itself the "Access
+   * authorized this caller" signal — see {@link AccessContextLike}.
+   */
+  access?: AccessContextLike;
   cache?: {
     purge: (options: {
       purgeEverything?: boolean;
@@ -31,6 +38,48 @@ interface ExecutionContextLike {
   passThroughOnException?: () => void;
   waitUntil?: (promise: Promise<unknown>) => void;
 }
+/**
+ * The identity Cloudflare Access attaches to a Worker-protected request.
+ *
+ * Shape follows the Access application-token payload: `sub` is the stable per-user
+ * id, `email` the verified address, `common_name` the service-token name (machine
+ * callers, whose `sub` is empty), and `exp` the credential expiry in epoch
+ * **seconds**. Group membership is whatever the Access policy emits — a list of
+ * names, or of `{ id, name }` objects — hence `unknown`; normalize before use.
+ *
+ * Cloudflare may add further fields, so the index signature keeps them rather
+ * than dropping them: this is a view of a payload we do not own.
+ */
+interface AccessIdentityLike {
+  [claim: string]: unknown;
+  /** Service-token name. Present for non-interactive (machine) callers instead of `email`. */
+  common_name?: string;
+  /** Verified user email. Present for interactive (SSO) callers. */
+  email?: string;
+  /** Credential expiry, epoch **seconds**. */
+  exp?: number;
+  /** IdP group membership — names or `{ id, name }` objects, depending on the policy. */
+  groups?: unknown;
+  /** Display name from the identity provider, when it emits one. */
+  name?: string;
+  /** Stable per-user id, and what consumers key a user on. Empty for service tokens. */
+  sub?: string;
+  /** Cloudflare's per-user UUID. Carried through, but deliberately not used as an id — only this path emits it, so keying on it would not match the JWT path. */
+  user_uuid?: string;
+}
+/**
+ * The `ctx.access` facade Cloudflare exposes on a Worker protected by Access.
+ *
+ * Reading the identity from here is preferable to verifying the
+ * `Cf-Access-Jwt-Assertion` header: the platform has already authenticated the
+ * caller, so there is no JWKS fetch, no audience check to get wrong, and nothing
+ * a request can forge — the field simply does not exist unless Access authorized
+ * the call. The header path remains the fallback for hostname-scoped Access
+ * applications, which do not populate this.
+ */
+interface AccessContextLike {
+  getIdentity: () => AccessIdentityLike | null | undefined | Promise<AccessIdentityLike | null | undefined>;
+}
 /**
  * No-op `ExecutionContext` used when the host runtime didn't supply one (a
  * non-Cloudflare preview, or a unit test), so the worker's `fetch` always
@@ -65,6 +114,35 @@ interface QueueMessageLike<Body = unknown> {
   }) => void;
   readonly timestamp: Date;
 }
+/** Options accepted by {@link HttpCacheLike.match} and {@link HttpCacheLike.delete}. */
+interface HttpCacheQueryOptions {
+  /** Match a non-`GET` request against a stored `GET` entry. */
+  ignoreMethod?: boolean;
+}
+/**
+ * Minimal projection of one Web Cache API cache — the store a host puts in front
+ * of the app, reached on Cloudflare as `caches.default` (the colo cache).
+ *
+ * Only the three calls Lunora makes are declared, so a host that has a cache but
+ * not the whole `Cache` interface still satisfies it, and a unit test can pass a
+ * plain object double. This is a **host** primitive, not a binding: it is reached
+ * through a runtime global rather than `env`, and a target without one leaves it
+ * `undefined` rather than shipping a fake — see `httpCache` in
+ * `PlatformCapabilities`.
+ *
+ * The stored entry is keyed by the request, so a caller that needs `Vary`
+ * semantics must fold the varying header values into the key itself: Cloudflare's
+ * cache honours `Vary` for `Accept-Encoding` only, and a projection cannot make
+ * that portable.
+ */
+interface HttpCacheLike {
+  /** Evict the entry stored under `request`. Resolves `true` when something was removed. */
+  delete: (request: Request | string, options?: HttpCacheQueryOptions) => Promise<boolean>;
+  /** The stored response for `request`, or `undefined` on a miss. */
+  match: (request: Request | string, options?: HttpCacheQueryOptions) => Promise<Response | undefined>;
+  /** Store `response` under `request`. Rejects for a `206`, a `Vary: *`, or a `Set-Cookie`-bearing response. */
+  put: (request: Request | string, response: Response) => Promise<void>;
+}
 /** A single vector match. */
 interface VectorMatchLike {
   id: string;
@@ -312,16 +390,18 @@ interface R2BucketLike {
     delimiter?: string;
     limit?: number;
     prefix?: string;
+    startAfter?: string;
   }) => Promise<{
     cursor?: string;
     objects: R2ObjectLike[];
     truncated?: boolean;
   }>;
-  put: (key: string, body: ReadableStream | ArrayBuffer | Blob | string | null, options?: {
+  put: (key: string, body: ReadableStream | ArrayBuffer | ArrayBufferView | Blob | string | null, options?: {
     customMetadata?: Record<string, string>;
     httpMetadata?: {
       contentType?: string;
     };
+    sha256?: ArrayBuffer | string;
   }) => Promise<R2ObjectLike>;
   /** Resume an in-progress multipart upload by id (R2 `resumeMultipartUpload`). Optional; see {@link Storage.resumeMultipartUpload}. */
   resumeMultipartUpload?: (key: string, uploadId: string) => R2MultipartUploadLike;
@@ -417,15 +497,15 @@ interface MessageSendRequestLike<Body = unknown> {
   delaySeconds?: number;
 }
 /**
- * Minimal structural projection of workers-types' `Queue&lt;Body>` (the producer
+ * Minimal structural projection of workers-types' `Queue<Body>` (the producer
  * binding). The real binding's `send`/`sendBatch` resolve to a metadata object;
- * we widen the return to `Promise&lt;unknown>` so a plain-object fake satisfies it.
+ * we widen the return to `Promise<unknown>` so a plain-object fake satisfies it.
  */
 interface QueueBindingLike<Body = unknown> {
   send: (message: Body, options?: QueueSendOptions) => Promise<unknown>;
   sendBatch: (messages: Iterable<MessageSendRequestLike<Body>>, options?: QueueSendBatchOptions) => Promise<unknown>;
 }
-/** Structural mirror of workers-types' `Message&lt;Body>` (one delivered message). */
+/** Structural mirror of workers-types' `Message<Body>` (one delivered message). */
 interface MessageLike<Body = unknown> {
   /** Acknowledge this message so it is not redelivered. */
   ack: () => void;
@@ -436,7 +516,7 @@ interface MessageLike<Body = unknown> {
   retry: (options?: QueueRetryOptions) => void;
   readonly timestamp: Date;
 }
-/** Structural mirror of workers-types' `MessageBatch&lt;Body>` handed to a consumer. */
+/** Structural mirror of workers-types' `MessageBatch<Body>` handed to a consumer. */
 interface MessageBatchLike<Body = unknown> {
   /** Acknowledge every message in the batch. */
   ackAll: () => void;
@@ -481,22 +561,131 @@ interface PlatformCapabilities {
     analytics?: Capability;
     /** Browser rendering / headless browser. */
     browser?: Capability;
-    /** Container execution (Cloudflare Containers / Fargate). */
+    /**
+     * `.commitOrdered()` tables — the `_commitSeq` system field: a per-shard
+     * integer allocated once per mutation and strictly increasing in commit
+     * order.
+     *
+     * Listed as a capability rather than assumed, because the ordering
+     * guarantee is not the engine's to give. It rests on two things the HOST
+     * provides: an atomic write boundary the counter bump shares with the
+     * rows it stamps, and serialized execution so two mutations cannot
+     * interleave their allocations. A host that offers neither can still
+     * create the counter and hand out increasing numbers — they just would
+     * not order commits, which is the whole contract.
+     */
+    commitOrderedTables?: Capability;
+    /**
+     * Container execution (Cloudflare Containers / Fargate), including
+     * `ctx.containers.<name>.exec`. Deliberately one rating rather than two:
+     * `exec` is a method on the accessor this key already gates, not a
+     * separate app-imported surface, so there is no usage signal codegen
+     * could gate it on independently and nothing that could act on a second
+     * rating. A host that can reach a container but cannot carry a command
+     * result back should say so in this note.
+     */
     containers?: Capability;
     /** Cross-shard fan-out queries. */
     crossShardFanout?: Capability;
+    /**
+     * Durable streams: a `.stream()` run whose chunks are persisted and
+     * whose producer outlives the socket that opened it, so a reconnecting
+     * or second client resumes the same transcript.
+     */
+    durableStreams?: Capability;
     /** Global (replicated) tables backed by a SQL store. */
     globalTables?: Capability;
+    /**
+     * A shared HTTP cache in front of the app that the runtime can READ AND
+     * WRITE — the Web Cache API (`caches.default` on Cloudflare), projected
+     * as `HttpCacheLike`.
+     *
+     * Rated separately from the app merely emitting `Cache-Control`, because
+     * only this half needs a host primitive. Emitting the header is portable
+     * by construction: any host that returns an HTTP response can do it, and
+     * browsers and downstream CDNs honour it wherever the app runs. What is
+     * not portable is a store the Worker itself can `match`/`put` against,
+     * which is why `@lunora/runtime`'s REST edge cache degrades to
+     * headers-only on a target rated `unsupported` rather than failing.
+     */
+    httpCache?: Capability;
     /** BYO database via connection pooling (Hyperdrive / RDS Proxy). */
     hyperdrive?: Capability;
+    /**
+     * An identity-aware proxy in front of the app that authenticates the
+     * caller before the request reaches it, and hands the runtime a verified
+     * identity **out-of-band** — on the execution context rather than on the
+     * request (Cloudflare Access attached to a Worker; IAP; an ALB OIDC
+     * action).
+     *
+     * Rated separately from the header-stamping form of the same product
+     * because only this one needs a host primitive. An identity-aware proxy
+     * that merely adds a signed header is portable by construction: any host
+     * that receives an HTTP request can verify it, which is why
+     * `@lunora/cloudflare-access` still works on a target rated
+     * `unsupported` here (it falls back to the `Cf-Access-Jwt-Assertion`
+     * JWT). What is not portable is the identity arriving beside the
+     * request, which is why `ExecutionContextLike.access` is a projection a
+     * host either populates or does not.
+     */
+    identityProxy?: Capability;
+    /** Image transforms (resize/format/optimize) via an Images binding. */
+    images?: Capability;
     /** Key-value storage (KV / Redis / DynamoDB). */
     keyValueStore?: Capability;
     /** Local SQL execution inside a shard. */
     localSql?: Capability;
     /** Email sending (Resend / SES / etc). */
     mail?: Capability;
-    /** Object storage (R2 / S3 / MinIO). */
+    /**
+     * `.memory()` tables — the ephemeral tier: rows cleared on every shard
+     * cold start, never written to the CDC changelog, refilled by
+     * `onShardInit`.
+     *
+     * The rating answers "does a memory table avoid durable storage on this
+     * host", NOT "does it work". The lifetime semantics are the engine's and
+     * hold everywhere; whether the rows actually stay out of the durable
+     * store depends on the host offering a second, memory-backed SQL handle,
+     * which is a per-target fact.
+     */
+    memoryTables?: Capability;
+    /**
+     * Object storage (R2 / S3 / MinIO).
+     *
+     * `ctx.storage.deleteAfterCommit(key)` rides on this rating and gets no
+     * key of its own: it needs no host primitive beyond the bucket. The
+     * post-commit flush uses `ShardHost.waitUntil` where the host has one and
+     * is awaited inline where it does not, so a host that can serve
+     * `objectStorage` serves the deferral at the same level.
+     */
     objectStorage?: Capability;
+    /**
+     * Snapshot backups kept in object storage rather than on the machine
+     * that took them — `lunora backup create|list|restore --bucket`, and
+     * the platform's own `backupCron`. Distinct from
+     * `objectStorage` above because it needs three things a
+     * bucket alone does not imply: an admin-gated read of one object
+     * (`GET /_lunora/admin/storage/object`), a checksum-verified write, and
+     * a scheduler to run the unattended half.
+     */
+    objectStorageBackups?: Capability;
+    /**
+     * The CDC changelog's cold tier: rows a retention sweep is about to
+     * destroy are written to an object-storage bucket first
+     * (`LUNORA_CDC_ARCHIVE`), and a consumer whose cursor has fallen below
+     * the retained window is served from there instead of being told to
+     * re-seed.
+     *
+     * Distinct from `objectStorage` because it needs the bucket to do one
+     * thing a plain byte store need not: resume a key-ordered listing from a
+     * position (`list({ startAfter })`). Without it the read-back re-lists
+     * the prefix from the front every time and stops finding the range it
+     * needs once enough segments precede the cursor — which fails as a
+     * refusal rather than a gap, but fails permanently and silently, so a
+     * host that cannot seek should say `unsupported` here rather than
+     * inherit `objectStorage`'s rating.
+     */
+    objectStorageCdcArchive?: Capability;
     /** Pipelines / streaming data. */
     pipelines?: Capability;
     /** Queue-backed workpools. */
@@ -505,10 +694,26 @@ interface PlatformCapabilities {
     scheduler?: Capability;
     /** Secrets management. */
     secrets?: Capability;
+    /**
+     * `onQueryChange` reactors — server-side reactivity: a subscriber that is
+     * not a socket, woken after a write flush when a watched read's result
+     * changed.
+     *
+     * Host-dependent because the whole mechanism rests on the host being able
+     * to run work AFTER a write commits, on the same shard, without a client
+     * connection to hang it off — and on that work being serialized against
+     * further writes so a reactor's own writes cascade deterministically
+     * rather than interleaving.
+     */
+    serverReactors?: Capability;
     /** Alarms / scheduled wakeup inside a shard. */
     shardAlarms?: Capability;
     /** Durable Object-style sharded state. */
     shardedState?: Capability;
+    /** Geographic placement of a shard (`ShardPlacement.locationHint`). */
+    shardPlacement?: Capability;
+    /** Region-local read replicas of a shard, for one-shot queries. */
+    shardReadReplicas?: Capability;
     /** Vector database (Vectorize / pgvector / Pinecone). */
     vectorStore?: Capability;
     /** Hibernated WebSocket subscriptions. */
@@ -535,29 +740,72 @@ declare const CLOUDFLARE_CAPABILITIES: PlatformCapabilities;
  * The Node capability matrix — `@lunora/platform-node`'s honest self-rating
  * (plan 234).
  *
- * `@lunora/platform-node` is a spike: a `ShardHost`/`SocketHost`/
- * `ShardDirectory`/`ShardKvStore`/`SchedulerHost` implementation over
- * `better-sqlite3` and an in-process registry, built to run the conformance
- * TCK against a second host and discover what the contracts under-specify.
- * It is a single Node process with no distributed placement, no host-level
- * scheduler to re-arm timers after a restart, and no bindings at all for the
- * Cloudflare-specific products (R2, Vectorize, Workers AI, Queues,
- * Workflows, Containers, Browser Rendering, Analytics Engine, Secrets Store,
- * Hyperdrive) most `ctx.*` surfaces are built on. Every one of those is
- * rated `"unsupported"` here rather than left undeclared — see
- * `gateAgainstMatrix` in `@lunora/codegen`, whose fail-closed gate (plan
- * 229) treats an undeclared feature as unsupported anyway, but under a
- * different diagnostic name than an honest, explicit rating.
+ * `@lunora/platform-node` implements every contract in this package
+ * (`ShardHost`, `SocketHost`, `ShardDirectory`, `ShardKvStore`,
+ * `SchedulerHost`) over `better-sqlite3` and an in-process registry, plus the
+ * `.global()` table backend via `@lunora/sql-store`. It began as a spike to run
+ * the conformance TCK against a second host; the durability gaps that spike
+ * surfaced — alarms and scheduler jobs that were persisted but never re-armed,
+ * socket attachments that lived only in memory — are closed, and each is now
+ * pinned by a restart test rather than only by a simulated recycle.
  *
- * Two features are rated `"emulated"` rather than `"native"` even though
- * this package fully implements their contract, because "native" would
- * overstate what a bare Node process provides on its own: `keyValueStore` is
- * a SQL table wearing a KV-shaped API, not a dedicated KV product, and
- * `websocketHibernation` never actually evicts a socket to save memory — it
- * only proves the attachment/tag durability half of the contract, not real
- * hibernation. Both ratings, and the `"unsupported"` ones for `scheduler`
- * durability and `globalTables`, are argued in detail in
- * `plans/234-node-host-findings.md`.
+ * `scheduler` and `shardAlarms` were rated `"unsupported"` under plan 267, on
+ * the grounds that the host stored and timed both while its timer body only
+ * cleared bookkeeping — nothing dispatched the scheduled function or woke the
+ * alarm. That rating was correct for the code it described, and the code is
+ * what changed: both now dispatch (through `onDispatch` / `onAlarm`) and both
+ * re-arm from their durable rows on construction, so `"emulated"` — built on
+ * lower-level primitives and *working* — is now the honest reading.
+ *
+ * What remains genuinely absent is everything a single Node process cannot
+ * distribute: placement across nodes, failover, and most Cloudflare-specific
+ * product bindings (Vectorize, Workers AI, Containers, Browser Rendering,
+ * Analytics Engine, Secrets Store, Hyperdrive). Workflows, object storage and
+ * queues are the three that CAN be emulated locally — `defineWorkflow` handlers
+ * compile onto the `@visulima/workflow` engine, R2 becomes a filesystem bucket,
+ * and Queues becomes a durable table with the same batch/ack/retry/dead-letter
+ * semantics — so those three are rated `"emulated"`; the rest of the Cloudflare
+ * products most `ctx.*` surfaces are built on are rated `"unsupported"` here
+ * rather than left undeclared — see `gateAgainstMatrix` in `@lunora/codegen`,
+ * whose fail-closed gate (plan 229) treats an undeclared feature as unsupported
+ * anyway, but under a different diagnostic name than an honest, explicit rating.
+ *
+ * Almost nothing here is rated `"native"`, and that is the matrix's own
+ * definition doing its job rather than a hedge: `native` means the platform
+ * itself provides the feature, and a bare Node process provides essentially
+ * none of them — Lunora builds alarms out of `setTimeout` plus a durable row,
+ * a KV store out of a SQL table, and `.global()` tables out of a second SQLite
+ * file. `localSql` is the exception, because SQLite genuinely is the platform
+ * primitive there. The ratings say who does the work; the notes say how well.
+ * Both are argued in detail in `plans/234-node-host-findings.md`.
  */
 declare const NODE_CAPABILITIES: PlatformCapabilities;
-export { type AnalyticsEngineDataPoint, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, CLOUDFLARE_CAPABILITIES, type Capability, type CapabilityLevel, type D1DatabaseLike, type D1PreparedStatementLike, type D1SessionLike, type ExecutionContextLike, type KVNamespaceLike, type KvGetOptions, type KvListKey, type KvNamespaceListResult, type KvNamespacePutOptions, type KvValue, type KvValueType, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, NODE_CAPABILITIES, NOOP_EXECUTION_CONTEXT, type PlatformCapabilities, type QueueBindingLike, type QueueContentType, type QueueMessageLike, type QueueRetryOptions, type QueueSendBatchOptions, type QueueSendOptions, type QueueSendOptionsLike, type QueueSendRequestLike, type R2BucketLike, type R2MultipartUploadLike, type R2ObjectBodyLike, type R2ObjectLike, type R2RangeLike, type R2UploadedPartLike, type VectorMatchLike, type VectorMetric, type VectorRecordLike, type VectorizeDeleteMutation, type VectorizeIndexDetails, type VectorizeIndexLike, type VectorizeMatch, type VectorizeMatches, type VectorizeQueryOptions, type VectorizeUpsertMutation, type VectorizeVector };
+export { type AnalyticsEngineDataPoint, type AnalyticsEngineDataPointLike, type AnalyticsEngineDatasetLike, CLOUDFLARE_CAPABILITIES, type Capability, type CapabilityLevel, type D1DatabaseLike, type D1PreparedStatementLike, type D1SessionLike,
+/**
+ * `@lunora/platform` — provider-neutral host contracts for Lunora.
+ *
+ * This package defines the structural interfaces that separate the Lunora
+ * engine from any specific host (Cloudflare Workers, AWS, Rivet, Node, etc.).
+ * It contains **types and capability metadata only** — near-zero runtime code.
+ *
+ * The contracts fall into four groups:
+ *
+ * 1. **Shard host** (`ShardHost`) — single-writer execution, transactions,
+ * local SQL, alarms, and background continuation per shard key.
+ * 2. **Socket host** (`SocketHost`) — hibernated WebSocket subscriptions with
+ * durable attachments and tagged fan-out.
+ * 3. **Shard directory** (`ShardDirectory`) — deterministic placement and RPC
+ * dispatch from shard keys to stubs.
+ * 4. **Scheduler host** (`SchedulerHost`) — durable delayed jobs, cron, and
+ * at-least-once dispatch.
+ *
+ * Plus canonical binding projections (`KVNamespaceLike`, `R2BucketLike`,
+ * `QueueBindingLike`, `D1DatabaseLike`, `VectorizeIndexLike`, …) and the
+ * `PlatformCapabilities` matrix that codegen uses to tailor emitted types per
+ * target.
+ *
+ * This package is **zero-dependency** and safe on every runtime (browser,
+ * workerd, Node). It is intended to be the leaf dependency every other
+ * `@lunora/*` package can import without creating cycles.
+ */
+type ExecutionContextLike, type HttpCacheLike, type HttpCacheQueryOptions, type KVNamespaceLike, type KvGetOptions, type KvListKey, type KvNamespaceListResult, type KvNamespacePutOptions, type KvValue, type KvValueType, type MessageBatchLike, type MessageLike, type MessageSendRequestLike, NODE_CAPABILITIES, NOOP_EXECUTION_CONTEXT, type PlatformCapabilities, type QueueBindingLike, type QueueContentType, type QueueMessageLike, type QueueRetryOptions, type QueueSendBatchOptions, type QueueSendOptions, type QueueSendOptionsLike, type QueueSendRequestLike, type R2BucketLike, type R2MultipartUploadLike, type R2ObjectBodyLike, type R2ObjectLike, type R2RangeLike, type R2UploadedPartLike, type VectorMatchLike, type VectorMetric, type VectorRecordLike, type VectorizeDeleteMutation, type VectorizeIndexDetails, type VectorizeIndexLike, type VectorizeMatch, type VectorizeMatches, type VectorizeQueryOptions, type VectorizeUpsertMutation, type VectorizeVector };