bridgebench 3.1.0-alpha.0 → 3.1.0-alpha.2

package/tasks/security/public/vuln-token-alg-confusion.yaml

@@ -0,0 +1,252 @@
+id: vuln-token-alg-confusion
+version: 1.0.0
+category: security
+cluster: vuln-discovery
+difficulty: expert
+title: Latchkey Session-Token Verification Review
+summary: Review a fictional session-token issuance/verification service where one real, reachable token-forgery vulnerability hides among three benign look-alikes (long TTL, Math.random request id, dev-secret fallback) that are each neutralized elsewhere in the artifacts.
+prompt: |
+  You are performing a defensive security review of "Latchkey", an internal
+  session-token issuance and verification service. Six artifacts describe the
+  production deployment: token-issuer, token-verifier, key-loader,
+  latchkey-config, keys-endpoint-spec, and integration-note.
+
+  Exactly one of the behaviors in these artifacts is a real, reachable
+  vulnerability; the others are look-alikes that are neutralized somewhere in the
+  same artifacts. Answer each deliverable using ONLY the supplied artifacts. Cite
+  the artifact id(s) you rely on for every claim. If something is not defined or
+  not reachable in the artifacts, say so explicitly. Reason about reachability
+  ONLY — do NOT write a forged token, signing code, or any exploit payload.
+
+  1. Name the single real vulnerability class present in token-verifier, using
+     standard terminology, and point to the exact code behavior that constitutes
+     it.
+
+  2. State the precondition / exploitability chain: the specific facts across the
+     artifacts that together make it reachable by an external attacker, and what
+     capability (not payload) an attacker needs. If any required precondition is
+     NOT satisfied by the artifacts, say so.
+
+  3. A reviewer flags the 24-hour token lifetime (lease of ttlSeconds) as the
+     critical issue. Is it? Rule it in or out and cite the mechanism that decides
+     it.
+
+  4. A reviewer flags the Math.random() requestId in token-issuer as a
+     weak-randomness vulnerability. Is it? Rule it in or out and cite the
+     evidence.
+
+  5. A reviewer flags the `|| 'dev-secret'` fallback in key-loader as a hardcoded
+     secret that is reachable in production. Is it? Rule it in or out and cite the
+     mechanism that decides it.
+
+  6. Give the severity of the one real vulnerability and the minimal control that
+     closes it. State the control precisely: what the server must do about the
+     algorithm named in the token header.
+artifacts:
+  - id: token-issuer
+    type: code
+    label: Latchkey token issuer (RS256)
+    content: |
+      // token-issuer.ts — issues Latchkey session tokens. RS256 only.
+      import { rsaSign } from './latchkey-crypto';
+      import { loadSigningKey } from './key-loader';
+      import { config } from './latchkey-config';
+      import { randomUuid } from './latchkey-crypto'; // CSPRNG-backed uuid
+
+      export function issueToken(sub: string): string {
+        // requestId is a LOG-CORRELATION tag only. It is never used as a jti,
+        // nonce, CSRF token, signature salt, or any secret (see integration-note).
+        // Math.random is adequate for correlating log lines; nothing here relies
+        // on it being unpredictable.
+        const requestId = Math.random().toString(36).slice(2);
+
+        const header = { alg: 'RS256', typ: 'LST' };
+        const now = Math.floor(Date.now() / 1000);
+        const claims = {
+          sub,
+          iss: config.expectedIssuer,
+          aud: config.expectedAudience,
+          exp: now + config.ttlSeconds, // 24h; every verify still checks revocation
+          jti: randomUuid(),            // cryptographically random token id (NOT Math.random)
+        };
+
+        log.info('issuing session token', { sub, requestId });
+
+        const signingInput = `${b64url(header)}.${b64url(claims)}`;
+        const sig = rsaSign(signingInput, loadSigningKey().privateKeyPem);
+        return `${signingInput}.${sig}`;
+      }
+  - id: token-verifier
+    type: code
+    label: Latchkey token verifier
+    content: |
+      // token-verifier.ts — verifies a compact Latchkey token of the form
+      //   base64url(header) . base64url(claims) . base64url(signature)
+
+      import { rsaVerify, hmacVerify } from './latchkey-crypto';
+      import { loadVerifyKey } from './key-loader';
+      import { isRevoked } from './revocation';
+      import { config } from './latchkey-config';
+
+      export interface Claims { sub: string; iss: string; aud: string; exp: number; jti: string; }
+
+      export function verifyToken(token: string): Claims {
+        const [rawHeader, rawClaims, rawSig] = token.split('.');
+        const header = JSON.parse(b64urlDecode(rawHeader)); // attacker-controlled bytes
+        const claims = JSON.parse(b64urlDecode(rawClaims)) as Claims;
+        const signingInput = `${rawHeader}.${rawClaims}`;
+
+        // The single verification key this service holds (see key-loader).
+        const key = loadVerifyKey();
+
+        // Choose the verification routine from the algorithm the CALLER named in
+        // the token header.
+        let signatureOk: boolean;
+        switch (header.alg) {
+          case 'RS256':
+            signatureOk = rsaVerify(signingInput, rawSig, key.publicKeyPem);
+            break;
+          case 'HS256':
+            // Symmetric path for internal callers that cannot do RSA. There is no
+            // separate HS256 key configured, so we key the HMAC with the RSA
+            // public key material we already hold.
+            signatureOk = hmacVerify(signingInput, rawSig, key.publicKeyPem);
+            break;
+          default:
+            throw new VerifyError('UNSUPPORTED_ALG');
+        }
+        if (!signatureOk) throw new VerifyError('BAD_SIGNATURE');
+
+        // Claim checks are done MANUALLY after the signature check. We deliberately
+        // do not pass audience/issuer options into the verify primitives above;
+        // these direct comparisons run on every verify.
+        if (claims.iss !== config.expectedIssuer) throw new VerifyError('BAD_ISS');
+        if (claims.aud !== config.expectedAudience) throw new VerifyError('BAD_AUD');
+        if (claims.exp * 1000 <= Date.now()) throw new VerifyError('EXPIRED');
+
+        // Live revocation: consulted on EVERY verify, so a stolen-but-revoked jti
+        // is rejected no matter how far off exp is.
+        if (isRevoked(claims.jti)) throw new VerifyError('REVOKED');
+
+        return claims;
+      }
+  - id: key-loader
+    type: code
+    label: Latchkey key material loader
+    content: |
+      // key-loader.ts — loads Latchkey key material.
+      import { config } from './latchkey-config';
+
+      export interface VerifyKey { publicKeyPem: string; }
+      export interface SignKey { privateKeyPem: string; }
+
+      let cachedVerify: VerifyKey | null = null;
+
+      // Runs ONCE at boot, before the server binds its port (see integration-note).
+      // Outside development the public key MUST be present, so control never reaches
+      // the 'dev-secret' fallback below in production — this throws first.
+      export function assertKeyMaterial(): void {
+        if (config.env !== 'development' && !process.env.LATCHKEY_PUBLIC_KEY) {
+          throw new Error('LATCHKEY_PUBLIC_KEY is required outside development');
+        }
+      }
+
+      export function loadVerifyKey(): VerifyKey {
+        if (cachedVerify) return cachedVerify;
+        // In development only, fall back to a fixed string so tests can run without
+        // real key material. assertKeyMaterial() has already aborted boot in prod
+        // if the real key is missing.
+        const pem = process.env.LATCHKEY_PUBLIC_KEY || 'dev-secret';
+        cachedVerify = { publicKeyPem: pem };
+        return cachedVerify;
+      }
+
+      export function loadSigningKey(): SignKey {
+        return { privateKeyPem: requireEnv('LATCHKEY_PRIVATE_KEY') };
+      }
+  - id: latchkey-config
+    type: config
+    label: Latchkey runtime configuration (production)
+    content: |
+      # latchkey.production.yaml — full session-token config, no keys omitted.
+      env: production
+      expectedIssuer: "https://auth.latchkey.internal"
+      expectedAudience: "latchkey-session"
+      ttlSeconds: 86400            # 24h session lifetime
+
+      revocation:
+        enabled: true             # consulted on EVERY verify (see token-verifier isRevoked)
+        store: "latchkey-revset"  # shared, synchronous revocation set
+
+      keys:
+        publicKeyEnv: LATCHKEY_PUBLIC_KEY
+        privateKeyEnv: LATCHKEY_PRIVATE_KEY
+        # The RSA public key is PUBLISHED (see keys-endpoint-spec); the private key
+        # is held only by the issuer. No symmetric / shared secret is configured for
+        # this service at all — HS256 has no key of its own.
+
+      # Algorithms the verifier will accept. There is no server-side pin narrower
+      # than this list; the verifier selects its routine from the token header.
+      allowedAlgs: ["RS256", "HS256"]
+  - id: keys-endpoint-spec
+    type: spec
+    label: Latchkey public key distribution endpoint
+    content: |
+      Latchkey key distribution — GET /.well-known/latchkey-keys.json
+
+      Access: PUBLIC, unauthenticated. World-readable by design so any client or
+      partner can fetch the key and verify session tokens offline.
+
+      Response (200):
+        {
+          "keys": [
+            {
+              "kid": "lk-2026-03",
+              "kty": "RSA",
+              "use": "sig",
+              "alg": "RS256",
+              "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...AQAB\n-----END PUBLIC KEY-----"
+            }
+          ]
+        }
+
+      The full PEM of the RSA PUBLIC key is served verbatim in the `pem` field. The
+      private key is never exposed here or anywhere else.
+
+      This is the COMPLETE and only key set for the service. There is exactly one
+      active verification key — the RSA public key above — and no separate
+      HS256 / symmetric key is distributed at this endpoint or anywhere else. Any
+      party on the internet can retrieve these exact public key bytes.
+  - id: integration-note
+    type: note
+    label: Latchkey integration notes (authoritative, as-deployed)
+    content: |
+      Latchkey integration notes — authoritative; reflects production as deployed.
+
+      - Boot: the server calls assertKeyMaterial() before it binds the port. In
+        production (env != development) a missing LATCHKEY_PUBLIC_KEY aborts boot,
+        so the 'dev-secret' string in key-loader is never live in production.
+
+      - Revocation is mandatory and synchronous: verifyToken consults the shared
+        revocation set on every call. A token is rejected the instant its jti is
+        revoked, so the 24h ttlSeconds is NOT a standing-access window beyond
+        revocation. Token lifetime is a product decision; revocation is the security
+        control.
+
+      - requestId (Math.random) is a log-correlation tag ONLY — never a jti, nonce,
+        CSRF token, or signature input. The jti is generated by randomUuid(), a
+        CSPRNG-backed identifier.
+
+      - iss and aud are validated inside verifyToken AFTER the signature check, by
+        direct comparison against config.expectedIssuer / expectedAudience. We do
+        not pass audience/issuer options into the low-level verify primitives; the
+        manual comparison is equivalent and runs on every verify.
+
+      - By design the verifier selects its verification routine from the algorithm
+        named in the token header, to let "internal callers that cannot do RSA" use
+        HS256.
+
+      This note, latchkey-config, keys-endpoint-spec, and the three code files are
+      the COMPLETE surface for token issuance and verification. There are no other
+      verify paths, key sources, or algorithm branches.
+tags: [security, vuln-discovery, jwt, algorithm-confusion, crypto-misuse]

