The log a customer can search

/internal        1,656   35.84%    busiest single route: /internal/session, 1,423
/v1              1,857   40.19%
other            1,108   23.98%
no endpoint         22             32 whole-table, and 31 of those are real

export interface AnalyticalStore {
  query(sql: string): Promise<string[][]>;
}

scoped, honest window (1 hour)                       0 rows
the same query, from carrying ' OR 1=1 --       11,683 rows
the whole table, for comparison                 11,683 rows
distinct environment_id under the payload          152

export function clickHouseInstant(at: Date): string {
  return at.toISOString().replace("T", " ").replace("Z", "");
}

/** FR-ANL-07's query surface, as arithmetic (chapter 4.8).
 *
 * EVERYTHING HERE RUNS WITH NO STORE, NO DATABASE AND NO BROKER, which is the shape
 * chapter 4.7 separated `exitCodeFor` for: a contract with branches a test can drive is
 * worth more than one that needs Docker. The reader and the route come next; what this
 * file owns is what the caller is allowed to have asked for.
 */
import { z } from "zod";
 
/** The value that names the request the router matched nothing for.
 *
 * NOT A ROUTE, AND THAT IS WHY IT HAS TO BE SPELLED. The accepted endpoint set is derived
 * from the running router (below), and the router contains no entry for a request that
 * matched none of its entries — so the most diagnostic question a 404 investigation asks
 * would have been the one question the filter could not express. 32 rows carry
 * `endpoint IS NULL` in the lane today.
 *
 * It cannot collide with a derived route: every route template this api registers begins
 * with `/`. */
export const UNMATCHED = "unmatched";
 
/** FR-ANL-07 retains thirty days. DR-09's ninety is the raw-event figure and this table is
 * not raw events — `analytics/0005_connection_events.sql:4` states the reason one clause
 * cannot express two, and `SHOW CREATE` reports `toDateTime(ts) + toIntervalDay(30)`. */
export const RETENTION_DAYS = 30;
 
/** The default window when the caller names neither end. */
export const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
 
/** An ISO-8601 instant, as a `Date`.
 *
 * THE TYPE IS THE GUARD, AND THIS IS THE LINE THAT MAKES IT ONE. `AnalyticalStore.query`
 * takes a SQL string and has no parameter binding (R9), so the defence against a hostile
 * window cannot be escaping — it is that nothing downstream ever holds the caller's text.
 * What leaves this schema is a `Date`, and `clickHouseInstant` below is the only function
 * that turns one into SQL. There is no path from a query string to a statement.
 *
 * `offset: true` accepts `+07:00` as well as `Z`; both are instants. A bare `2026-09-16`
 * is refused, because a date is not an instant and the surface would have to invent a
 * timezone to make one. */
const instant = z.iso
  .datetime({ offset: true })
  .transform((v) => new Date(v))
  /** The belt beside the braces. `z.iso.datetime` refuses `2026-13-45T00:00:00Z`; this
   * catches anything that parses as a string and not as a moment, and costs one call. */
  .refine((d) => !Number.isNaN(d.getTime()), { message: "not a valid instant" });
 
/** The query schema, built against the endpoint set the running router reports.
 *
 * A FACTORY BECAUSE THE CLOSED SET IS NOT KNOWN AT IMPORT TIME. `deriveTargets` reads
 * `app.getHttpAdapter().getInstance()` — the cross-tenant suite's own mechanism
 * (`isolation/targets.ts`) — so the set exists only once the application is built. Passing
 * it in is also what lets every refusal in this file be unit-tested against a set of three.
 *
 * `z.strictObject`, MIRRORING `historyQuerySchema` (`messages/messages.schema.ts`) IN FORM
 * AND BOUNDS — 1..200, default 50, `older`/`newer`. Strict is the half that is easy to
 * drop: a plain `z.object` accepts `limt=200` silently and serves the default 50, so a
 * caller's typo becomes a wrong answer rather than a 400. Mirrored rather than moved to a
 * shared module: that file carries six titled fences in each locale and is clean in the
 * fence chain, and relocating a four-line shape would cost twelve hunks. */
