@volter/twin-upstash 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 [yyyy] [name of copyright owner]
+
+   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/README.md

@@ -0,0 +1,202 @@
+# @volter/twin-upstash
+
+A local **Upstash Redis** twin: a real, stateful Redis served over Upstash's REST protocol, built on
+the shared `@volter/world-core` kernel.
+
+Point the unmodified `@upstash/redis` SDK at it with nothing but its own `url` option and it works —
+including `@upstash/ratelimit` layered on top, which genuinely enforces a limit because this twin
+**runs its Lua**, rather than recognising it.
+
+```bash
+bun packages/twin/upstash/src/cli.ts serve --port 8079
+# then, in your app:
+#   UPSTASH_REDIS_REST_URL=http://127.0.0.1:8079
+#   UPSTASH_REDIS_REST_TOKEN=any-non-empty-token
+```
+
+## It is a Redis, not a shape-matcher
+
+`GET` returns what `SET` actually wrote. `INCR` on `"abc"` raises the vendor's own
+`ERR value is not an integer or out of range`. `LPUSH` against a string raises `WRONGTYPE`. A key
+with a TTL stops existing — for `GET`, `EXISTS`, `TTL`, `TYPE`, `KEYS` and `DBSIZE` at once — once
+the request clock passes its deadline. Strings, counters, hashes, sets, sorted sets, lists and
+streams are all modeled with their real semantics, and every key is one kernel subject, so state
+survives a restart against the same root.
+
+The one place this matters most: **`SET … NX` on an existing key answers `null`, not `"OK"`.** The
+real consumer this pack was grounded against (`dub`) branches on `res === null` in a dozen
+distributed-lock and dedupe paths; a twin that answered `"OK"` would turn every one of them into a
+silent no-op.
+
+## `EVAL` runs a Lua interpreter
+
+`upstash-lua.ts` is a tokenizer, parser and evaluator for the Lua subset real Redis scripts use.
+It was a deliberate choice over the cheaper alternative — recognising known script SHA1s and
+dispatching to hand-written TypeScript — because recognition is a fake-success generator: it passes
+for the exact bytes it memorised and silently mis-answers anything one character different, and the
+whole point of `EVAL` is that the caller supplies the program.
+
+So `@upstash/ratelimit`'s fixed-window, sliding-window and token-bucket scripts run **verbatim**, and
+nothing about them is special-cased anywhere in this pack. Their SHA1s are used only the way real
+Redis uses them: `EVALSHA` first, `NOSCRIPT No matching script. Please use EVAL.` on a miss, then
+`EVAL`, then cached. (That error string is load-bearing — the SDK's `safeEval` greps for it to
+decide whether to retry.)
+
+Supported: locals, `if`/`elseif`/`else`, numeric and generic `for`, `while`, `repeat`/`until`,
+`break`, tables, closures, the full Lua 5.1 operator set, and the `math`/`table`/`string`/`redis`
+library subset scripts actually reach for. **Unsupported constructs fail loudly by name** —
+`cjson`, `goto`, metatables, coroutines and Lua *patterns* in `string.find`/`gsub` each raise an
+error saying so, rather than being quietly mis-evaluated.
+
+The interpreter follows Lua, not JavaScript, where the two differ and it matters:
+
+- `==` does **not** coerce across types, so `"3" == 3` is false. This is faithful to a real quirk:
+  `@upstash/ratelimit`'s `cachedFixedWindow` script compares a number against a raw `ARGV` string,
+  which never matches on real Redis either. Coercing would make this twin *more* correct than the
+  vendor and hide the caller's actual behaviour.
+- Only `nil` and `false` are falsy — `0` and `""` are true.
+- A nil bulk reply becomes Lua `false`; a Lua number returned to Redis is truncated toward zero; an
+  array reply stops at the first nil.
+- `%` takes the sign of the divisor.
+
+A script is **atomic**: one that raises part-way leaves nothing behind, including the writes it had
+already made.
+
+## The REST protocol, including the parts that bite
+
+Five request forms, all served:
+
+| | |
+|---|---|
+| `POST /` | the whole command as a JSON array — `["SET","k","v","EX",100]` |
+| `GET\|POST\|PUT\|HEAD /CMD/arg/…` | path-style, args percent-decoded, command name case-insensitive |
+| `POST /set/k?EX=100` | the raw body becomes the last argument; query params become option tokens |
+| `POST /pipeline` | an array of command arrays, non-atomic |
+| `POST /multi-exec` | the same shape, as a transaction |
+
+Three details that a naive twin gets wrong and that break the real SDK:
+
+1. **`/pipeline` is not optional.** `@upstash/redis` has `enableAutoPipelining: true` *by default*,
+   so a plain `await redis.get("k")` arrives at `POST /pipeline` with body `[["get","k"]]` — not at
+   `POST /`. A twin serving only `POST /` fails against a default-configured client.
+2. **A command error is HTTP 400, not 200.** The SDK has two error paths, and only the `!res.ok` one
+   appends its `, command was: […]` suffix. Serving 200 silently changes the error text every
+   consumer's tests assert on.
+3. **`Upstash-Encoding: base64` is on by default**, and its rule is subtler than the docs say: every
+   string in `result` is encoded at any array depth *except* the simple-**status** reply `OK`. A
+   bulk string whose value happens to be `"OK"` **is** encoded (`T0s=`), and `PING`'s status `PONG`
+   is encoded too. Getting this wrong is invisible in a curl session and catastrophic through the
+   SDK, whose `base64decode` swallows failures and returns its input — so an unencoded `"PONG"`
+   (valid base64!) decodes to mojibake instead of erroring.
+
+Error semantics were probed rather than assumed. A **runtime** error (`WRONGTYPE`, a bad integer) is
+reported per-item at HTTP 200 and does **not** abort — not in a pipeline and, contrary to intuition,
+not in `/multi-exec` either, because Upstash's own docs say "all commands will be executed …
+same semantics with Redis". A **queue-time** fault (an unavailable command, a bad arity) discards
+the whole batch pre-execution at HTTP 400, with the transaction endpoint answering `EXECABORT …` or
+`… at index N, discarding transaction`.
+
+Auth accepts `Authorization: Bearer <t>`, a bare `Authorization: <t>` (undocumented but real), and
+`?_token=`. A missing or wrong credential answers the vendor's literal 401 body:
+`WRONGPASS invalid or missing auth token. See …`. Pass `--token` to make the twin demand a specific
+one; omit it and any non-empty credential is accepted (a missing one is still refused).
+
+## Time is injected, never read from the wall
+
+TTL expiry, rate-limit windows and stream ids all need a clock, and this repo forbids `Date.now()`
+inside twin behaviour — a verify has to be bit-reproducible. So every time-dependent behaviour is
+measured against **the request's own `occurredAt`**, the same timestamp the kernel stamps its action
+with. A verify pins it and gets deterministic TTL arithmetic; to test *expiry* it issues the next
+request with a later pinned instant, which is a clock advance expressed as data.
+`createUpstashRedisTwinServer({ now })` exposes the same seam over HTTP, which is how the SDK
+fidelity test proves a rate-limit window rolls over without racing anything.
+
+Expiration is **lazy**, exactly like Redis: an expired key is not swept, it simply stops being
+visible to every read at once.
+
+## Coverage
+
+**Partial and honest.** The capability manifest (`upstash-capabilities.ts`) is the *real vendor
+surface* as the denominator — enumerated top-down from Redis's own command groups as Upstash
+supports them (string, bitmap, hash, list, set, sorted-set, HyperLogLog, geo, stream, JSON, pub/sub,
+scripting, generic, server, transactions, connection) crossed with the REST protocol's own surface —
+not a list of what was built. Whole families this twin has **not** built appear as `todo`s rather
+than being left out of the count:
+
+- **RedisJSON** (`JSON.SET`/`GET`/`ARRAPPEND`/`NUMINCRBY`…), **bitmaps** (`SETBIT`/`BITCOUNT`/
+  `BITFIELD`), **HyperLogLog** (`PFADD`/`PFCOUNT`), **geo** (`GEOADD`/`GEOSEARCH`).
+- **Pub/Sub**, including the two SSE endpoints (`POST /monitor`, `POST /subscribe/{channel}`).
+- **Stream consumer groups** (`XGROUP`/`XREADGROUP`/`XACK`/`XCLAIM`), `XREAD`, and `XTRIM`/`MAXLEN`.
+- Set algebra (`SINTER`/`SUNION`/`SDIFF`), sorted-set `BYLEX` and `*STORE`, list `LMOVE`/`LINSERT`,
+  `HSCAN`, per-field hash TTLs, `GETRANGE`/`SETRANGE`/`LCS`, `COPY`, `DUMP`/`RESTORE`, `INFO`,
+  `CONFIG`, Redis **Functions**, and the `cjson`/`bit`/`struct` Lua libraries.
+- The `resp2` response format, and the quota refusals (`ERR max daily request limit exceeded` and
+  friends) — Upstash documents those error strings but publishes no figures, and the grounding pass
+  could not trigger them, so their HTTP status is **unverified** and nothing here claims one.
+
+Two options are **refused by name** rather than accepted-and-ignored, because silently not doing what
+was asked is the fake success this repo forbids: `ZRANGE … BYLEX` and `XADD … MAXLEN|MINID`.
+
+### No UI mirror
+
+Upstash Redis is an **API-first** vendor: an integrator *calls* it from code, and the Upstash console
+is a database-config and metrics dashboard for keys, plans and usage graphs — not where the work
+happens, and not an agent navigation target. So this pack ships no mirror and has no UI capabilities;
+coverage is API + connector. (`ui-scope.json` records the same decision, and the manifest test
+asserts that no UI capability ever appears here.)
+
+### SDK versions
+
+Pinned exactly, and driven unmodified in `upstash-sdk.integration.test.ts`:
+`@upstash/redis@1.35.7` and `@upstash/ratelimit@2.0.8`. "Unmodified" means un-patched, not
+un-configured — the only thing done to either is passing `url`/`token` through the SDK's own public
+constructor, with every other default (`enableAutoPipelining`, `responseEncoding: "base64"`,
+`automaticDeserialization`, `readYourWrites`) left alone.
+
+## Connector
+
+`pull` is **handle-driven**: Redis has no cheap "give me everything" endpoint (`KEYS *` is O(N) and
+Upstash's own docs warn against it on a production database), so `pullUpstashRedisKeys` pulls the
+current real value of keys the caller *names*, dispatching per type and folding them through
+the kernel observation path — so a re-pull of identical state appends zero deltas. A key the vendor does not have is
+skipped, never invented as an empty one.
+
+`pullUpstashRedisScan` exists for callers who want a walk, and takes a hard `limit`; it is
+deliberately **not** wired into the sync entrypoint, because that would put an unbounded walk of a
+production keyspace one call away.
+
+`push` is a filed `todo`, and deliberately so: a blind write-back into a production *cache* is
+destructive in a way a push to a ticket tracker is not, and the safe design (an explicit key
+allowlist plus a dry-run diff) has not been settled.
+
+## Rate budget
+
+Upstash publishes a real scalar and it is enormous — **10,000 commands/sec** on Free, Pay-As-You-Go
+and every Fixed plan up to 50 GB. Taken at face value that would license 600,000 calls a minute,
+which is not a guard.
+
+The limit that actually binds a connector loop is the **quota**: 500,000 commands per *month* on the
+free tier (~11.6/minute sustained), and per-command billing on PAYG where the docs are explicit that
+"one command is one billable request" and that each command inside a pipeline is billed
+individually. So the ceiling (600 units / 60s at weight 2 = **300 commands/minute**) is sized against
+spend, not throttling: 2,000× tighter than the documented rate limit so it can never be what trips
+the vendor's own limiter, loose enough for a few-hundred-key pull to finish in one window, and tight
+enough that burning the free monthly quota would take ~28 hours of looping instead of 50 seconds.
+`scan` costs 8 because its cost scales with the customer's keyspace rather than the request.
+
+See `upstash-budget.ts`; the mechanism is the kernel's shared `RateBudget`, and this pack
+supplies only the numbers plus the choke point every connector entrypoint applies unconditionally.
+
+## Grounding
+
+Three independent sources, cross-checked — see `spec-sources.json` for the full citation:
+
+1. **Docs** — the REST API page, the Redis-compatibility matrix, the troubleshooting pages and the
+   billing table.
+2. **SDK source** — the actually-installed `@upstash/redis@1.35.7` and `@upstash/ratelimit@2.0.8`
+   packages, read rather than recalled. This is where auto-pipelining's default, the `keepTtl`
+   camelCase quirk, the `EVAL` argument order and the `NOSCRIPT` fallback came from.
+3. **Live probes** of a real ephemeral Upstash database. Every literal error string, status code and
+   encoding rule in this pack came off that server, and it corrected the docs in five places —
+   including the docs' own stale `"value is not an int"` example, the undocumented HTTP 413, and
+   `OPTIONS` answering 200 rather than 405.

package/api/src/fetch.ts

@@ -0,0 +1,54 @@
+// The Developer API lane of the upstash pack (`api.upstash.com/v2`), as a plain fetch: the pack's router
+// (../../src/upstash-server.ts) sends every request for api.upstash.com here, and every one for
+// console.upstash.com (its sign-in, the Account > Developer API tab, Account > Teams and a team invitation's link, and the
+// QStash page, screens/). What the World clock has made due is caught up first (semantics/time.ts). The generated surface is Upstash's own
+// OpenAPI document; the key gate sits in front of the dispatch (key-gate.ts), then the kernel's cross-cutting checks
+// (read-only, a malformed body), then the handlers (semantics/). An operation this lane does not serve is the gap,
+// answered 404 in the document's Error schema (the twin's decision: the document declares no error response).
+import { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext, type DerivedOperation, type DerivedOwner, type DerivedSurface } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { apiSemantics } from './semantics/index.ts';
+import { keyGate } from './key-gate.ts';
+import { developerApiPage } from './screens/developer-api.tsx';
+import { sessionFlow } from './screens/session.tsx';
+import { qstashPage } from './screens/qstash.tsx';
+import { teamsPages } from './screens/teams.tsx';
+import { catchUp } from './semantics/time.ts';
+
+const SCREEN: DerivedOperation = { id: 'DeveloperApiPage', method: 'POST', path: '/account/api', class: 'action' };
+const GATE: DerivedOperation = { id: 'TwinKeyGate', method: 'GET', path: '/v2/redis/databases', class: 'retrieve' };
+
+export const API_HOST = 'api.upstash.com';
+export const CONSOLE_HOST = 'console.upstash.com';
+
+/** The lane's fetch: a request, and the vendor host it was sent to (api.upstash.com or console.upstash.com). */
+export type UpstashRedisApiFetch = ((request: Request, host: string) => Promise<Response>) & {
+  owners(): Record<string, DerivedOwner>;
+  /** What the World clock has made due (a daily backup, a backup completing), caught up for a request another wire of
+   *  the pack answers: the REST API's write lands after the night's backup, never inside it. */
+  catchUp(request: Request): Promise<void>;
+};
+
+export function createUpstashApiLaneFetch(options: { root?: string; readOnly?: boolean; clock?: () => string } = {}): UpstashRedisApiFetch {
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  const derived = createDerivedFetch({
+    surface: surface as DerivedSurface,
+    handlers: bindSemantics(manifest, apiSemantics, scope),
+    core: coreFor(manifest, scope),
+    around: crossCutting(manifest, { readOnly: options.readOnly ?? false, ...scope }),
+    gap: () => Response.json({ code: 'not_found', message: 'Not Found' }, { status: 404 }),
+  });
+  const contextFor = (request: Request) => semanticsContext(manifest, request, SCREEN, scope);
+  const due = async (request: Request): Promise<void> => { if (!options.readOnly) await catchUp(await contextFor(new Request(request.url))); };
+  return Object.assign(async (request: Request, host: string): Promise<Response> => {
+    await due(request);
+    if (host === CONSOLE_HOST) {
+      const screen = (await sessionFlow(request.clone(), await contextFor(new Request(request.url)))) ?? (await qstashPage(request.clone(), contextFor))
+        ?? (await teamsPages(request.clone(), contextFor)) ?? (await developerApiPage(request, contextFor));
+      return screen ?? new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+    }
+    const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), GATE, scope);
+    return keyGate(ctx, request) ?? derived(request);
+  }, { owners: () => derived.owners(), catchUp: due });
+}