package/tasks/speed/public/speed-api-diff-changelog.yaml

@@ -0,0 +1,42 @@
+id: speed-api-diff-changelog
+version: 1.0.0
+category: speed
+cluster: retrieval-synthesis
+difficulty: hard
+title: Write a Changelog Entry From an API Schema Diff
+summary: >-
+  Compare two versions of an API response schema, classify each field change as breaking or
+  non-breaking, and write a migration-focused changelog entry.
+prompt: |
+  Compare [schema-v1] and [schema-v2] for the same endpoint and produce a changelog entry.
+
+  1. A bulleted list of every field-level change, each tagged (BREAKING) or (non-breaking) with a
+     one-clause reason.
+  2. A short "Migration" paragraph telling integrators exactly what they must change before upgrading.
+artifacts:
+  - id: schema-v1
+    type: spec
+    label: Response schema v1
+    content: |
+      GET /users/{id} -> 200 UserV1
+      UserV1 = {
+        id: string,
+        name: string,
+        email: string,
+        role: "admin" | "member",
+        createdAt: string   // unix seconds encoded as a numeric string
+      }
+  - id: schema-v2
+    type: spec
+    label: Response schema v2
+    content: |
+      GET /users/{id} -> 200 UserV2
+      UserV2 = {
+        id: string,
+        fullName: string,                         // renamed from name
+        email: string,
+        roles: ("admin" | "member" | "billing")[], // was a single role
+        createdAt: string,                         // now ISO-8601 date-time
+        avatarUrl: string | null                   // new, nullable
+      }
+tags: [api, changelog, versioning]