export function buildRequestLogQuerySchema(endpoints: ReadonlySet<string>) {
  return z
    .strictObject({
      /** INCLUSIVE. Absent means `to - 24h`; clamped to the retention edge rather than
       * refused, because a caller asking for ninety days is asking a reasonable question
       * the data cannot answer (R8, and FR-ANL-08 says 90 where FR-ANL-07 retains 30). */
      from: instant.optional(),
      /** EXCLUSIVE, and the half-open range is chapter 4.7's precedent. There a
       * reconciler's off-by-one reports drift; here it duplicates a row across two pages,
       * because the row on the boundary belongs to both windows. Absent means now. */
      to: instant.optional(),
      cursor: z.string().min(1).optional(),
      direction: z.enum(["older", "newer"]).default("older"),
      /** REFUSED OUT OF BOUNDS, NOT CLAMPED — see `resolveWindow` for the field that is
       * clamped instead, and why the two differ. */
      limit: z.coerce.number().int().min(1).max(200).default(50),
      /** A MEMBER OF A CLOSED SET DERIVED FROM THE ROUTER, or `unmatched`. A value from a
       * derived set is not text reaching SQL; an unknown one is a 400 rather than an empty
       * page, which is the same distinction the retention edge draws between "nothing
       * matched" and "this question cannot be answered". */
      endpoint: z
        .string()
        .refine((v) => v === UNMATCHED || endpoints.has(v), {
          message: "unknown endpoint",
        })
        .optional(),
      /** `status` is `UInt16` in the store and an HTTP status here: the column's range is
       * wider than the protocol's, and the narrower of the two is the honest bound. */
      status: z.coerce.number().int().min(100).max(599).optional(),
    })
    .superRefine((q, ctx) => {
      // `to` is exclusive, so equal ends describe a window that can hold nothing. A
      // caller who wrote them is asking for something they did not mean.
      if (q.from && q.to && q.to.getTime() <= q.from.getTime()) {
        ctx.addIssue({
          code: "custom",
          path: ["to"],
          message: "`to` must be after `from`",
        });
      }
    });
}
 
export type RequestLogQuerySchema = ReturnType<typeof buildRequestLogQuerySchema>;
export type RequestLogQuery = z.infer<RequestLogQuerySchema>;
 
/** The window a page is actually read over. */
export interface ResolvedWindow {
  /** Inclusive. */
  from: Date;
  /** Exclusive. */
  to: Date;
  /** `now - RETENTION_DAYS`, the nominal guarantee, reported to the caller. */
  retentionEdge: Date;
  /** `from` was older than the edge and was moved forward. */
  clamped: boolean;
  /** The whole requested window is older than the edge, so it can hold nothing. The
   * reader skips the store for this: a query that cannot return a row should not cost
   * one. */
  empty: boolean;
}
 
/** Apply the defaults and the retention edge.
 *
 * `now` IS A PARAMETER. Every bound here is relative to it, and a function that reads the
 * clock has no boundary a test can sit on — chapter 4.7's reconciler paid for the same
 * thing in the other direction, where the smallest breaching drift had to be computable.
 *
 * WHY `from` IS CLAMPED WHERE `limit` IS REFUSED, which is the one asymmetry on this
 * surface and is a decision rather than an accident. `limit`'s bound is published in the
 * contract, so a caller outside it has made a mistake they can see and fix, and a 400 says
 * which field. The retention edge is a property of the store that moves every second and
 * is published as a guarantee rather than as a bound — a caller cannot know it when they
 * write the request, so refusing them for missing it would refuse a reasonable question.
 * They get the window the data can answer for, and `retention_edge` beside it. */
export function resolveWindow(
  query: Pick<RequestLogQuery, "from" | "to">,
  now: Date,
  retentionDays: number = RETENTION_DAYS,
): ResolvedWindow {
  const retentionEdge = new Date(now.getTime() - retentionDays * 24 * 60 * 60 * 1000);
  const to = query.to ?? now;
  const requestedFrom = query.from ?? new Date(to.getTime() - DEFAULT_WINDOW_MS);
  const clamped = requestedFrom.getTime() < retentionEdge.getTime();
  const from = clamped ? retentionEdge : requestedFrom;
  // A window whose exclusive end is at or before its inclusive start holds nothing. It
  // arrives here one way only: the caller asked for a period entirely older than the
  // edge, and the clamp moved `from` past `to`. It is NOT a refusal — the answer "that
  // is gone" is the one R8 exists to give, and the caller reads it off `window` and
  // `retention_edge` rather than off an empty page that could also mean a quiet day.
  const empty = from.getTime() >= to.getTime();
  return { from: empty ? to : from, to, retentionEdge, clamped, empty };
}
 
