@supatype/cli 0.2.0 → 0.3.0

package/src/type-extractor.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, realpathSync } from "node:fs"
 import { createHash } from "node:crypto"
 import { dirname, isAbsolute, relative, resolve } from "node:path"
 import ts from "typescript"
+import { isIdentityDependent, type AccessRuleNode } from "./cache-identity-scope.js"
 import {
   applyImportRename,
   createResolveContext,
@@ -107,7 +108,17 @@ export function extractSchemaAstFromTypes(
         )
       }
 
-      const { tableName, access, options, indexes, constraints, hooks, validators } =
+      const {
+        tableName,
+        access,
+        options,
+        indexes,
+        constraints,
+        hooks,
+        validators,
+        searchFields,
+        cache,
+      } =
         parseModelMeta(
         metaArg,
         sourceFile,
@@ -128,6 +139,8 @@ export function extractSchemaAstFromTypes(
           hooks,
           constraints,
           validators,
+          searchFields,
+          cache,
         ),
       )
     }
@@ -474,6 +487,7 @@ function parseFieldType(
     fieldDefault: undefined as string | number | boolean | null | undefined,
     localized: false,
     notLocalized: false,
+    searchable: false,
     bounds: {} as DeclaredBounds,
   }
 
@@ -522,6 +536,10 @@ function parseFieldType(
         continue
       }
       case "Searchable":
+        // Used to unwrap and drop the declaration on the floor, so a schema saying a column was
+        // searchable compiled, pushed, and produced a Studio list view with no search box: the
+        // engine was never told, so the admin config carried no `searchFields` for Studio to read.
+        flags.searchable = true
         current = current.typeArguments?.[0] ?? current
         continue
       case "EditorReadOnly":
@@ -674,6 +692,7 @@ function parseFieldType(
     platform: {
       ...scalarBase.platform,
       ...(flags.editorReadOnly && { readOnly: true }),
+      ...(flags.searchable && { searchable: true }),
     },
   }
 
@@ -1604,6 +1623,47 @@ function parseAssetFieldOptions(
   return { localized: false }
 }
 