package/tasks/speed/public/speed-callbacks-to-async.yaml

@@ -0,0 +1,39 @@
+id: speed-callbacks-to-async
+version: 1.0.0
+category: speed
+cluster: code-transformation
+difficulty: hard
+title: Convert a Node Callback Pipeline to Async/Await
+summary: >-
+  Rewrite a nested Node.js callback function into an equivalent async/await implementation, preserving
+  its result shape and error propagation while parallelizing the two independent reads.
+prompt: |
+  Rewrite [callback-code] using async/await and the `fs.promises` API. Preserve the returned object
+  shape and error behavior.
+
+  1. The rewritten async function with the same name and inputs (dropping the trailing callback and
+     returning a promise instead).
+  2. Any step failing must reject the returned promise with that error.
+  3. Read `config.json` first; `a.txt` and `b.txt` are independent, so read them concurrently.
+artifacts:
+  - id: callback-code
+    type: code
+    label: Original callback version
+    content: |
+      const fs = require('fs');
+
+      function loadBundle(dir, cb) {
+        fs.readFile(dir + '/config.json', 'utf8', (e1, cfg) => {
+          if (e1) return cb(e1);
+          fs.readFile(dir + '/a.txt', 'utf8', (e2, a) => {
+            if (e2) return cb(e2);
+            fs.readFile(dir + '/b.txt', 'utf8', (e3, b) => {
+              if (e3) return cb(e3);
+              cb(null, { config: JSON.parse(cfg), a, b });
+            });
+          });
+        });
+      }
+
+      module.exports = { loadBundle };
+tags: [javascript, async, refactor]