/** The only function that turns an instant into SQL.
 *
 * `DateTime64(3)` — milliseconds, and the store parses `YYYY-MM-DD hh:mm:ss.SSS` in the
 * column's own timezone, so the value is rendered from the UTC parts rather than through
 * a locale-dependent formatter. Takes a `Date` and not a string, which is the whole of the
 * injection argument: there is nothing to escape because there is nothing to quote. */
export function clickHouseInstant(at: Date): string {
  return at.toISOString().replace("T", " ").replace("Z", "");
}

\N	GET	200

endpoint             NULL on     31 real rows  (23 rate-limited, 8 unmatched)
limited_operation    NULL on 11,660 of 11,683  — 99.8% of the table

/** The request log's cursor (chapter 4.8, FR-ANL-07, EIR-API-06).
 *
 * OPAQUE, LIKE THE HISTORY CURSOR, AND FOR THE SAME REASON — constitution V offers cursor
 * pagination and not offsets, and a client that never saw inside a token cannot break when
 * the inside changes. `messages/cursor.ts` is the precedent and this is deliberately not
 * an extension of it.
 *
 * AND IT CANNOT KEY THE SAME WAY, WHICH IS THE INTERESTING HALF. The message cursor stands
 * on `(channel_id, sequence)` — a server-assigned strictly increasing number constitution
 * II requires message ordering to use. `api_requests` has no such column. Its key is
 * `(environment_id, ts, request_id)` and `ts` is `DateTime64(3)`, so two requests in the
 * same millisecond are ordered by `request_id` and nothing else. Measured on the lane: 42
 * `(environment_id, ts)` pairs hold more than one row, 89 rows in total. A `ts`-only cursor
 * skips or repeats every one of them, and that share grows with request rate rather than
 * with elapsed time — it gets worse on a busy tenant, which is the tenant that pages.
 *
 * SO THE TOKEN CARRIES THE PAIR, AND THE COMPARISON HAPPENS IN SQL. The `request_id` half
 * travels as its canonical text and is compared as a `UUID` by the store, which is what
 * keeps the comparison consistent with the table's own `ORDER BY`: ClickHouse does not
 * order UUIDs by that text. Comparing them as strings in the statement would produce a
 * page boundary the index disagrees with. */
 
const PREFIX = "rl:";
 
/** The canonical text of a UUID, and nothing else.
 *
 * THIS REGULAR EXPRESSION IS PART OF THE INJECTION ARGUMENT, not a tidiness check.
 * `AnalyticalStore.query` takes a SQL string and has no parameter binding (R9), so a
 * cursor is caller-supplied text that reaches a statement. What reaches it is a value this
 * pattern admitted and a number, and neither can carry a quote. */
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
/** THE INSTANTS THE COLUMN CAN HOLD, AND `Number.isSafeInteger` IS NOT ONE OF THEM.
 *
 * The first draft bounded the timestamp half with `Number.isSafeInteger` and a 15-digit
 * pattern, and its own refusal block caught it: `rl:999999999999999:<uuid>` is a safe
 * integer, decodes to **the year 33658**, and would have been rendered into a
 * `DateTime64(3)` comparison the store cannot express. A bound on the JavaScript number is
 * not a bound on the instant.
 *
 * Both ends are facts about the column rather than round numbers. The floor is the DDL's
 * own `CONSTRAINT ts_is_real CHECK ts > toDateTime64('2020-01-01 00:00:00', 3, 'UTC')` —
 * no row this cursor could have been minted from is older. The ceiling is
 * `DateTime64`'s representable maximum, `2299-12-31`. */
const TS_FLOOR_MS = Date.UTC(2020, 0, 1);
const TS_CEILING_MS = Date.UTC(2300, 0, 1);
 
export interface RequestLogPosition {
  /** The row's `ts`, to the millisecond the column stores. */
  ts: Date;
  /** The row's `request_id`, canonical lower-case text. */
  requestId: string;
}
 
export function encodeRequestLogCursor(at: RequestLogPosition): string {
  return Buffer.from(`${PREFIX}${at.ts.getTime()}:${at.requestId}`, "utf8").toString(
    "base64url",
  );
}
 
/** Decode a cursor, or null for anything this module did not produce.
 *
 * NULL BECOMES A 400 AT THE ROUTE — never a 500, and never a silent fall back to the top
 * of the window, which would serve a page the caller did not ask for and looks like
 * working software. That is the rule `messages/cursor.ts` wrote in chapter 2.4.
 *
 * `Buffer.from(x, "base64url")` NEVER THROWS: it decodes what it can and drops the rest,
 * so the pattern below is the whole refusal and the `try` around the decode would be
 * decoration. Every field is re-checked after decoding. */