package/api/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.yaml.gz","format":"openapi","version":"1.0.0","basePath":"/v2","resources":[{"name":"AuditLog","schema":"AuditLog","fields":[{"name":"action","type":"integer","nullable":false},{"name":"action_string","type":"string","nullable":false},{"name":"actor","type":"string","nullable":false},{"name":"customer_id","type":"string","nullable":false},{"name":"entity","type":"string","nullable":false},{"name":"ip","type":"string","nullable":false},{"name":"log_id","type":"string","nullable":false},{"name":"notes","type":"string","nullable":false},{"name":"readable_format","type":"string","nullable":false},{"name":"reason","type":"string","nullable":false},{"name":"secondary_entity","type":"string","nullable":false},{"name":"source","type":"string","nullable":false},{"name":"third_entity","type":"string","nullable":false},{"name":"timestamp","type":"integer","nullable":false},{"name":"ttl","type":"integer","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"Backup","schema":"Backup","fields":[{"name":"backup_id","type":"string","nullable":false},{"name":"backup_size","type":"integer","nullable":false},{"name":"creation_time","type":"integer","nullable":false},{"name":"customer_id","type":"string","nullable":false},{"name":"daily_backup","type":"string","nullable":false,"enum":["true","false"]},{"name":"database_id","type":"string","nullable":false},{"name":"hourly_backup","type":"string","nullable":false,"enum":["true","false"]},{"name":"internal_backup_tag","type":"string","nullable":false},{"name":"name","type":"string","nullable":false},{"name":"state","type":"string","nullable":false,"enum":["pending","completed","failed"]}],"stateCandidates":[{"field":"daily_backup","values":["false","true"]},{"field":"hourly_backup","values":["false","true"]},{"field":"state","values":["completed","failed","pending"]}],"expandable":[]},{"name":"Database","schema":"Database","fields":[{"name":"all_members","type":"array","nullable":false},{"name":"auto_upgrade","type":"boolean","nullable":false},{"name":"budget","type":"integer","nullable":false},{"name":"consistent","type":"boolean","nullable":false},{"name":"creation_time","type":"integer","nullable":false},{"name":"customer_id","type":"string","nullable":false},{"name":"daily_backup_enabled","type":"boolean","nullable":false},{"name":"database_id","type":"string","nullable":false},{"name":"database_name","type":"string","nullable":false},{"name":"db_acl_default_user_status","type":"string","nullable":false,"enum":["true","false"]},{"name":"db_acl_enabled","type":"string","nullable":false,"enum":["true","false"]},{"name":"db_conn_idle_timeout","type":"integer","nullable":false},{"name":"db_disk_threshold","type":"integer","nullable":false},{"name":"db_eviction","type":"boolean","nullable":false},{"name":"db_lua_credits_per_min","type":"integer","nullable":false},{"name":"db_lua_timeout","type":"integer","nullable":false},{"name":"db_max_clients","type":"integer","nullable":false},{"name":"db_max_commands_per_second","type":"integer","nullable":false},{"name":"db_max_entry_size","type":"integer","nullable":false},{"name":"db_max_loads_per_sec","type":"integer","nullable":false},{"name":"db_max_request_size","type":"integer","nullable":false},{"name":"db_memory_threshold","type":"integer","nullable":false},{"name":"db_request_limit","type":"integer","nullable":false},{"name":"db_resource_size","type":"string","nullable":false,"enum":["S","M","L","XL","XXL","3XL"]},{"name":"db_store_max_idle","type":"integer","nullable":false},{"name":"db_type","type":"string","nullable":false,"enum":["bolt","badger","pebble"]},{"name":"endpoint","type":"string","nullable":false},{"name":"eviction","type":"boolean","nullable":false},{"name":"last_plan_upgrade_time","type":"integer","nullable":false},{"name":"modifying_state","type":"string","nullable":false},{"name":"password","type":"string","nullable":false},{"name":"port","type":"integer","nullable":false},{"name":"primary_members","type":"array","nullable":false},{"name":"primary_region","type":"string","nullable":false,"enum":["us-east-1","us-east-2","us-west-1","us-west-2","ca-central-1","eu-central-1","eu-west-1","eu-west-2","sa-east-1","ap-south-1","ap-northeast-1","ap-southeast-1","ap-southeast-2","af-south-1","us-central1","us-east4","europe-west1","asia-northeast1"]},{"name":"prod_pack_enabled","type":"boolean","nullable":false},{"name":"prometheus_enabled","type":"string","nullable":false,"enum":["true","false"]},{"name":"read_only_rest_token","type":"string","nullable":false},{"name":"read_regions","type":"array","nullable":false},{"name":"region","type":"string","nullable":false,"enum":["global"]},{"name":"replicas","type":"integer","nullable":false},{"name":"rest_token","type":"string","nullable":false},{"name":"securityAddons","type":"object","nullable":false},{"name":"state","type":"string","nullable":false,"enum":["active","suspended","passive"]},{"name":"tls","type":"boolean","nullable":false},{"name":"type","type":"string","nullable":false,"enum":["free","payg","pro","paid"]}],"stateCandidates":[{"field":"db_acl_default_user_status","values":["false","true"]},{"field":"db_acl_enabled","values":["false","true"]},{"field":"db_resource_size","values":["3XL","L","M","S","XL","XXL"]},{"field":"db_type","values":["badger","bolt","pebble"]},{"field":"primary_region","values":["af-south-1","ap-northeast-1","ap-south-1","ap-southeast-1","ap-southeast-2","asia-northeast1","ca-central-1","eu-central-1","eu-west-1","eu-west-2","europe-west1","sa-east-1","us-central1","us-east-1","us-east-2","us-east4","us-west-1","us-west-2"]},{"field":"prometheus_enabled","values":["false","true"]},{"field":"state","values":["active","passive","suspended"]},{"field":"type","values":["free","paid","payg","pro"]}],"expandable":[]},{"name":"QStashUser","schema":"QStashUser","fields":[{"name":"active","type":"boolean","nullable":false},{"name":"budget","type":"integer","nullable":false},{"name":"created_by","type":"string","nullable":false},{"name":"creation_time","type":"integer","nullable":false},{"name":"customer_id","type":"string","nullable":false},{"name":"deletion_time","type":"integer","nullable":false},{"name":"enterprise","type":"object","nullable":false},{"name":"id","type":"string","nullable":false},{"name":"last_plan_upgrade_time","type":"integer","nullable":false},{"name":"max_bandwidth_per_second","type":"integer","nullable":false},{"name":"max_delay","type":"integer","nullable":false},{"name":"max_dlq_retention_time_milis","type":"integer","nullable":false},{"name":"max_dlq_size","type":"integer","nullable":false},{"name":"max_endpoints_per_topic","type":"integer","nullable":false},{"name":"max_events_size","type":"integer","nullable":false},{"name":"max_global_parallelism","type":"integer","nullable":false},{"name":"max_message_size","type":"integer","nullable":false},{"name":"max_parallelism","type":"integer","nullable":false},{"name":"max_queues","type":"integer","nullable":false},{"name":"max_requests_per_day","type":"integer","nullable":false},{"name":"max_requests_per_day_hard","type":"integer","nullable":false},{"name":"max_requests_per_second","type":"integer","nullable":false},{"name":"max_retries","type":"integer","nullable":false},{"name":"max_schedules","type":"integer","nullable":false},{"name":"max_topics","type":"integer","nullable":false},{"name":"modifying_state","type":"string","nullable":false},{"name":"prod_pack_enabled","type":"boolean","nullable":false},{"name":"prometheus_enabled","type":"string","nullable":false,"enum":["true","false"]},{"name":"read_only_token","type":"string","nullable":false},{"name":"region","type":"string","nullable":false,"enum":["eu-central-1","us-east-1"]},{"name":"reserved_price","type":"integer","nullable":false},{"name":"reserved_type","type":"string","nullable":false},{"name":"state","type":"string","nullable":false},{"name":"timeout","type":"integer","nullable":false},{"name":"token","type":"string","nullable":false},{"name":"type","type":"string","nullable":false,"enum":["free","paid"]}],"stateCandidates":[{"field":"active","values":["false","true"]},{"field":"prometheus_enabled","values":["false","true"]},{"field":"region","values":["eu-central-1","us-east-1"]},{"field":"state","values":[]},{"field":"type","values":["free","paid"]}],"expandable":[]},{"name":"SearchIndex","schema":"SearchIndex","fields":[{"name":"creation_time","type":"integer","nullable":false},{"name":"customer_id","type":"string","nullable":false},{"name":"endpoint","type":"string","nullable":false},{"name":"id","type":"string","nullable":false},{"name":"input_enrichment_enabled","type":"boolean","nullable":false},{"name":"max_daily_queries","type":"integer","nullable":false},{"name":"max_daily_updates","type":"integer","nullable":false},{"name":"max_monthly_bandwidth","type":"integer","nullable":false},{"name":"max_monthly_reranks","type":"integer","nullable":false},{"name":"max_query_per_second","type":"integer","nullable":false},{"name":"max_reads_per_request","type":"integer","nullable":false},{"name":"max_vector_count","type":"integer","nullable":false},{"name":"max_writes_per_request","type":"integer","nullable":false},{"name":"max_writes_per_second","type":"integer","nullable":false},{"name":"name","type":"string","nullable":false},{"name":"read_only_token","type":"string","nullable":false},{"name":"region","type":"string","nullable":false,"enum":["eu-west-1","us-central1"]},{"name":"throughput_vector","type":"array","nullable":false},{"name":"token","type":"string","nullable":false},{"name":"type","type":"string","nullable":false,"enum":["free","payg","fixed"]},{"name":"vercel_email","type":"string","nullable":false}],"stateCandidates":[{"field":"region","values":["eu-west-1","us-central1"]},{"field":"type","values":["fixed","free","payg"]}],"expandable":[]},{"name":"Team","schema":"Team","fields":[{"name":"copy_cc","type":"boolean","nullable":false},{"name":"team_id","type":"string","nullable":false},{"name":"team_name","type":"string","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"TeamMember","schema":"TeamMember","fields":[{"name":"copy_cc","type":"boolean","nullable":false},{"name":"member_email","type":"string","nullable":false},{"name":"member_role","type":"string","nullable":false,"enum":["owner","admin","dev","finance"]},{"name":"team_id","type":"string","nullable":false},{"name":"team_name","type":"string","nullable":false}],"stateCandidates":[{"field":"member_role","values":["admin","dev","finance","owner"]}],"expandable":[]},{"name":"VectorIndex","schema":"VectorIndex","fields":[{"name":"creation_time","type":"number","nullable":false},{"name":"customer_id","type":"string","nullable":false},{"name":"dimension_count","type":"number","nullable":false},{"name":"embedding_model","type":"string","nullable":false,"enum":["BGE_SMALL_EN_V1_5","BGE_BASE_EN_V1_5","BGE_LARGE_EN_V1_5","BGE_M3"]},{"name":"endpoint","type":"string","nullable":false},{"name":"id","type":"string","nullable":false},{"name":"index_type","type":"string","nullable":false,"enum":["DENSE","SPARSE","HYBRID"]},{"name":"max_daily_queries","type":"number","nullable":false},{"name":"max_daily_updates","type":"number","nullable":false},{"name":"max_monthly_bandwidth","type":"number","nullable":false},{"name":"max_query_per_second","type":"number","nullable":false},{"name":"max_reads_per_request","type":"number","nullable":false},{"name":"max_total_metadata_size","type":"number","nullable":false},{"name":"max_vector_count","type":"number","nullable":false},{"name":"max_writes_per_request","type":"number","nullable":false},{"name":"max_writes_per_second","type":"number","nullable":false},{"name":"name","type":"string","nullable":false},{"name":"read_only_token","type":"string","nullable":false},{"name":"region","type":"string","nullable":false,"enum":["eu-west-1","us-east-1","us-central1"]},{"name":"reserved_price","type":"number","nullable":false},{"name":"similarity_function","type":"string","nullable":false,"enum":["COSINE","EUCLIDEAN","DOT_PRODUCT"]},{"name":"sparse_embedding_model","type":"string","nullable":false,"enum":["BM25","BGE_M3"]},{"name":"throughput_vector","type":"array","nullable":false},{"name":"token","type":"string","nullable":false},{"name":"type","type":"string","nullable":false,"enum":["free","payg","fixed"]}],"stateCandidates":[{"field":"embedding_model","values":["BGE_BASE_EN_V1_5","BGE_LARGE_EN_V1_5","BGE_M3","BGE_SMALL_EN_V1_5"]},{"field":"index_type","values":["DENSE","HYBRID","SPARSE"]},{"field":"region","values":["eu-west-1","us-central1","us-east-1"]},{"field":"similarity_function","values":["COSINE","DOT_PRODUCT","EUCLIDEAN"]},{"field":"sparse_embedding_model","values":["BGE_M3","BM25"]},{"field":"type","values":["fixed","free","payg"]}],"expandable":[]}],"operations":[{"id":"listAuditLogs","method":"get","path":"/auditlogs","pathParams":[],"query":[],"basePath":"","body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"AuditLog","list":true},"class":"list","resource":"AuditLog"},{"id":"disableQStashProdPack","method":"post","path":"/qstash/disable-prodpack/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"enableQStashProdPack","method":"post","path":"/qstash/enable-prodpack/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"getQStashIPv4","method":"get","path":"/qstash/ipv4","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"moveQStashToTeam","method":"post","path":"/qstash/move-to-team","pathParams":[],"query":[],"body":[{"name":"qstash_id","type":"string","required":true},{"name":"target_team_id","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"resetQStashToken","method":"post","path":"/qstash/rotate-token/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"QStashUser","list":false},"class":"action","resource":"QStashUser"},{"id":"setQStashPlan","method":"post","path":"/qstash/set-plan/{id}","pathParams":["id"],"query":[],"body":[{"name":"plan_name","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"getQStashStats","method":"get","path":"/qstash/stats/{id}","pathParams":["id"],"query":[{"name":"period","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"updateQStashBudget","method":"patch","path":"/qstash/update-budget/{id}","pathParams":["id"],"query":[],"body":[{"name":"budget","type":"integer","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"getQStashUser","method":"get","path":"/qstash/user/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"QStashUser","list":false},"class":"retrieve","resource":"QStashUser"},{"id":"listQStashUsers","method":"get","path":"/qstash/users","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"QStashUser","list":true},"class":"list","resource":"QStashUser"},{"id":"changePlan","method":"post","path":"/redis/{id}/change-plan","pathParams":["id"],"query":[],"body":[{"name":"auto_upgrade","type":"boolean","required":false},{"name":"database_id","type":"string","required":false},{"name":"plan_name","type":"string","required":true},{"name":"prod_pack_enabled","type":"boolean","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"createBackup","method":"post","path":"/redis/create-backup/{id}","pathParams":["id"],"query":[],"body":[{"name":"name","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"createDatabase","method":"post","path":"/redis/database","pathParams":[],"query":[],"body":[{"name":"budget","type":"integer","required":false},{"name":"database_name","type":"string","required":true},{"name":"eviction","type":"boolean","required":false},{"name":"plan","type":"string","required":false},{"name":"platform","type":"string","required":false},{"name":"primary_region","type":"string","required":true},{"name":"read_regions","type":"array","required":false},{"name":"region","type":"string","required":false},{"name":"tls","type":"boolean","required":false}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"Database","list":false},"class":"create","resource":"Database"},{"id":"getDatabase","method":"get","path":"/redis/database/{id}","pathParams":["id"],"query":[{"name":"credentials","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Database","list":false},"class":"retrieve","resource":"Database"},{"id":"deleteDatabase","method":"delete","path":"/redis/database/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete","resource":"Database"},{"id":"listDatabases","method":"get","path":"/redis/databases","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Database","list":true},"class":"list","resource":"Database"},{"id":"deleteBackup","method":"delete","path":"/redis/delete-backup/{id}/{backup_id}","pathParams":["id","backup_id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete"},{"id":"disableAutoUpgrade","method":"post","path":"/redis/disable-autoupgrade/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"disableDailyBackup","method":"patch","path":"/redis/disable-dailybackup/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"disableEviction","method":"post","path":"/redis/disable-eviction/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"enableAutoUpgrade","method":"post","path":"/redis/enable-autoupgrade/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"enableDailyBackup","method":"patch","path":"/redis/enable-dailybackup/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"enableEviction","method":"post","path":"/redis/enable-eviction/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"enableTls","method":"post","path":"/redis/enable-tls/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Database","list":false},"class":"action","resource":"Database"},{"id":"listBackup","method":"get","path":"/redis/list-backup/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Backup","list":true},"class":"list","resource":"Backup"},{"id":"moveToTeam","method":"post","path":"/redis/move-to-team","pathParams":[],"query":[],"body":[{"name":"database_id","type":"string","required":true},{"name":"team_id","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"renameDatabase","method":"post","path":"/redis/rename/{id}","pathParams":["id"],"query":[],"body":[{"name":"name","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"Database","list":false},"class":"action","resource":"Database"},{"id":"resetPassword","method":"post","path":"/redis/reset-password/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Database","list":false},"class":"action","resource":"Database"},{"id":"restoreBackup","method":"post","path":"/redis/restore-backup/{id}","pathParams":["id"],"query":[],"body":[{"name":"backup_id","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"getDatabaseStats","method":"get","path":"/redis/stats/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"updateBudget","method":"patch","path":"/redis/update-budget/{id}","pathParams":["id"],"query":[],"body":[{"name":"budget","type":"integer","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"updateRegions","method":"post","path":"/redis/update-regions/{id}","pathParams":["id"],"query":[],"body":[{"name":"read_regions","type":"array","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"listSearchIndexes","method":"get","path":"/search","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"SearchIndex","list":true},"class":"computed","resource":"SearchIndex"},{"id":"createSearchIndex","method":"post","path":"/search","pathParams":[],"query":[],"body":[{"name":"name","type":"string","required":true},{"name":"region","type":"string","required":true},{"name":"type","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"SearchIndex","list":false},"class":"create","resource":"SearchIndex"},{"id":"getSearchIndex","method":"get","path":"/search/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"SearchIndex","list":false},"class":"retrieve","resource":"SearchIndex"},{"id":"deleteSearchIndex","method":"delete","path":"/search/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete","resource":"SearchIndex"},{"id":"renameSearchIndex","method":"post","path":"/search/{id}/rename","pathParams":["id"],"query":[],"body":[{"name":"name","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action","resource":"SearchIndex"},{"id":"resetSearchPassword","method":"post","path":"/search/{id}/reset-password","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"SearchIndex"},{"id":"getSearchIndexStats","method":"get","path":"/search/{id}/stats","pathParams":["id"],"query":[{"name":"period","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed","resource":"SearchIndex"},{"id":"transferSearchIndex","method":"post","path":"/search/{id}/transfer","pathParams":["id"],"query":[],"body":[{"name":"target_account","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action","resource":"SearchIndex"},{"id":"getGlobalSearchStats","method":"get","path":"/search/stats","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"createTeam","method":"post","path":"/team","pathParams":[],"query":[],"body":[{"name":"copy_cc","type":"boolean","required":true},{"name":"team_name","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"Team","list":false},"class":"action","resource":"Team"},{"id":"deleteTeam","method":"delete","path":"/team/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete"},{"id":"listTeams","method":"get","path":"/teams","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Team","list":true},"class":"list","resource":"Team"},{"id":"getTeamMembers","method":"get","path":"/teams/{team_id}","pathParams":["team_id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"TeamMember","list":true},"class":"list","resource":"TeamMember"},{"id":"addTeamMember","method":"post","path":"/teams/member","pathParams":[],"query":[],"body":[{"name":"member_email","type":"string","required":true},{"name":"member_role","type":"string","required":true},{"name":"team_id","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"TeamMember","list":false},"class":"action","resource":"TeamMember"},{"id":"deleteTeamMember","method":"delete","path":"/teams/member","pathParams":[],"query":[],"body":[{"name":"member_email","type":"string","required":true},{"name":"team_id","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action"},{"id":"listIndices","method":"get","path":"/vector/index","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"VectorIndex","list":true},"class":"list","resource":"VectorIndex"},{"id":"createIndex","method":"post","path":"/vector/index","pathParams":[],"query":[],"body":[{"name":"dimension_count","type":"number","required":true},{"name":"embedding_model","type":"string","required":false},{"name":"index_type","type":"string","required":false},{"name":"name","type":"string","required":true},{"name":"region","type":"string","required":true},{"name":"similarity_function","type":"string","required":true},{"name":"sparse_embedding_model","type":"string","required":false},{"name":"type","type":"string","required":false}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"VectorIndex","list":false},"class":"create","resource":"VectorIndex"},{"id":"getIndex","method":"get","path":"/vector/index/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"VectorIndex","list":false},"class":"retrieve","resource":"VectorIndex"},{"id":"deleteIndex","method":"delete","path":"/vector/index/{id}","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete","resource":"VectorIndex"},{"id":"renameIndex","method":"post","path":"/vector/index/{id}/rename","pathParams":["id"],"query":[],"body":[{"name":"name","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action","resource":"VectorIndex"},{"id":"resetIndexPasswords","method":"post","path":"/vector/index/{id}/reset-password","pathParams":["id"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"VectorIndex"},{"id":"setIndexPlan","method":"post","path":"/vector/index/{id}/setplan","pathParams":["id"],"query":[],"body":[{"name":"target_plan","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action","resource":"VectorIndex"},{"id":"getVectorIndexStats","method":"get","path":"/vector/index/{id}/stats","pathParams":["id"],"query":[{"name":"period","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed","resource":"VectorIndex"},{"id":"transferIndex","method":"post","path":"/vector/index/{id}/transfer","pathParams":["id"],"query":[],"body":[{"name":"target_account","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action","resource":"VectorIndex"},{"id":"getGlobalVectorStats","method":"get","path":"/vector/index/stats","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"}]}

package/api/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"Database":{"retrieve":"/v2/redis/database/{id}","create":{"path":"/v2/redis/database","encoding":"json","body":[{"name":"budget","type":"integer","required":false},{"name":"database_name","type":"string","required":true},{"name":"eviction","type":"boolean","required":false},{"name":"plan","type":"string","required":false},{"name":"platform","type":"string","required":false},{"name":"primary_region","type":"string","required":true},{"name":"read_regions","type":"array","required":false},{"name":"region","type":"string","required":false},{"name":"tls","type":"boolean","required":false}]},"actions":[],"states":{},"embeds":{}},"Backup":{"list":"/v2/redis/list-backup/{id}","actions":[],"states":{"state":["completed","pending"]},"embeds":{}},"Team":{"actions":[],"states":{},"embeds":{}},"TeamMember":{"actions":[],"states":{},"embeds":{}}}}

package/api/src/index.ts

@@ -0,0 +1,19 @@
+// The Developer API lane of the upstash pack (api.upstash.com and console.upstash.com), as a plain fetch: the whole pack's
+// fetch (the Redis REST wire, the Developer API and the console's pages, and QStash), whose owners are the operations this
+// lane serves. Its life walks through all of them: a customer makes its API keys on the console, makes and changes its
+// databases, backups and team through the Developer API, and its game reads and writes the databases through the REST API
+// and publishes through QStash (journeys/customer-life.outline.md).
+import type { DerivedFetch } from '@volter/world-core';
+import { createUpstashRedisTwinFetch } from '../../src/upstash-server.ts';
+import { createUpstashApiLaneFetch } from './fetch.ts';
+
+export { manifest } from './manifest.ts';
+export { createUpstashApiLaneFetch, API_HOST, CONSOLE_HOST, type UpstashRedisApiFetch } from './fetch.ts';
+// how a journey reads a REST answer sent with Upstash-Encoding: base64: the pack's own view (../../src/index.ts)
+export { answerViews } from '../../src/index.ts';
+
+export function createUpstashApiTwinFetch(options: { root?: string; readOnly?: boolean } = {}): DerivedFetch {
+  const lane = createUpstashApiLaneFetch(options);
+  const pack = createUpstashRedisTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}) });
+  return Object.assign((request: Request) => pack(request), { owners: () => lane.owners() });
+}

package/api/src/key-gate.ts

@@ -0,0 +1,30 @@
+// The Developer API lane's key gate, in front of its dispatch. "Upstash API uses HTTP Basic authentication. You should
+// pass EMAIL and API_KEY as basic authentication username and password respectively"
+// (https://upstash.com/docs/devops/developer-api/authentication); a key is made on the console's Developer API tab with a
+// name, a permission (Read/Write or Read Only) and an expiration (https://upstash.com/docs/devops/developer-api/introduction).
+//
+// The gate admits exactly an email and a key this lane issued, live and unexpired: a key made on the console's Developer
+// API tab (screens/developer-api.tsx) or, for an account a World needs of its own, one the World issues through
+// `POST /_twin/users/:email/api-key` (screens/session.tsx). Where the reference stops and the twin decides: anything
+// else (no well-formed Basic credential, an email or key the lane never issued, a deleted or expired key) answers 401
+// {code: unauthorized}; a Read Only key asking for anything but a read answers 403 {code: forbidden}.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+const refuse = (status: number, code: string, message: string): Response => Response.json({ code, message }, { status });
+
+/** The gate's answer for a request, or undefined when it may pass. */
+export function keyGate(ctx: SemanticsContext, request: Request): Response | undefined {
+  const m = /^basic\s+(\S+)$/i.exec(request.headers.get('authorization') ?? '');
+  const decoded = m ? Buffer.from(m[1]!, 'base64').toString('utf8') : '';
+  const colon = decoded.indexOf(':');
+  if (colon <= 0) return refuse(401, 'unauthorized', 'Unauthorized: send EMAIL:API_KEY as HTTP Basic authentication');
+  const email = decoded.slice(0, colon).toLowerCase();
+  const key = decoded.slice(colon + 1);
+  const sha = createHash('sha256').update(key).digest('hex');
+  const held = ctx.rowsRaw('_api_key').find((k) => k.email === email && k.key_sha256 === sha && k.deleted !== true
+    && (k.expires_at === null || String(k.expires_at) > ctx.occurredAt));
+  if (!held) return refuse(401, 'unauthorized', 'Unauthorized: the API key is not valid');
+  if (held.permission === 'read_only' && request.method !== 'GET') return refuse(403, 'forbidden', 'Forbidden: this API key is Read Only');
+  return undefined;
+}