package/tasks/speed/public/speed-class-to-hooks.yaml

@@ -0,0 +1,47 @@
+id: speed-class-to-hooks
+version: 1.0.0
+category: speed
+cluster: code-transformation
+difficulty: hard
+title: Migrate a React Class Component to a Function Component With Hooks
+summary: >-
+  Convert a small React class component that fetches on mount, polls on an interval, cleans up on
+  unmount, and holds two pieces of state into an equivalent function component using hooks.
+prompt: |
+  Rewrite [class-component] as a TypeScript function component using hooks. Preserve behavior: fetch on
+  mount with abort on unmount, the polling interval, both state fields, and the rendered output.
+
+  1. The function component using `useState` and `useEffect` with a correct cleanup.
+  2. Keep the same props (`serviceId`, `intervalMs`) and the same rendered markup.
+  3. On unmount, abort the in-flight fetch and clear the interval.
+artifacts:
+  - id: class-component
+    type: code
+    label: Class component
+    content: |
+      class StatusPanel extends React.Component {
+        state = { status: 'loading', lastChecked: null };
+        controller = new AbortController();
+        timer = undefined;
+
+        async componentDidMount() {
+          const r = await fetch(`/api/status/${this.props.serviceId}`, { signal: this.controller.signal });
+          this.setState({ status: (await r.json()).state, lastChecked: Date.now() });
+          this.timer = setInterval(() => this.refresh(), this.props.intervalMs);
+        }
+
+        componentWillUnmount() {
+          this.controller.abort();
+          clearInterval(this.timer);
+        }
+
+        async refresh() {
+          const r = await fetch(`/api/status/${this.props.serviceId}`);
+          this.setState({ status: (await r.json()).state, lastChecked: Date.now() });
+        }
+
+        render() {
+          return <div>{this.state.status} @ {String(this.state.lastChecked)}</div>;
+        }
+      }
+tags: [react, hooks, migration]