export function decodeRequestLogCursor(token: string): RequestLogPosition | null {
  const raw = Buffer.from(token, "base64url").toString("utf8");
  const match = /^rl:(\d{1,15}):([0-9a-fA-F-]{36})$/.exec(raw);
  if (!match) return null;
  const [, msText = "", idText = ""] = match;
  const ms = Number(msText);
  // AND NO `Number.isSafeInteger` BESIDE THIS. There was one, and the branch report said
  // it could never be false: `\d{1,15}` caps the value at 999,999,999,999,999, which is
  // a safe integer, so the guard was dead the moment the range check went in beside it.
  // Chapter 4.6 reached 100% branches by deleting two arms that could not run; this is
  // the same finding one file over, and the range check subsumes it either way — a value
  // too large to represent exactly is also far past the ceiling.
  if (ms < TS_FLOOR_MS || ms >= TS_CEILING_MS) return null;
  const requestId = idText.toLowerCase();
  if (!UUID.test(requestId)) return null;
  return { ts: new Date(ms), requestId };
}

uniform sample        n=4      n=100    n=155    n=10,000
  p50 error        16.6667%   0.9804%       0%     0.8998%
 
skewed sample         n=4      n=100    n=1,000  n=10,000
  p50 error         2.6162%   4.7263%   4.7579%   9.5158%
  p95 error         0.8200%   9.0398%   9.0404%   9.5163%

quantile(0.99)       4961.26
quantileExact(0.99)  10000        50.39% low

gauntlet targets: 43 derived, 36 attacked, 6 exempt
unclassified: ["GET /v1/request-log"]
CLASSIFICATIONS.length 42 against 43

