spacewave 0.0.0 → 0.57.7

package/AGENTS.md

@@ -0,0 +1,82 @@
+# Building with Spacewave
+
+Use this guide when adding the `spacewave` npm package to an application. Start with the [README](README.md) for setup and the [API reference](API.md) for signatures and error codes. The [task board](examples/task-board) is a complete integration with vanilla TypeScript and React clients sharing one server.
+
+## Package and runtime
+
+Install with `npm install spacewave`, or use `spacewave@next` for a prerelease. Use ESM and Node.js `>=24.15.0 <25` for the server. The package contains its compiled engine; consuming it requires no Go compiler or installation scripts.
+
+| Import | Use |
+| --- | --- |
+| `spacewave` | `defineSchema`, `connect`, `SyncError`, and public types |
+| `spacewave/server` | `createServer` and server configuration types; Node only |
+| `spacewave/react` | Optional `createSyncContext(schema)` bindings for React `>=19.2.0 <20` |
+
+Use these public entry points. Package internals and generated engine files are implementation details.
+
+For server type checking, install `@types/node` 24.x and include `"node"` in `compilerOptions.types`. React applications also need their matching React types. Check the application against the installed package so repository aliases cannot hide missing dependencies or exports.
+
+## Shared schema
+
+Keep one browser-safe schema module containing the application ID, version, collection validators, and declared mutation inputs and outputs. Import it from clients and the server. Keep token verification, authorization, and mutation handlers in server modules.
+
+Use a Standard Schema v1 validator, such as Zod. Collection writes take validator inputs; reads return stored validator outputs. Store strict JSON: null, booleans, finite numbers, strings, arrays, and plain objects. A missing record is `undefined`; a stored `null` is a value.
+
+Treat the schema ID and version as the persisted application's compatibility contract. To change an existing dataset's schema, supply an explicit migration from its stored version. `createServer` completes that maintenance transaction before admitting clients. See [Migration](API.md#migration).
+
+## Server and access
+
+Create one server per dataset directory. `createServer({ directory, schema, authenticate, authorize, mutations })` opens durable storage and returns after startup and maintenance finish.
+
+- Return a stable `subject` and `scope` from the application's real token verifier. The scope selects the caller's dataset. Supply `expiresAt` or a revocation `signal` when available.
+- Grant collection actions through `authorize({ principal, scope, collection, action })`. Read and write permissions are separate, and subscription deliveries recheck read permission. A prefix is a query selector, not an authorization boundary; this RC has no row-level authorization.
+- Use `server.as(principal)` for server-side work that follows the same policy. Reserve `server.admin(scope)` for deliberate privileged operations; it bypasses collection authorization.
+- Use `server.listen()` for a listener Spacewave owns, or `server.attach(http)` to add sync to an existing HTTP server. Set `allowedOrigins` for the frontend and use `wss://` with HTTPS. Pass tokens through `getAccessToken`, keeping them out of URLs.
+- Call `await server.close()` during shutdown. It closes its attachments, application, and storage. When using `attach(http)`, close the supplied HTTP server separately.
+
+The example's `local-demo` verifier is only for local development. Replace it before serving other users.
+
+## Client and React lifetime
+
+Await `connect({ url, schema, getAccessToken })` before using the database. Admission includes authentication and schema compatibility checks. `getAccessToken(signal)` runs for each connection attempt; obtain the current token there. The client manages reconnection.
+
+Keep a database for the application's intended connection lifetime. Use `collection(name).subscribe()` or `.watch()` for changing state, and render freshness alongside the data:
+
+| Status | Meaning |
+| --- | --- |
+| `loading` | Waiting for the first snapshot |
+| `current` | Latest received snapshot on a live connection |
+| `stale` | Last received snapshot while reconnecting |
+| `error` | Subscription ended with a failure |
+
+Snapshots contain all matching `{ key, value }` records, ordered by key. They replace the previous snapshot. A query supports only `{ prefix?: string }`; it has no SQL, pagination, row filters, or deltas.
+
+Forward cancellation signals to operations. Release subscriptions when views leave and close the database with `await db.close()` when its application lifetime ends.
+
+For React, call `createSyncContext(schema)` once at module scope. Its `SyncProvider` receives an existing database; `useCollection` manages the component's subscription and `useDatabase` exposes the database for writes. The application closes the database. Keep top-level calls to `connect()` in client startup modules; importing a package entry alone is safe during server rendering.
+
+## Writes, transactions, and recovery
+
+Use collection `put` and `delete` for single-record changes. For an operation spanning records, declare a named mutation and implement its handler with `context.collection(name)` so its reads and writes share one transaction. The server validates mutation inputs and outputs.
+
+Keep external side effects out of mutation handlers. Transaction rollback and acceptance receipts cover collection data and the returned result; they cannot roll back an email, payment, or unrelated HTTP request.
+
+Each write has a request ID. When recovery matters, choose the ID before dispatch and keep the exact input available. Handle `SyncError` by its stable `code`:
+
+- On `UNCERTAIN`, acceptance is unknown. Offer a retry of the same operation with the same request ID and exact input. An accepted duplicate returns the original result, including after a server restart.
+- On `CONFLICT`, the request ID was reused with different input. Correct the caller's request handling.
+- On `UNAVAILABLE`, the server or storage cannot currently serve the operation. Preserve the user's intent and let the application decide when to retry.
+
+Receipts remain for the dataset lifetime. The client has no durable offline replica, offline write queue, or optimistic updates. Render accepted server snapshots and keep any pending form input separate from them. See [Uncertain writes](API.md#uncertain-writes) for a concrete retry example.
+
+## Verify the integration
+
+Run the application against the installed artifact and check the behavior the change affects:
+
+- Type-check shared schema, server code, and client code with strict TypeScript.
+- Connect two clients in the same scope and a server writer. Confirm accepted changes reach both clients, then close and reopen the server to verify persistence.
+- Exercise rejected tokens, denied operations, and separate scopes. Confirm each caller sees only its authorized dataset.
+- Interrupt and restore the connection. Check stale state, recovery, and reuse of the original request ID for an uncertain write.
+- Unmount subscribed views and close clients and servers. Confirm subscriptions and processes finish.
+
+Keep queries sized for the view: defaults cap them at 10,000 records and 8 MiB per snapshot, with 256 KiB per record. Changes produce complete snapshots, so record count alone does not describe the workload. Measure scan and delivery time, memory, and storage growth with representative data before raising limits. See the [README's current scope](README.md#current-scope).

package/API.md

@@ -0,0 +1,364 @@
+# Spacewave API reference
+
+Spacewave provides typed live collections backed by durable storage. An
+application declares a schema of collections and mutations. Clients hold one
+WebSocket connection and read full snapshots that update live. A Node server
+owns storage, authentication, and per-operation authorization.
+
+Package entries:
+
+- `spacewave`: schema, client, and error API for browsers and Node.
+- `spacewave/server`: `createServer` for Node applications.
+- `spacewave/react`: optional React bindings.
+
+The server requires Node 24.15 or later, below 25. The React bindings require
+React 19.2 or later, below 20.
+
+## Schema
+
+```ts
+import { defineSchema } from 'spacewave'
+import { z } from 'zod'
+
+const todo = z.object({ title: z.string().min(1).max(120), done: z.boolean() })
+
+export const schema = defineSchema({
+  id: 'task-board',
+  version: 1,
+  collections: { todos: todo },
+  mutations: {
+    completeTodo: {
+      input: z.object({ id: z.string().min(1) }),
+      output: todo,
+    },
+  },
+})
+```
+
+`defineSchema(schema)` checks that `id` is nonempty and `version` is a safe
+integer from 1 to 4294967295, then returns the schema with its inferred types.
+Collection and mutation values are Standard Schema v1 validators; zod is one
+compatible library. `Input<V>` and `Output<V>` infer a validator's input and
+output types.
+
+Every stored value is JSON. A write must be JSON-compatible: null, booleans,
+finite numbers, strings, arrays, and plain objects. `undefined`, `bigint`,
+symbols, functions, non-finite numbers, cycles, and class instances are
+rejected. Object keys are stored in a canonical sorted form, so the same value
+always produces the same bytes.
+
+The server validates each write against the validator and stores the
+validator's output form. Reads and watch snapshots return that stored form, so
+client types use `Output<V>`.
+
+## Client
+
+```ts
+import { connect } from 'spacewave'
+
+const db = await connect({
+  url: 'ws://localhost:8787/sync',
+  schema,
+  getAccessToken: () => 'local-demo',
+})
+```
+
+`connect(options)` returns `Promise<Database<S>>`. It resolves after
+authentication, the wire and schema version check, and root admission. On
+failure it closes the connection and throws `SyncError`.
+
+`ConnectOptions<S>`:
+
+| Field | Contract |
+| --- | --- |
+| `url` | WebSocket URL without credentials, query, or fragment. |
+| `schema` | The application schema. |
+| `getAccessToken(signal)` | Returns the token or a promise of it. Called for each connection attempt. |
+| `signal?` | Aborting closes the client. |
+| `requestTimeoutMs?` | Per-request timeout. Default 15000. |
+
+`Database<S>`:
+
+| Member | Contract |
+| --- | --- |
+| `connection` | `ConnectionStatus`: `current` state plus `subscribe(listener)`, which returns a disposer. |
+| `collection(name)` | Typed access for one schema collection name. |
+| `mutate(name, input, options?)` | Runs a declared mutation and returns its declared output type. |
+| `close()` | Idempotent. Also available through `await using` (`AsyncDisposable`). |
+
+`ConnectionState` is `{ status: 'ready' | 'reconnecting' | 'closed', error? }`.
+A new client is `reconnecting` until admission completes, and `closed` after
+`close()`.
+
+One collection exposes:
+
+| Member | Contract |
+| --- | --- |
+| `get(key, options?)` | `Promise<Output \| undefined>`. |
+| `scan(query?, options?)` | One full snapshot of the prefix, ordered by key. |
+| `put(key, value, options?)` | Writes one record. `value` is the validator's input type. |
+| `delete(key, options?)` | Removes one record. |
+| `watch(query?, options?)` | `AsyncIterable<SubscriptionState<Output>>`. |
+| `subscribe(query, observer, options?)` | Pushes states to `observer.next`; `observer.error?` sees failures. Returns an unsubscribe function. |
+
+`CallOptions` is `{ signal?, requestId? }`. Forward `AbortSignal` into every
+call; cancellation propagates to the server.
+
+A record key is nonempty UTF-8 within 1024 bytes.
+
+### Subscriptions
+
+`SubscriptionState<T>` is `{ status, data, error? }` where `data` is a readonly
+array of `{ key, value }` entries:
+
+| Status | Meaning |
+| --- | --- |
+| `loading` | No snapshot has arrived yet. |
+| `current` | The connection is live and `data` is its latest received server snapshot. |
+| `stale` | The connection was lost; `data` is the last known snapshot. |
+| `error` | The subscription ended; `error` says why. |
+
+`Query` is `{ prefix?: string }`. An empty prefix covers the whole collection.
+
+Each state carries the full snapshot of every record matching the prefix,
+ordered by key. There are no per-row deltas and no per-row filters. The client
+reconnects on its own: a lost connection publishes `stale` and the stream
+resumes with `current` once the server admits the client again. An
+unrecoverable failure publishes `error` and ends the stream.
+
+```ts
+const unsubscribe = db.collection('todos').subscribe({}, {
+  next: (state) => console.log(state.status, state.data.length),
+})
+```
+
+### Uncertain writes
+
+Every write carries a request ID. The client generates one when a call omits
+`requestId`; the server accepts 1 to 128 characters.
+
+The client retries a write once when a call fails with a recoverable
+connection error, using the same request ID. If acceptance still cannot be
+confirmed, the call throws `SyncError('UNCERTAIN', ..., requestId)`. The write may or may not have
+been accepted. Retry the exact same call with the same request ID and input:
+the server recognizes the duplicate and returns the original result. Reusing a
+request ID with different input throws `CONFLICT`.
+
+Receipts of accepted writes persist in each scope's dataset for the dataset
+lifetime, so a retry stays idempotent across restarts.
+
+The client keeps no offline queue and applies no optimistic writes. If the server is unreachable, operations fail with `UNAVAILABLE`; a write that may have been sent can fail with `UNCERTAIN`. The application decides when to retry. Rendered state comes from server snapshots.
+
+```ts
+import { SyncError } from 'spacewave'
+
+const requestId = crypto.randomUUID()
+try {
+  await db.collection('todos').put(id, todo, { requestId })
+} catch (error) {
+  if (error instanceof SyncError && error.code === 'UNCERTAIN') {
+    // Same request ID, same input.
+    await db.collection('todos').put(id, todo, { requestId })
+  } else {
+    throw error
+  }
+}
+```
+
+## Errors
+
+`SyncError` extends `Error` with a stable `code` and, for writes, the
+`requestId`.
+
+| Code | Meaning |
+| --- | --- |
+| `VALIDATION` | Input, key, or configuration is invalid. |
+| `AUTHENTICATION` | The token or principal was rejected, expired, or retired. |
+| `DENIED` | `authorize` returned false. |
+| `MISSING_COLLECTION` | The collection is not declared in the schema. |
+| `SCHEMA_MISMATCH` | Application ID, schema version, or wire version differs. |
+| `QUERY_LIMIT` | A record, snapshot, or scan limit was exceeded. |
+| `CONFLICT` | A request ID was reused with different input. |
+| `UNAVAILABLE` | The connection or storage is temporarily unavailable. |
+| `UNCERTAIN` | A write's acceptance could not be confirmed. Retry the same request ID and input. |
+| `STORAGE` | Durable storage failed. |
+| `CLOSED` | The client or server is closed. |
+
+## React
+
+```ts
+import { createSyncContext } from 'spacewave/react'
+
+const { SyncProvider, useDatabase, useCollection } = createSyncContext(schema)
+```
+
+`createSyncContext(schema)` binds collection names and validator output types
+at compile time. The schema argument carries no runtime state.
+
+| Binding | Contract |
+| --- | --- |
+| `SyncProvider({ db, children })` | Supplies an already-connected `Database<S>`. It never opens, retries, or closes the db; the application owns that lifetime. |
+| `useDatabase()` | Returns the typed `Database<S>`. Throws when no provider is above in the tree. |
+| `useCollection(name, query?)` | Returns `SubscriptionState<Output>` for the collection. |
+
+The subscription restarts only when the db, the collection name, or the query
+prefix changes, so an inline query object does not resubscribe on every render.
+While a subscription loads or restarts, the state is `loading`; the previous
+query's data is not shown as current. Unmounting a component aborts its watch
+signal. Closing the db remains the application's job, for example on
+`pagehide`.
+
+```tsx
+function TodoList() {
+  const todos = useCollection('todos')
+  if (todos.status === 'loading') return <p>Loading tasks…</p>
+  if (todos.status === 'error') return <p>{todos.error?.message}</p>
+  return (
+    <ul>
+      {todos.data.map((entry) => (
+        <li key={entry.key}>{entry.value.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+createRoot(document.getElementById('app')!).render(
+  <SyncProvider db={db}>
+    <TodoList />
+  </SyncProvider>,
+)
+```
+
+## Server
+
+```ts
+import { createServer } from 'spacewave/server'
+
+const server = await createServer({
+  directory: './data',
+  schema,
+  authenticate: async (token) => {
+    if (token !== 'local-demo') throw new Error('unknown token')
+    return { subject: 'demo', scope: 'demo' }
+  },
+  authorize: ({ collection }) => collection === 'todos',
+  mutations: {
+    completeTodo: async (context, input) => {
+      const todo = await context.collection('todos').get(input.id)
+      if (!todo) throw new Error('unknown task')
+      const updated = { ...todo, done: true }
+      await context.collection('todos').put(input.id, updated)
+      return updated
+    },
+  },
+})
+```
+
+`createServer(options)` returns `Promise<SyncServer<S, P>>`. It opens the
+dataset, checks the stored application ID and version, runs any migration, and
+only then returns a server that can admit callers. Failures throw `SyncError`.
+
+`ServerOptions<S, P>`:
+
+| Field | Contract |
+| --- | --- |
+| `directory` | Dataset directory. This is the public storage option. |
+| `schema` | The application schema. |
+| `authenticate(token, signal)` | Returns `Promise<Principal>`. Called once per connection after the wire and schema version check. Throwing rejects the connection; each connection gets one attempt. |
+| `authorize(access)` | Returns `boolean \| Promise<boolean>`. Called for every operation and again for every watch delivery. |
+| `mutations` | One handler per declared mutation. |
+| `limits?` | `maxRecords` (default 10000), `maxSnapshotBytes` (default 8 MiB), `maxRecordBytes` (default 256 KiB). Exceeding a bound fails that query or write with `QUERY_LIMIT`. |
+| `migration?` | Runs before any caller is admitted when the stored schema version differs. |
+
+Storage uses built-in SQLite in a dedicated worker. A directory permits one open server writer at a time.
+
+`Principal` is `{ subject, scope, expiresAt?, signal? }`. `subject` and `scope`
+must be nonempty, with `subject` within 256 UTF-8 bytes. `expiresAt` is a Unix
+millisecond time; the connection retires at that time. Aborting `signal`
+retires the connection.
+
+`authorize` receives `{ principal, scope, collection, action }` where `action`
+is `'read'` or `'write'`. Returning false rejects the operation with `DENIED`.
+Authorization is per collection and action; queries cover a whole collection
+or a prefix. There are no per-row grants or filters.
+
+A mutation handler receives `(context, input)` and returns the mutation
+output's input type. `context` provides `collection(name)` with `get`, `scan`,
+`put`, and `delete` inside the same transaction, plus `principal`, `scope`,
+and `signal`. The server validates the handler's input and returned output
+against the schema and stores the output form.
+
+### Migration
+
+```ts
+migration: {
+  from: 1,
+  async run({ scopes, scope }) {
+    for (const name of await scopes()) {
+      const todos = scope(name).collection('todos')
+      for (const entry of await todos.scan()) {
+        await todos.put(entry.key, { title: entry.value.title, done: false })
+      }
+    }
+  },
+}
+```
+
+`Migration<S>` is `{ from, run(context) }`. `run` receives `scopes()` listing
+the stored scopes, `scope(name)` returning a transaction for that scope, and
+`signal`. The migration runs inside one maintenance transaction before any
+caller is admitted. If the stored version differs and no matching migration is
+supplied, or the dataset belongs to a different application ID, `createServer`
+fails with `SCHEMA_MISMATCH`.
+
+### Hosting and lifetime
+
+| Member | Contract |
+| --- | --- |
+| `listen(options?)` | Opens its own HTTP server. `ListenerOptions` adds `port?` (default 8787) and `host?` (default 127.0.0.1). Returns `Listener` with a `ws://` `url` and `close()`. |
+| `attach(http, options?)` | Handles the upgrade event of a supplied HTTP server. Other routes and upgrade paths stay yours. Returns `Attachment` with `close()`. |
+| `as(principal)` | `DatabaseAccess<S>` for direct server-side access as that principal. Every operation still passes `authorize`. |
+| `admin(scope)` | Privileged access as subject `admin`, with only the base principal fields. Handlers that require application-specific principal fields should use `as(principal)`. Collection authorization is bypassed; validation still applies. |
+| `close()` | Closes every attachment the server created, then the application, then storage the server opened. Idempotent. Also available through `await using`. |
+
+`AttachmentOptions` for both forms:
+
+| Field | Contract |
+| --- | --- |
+| `path?` | Upgrade path. Default `/sync`. |
+| `allowedOrigins?` | Exact Origin values to accept. |
+| `maxRequestBytes?` | Maximum WebSocket message size. Default 1 MiB. |
+
+Origin handling: a request without an Origin header, such as a non-browser
+client, is accepted. With `allowedOrigins` set, the Origin must be one of the
+listed values. Otherwise the Origin must match the request's own Host header
+with an `http` or `https` scheme. Upgrades with a query string are refused.
+
+```ts
+import { createServer as createHTTPServer } from 'node:http'
+
+const listener = await server.listen({ port: 8787 })
+console.log(listener.url)
+
+const http = createHTTPServer((request, response) => response.end())
+server.attach(http, { path: '/sync', allowedOrigins: ['https://example.com'] })
+http.listen(3000)
+```
+
+## Limits and performance
+
+Queries return complete, ordered snapshots of a collection or prefix. Defaults bound a query to 10,000 records and 8 MiB of encoded keys and values, and a record to 256 KiB. Exceeding a bound produces `QUERY_LIMIT`. These are safety bounds, not throughput guarantees.
+
+A qualification workload on Node 24.21.0 and macOS arm64 used 1,000 numeric records, three subscribers, and ten writes. Identical queries shared one producer.
+
+| Measurement | Observed sample |
+| --- | --- |
+| Write acceptance, p50 / p95 | 234 / 242 ms |
+| Delivery to all subscribers, p50 / p95 | 947 / 1,041 ms |
+| Initial bulk seeding | 13.57 seconds |
+| RSS when ready / after the workload | 336 MB / 1.10 GB |
+| Encoded snapshot | 28.9 KB |
+
+Each changed revision still requires a complete scan. RSS includes the compiled runtime and is not a retained-heap measurement. These observations describe one workload; measure representative scan and delivery time, memory, and storage growth before raising limits. Acceptance receipts and World history accumulate for the dataset lifetime.
+
+A qualified release artifact's `qualification.json` records its own sample, source revision, package sizes, and checksum. See the [README](README.md) for supported runtimes and current release scope.

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Release notes
+
+## 0.1.0-rc.1
+
+The first typed sync release candidate provides shared Standard Schema contracts, live ordered collections, named atomic server mutations, scoped authentication and authorization, durable SQLite storage, retained acceptance receipts, reconnect recovery, and optional React bindings.
+
+The package ships ESM client, server, and React exports with public TypeScript declarations and a compiled engine worker. Node 24.15–24.x is required for the server. Complete vanilla TypeScript and React task boards use the same contract and storage.
+
+Subscriptions share a bounded producer for identical scope, collection, and prefix queries. Each subscriber retains its own authorization checks and cancellation lifetime. Query limits fail the affected subscription while independent queries continue.
+
+This RC supports online authoritative operation. Offline replicas, optimistic writes, receipt pruning, and SQL query APIs are outside this release. The schema version is an application compatibility contract; changing it requires an explicit maintenance migration. Receipts and World history increase storage over the dataset lifetime. See the README for measured workload limits.

package/LICENSE

@@ -0,0 +1,191 @@
+                                 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
+
+   Copyright (c) 2018-2026 Aperture Robotics, LLC.
+   Copyright (c) 2018-2026 Christian Stewart <christian@cjs.zip>
+
+   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.