package/tasks/speed/public/speed-config-schema-json.yaml

@@ -0,0 +1,34 @@
+id: speed-config-schema-json
+version: 1.0.0
+category: speed
+cluster: structured-output
+difficulty: hard
+title: Author a JSON Schema for a Service Config File
+summary: >-
+  Write a strict draft 2020-12 JSON Schema validating a service configuration object, enforcing types,
+  enums, numeric ranges, a conditional requirement, and no unexpected properties.
+prompt: |
+  Produce a single JSON Schema (draft 2020-12) that validates the config described in [config-spec].
+  Emit only the JSON.
+
+  1. Types, `enum`s, defaults, and numeric bounds for every field.
+  2. `additionalProperties: false` at each fixed object level and a correct top-level `required` list.
+  3. A conditional: when `tls.enabled` is true, `tls.certPath` and `tls.keyPath` are required.
+artifacts:
+  - id: config-spec
+    type: spec
+    label: Config shape
+    content: |
+      serviceName : string, required, 1..64 characters
+      port        : integer, required, 1..65535
+      logLevel    : one of "debug" | "info" | "warn" | "error", default "info"
+      replicas    : integer, 1..50, default 1
+      tls         : object, required
+        tls.enabled  : boolean, required
+        tls.certPath : string
+        tls.keyPath  : string
+      featureFlags: optional object mapping arbitrary string keys to boolean values
+
+      No properties beyond those listed are permitted at any level, except that featureFlags may hold
+      arbitrary string -> boolean entries.
+tags: [json-schema, validation, config]

package/tasks/speed/public/speed-csv-report-generator.yaml

@@ -0,0 +1,38 @@
+id: speed-csv-report-generator
+version: 1.0.0
+category: speed
+cluster: long-generation
+difficulty: hard
+title: Build a CSV Sales-Summary Generator From In-Memory Rows
+summary: >-
+  Write a complete TypeScript module that aggregates order rows into a per-region monthly summary and
+  serializes it to RFC 4180 CSV, including proper quoting and a totals row.
+prompt: |
+  Implement `salesSummaryCsv(rows: OrderRow[]): string` in TypeScript per [summary-spec] and
+  [csv-rules]. Emit the whole module, including any helpers.
+
+  1. The `OrderRow` interface and the `salesSummaryCsv` function.
+  2. Correct RFC 4180 quoting for fields containing commas, quotes, or newlines.
+  3. A trailing `TOTAL` row summing net revenue across all regions and months.
+artifacts:
+  - id: summary-spec
+    type: spec
+    label: Aggregation
+    content: |
+      OrderRow = { region: string; isoDate: string; revenue: number; refunded: boolean }
+      - group by (region, YYYY-MM derived from isoDate)
+      - net revenue per group = sum(revenue where refunded === false) - sum(revenue where refunded === true)
+      - output columns, in order: Region,Month,Orders,NetRevenue
+      - Orders counts every row in the group regardless of refunded
+      - sort output rows by Region ascending, then Month ascending
+      - NetRevenue is formatted to exactly two decimals
+  - id: csv-rules
+    type: spec
+    label: CSV format
+    content: |
+      - RFC 4180: any field containing a comma, double-quote, CR, or LF is wrapped in double quotes
+      - an embedded double-quote is escaped by doubling it
+      - a header row comes first; rows are joined with CRLF
+      - the final TOTAL row uses "TOTAL" in Region, an empty Month, the total order count, and the
+        summed NetRevenue across every group
+tags: [typescript, csv, reporting]

package/tasks/speed/public/speed-debounce-hook.yaml