@@ -129,16 +129,36 @@ export interface ListVerdict {
  * paginated route answers `{ data: [...] }` and a bare route answers an array.
  * Exported and pure because only ONE arm can execute against the routes that exist
  * today, and a count of zero from an unrecognised shape reads exactly like a count of
  * zero from a correctly-scoped list — which is the one answer this suite must never
  * confuse with success. `listAttack` therefore asserts the shape was recognised
  * rather than trusting the count. */
+/** The rows out of a list response.
+ *
+ * A NAMED SET OF SHAPES, AND IT STAYS ONE. Chapter 4.8 tried to replace this with "the
+ * first array-valued property", on the reflex that a hand-maintained table cannot be
+ * checked — and the test below refused the change, correctly. **This table IS checked**,
+ * twice over: it pins that an unrecognised shape returns `[]`, and every `list` attack
+ * carries a `count > 0` control that then fails. So an unknown shape cannot pass quietly,
+ * which is the precondition the reflex assumes is missing.
+ *
+ * And the derived version was worse in the direction that matters: it would count ANY
+ * array in the body — a cursor list, an embedded collection, an echo of what was asked
+ * for — as rows, which is a false pass where this is a loud failure. `{ requests }` is
+ * added by name.
+ *
+ * WHAT THE FAILURE READS LIKE IS THE ONE REAL COST. An unrecognised shape fails as *"the
+ * attacker's own listing came back empty"*, which names a symptom and not the cause. The
+ * test below is what turns that into a sentence about the recogniser. */
 export function rowsOf(body: unknown): unknown[] {
   if (Array.isArray(body)) return body;
-  const data = (body as { data?: unknown } | null)?.data;
-  if (Array.isArray(data)) return data;
+  const shaped = body as { data?: unknown; requests?: unknown } | null;
+  if (Array.isArray(shaped?.data)) return shaped.data;
+  // Chapter 4.8's envelope: the array is named for the resource, as
+  // `messages.service.ts` names its own. R23 refused `rows` for being a storage word.
+  if (Array.isArray(shaped?.requests)) return shaped.requests;
   return [];
 }
 
 export async function listAttack(
   baseUrl: string,
   credential: string,

min 0.29 s   p50 1.60 s   max 1.61 s      n=6/6
                                          2.7% of FR-ANL-04's 60 s

@@ -648,12 +648,63 @@ describe("integrating with Relay from the outside", () => {
     // resolves on the first match cannot.
     expect(frames.filter((f) => f.type === "message.created")).toHaveLength(1);
     expect(frames.filter((f) => f.type === "message.updated")).toHaveLength(1);
     socket.close();
   });
 
+  /** THE REQUEST LOG (FR-ANL-07), AND WHAT AN OUTSIDER ACTUALLY FINDS THERE.
+   *
+   * By the time this runs the suite has made a dozen calls with this credential —
+   * channels, members, tokens, sends, a history read. So the log should not be empty, and
+   * **it is.** The platform ships no ingester: `compose.yaml` starts the stores, the api
+   * and the gateway, and nothing drains the analytics stream into ClickHouse. The records
+   * are published and they wait.
+   *
+   * THAT IS THE ASSERTION RATHER THAN A REASON TO OMIT THE ROUTE. A customer's-eye test
+   * showing an empty log because the platform ships no ingester is the freshness gap
+   * arriving where a customer would actually meet it — and it asserts something true,
+   * where skipping the endpoint asserts nothing at all. When an ingester ships, this test
+   * goes red and the line below is where the number goes.
+   *
+   * WHAT IS ASSERTED REGARDLESS: the envelope is the documented one, and the refusals
+   * work. Those do not depend on a row existing. */
+  it("serves a request log with the documented envelope, and it is empty", async () => {
+    const res = await fetch(`${api}/v1/request-log`, {
+      headers: { authorization: `Bearer ${credential}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(Array.isArray(body["requests"])).toBe(true);
+    expect(typeof body["has_more"]).toBe("boolean");
+    expect(body["window"]).toBeTruthy();
+    expect(typeof body["retention_edge"]).toBe("string");
+    // `next_cursor` and `prev_cursor` are DECLARED and null at the ends, which is a
+    // different fact from being absent — a client that reads `next_cursor` off this
+    // response gets null rather than undefined.
+    expect(body).toHaveProperty("next_cursor");
+    expect(body).toHaveProperty("prev_cursor");
+
+    // EMPTY, AND THIS SUITE IS THE EVIDENCE THAT IT SHOULD NOT BE. Every request above
+    // was made with this credential and every one of them was recorded — to a stream
+    // nothing reads.
+    expect(body["requests"]).toEqual([]);
+    expect(body["has_more"]).toBe(false);
+  });
+
+  it("refuses a page size outside the published bound, and says which field", async () => {
+    const res = await fetch(`${api}/v1/request-log?limit=201`, {
+      headers: { authorization: `Bearer ${credential}` },
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body["field"]).toBe("limit");
+    expect(typeof body["code"]).toBe("string");
+    expect(typeof body["docs_url"]).toBe("string");
+    expect(typeof body["request_id"]).toBe("string");
+  });
+
   it("cannot see another tenant's channel, and cannot tell it apart from an absent one", async () => {
     // The documented isolation property, exercised the only way an outsider can:
     // with an id that is well formed and is not theirs. The reference says both
     // answer identically, so this checks that rather than taking it on faith.
     const nowhere = "00000000-0000-4000-8000-000000000000";
     const a = await fetch(`${api}/v1/channels/${nowhere}/messages`, {
@@ -664,16 +715,24 @@ describe("integrating with Relay from the outside", () => {
     });
     expect(a.status).toBe(404);
     expect(b.status).toBe(404);
     for (const res of [a, b]) {
       const body = (await res.json()) as Record<string, unknown>;
       expect(body["code"]).toBe("not_found");
-      // A PATH PER CODE, not a fragment on one page. `docsUrl` here is
-      // `${ERROR_DOCS_BASE}/${code}`; published later moved to an anchor on a single
-      // error-reference page, which is part of the debt the error-registry chapter
-      // opens and puts in Part 4. Asserted as this platform actually answers.
-      expect(String(body["docs_url"])).toContain("/not_found");
+      // AN ANCHOR ON ONE PAGE, AND THIS LINE SAID THE OPPOSITE FOR A PART AND A HALF.
+      //
+      // It read `toContain("/not_found")` — a path per code — under a comment ending
+      // *"Asserted as this platform actually answers."* It was not: `docsUrl` returns
+      // `${base}#${code}`, and the commit that made it an anchor landed BEFORE this
+      // suite was written. So the suite has never passed, and nothing said so, because
+      // it needs a running platform that no lane starts. Chapter 4.8 found it by
+      // standing the stack up to run its own new test in this file.
+      //
+      // The platform is right and the test was wrong: `docs/08-error-reference.md` is
+      // ONE page with a section per code, so a path per code would 404 for every
+      // refusal this platform sends.
+      expect(String(body["docs_url"])).toContain("#not_found");
       // Every error carries one, and it is what a support request quotes.
       expect(typeof body["request_id"]).toBe("string");
     }
   });
 });