@worker-protocol/cloudflare 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Rowing Tech, S.A.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+worker-protocol
+Copyright 2026 Rowing Tech, S.A.
+
+This product includes software developed at Rowing Tech, S.A. (https://rowing.tech).
+
+Licensed under the Apache License, Version 2.0. See LICENSE for the full text.
+
+"worker-protocol" and any conformance claim made in its name are not licensed under Apache-2.0;
+see section 6 of the License.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# @worker-protocol/cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The protocol's stores in Durable Objects, and the two Queues between an outbox and a sink: one
+mixin per piece, for Workers on Cloudflare.
+
+**worker-protocol is an open specification for Workers that can be seen, operated and given work by
+people who did not build them.** `@worker-protocol/hono` carries everything the protocol fixes and
+leaves to the platform what depends on it: where ENDP-16's outcomes, SUB-7's subscriptions and
+LOG-2's records live, and what carries a delivery. On Cloudflare that is a Durable Object and a
+Queue, and this package is the one way of writing both.
+
+## Install
+
+```
+npm i @worker-protocol/cloudflare @worker-protocol/hono hono zod
+```
+
+`hono` (`^4.13.7`) and `zod` (`^4.5.4`) are peer dependencies, shared with `@worker-protocol/hono`.
+The declarations name the Workers runtime's own types — `DurableObjectState`, `Queue`,
+`MessageBatch` — so a Worker type-checks against them with what `wrangler types` writes.
+
+**What has run, and what has not yet.** Every piece runs on workerd in this package's suite, and
+`examples/fleet-worker`, built on it, delivers to a subscriber's sink across Miniflare's Queues in
+the conformance suite. What no local run shows is a real Cloudflare account: what reaches the
+dead-letter queue after the platform's last retry, the platform's limits on batches and alarms,
+and how much writing a delivery's outcome costs the one object at scale. Those are the first things
+to watch in a first deployment.
+
+## One mixin per piece
+
+| Mixin | What it adds | Where it goes |
+|---|---|---|
+| `withOutcomes` | ENDP-16's reservations and recorded outcomes | the object `actions.outcomes` reads |
+| `withSubscriptions` | SUB-7's subscriptions, found and ensured in one step | **one** object, never one per shard |
+| `withOutbox` | an outbox, drained when a call ends and retried by the alarm | every object whose changes raise events |
+| `withLogs` | LOG-2's window, filtered and paged in SQL | the object `/logs` reads, and a Tail Worker writes |
+
+Mixins rather than one base class, because a Worker in production keeps one object per vehicle and
+one for the fleet: the subscriptions belong in the one, an outbox in every other, and a class that
+carried everything would put subscription tables in thousands of objects. Plain functions over
+`SqlStorage` would compose with any base class as well, at the price of a dozen one-line RPC
+wrappers per Worker per piece — the boilerplate this package exists to remove. A Worker with a
+single object composes all four in it:
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { withLogs, withOutbox, withOutcomes, withSubscriptions } from "@worker-protocol/cloudflare";
+
+export class Fleet extends withLogs(
+  withOutbox(withSubscriptions(withOutcomes(DurableObject<Env>)), {
+    events: (env) => env.EVENTS,
+  }),
+  { keep: 500 },
+) {
+  async ingest(readings: Reading[], now: number) {
+    // ...the domain's own writes...
+    this.enqueue(now, [taskRaised(task)]); // same transaction as the writes above
+    await this.flush(); // sends what was raised; what does not go, the alarm retries
+  }
+}
+```
+
+And one that shards puts each where it belongs:
+
+```ts
+export class Fleet extends withSubscriptions(DurableObject<Env>) {}
+export class Asset extends withOutbox(DurableObject<Env>, { events: (env) => env.EVENTS }) {
+  override async wake() {
+    // the domain's own alarm, asked for with `this.wakeAt(at)`
+    await this.ctx.storage.deleteAll();
+  }
+}
+```
+
+Each piece keeps its tables under a `wp_` prefix, so none meets a table of the domain's.
+
+## Migrations, object by object
+
+A Worker with an object per vehicle has thousands of copies of each piece's tables, and a column
+or an index added in a later release has to reach every one of them — each on its own, the first
+time it is reached after a deploy. `CREATE TABLE IF NOT EXISTS` reaches only the objects created
+after the change, so each piece instead declares a `Schema`: its name, and every step its tables
+have ever taken, oldest first. `migrate(storage, schema)` runs at the start of every method,
+applies the steps an object still lacks in one transaction with the version it records in
+`wp_schema`, and costs one read of that table when there is nothing to do.
+
+A published step is never edited, and a change is a new step at the end. An object written by a
+later release than the one running is refused rather than read, because older code over a newer
+shape is a rollback and not a migration.
+
+`migrate` is exported for a domain's own tables too, under a piece name of its own, so one object
+keeps one record of what shape it is in:
+
+```ts
+import { migrate, type Schema } from "@worker-protocol/cloudflare";
+
+const VEHICLES: Schema = {
+  piece: "fleet.vehicles",
+  steps: [
+    ["CREATE TABLE IF NOT EXISTS vehicle (plate TEXT PRIMARY KEY)"],
+    ["ALTER TABLE vehicle ADD COLUMN kind TEXT NOT NULL DEFAULT 'unknown'"],
+  ],
+};
+
+const sql = migrate(this.ctx.storage, VEHICLES);
+```
+
+**There is no ORM here, on purpose.** The tables are few, the queries plain, and most of what they
+hold is a JSON record in one column. A query builder carried by a library would be a version every
+Worker installing it has to agree with — and Drizzle's migrations keep one journal per database,
+which a Worker using Drizzle for its own tables in the same object would share with this package's.
+A Worker that wants Drizzle or Kysely for its domain uses it, beside these tables.
+
+## The outbox, and the one alarm
+
+`enqueue(at, events)` writes each event with its id in the same transaction as the calling method's
+own writes, so there is no moment at which a Fact changed and its event was not yet owed. The row
+holds the whole event, so the domain's retention need not wait for what is pending — an outbox of
+ids, rendered into events only when they are sent, would duplicate nothing and make every Worker
+coordinate its retention with it by hand. An id still
+waiting is not enqueued twice; once sent, the same id enqueued again is a republication under the
+same `source` and `id`, which a consumer remembering them discards (EVT-8).
+
+`flush()` sends what is waiting to the events Queue, in order, a hundred at a time, and never
+rejects: what could not be sent stays, and the alarm tries again from five seconds, doubling to
+five minutes. **A Durable Object has one alarm**, so the domain does not set it: it asks with
+`wakeAt(at)` and overrides `wake()`, and the alarm fires at the earlier of the domain's instant and
+the outbox's retry. A base class that sets the alarm itself does not compose with this one.
+
+## The two Queues
+
+```ts
+import { consumeQueues, deliveryQueue, durableSubscriptions } from "@worker-protocol/cloudflare";
+
+const hubOf = (env: Env) =>
+  eventHub({
+    id: ID,
+    events: EVENTS,
+    subscriptions: {
+      abandonAfterSeconds: 86_400,
+      store: durableSubscriptions(fleetOf(env)),
+      queue: deliveryQueue(env.DELIVERIES),
+    },
+  });
+
+export default {
+  fetch: app.fetch,
+  queue: consumeQueues<Env>({
+    queues: { events: "fleet-events", deliveries: "fleet-deliveries" },
+    hub: hubOf,
+    deadLetter: (env) => env.DEAD,
+    broker: ({ event }) => publishToKafka(event), // where the Worker declares a broker
+    record: ({ rows, env }) => fleetOf(env).record(rows), // where it keeps logs
+  }),
+};
+```
+
+The consumer of the events Queue publishes each batch through the hub — the subscriptions are read
+once per type for the whole batch — and leaves one delivery per matching subscription on the
+deliveries Queue, then hands each event to the broker. An event of a type the Worker does not
+declare is set aside rather than retried, since no retry would mend it, and a failure to reach the
+store retries the batch whole, once. The consumer of the deliveries Queue runs `deliver()` and hands
+its decision back: `retry({ delaySeconds })`, or `ack()`.
+
+What is given up goes to the dead-letter queue as a `GivenUp`, tagged by its `kind` — a delivery
+refused for good, outside EVT-8's window or abandoned with its subscription, with the reason; or an
+event of an undeclared type — to be inspected and never redriven, and to a record an operator reads
+through `/logs`. Name the same queue as each consumer's `dead_letter_queue` in
+`wrangler.jsonc`, so it also receives what the platform drops after `max_retries`, and set
+`max_retries` well above what the hub asks for: its default of 3 cuts a delivery short.
+
+## Also exported
+
+`durableOutcomes`, `durableSubscriptions` and `durableLogs` turn a stub into the store `mount()`
+takes. A subscription crosses the RPC boundary as JSON — its filters nest, and a stub's types do not
+survive a recursive one — and these do the parsing, so a Worker never sees the strings.
+`tailRecords(events)` is what a Tail Worker records of the invocations it is handed: an exception
+nobody caught and an invocation that ended badly, and never their `console` output.
+
+## Related packages
+
+- `@worker-protocol/hono` — `mount()` and `eventHub()`, which these stores are for.
+- `@worker-protocol/client` — `consume()` and `sink()`, the other end of a subscription.
+- `@worker-protocol/conformance` — point it at a Worker's base URL, get a report of what it complies
+  with.
+
+## License and name
+
+Apache-2.0, patent grant included — implement the protocol in any product, commercial or not,
+without asking anyone. The name is not part of that grant (Apache-2.0 §6): a claim that something
+*speaks worker-protocol* is one this project vouches for, and the conformance tool is how it is
+earned.

package/dist/durable.d.ts

@@ -0,0 +1,38 @@
+import type { DurableObject } from "cloudflare:workers";
+/**
+ * Any Durable Object class, as a mixin here takes it.
+ *
+ * The rest parameter is `any[]` because TypeScript requires exactly that of a mixin's base
+ * constructor (TS2545), and it is the one `any` in this package: the constructor is the platform's,
+ * called by the platform with `(ctx, env)`, and nothing here calls it.
+ */
+export type DurableObjectClass = abstract new (...args: any[]) => DurableObject<unknown>;
+/**
+ * What a mixin answers: the class it was given, with the methods it adds.
+ *
+ * Spelled out as the return type of every mixin, rather than inferred from the class inside it,
+ * because the inferred type carries `ctx` and `env` — protected on `DurableObject` — and TypeScript
+ * cannot write a protected member of an anonymous class into a declaration file (TS4094). The
+ * intersection keeps both: a subclass still reaches `this.ctx`, through the class it was given.
+ */
+export type Mixed<B extends DurableObjectClass, M> = B & (abstract new (...args: any[]) => M);
+/** The environment a Durable Object class was declared with, read back off the class. */
+export type EnvOf<B extends DurableObjectClass> = InstanceType<B> extends DurableObject<infer E> ? E : never;
+/** The one row a query answers, or `undefined`. */
+export declare const first: <T extends Record<string, SqlStorageValue>>(cursor: SqlStorageCursor<T>) => T | undefined;
+/** What one `sendBatch` carries: the platform's own cap per call. */
+export declare const BATCH = 100;
+/** Bodies as Queue messages, in JSON rather than structured clone so a dead-letter queue reads. */
+export declare const asJson: <T>(bodies: T[]) => {
+    body: T;
+    contentType: "json";
+}[];
+/**
+ * A stub's view of what a mixin adds: every method, over RPC, answering a promise.
+ *
+ * Derived rather than written out, so that a mixin's methods and the adapter that reaches them over
+ * a stub are one list and cannot drift.
+ */
+export type Rpc<M> = {
+    [K in keyof M]: M[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
+};

package/dist/durable.js

@@ -0,0 +1,6 @@
+/** The one row a query answers, or `undefined`. */
+export const first = (cursor) => cursor.toArray()[0];
+/** What one `sendBatch` carries: the platform's own cap per call. */
+export const BATCH = 100;
+/** Bodies as Queue messages, in JSON rather than structured clone so a dead-letter queue reads. */
+export const asJson = (bodies) => bodies.map((body) => ({ body, contentType: "json" }));

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@worker-protocol/cloudflare` — the protocol's stores in Durable Objects, and the two Queues
+ * between an outbox and a sink.
+ *
+ * `@worker-protocol/hono` leaves to the platform what depends on it: where ENDP-16's outcomes,
+ * SUB-7's subscriptions and LOG-2's records live, and what carries a delivery. On Cloudflare that is
+ * a Durable Object and a Queue, and this package is the one way of writing both, so that each Worker
+ * on the platform does not write it again with its own mistakes.
+ *
+ * **One mixin per piece**, because a Worker in production keeps one object per vehicle and one for
+ * the fleet, and each object should carry only what it holds: the subscriptions in the one, an
+ * outbox in every other. A Worker with a single object composes all four in it.
+ */
+export type { DurableObjectClass, EnvOf, Mixed } from "./durable.ts";
+export { durableLogs, type LogMethods, type LogRow, type LogRows, type LogsQuery, type LogsRpc, tailRecords, withLogs, } from "./logs.ts";
+export { type Flushed, type OutboxEvent, type OutboxMethods, withOutbox } from "./outbox.ts";
+export { durableOutcomes, type OutcomeMethods, type OutcomesRpc, withOutcomes, } from "./outcomes.ts";
+export { consumeQueues, deliveryQueue, type GivenUp, type QueuesConfig, } from "./queues.ts";
+export { migrate, type Schema } from "./schema.ts";
+export { durableSubscriptions, type SubscriptionMethods, type SubscriptionsRpc, withSubscriptions, } from "./subscriptions.ts";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@worker-protocol/cloudflare` — the protocol's stores in Durable Objects, and the two Queues
+ * between an outbox and a sink.
+ *
+ * `@worker-protocol/hono` leaves to the platform what depends on it: where ENDP-16's outcomes,
+ * SUB-7's subscriptions and LOG-2's records live, and what carries a delivery. On Cloudflare that is
+ * a Durable Object and a Queue, and this package is the one way of writing both, so that each Worker
+ * on the platform does not write it again with its own mistakes.
+ *
+ * **One mixin per piece**, because a Worker in production keeps one object per vehicle and one for
+ * the fleet, and each object should carry only what it holds: the subscriptions in the one, an
+ * outbox in every other. A Worker with a single object composes all four in it.
+ */
+export { durableLogs, tailRecords, withLogs, } from "./logs.js";
+export { withOutbox } from "./outbox.js";
+export { durableOutcomes, withOutcomes, } from "./outcomes.js";
+export { consumeQueues, deliveryQueue, } from "./queues.js";
+export { migrate } from "./schema.js";
+export { durableSubscriptions, withSubscriptions, } from "./subscriptions.js";

package/dist/logs.d.ts

@@ -0,0 +1,64 @@
+import { type LogFacts, type LogLevel } from "@worker-protocol/hono";
+import type { DurableObjectClass, Mixed, Rpc } from "./durable.ts";
+/**
+ * LOG-2's window, in the Durable Object a Worker writes its records to.
+ *
+ * **Written on purpose, never captured.** There is no API in the Workers runtime for reading a
+ * Worker's own `console` back, and this does not go looking for one: a Worker records what is worth
+ * a line, in one call, the way it raises an event. A record written on purpose belongs to the work
+ * that produced it; a `console` line scraped out of the runtime belongs to whichever isolate was
+ * running.
+ *
+ * SQL, because a read filters by a level floor and a half-open interval (LOG-7, LOG-8), and a store
+ * that cannot filter would hand the Worker every row so it could throw most of them away. `seq` is
+ * what makes ENDP-33 free: it only grows, a cursor names one, and a page asks for what is below it,
+ * so a record written since the last page cannot appear in the next.
+ */
+/** One record as it crosses the RPC boundary: an instant as a number, and `fields` flat (LOG-9). */
+export type LogRow = {
+    at: number;
+    level: LogLevel;
+    message: string;
+    fields?: Record<string, string | number | boolean>;
+};
+/** One page as the object answers it, before `durableLogs` turns instants into `Date`s. */
+export type LogRows = {
+    rows: LogRow[];
+    nextCursor?: string;
+};
+/** A read as the object takes it: `mount()`'s query, with the floor and the cursor as numbers. */
+export type LogsQuery = {
+    /** LOG-7. The floor: this level and every level above it. */
+    minRank: number;
+    /** ENDP-21. The position the caller's cursor named, or `null` for the first page. */
+    before: number | null;
+    from: number | null;
+    to: number | null;
+    limit: number;
+};
+/** What `withLogs` adds to a Durable Object. */
+export interface LogMethods {
+    record(rows: LogRow[]): void;
+    logs(query: LogsQuery): LogRows;
+}
+export declare function withLogs<B extends DurableObjectClass>(Base: B, options: {
+    /** LOG-2: how many records the window holds. The oldest go first. */
+    keep: number;
+}): Mixed<B, LogMethods>;
+/** What `durableLogs` needs of a stub: the read `withLogs` adds, over RPC. */
+export type LogsRpc = Pick<Rpc<LogMethods>, "logs">;
+/** `logs` for `mount()`, over the object with `withLogs`. `mount()` decodes the query. */
+export declare const durableLogs: (stub: LogsRpc, options: {
+    pageSize: number;
+}) => LogFacts;
+/**
+ * What a Tail Worker records of the invocations it is handed: an exception nobody caught, and an
+ * invocation that ended badly — the two things a Worker cannot record about itself, because by
+ * then it has stopped running.
+ *
+ * **It throws `event.logs` away**, which is every `console` call the producer made: forwarding it
+ * would be the capture `spec/logs.md` argues against. That filter is also what stops a tail from
+ * feeding itself — its own write to the object is traced, comes back as `ok` with no exceptions,
+ * and records nothing.
+ */
+export declare function tailRecords(events: TraceItem[]): LogRow[];