@@ -0,0 +1,28 @@
+id: speed-debounce-hook
+version: 1.0.0
+category: speed
+cluster: short-completion
+difficulty: hard
+title: Write a Typed useDebouncedValue React Hook
+summary: >-
+  Implement a small, correct React hook that returns a debounced copy of a value, honoring the
+  behavioral contract for cleanup, delay changes, and the initial render.
+prompt: |
+  Implement `useDebouncedValue` in TypeScript for React 18 exactly per [hook-contract]. Return only the
+  hook implementation and its import line.
+
+  1. The `useDebouncedValue<T>(value: T, delayMs: number): T` implementation.
+  2. A one-sentence note stating what happens to a pending update when `value` changes again before
+     `delayMs` elapses.
+artifacts:
+  - id: hook-contract
+    type: spec
+    label: Hook behavior
+    content: |
+      useDebouncedValue<T>(value, delayMs)
+      - returns the initial value immediately on first render (no delay)
+      - after value changes, returns the new value only once delayMs has elapsed with no further change
+      - a change during the wait window cancels the previous pending update and restarts the timer
+      - clears its timer on unmount
+      - re-reads delayMs on every change, so a changed delay applies to the next debounce window
+tags: [react, hooks, typescript]

package/tasks/speed/public/speed-log-triage-summary.yaml

@@ -0,0 +1,35 @@
+id: speed-log-triage-summary
+version: 1.0.0
+category: speed
+cluster: retrieval-synthesis
+difficulty: hard
+title: Synthesize an Incident Summary From Logs and a Deploy Record
+summary: >-
+  Read a short application log excerpt and a deploy record, correlate them, and produce a concise
+  incident summary plus the single configuration change that restores prior behavior.
+prompt: |
+  Using [app-log] and [deploy-record], write a short incident summary and a one-line configuration fix.
+
+  1. A 3-4 sentence summary: what failed, the first timestamp it appeared, the likely trigger
+     (correlated with [deploy-record]), and the user-visible impact.
+  2. The single environment-variable change (name and value) that would restore the prior behavior,
+     citing the log line that identifies it.
+artifacts:
+  - id: app-log
+    type: log
+    label: Application log excerpt
+    content: |
+      2026-05-02T14:02:11Z INFO  boot: worker started, pool size 20
+      2026-05-02T14:03:40Z INFO  deploy: version 4.7.0 live
+      2026-05-02T14:03:41Z WARN  db: DB_POOL_MAX=5 (was 20) applied from env
+      2026-05-02T14:04:02Z ERROR db: pool exhausted, 15 requests queued > 3000ms
+      2026-05-02T14:04:03Z ERROR http: 503 returned to /checkout (db timeout)
+      2026-05-02T14:06:00Z ERROR http: 503 rate 34% on /checkout
+  - id: deploy-record
+    type: table
+    label: Deploy record
+    content: |
+      version | time                  | notes
+      4.6.3   | 2026-04-28T09:00:00Z  | baseline, DB_POOL_MAX=20
+      4.7.0   | 2026-05-02T14:03:40Z  | env refactor: consolidated pool settings
+tags: [incident, logs, synthesis]

package/tasks/speed/public/speed-openapi-fragment.yaml

@@ -0,0 +1,38 @@
+id: speed-openapi-fragment
+version: 1.0.0
+category: speed
+cluster: structured-output
+difficulty: hard
+title: Emit an OpenAPI 3.1 Path Fragment for a Documented Endpoint
+summary: >-
+  Produce a valid OpenAPI 3.1 YAML fragment describing one endpoint, its path parameter, request body,
+  and two response codes, matching the written contract exactly.
+prompt: |
+  Given [endpoint-contract], output a single OpenAPI 3.1 YAML fragment containing the `paths` entry for
+  `POST /projects/{projectId}/tasks` and the `components/schemas` it references. Emit only YAML.
+
+  1. The `paths` object for the endpoint, including the path parameter, request body, and the 201 and
+     422 responses.
+  2. `components/schemas` entries `TaskInput` and `Task` matching the field list, with required fields,
+     enums, and formats.
+artifacts:
+  - id: endpoint-contract
+    type: spec
+    label: Endpoint contract
+    content: |
+      POST /projects/{projectId}/tasks
+      - path param projectId: string, format uuid, required
+      - request body (application/json), required: TaskInput
+        TaskInput = {
+          title: string, 1..200 chars, required
+          assigneeId?: string (uuid)
+          priority: one of "low" | "med" | "high", default "med"
+        }
+      - 201 response (application/json): Task
+        Task = {
+          id: string uuid; projectId: string uuid; title: string;
+          assigneeId: string | null; priority: string; createdAt: string date-time
+        }
+      - 422 response (application/json): { message: string; field?: string }
+      - security: bearerAuth
+tags: [openapi, yaml, api-design]