+/** What `versions` resolved to on a model, or absent when the model declares none. */
+type ParsedVersions = { drafts: boolean; keep: number }
+
+/** Versions kept per record when a model states no retention. Mirrors `model-versioning.ts`. */
+const DEFAULT_VERSIONS_KEPT = 20
+
+/**
+ * `versions: true` or `versions: { drafts, keep }`.
+ *
+ * A malformed member is ignored rather than fatal, matching every other key here: the declaration is
+ * a *type*, so TypeScript has already refused anything `ModelVersionsOptions` does not allow, and
+ * this parser's job is reading what compiled rather than validating it a second time.
+ */
+function parseVersions(typeNode: ts.TypeNode): ParsedVersions | undefined {
+  if (isBooleanLiteralType(typeNode, true)) {
+    return { drafts: true, keep: DEFAULT_VERSIONS_KEPT }
+  }
+  if (isBooleanLiteralType(typeNode, false)) return undefined
+  if (!ts.isTypeLiteralNode(typeNode)) return undefined
+
+  const parsed: ParsedVersions = { drafts: true, keep: DEFAULT_VERSIONS_KEPT }
+  for (const member of typeNode.members) {
+    if (!ts.isPropertySignature(member) || !member.type) continue
+    const key = getPropertyName(member.name)
+    if (key === "drafts") {
+      if (isBooleanLiteralType(member.type, false)) parsed.drafts = false
+      if (isBooleanLiteralType(member.type, true)) parsed.drafts = true
+    } else if (
+      key === "keep" &&
+      ts.isLiteralTypeNode(member.type) &&
+      ts.isNumericLiteral(member.type.literal)
+    ) {
+      const keep = Number(member.type.literal.text)
+      // A retention of zero would prune the draft being edited, so it reads as "unstated" rather
+      // than as an instruction to keep nothing.
+      if (Number.isFinite(keep) && keep >= 1) parsed.keep = Math.floor(keep)
+    }
+  }
+  return parsed
+}
+
 function parseMetaLiteral(
   metaArg: ts.TypeNode | undefined,
   sourceFile: ts.SourceFile,
@@ -1613,6 +1673,8 @@ function parseMetaLiteral(
   timestamps?: boolean
   softDelete?: boolean
   autoLocalize?: boolean
+  versions?: ParsedVersions
+  searchable?: string[]
 } {
   const result: {
     tableName?: string
@@ -1620,6 +1682,8 @@ function parseMetaLiteral(
     timestamps?: boolean
     softDelete?: boolean
     autoLocalize?: boolean
+    versions?: ParsedVersions
+    searchable?: string[]
   } = {}
 
   if (!metaArg || !ts.isTypeLiteralNode(metaArg)) return result
@@ -1639,6 +1703,13 @@ function parseMetaLiteral(
       if (isBooleanLiteralType(member.type, false)) result.softDelete = false
     } else if (key === "autoLocalize" && isBooleanLiteralType(member.type, true)) {
       result.autoLocalize = true
+    } else if (key === "searchable" && ts.isTupleTypeNode(member.type)) {
+      result.searchable = member.type.elements
+        .map((el) => (ts.isLiteralTypeNode(el) && ts.isStringLiteral(el.literal) ? el.literal.text : null))
+        .filter((name): name is string => name !== null)
+    } else if (key === "versions") {
+      const versions = parseVersions(member.type)
+      if (versions !== undefined) result.versions = versions
     } else if (
       key === "tableName" &&
       ts.isLiteralTypeNode(member.type) &&
@@ -1680,6 +1751,8 @@ function parseModelMeta(
   constraints: unknown[]
   hooks: Record<string, ParsedModelHook>
   validators: Record<string, ParsedModelHook>
+  searchFields: string[]
+  cache: ParsedModelCache | undefined
 } {
   const literal = parseMetaLiteral(metaArg, sourceFile)
   const singleton = literal.singleton === true
@@ -1700,16 +1773,162 @@ function parseModelMeta(
   if (timestamps) options.timestamps = true
   if (softDelete) options.softDelete = true
   if (literal.autoLocalize === true) options.autoLocalize = true
+  if (literal.versions !== undefined) options.versions = literal.versions
+
+  const access = parseModelAccess(metaArg, sourceFile, modelName, fields, resolveCtx)
+  if (literal.versions !== undefined) assertVersionsWithoutFieldRules(access, modelName)
+
+  const cache = parseModelCache(metaArg, sourceFile)
+  if (cache !== undefined) assertCacheIsServable(cache, access, fields, modelName)
 
   return {
     tableName,
-    access: parseModelAccess(metaArg, sourceFile, modelName, fields, resolveCtx),
+    access,
     options,
+    searchFields: resolveSearchFields(literal.searchable, fields, modelName),
     indexes: parseModelIndexes(metaArg, sourceFile, fields),
     constraints: parseModelConstraints(metaArg, sourceFile, modelName, fields, resolveCtx),
     hooks: parseModelHooks(metaArg, sourceFile),
     validators: parseModelValidators(metaArg, sourceFile, modelName, fields),
+    // Always present, possibly undefined: a conditional spread here infers the key away entirely
+    // and the caller cannot destructure it. emitModel is what decides whether it reaches the AST.
+    cache,
+  }
+}
+
+/**
+ * Refuse a cache declaration the runtime cannot honour, naming the model and the reason.
+ *
+ * Both checks exist because the failure they prevent is silent. A public entry on a caller-varying
+ * table serves one user's rows to another and looks like a cache hit. `rows: true` on a table with
+ * no primary key is simply never registered, and reads stay exactly as fast as they were with a
+ * setting in the schema saying otherwise.
+ *
+ * Checked here rather than left to the server for the same reason the constraint operands are: the
+ * message can name what the author wrote.
+ */
+function assertCacheIsServable(
+  cache: ParsedModelCache,
+  access: Record<string, unknown>,
+  fields: Record<string, FieldAstV2>,
+  model: string,
+): void {
+  if (cache.public === true) {
+    const read = access["read"] as AccessRuleNode | undefined
+    if (isIdentityDependent(read)) {
+      throw new Error(
+        `Model "${model}": \`cache.public\` cannot be used with an \`access.read\` rule that ` +
+          `varies by caller. A public cache entry is shared by everyone, so one caller's rows ` +
+          `would be served to another. Use \`cache: { enabled: true }\` for per-user entries, or ` +
+          `make the read rule row-independent — a rule like \`Lte<"published_at", Now>\` varies by ` +
+          `row without varying by caller and is safe to share.`,
+      )
+    }
+  }
+
+  if (cache.rows === true) {
+    const keyed = Object.keys(fields).filter((f) => fields[f]?.["primaryKey"] === true)
+    if (keyed.length === 0) {
+      throw new Error(
+        `Model "${model}": \`cache.rows\` needs a primary key, because the row cache's key IS the ` +
+          `primary key — there is nothing to cache by. Declare one, or drop \`rows\` and keep the ` +
+          `response cache, which has no such requirement.`,
+      )
+    }
+  }
+
+  assertTtlIsInRange(cache.maxTtl, model)
+}
+
+/**
+ * The columns Studio's list view searches, from either way of saying so.
+ *
+ * Two spellings, because they answer different questions: `Searchable<string>` on the field says
+ * *this column is worth searching*, and `searchable: ["title", "name"]` on the model says *search
+ * these, in this order*, which matters because the list view filters on the first one. A model
+ * using both gets the explicit order first and any remaining flagged columns after it.
+ *
+ * A name that matches no field throws rather than being dropped. Silently ignoring it is how this
+ * whole feature came to be inert: the declaration compiled and nothing downstream ever saw it.
+ */
+function resolveSearchFields(
+  declared: string[] | undefined,
+  fields: Record<string, FieldAstV2>,
+  modelName: string,
+): string[] {
+  const ordered: string[] = []
+
+  for (const name of declared ?? []) {
+    if (fields[name] === undefined) {
+      throw new Error(
+        `Model "${modelName}": \`searchable\` names "${name}", which is not a field on this model. ` +
+          `Searchable columns are: ${Object.keys(fields).join(", ")}.`,
+      )
+    }
+    if (!ordered.includes(name)) ordered.push(name)
+  }
+
+  for (const [name, field] of Object.entries(fields)) {
+    if (field.annotations?.platform?.searchable !== true) continue
+    if (!ordered.includes(name)) ordered.push(name)
   }
+
+  return ordered
+}
+
+/**
+ * The bounds the admin API already enforces, enforced where the number was written.
+ *
+ * `cache_max_ttl` is refused outside 0–86400 by `PATCH /admin/v1/config/rest`, and a declared cap
+ * is the same quantity. Left to the server, an out-of-range `maxTtl` reaches it as part of a
+ * manifest rather than a request — nothing refuses a manifest — and the ceiling it produces is
+ * whatever the arithmetic makes of it: a negative cap reads as "no cap declared" and permits more
+ * than the author asked for, which is the one direction a ceiling must never move in.
+ */
+function assertTtlIsInRange(ttl: number | undefined, model: string): void {
+  if (ttl === undefined) return
+  if (!Number.isInteger(ttl)) {
+    throw new Error(
+      `Model "${model}": \`cache.maxTtl\` must be a whole number of seconds, not ${ttl}.`,
+    )
+  }
+  if (ttl < 0 || ttl > MAX_CACHE_TTL_SECONDS) {
+    throw new Error(
+      `Model "${model}": \`cache.maxTtl\` must be between 0 and ${MAX_CACHE_TTL_SECONDS} seconds ` +
+        `(24 hours), not ${ttl}. That is the same bound the admin API enforces on the project-wide ` +
+        `cache TTL, and a declaration outside it is not a cap the runtime can apply.`,
+    )
+  }
+}
+
+/** The admin API's bound on a cache TTL, in seconds. */
+const MAX_CACHE_TTL_SECONDS = 86_400
+
+/**
+ * Refuse a model that declares both `versions` and per-column rules.
+ *
+ * A version snapshot is opaque `jsonb`. `supatype_mask` is driven by security labels on a specific
+ * table's column and rewrites references to *that* column; the view tier puts the same expression in
+ * a view over the real columns. Neither can see inside a snapshot, so a masked value would sit in
+ * plain sight in `<table>_versions` for anyone able to read it, and there is no narrower grant to
+ * hide it behind now that drafts are visible to the record's creator.
+ *
+ * Refused here rather than left to the engine for the same reason the constraint operands are: the
+ * message can name the model and the columns the author wrote.
+ */
+function assertVersionsWithoutFieldRules(access: Record<string, unknown>, model: string): void {
+  const fields = access["fields"]
+  if (typeof fields !== "object" || fields === null) return
+  const masked = Object.keys(fields)
+  if (masked.length === 0) return
+
+  throw new Error(
+    `Model "${model}": \`versions\` and \`access.fields\` cannot both be declared. ` +
+      `A version snapshot is opaque JSONB, so the per-column rules on ` +
+      `${masked.map((c) => `\`${c}\``).join(", ")} cannot be enforced inside it and the value would ` +
+      `be readable in the versions table. Drop one: keep the field rules, or version a model that ` +
+      `does not mask a column.`,
+  )
 }
 
 /**
@@ -2980,3 +3199,63 @@ function resolveIndexedAccessRule(
   }
   return undefined
 }
+
+// ─── cache declaration (P8, plan §13) ────────────────────────────────────────
+
+/** The parsed `cache` block. Absent entirely when the model declared none. */
+export interface ParsedModelCache {
+  enabled?: boolean
+  maxTtl?: number
+  public?: boolean
+  rows?: boolean
+}
+
+/**
+ * Parse `cache: { ... }` off a model's meta argument.
+ *
+ * Shaped like `parseModelHooks`, and travelling the same way: onto the route manifest beside
+ * `hooks`, not into `annotations.platform`. The schema engine re-serialises its own parsed AST
+ * (`serde_json::to_value(&ast)`), and `PlatformModelAnnotations` carries only `access` and
+ * `search_fields` with no catch-all — so a key placed there is silently dropped on the way to the
+ * server rather than riding through. Verified rather than assumed; see plan §13.1.
+ */
+function parseModelCache(
+  metaArg: ts.TypeNode | undefined,
+  sourceFile: ts.SourceFile,
+): ParsedModelCache | undefined {
+  if (!metaArg || !ts.isTypeLiteralNode(metaArg)) return undefined
+
+  const prop = metaArg.members.find(
+    (member) => ts.isPropertySignature(member) && getPropertyName(member.name) === "cache",
+  )
+  if (!prop || !ts.isPropertySignature(prop) || !prop.type) return undefined
+  if (!ts.isTypeLiteralNode(prop.type)) return undefined
+
+  const parsed: ParsedModelCache = {}
+  for (const member of prop.type.members) {
+    if (!ts.isPropertySignature(member) || !member.type) continue
+    switch (getPropertyName(member.name)) {
+      case "enabled":
+        if (isBooleanLiteralType(member.type, true)) parsed.enabled = true
+        else if (isBooleanLiteralType(member.type, false)) parsed.enabled = false
+        break
+      case "public":
+        if (isBooleanLiteralType(member.type, true)) parsed.public = true
+        else if (isBooleanLiteralType(member.type, false)) parsed.public = false
+        break
+      case "rows":
+        if (isBooleanLiteralType(member.type, true)) parsed.rows = true
+        else if (isBooleanLiteralType(member.type, false)) parsed.rows = false
+        break
+      case "maxTtl": {
+        const ttl = parseNumericTypeArg(member.type, sourceFile)
+        if (ttl !== undefined) parsed.maxTtl = ttl
+        break
+      }
+    }
+  }
+  // A `cache: {}` with nothing readable in it is not a declaration. Returning an empty object
+  // would make the model "declared but permitting nothing", which reads the same as no block at
+  // all and would put an empty entry in every manifest.
+  return Object.keys(parsed).length > 0 ? parsed : undefined
+}

package/tests/api-config-cache-seed.test.ts

@@ -0,0 +1,180 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { freeTierCacheNote, seedApiConfigCache } from "../src/api-config-cache.js"
+
+/**
+ * Two things have to be true for a cached read to be served: the schema declares the table (the
+ * ceiling) and the runtime allowlist has it on (what is active). A push writes the first. Without
+ * this it does not write the second, and the symptom is a declaration that appears to do nothing
+ * and a BYPASS header nobody asked about.
+ */
+
+const dirs: string[] = []
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+function project(apiConfig: unknown | null): string {
+  const dir = mkdtempSync(join(tmpdir(), "supatype-seed-"))
+  dirs.push(dir)
+  if (apiConfig !== null) {
+    mkdirSync(join(dir, ".supatype"), { recursive: true })
+    writeFileSync(
+      join(dir, ".supatype", "api-config.json"),
+      typeof apiConfig === "string" ? apiConfig : JSON.stringify(apiConfig, null, 2),
+      "utf8",
+    )
+  }
+  return dir
+}
+
+/** The file as it now stands, typed loosely because these assertions are about what is in it. */
+const read = (dir: string): { rest?: { cache_tables?: Record<string, unknown>; cache_max_ttl?: unknown } } =>
+  JSON.parse(readFileSync(join(dir, ".supatype", "api-config.json"), "utf8")) as {
+    rest?: { cache_tables?: Record<string, unknown>; cache_max_ttl?: unknown }
+  }
+
+const ast = (cache: unknown, table = "posts") => ({
+  models: [{ name: "Post", annotations: { db: { tableName: table }, platform: { cache } } }],
+})
+
+const config = (rest: Record<string, unknown>) => ({
+  rest: { schema: "public", max_rows: 1000, ...rest },
+  graphql: { introspection: true },
+})
+
+describe("what a push switches on", () => {
+  it("turns on a table the schema has just started declaring", () => {
+    const dir = project(config({ cache_max_ttl: 60, cache_tables: {} }))
+
+    const result = seedApiConfigCache(dir, ast({ enabled: true }))
+
+    expect(result?.seeded).toEqual(["posts"])
+    expect(read(dir).rest?.cache_tables).toEqual({ posts: { enabled: true, allow_public: false } })
+  })
+
+  it("follows the schema on public rather than defaulting it off", () => {
+    // `public` in the schema is a considered statement that this table's reads are the same for
+    // everyone, and push has already refused it where the read rule varies by caller. Defaulting
+    // it off would make the declaration mean nothing until someone ticked the box it justified.
+    const dir = project(config({ cache_max_ttl: 60, cache_tables: {} }))
+
+    seedApiConfigCache(dir, ast({ enabled: true, public: true }))
+
+    expect(read(dir).rest?.cache_tables).toEqual({ posts: { enabled: true, allow_public: true } })
+  })
+
+  it("never rewrites an entry that already exists", () => {
+    // `push resets to declared` is the alternative §13.2 rejects by name: an operator narrows a
+    // table during an incident, someone pushes an unrelated model, and the mitigation is reverted
+    // at the worst possible moment with nothing in the output to say so.
+    const dir = project(config({ cache_max_ttl: 60, cache_tables: { posts: { enabled: false, allow_public: false } } }))
+
+    const result = seedApiConfigCache(dir, ast({ enabled: true, public: true }))
+
+    expect(result?.seeded).toEqual([])
+    expect(read(dir).rest?.cache_tables).toEqual({ posts: { enabled: false, allow_public: false } })
+  })
+
+  it("leaves a hard opt-out switched off", () => {
+    // `enabled: false` is the schema declining, so there is nothing to turn on.
+    const dir = project(config({ cache_max_ttl: 60, cache_tables: {} }))
+
+    const result = seedApiConfigCache(dir, ast({ enabled: false }))
+
+    expect(result?.seeded).toEqual([])
+    expect(read(dir).rest?.cache_tables).toEqual({})
+  })
+
+  it("leaves an entry whose declaration has gone, and does not need to remove it", () => {
+    // The server intersects the allowlist with the declaration on every request, so an entry with
+    // nothing declaring it caches nothing. Removing it would be tidier and would also mean a push
+    // editing entries it did not create.
+    const dir = project(config({ cache_max_ttl: 60, cache_tables: { legacy: { enabled: true, allow_public: false } } }))
+
+    seedApiConfigCache(dir, ast({ enabled: true }))
+
+    const tables = read(dir).rest?.cache_tables ?? {}
+    expect(tables["legacy"]).toEqual({ enabled: true, allow_public: false })
+    expect(tables["posts"]).toEqual({ enabled: true, allow_public: false })
+  })
+})
+
+describe("what it reports rather than fixes", () => {
+  it("says so when the project-wide TTL is off", () => {
+    // Zero is an off switch someone may have chosen. A push that turned it on would be overriding
+    // a decision rather than filling in a blank, so it is reported where the person who can decide
+    // is reading.
+    const dir = project(config({ cache_max_ttl: 0, cache_tables: {} }))
+
+    const result = seedApiConfigCache(dir, ast({ enabled: true }))
+
+    expect(result?.ttlIsOff).toBe(true)
+    expect(read(dir).rest?.cache_max_ttl).toBe(0)
+  })
+
+  it("says nothing about the TTL when no table declares a cache", () => {
+    const dir = project(config({ cache_max_ttl: 0, cache_tables: {} }))
+    expect(seedApiConfigCache(dir, ast(undefined))?.ttlIsOff).toBe(false)
+  })
+})
+
+describe("files it will not touch", () => {
+  it("does nothing where there is no local server to configure", () => {
+    // A cloud-only project, or a stack that has never been started. Not an error: `dev` creates it.
+    expect(seedApiConfigCache(project(null), ast({ enabled: true }))).toBeNull()
+  })
+
+  it("leaves a malformed file exactly as it found it", () => {
+    // The server reports this far more clearly than a push can, and rewriting it would destroy
+    // whatever the author was in the middle of.
+    const dir = project("{ this is not json")
+    expect(seedApiConfigCache(dir, ast({ enabled: true }))).toBeNull()
+    expect(readFileSync(join(dir, ".supatype", "api-config.json"), "utf8")).toBe("{ this is not json")
+  })
+
+  it("does not invent a rest section in a file that has none", () => {
+    const dir = project({ graphql: { introspection: true } })
+    expect(seedApiConfigCache(dir, ast({ enabled: true }))).toBeNull()
+    expect(read(dir).rest).toBeUndefined()
+  })
+})
+
+describe("the free-tier note", () => {
+  // §13.4: a free project with `cache` in its schema has asked for the paid feature in code, which
+  // is better qualified than any banner — and it is why the note names the tables. "Your cache is
+  // off" is a fact about the plan; "posts is served from PostgREST on every request" is a fact
+  // about their project.
+  it("names the tables rather than the feature", () => {
+    expect(freeTierCacheNote({ tables: ["posts"], honoured: false })).toContain(
+      "posts declare a cache in your schema",
+    )
+    expect(freeTierCacheNote({ tables: ["posts", "profiles"], honoured: false })).toContain(
+      "posts and profiles",
+    )
+    expect(freeTierCacheNote({ tables: ["a", "b", "c"], honoured: false })).toContain("a, b and c")
+  })
+
+  it("says the declaration was kept, because it was", () => {
+    // The tier decides what runs, not what a schema may say. A note that read as a rejection would
+    // invite someone to delete a correct declaration.
+    expect(freeTierCacheNote({ tables: ["posts"], honoured: false })).toContain("takes effect on a paid plan")
+  })
+
+  it("says nothing on a tier that honours the declaration", () => {
+    expect(freeTierCacheNote({ tables: ["posts"], honoured: true })).toBeNull()
+  })
+
+  it("says nothing when the schema declared nothing", () => {
+    expect(freeTierCacheNote({ tables: [], honoured: false })).toBeNull()
+  })
+
+  it("says nothing when nothing was reported at all", () => {
+    // An engine push, or a control plane too old to answer. Absence is a question that was never
+    // asked, and the only honest response to it is silence rather than an upsell.
+    expect(freeTierCacheNote(undefined)).toBeNull()
+    expect(freeTierCacheNote({})).toBeNull()
+  })
+})

package/tests/cache-identity-scope.test.ts

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import { isIdentityDependent, type AccessRuleNode } from "../src/cache-identity-scope.js"
+
+/**
+ * The corpus is shared with supatype-server's `internal/studiobootstrap.IsIdentityDependent`,
+ * which answers the same question at request time. Two implementations of one rule drift, and the
+ * drift is silent in both directions: a push that permits `public: true` where the runtime refuses
+ * to share is a feature that quietly does nothing; a push that permits it where the runtime *does*
+ * share is a data leak. Running both against one file is what makes the pair falsifiable.
+ */
+interface Corpus {
+  cases: { name: string; rule: AccessRuleNode | null; identityDependent: boolean }[]
+}
+
+const corpus = JSON.parse(
+  readFileSync(join(__dirname, "fixtures", "identity-scope-corpus.json"), "utf8"),
+) as Corpus
+
+describe("the identity-dependence rule, against the shared corpus", () => {
+  it.each(corpus.cases)("$name", ({ rule, identityDependent }) => {
+    expect(isIdentityDependent(rule)).toBe(identityDependent)
+  })
+
+  it("covers both answers, so a stuck implementation cannot pass", () => {
+    // A classifier hardcoded to `true` is the dangerous failure — it refuses every public cache
+    // and looks conservative while making the feature unusable. One hardcoded to `false` is the
+    // leak. The corpus has to be able to catch both.
+    const yes = corpus.cases.filter(c => c.identityDependent).length
+    expect(yes).toBeGreaterThan(5)
+    expect(corpus.cases.length - yes).toBeGreaterThan(5)
+  })
+})
+
+describe("the distinction the whole feature turns on", () => {
+  it("does not confuse row-dependence with caller-dependence", () => {
+    // `Lte<"published_at", Now>` changes which rows come back, and changes over time, and is the
+    // same for every caller. Refusing it would remove the case public caching exists for.
+    const publishedContent: AccessRuleNode = {
+      type: "compare",
+      left: { kind: "column" },
+      right: { kind: "now" },
+    }
+    expect(isIdentityDependent(publishedContent)).toBe(false)
+  })
+
+  it("catches the same shape when the operand is the caller", () => {
+    const ownRows: AccessRuleNode = {
+      type: "compare",
+      left: { kind: "column" },
+      right: { kind: "authUid" },
+    }
+    expect(isIdentityDependent(ownRows)).toBe(true)
+  })
+
+  it("fails closed on anything it does not recognise", () => {
+    // A rule type added to the language and not to this file must refuse sharing, not permit it.
+    expect(isIdentityDependent({ type: "aRuleInventedTomorrow" })).toBe(true)
+  })
+})