package/tasks/speed/public/speed-pagination-cursor.yaml

@@ -0,0 +1,40 @@
+id: speed-pagination-cursor
+version: 1.0.0
+category: speed
+cluster: stepwise-reasoning
+difficulty: hard
+title: Design a Stable Keyset Cursor and Encode Three Pages
+summary: >-
+  Specify and implement opaque keyset-pagination cursors for a sorted feed, then show the exact page
+  predicate and cursor values while paging through a small dataset.
+prompt: |
+  Per [feed-spec], implement cursor encode/decode and the next-page predicate, then trace paging over
+  [feed-rows] with page size 2.
+
+  1. `encodeCursor` / `decodeCursor` (base64url of the JSON keyset) plus the `WHERE` and `ORDER BY`
+     clause for the next page given a decoded cursor.
+  2. Walk [feed-rows] in pages of 2: for each page list the returned ids and the `nextCursor`
+     (its decoded form is fine), stopping when the feed is exhausted.
+artifacts:
+  - id: feed-spec
+    type: spec
+    label: Feed ordering and cursor
+    content: |
+      Rows are ordered by (score DESC, id ASC). A cursor is an opaque base64url token encoding the last
+      returned row's { score, id }. The next page selects rows strictly after the cursor in that order:
+        WHERE (score < cur.score) OR (score = cur.score AND id > cur.id)
+        ORDER BY score DESC, id ASC
+        LIMIT pageSize
+      The first page uses no cursor. nextCursor is null when fewer than pageSize rows are returned.
+  - id: feed-rows
+    type: table
+    label: Rows
+    content: |
+      id | score
+      a  | 90
+      b  | 90
+      c  | 80
+      d  | 80
+      e  | 80
+      f  | 70
+tags: [pagination, sql, api-design]

package/tasks/speed/public/speed-rate-limiter-design.yaml

@@ -0,0 +1,43 @@
+id: speed-rate-limiter-design
+version: 1.0.0
+category: speed
+cluster: stepwise-reasoning
+difficulty: hard
+title: Implement a Token-Bucket Rate Limiter and Trace Its Behavior
+summary: >-
+  Write a token-bucket rate limiter to a precise spec, then walk a given request timeline step by step
+  to state which requests are allowed or rejected and the tokens remaining.
+prompt: |
+  Using [bucket-spec], implement the limiter and then apply it to [request-trace].
+
+  1. Implement `class TokenBucket` in TypeScript with `tryRemove(now: number, cost = 1): boolean`.
+  2. For the eight timestamped requests in [request-trace], produce a table with columns:
+     request #, time, tokens-before, allowed?, tokens-after. Show the refill arithmetic for at least
+     two of the steps.
+artifacts:
+  - id: bucket-spec
+    type: spec
+    label: Token bucket
+    content: |
+      - capacity = 5 tokens; refillRate = 1 token per 1000 ms
+      - the bucket starts full (5 tokens) at t = 0, with lastRefill = 0
+      - on each call, refill first:
+          stored = min(capacity, stored + (now - lastRefill) / 1000 * refillRate)
+          lastRefill = now
+      - tokens are fractional internally
+      - tryRemove(now, cost): refill, then if stored >= cost subtract cost and return true,
+        otherwise leave stored unchanged and return false
+  - id: request-trace
+    type: table
+    label: Request timeline
+    content: |
+      request # | time(ms) | cost
+      1         | 0        | 3
+      2         | 200      | 2
+      3         | 500      | 1
+      4         | 900      | 1
+      5         | 1500     | 2
+      6         | 1600     | 1
+      7         | 4000     | 5
+      8         | 4200     | 1
+tags: [algorithms, rate-limiting, typescript]