chore(ratchet): delete the interface-data-api guardrail ratchet

AGENTS.md

@@ -30,7 +30,7 @@ The release commit writes `CHANGELOG.md`. Upgrade notes for that version follow
 
 ## Guardrails
 
-Finish every change with `pnpm run checks`. It runs typecheck, lint, format, knip, tests, size, ratchet, suppressions, and sync, and prints only what failed. The change is done when it prints no failure.
+Finish every change with `pnpm run checks`. It runs typecheck, lint, format, knip, tests, size, suppressions, and sync, and prints only what failed. The change is done when it prints no failure.
 
 The tools enforce most rules, listed in the table at the end. The sections below hold the rules no tool checks.
 
@@ -68,10 +68,6 @@ Verify a boundary against the imports a developer or agent would plausibly write
 
 `guardrails.suppressions.json` caps the suppressions in authored code: lint directives per rule they name (`*` for none), `@ts-expect-error`, `@ts-ignore` and `SAFETY:` comments, and under `config` each rule a lint config (`oxlint.config.*`, `.oxlintrc.json`, `eslint.config.*`) switches off or to a warning, keyed by rule and `files` glob anchored at the config's directory, so widening or moving a scope is a new ceiling of 0, while narrowing one takes over the room it gives up. Switching a rule off in a config is a suppression too: fix the code its rule reports instead. A suppression over its ceiling fails: fix the code, or remove another suppression of the same kind. A rule that keeps needing suppressions should be changed in the preset. Never raise or remove a number in that file: the check fails a ceiling higher than on the pull request base, and only the operator approves a raise. A directive disabling `anti-slop/require-safety-comment-for-type-assertion` is burn-down debt: remove the assertion, or, where it holds, replace the directive with `SAFETY: <why it holds>`, which takes over its room without a raise. After you remove suppressions, run `pnpm run suppressions:update` and commit the lowered file.
 
-### Debt
-
-`guardrails.ratchet.json` records the lint findings and oversize files this repository already had. Its numbers only go down. After you remove debt, or after a pack upgrade, run `pnpm run ratchet:update` and commit the file: it lowers the numbers and adds only the rules the new pack release enabled, at today's count. Never edit the numbers by hand; CI fails one added or raised against the base. A rule listed there is off for `oxlint`. The ratchet counts it instead, and the pre-commit hook rejects it on every line you add.
-
 ### What enforces what
 
 | Rule                                                                           | Enforced by                                         |
@@ -113,6 +109,5 @@ Verify a boundary against the imports a developer or agent would plausibly write
 | Entry-only rules exempt no tracked outsider                                    | `antelopejs-sync --check`                           |
 | A DMS layer's `build/backend-boundary.ts` is the pack's plugin                 | `antelopejs-sync --check`                           |
 | A test names the wrong implementation it catches                               | review; no tool                                     |
-| Existing debt only shrinks                                                     | `antelopejs-ratchet`                                |
 
 <!-- antelopejs-guardrails:end -->

guardrails.suppressions.json

@@ -1,5 +1,8 @@
 {
-  "rules": {},
+  "rules": {
+    "anti-slop/no-unsafe-dictionary-type": 1,
+    "typescript/no-unsafe-return": 1
+  },
   "tsExpectError": 5,
   "tsIgnore": 0,
   "safety": 4,

lefthook.yml

@@ -8,9 +8,6 @@ pre-commit:
       run: pnpm exec oxlint --no-error-on-unmatched-pattern {staged_files}
     antelopejs-size:
       run: pnpm exec antelopejs-check-size --staged {staged_files}
-    antelopejs-ratchet:
-      glob: "*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}"
-      run: pnpm exec antelopejs-ratchet --staged {staged_files}
     antelopejs-suppressions:
       glob: "*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}"
       run: pnpm exec antelopejs-suppressions --staged

package.json

@@ -64,9 +64,7 @@
     "prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
     "checks": "antelopejs-checks",
     "size": "antelopejs-check-size",
-    "ratchet": "antelopejs-ratchet",
     "sync": "antelopejs-sync",
-    "ratchet:update": "antelopejs-ratchet --update",
     "sync:check": "antelopejs-sync --check",
     "typecheck": "tsc --noEmit",
     "suppressions": "antelopejs-suppressions",
@@ -96,7 +94,8 @@
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "4.5.4"
   },
   "peerDependencies": {
     "@antelopejs/interface-api": ">=0.3.0 <1.0.0",

src/internal/deferred-joined-stream.ts

@@ -107,6 +107,7 @@ function forwardingDeferredJoinOperation(
 ): DeferredJoinedOperation {
   return function (this: DeferredJoinedStream, ...args: any[]) {
     // SAFETY: name comes from wireDeferredJoinedStream, which lists the own method names of Stream.prototype plus run, cursor and build, all present on any Stream, and Joined returns a Stream for the raw Stream it is given.
+    // oxlint-disable-next-line typescript/no-unsafe-return -- the method is looked up by a runtime name on a Stream, which TypeScript cannot relate to a signature; Reflect.apply and a typed lookup were tried and moved the finding to no-reflect-get, no-reflect-apply and no-unknown-returns
     return (materializeDeferredJoin(this) as any)[name](...args);
   };
 }

src/internal/field-types.ts

@@ -48,6 +48,7 @@ export interface FieldValues {
  * what the getter returned. Read a field through a guard.
  */
 export interface RowFields {
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- a table row holds whatever its table class declares (relation instances, getter results), and a route reads each field through a guard, so no schema-derived value type exists for the fields of a schemaless store row
   [field: string]: unknown;
 }
 

src/tests/components/access_control.test.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { expect } from "chai";
+import { z } from "zod";
 import { Controller } from "@antelopejs/interface-api";
 import type { SchemaInstance } from "@antelopejs/interface-database";
 import { Access, AccessMode, ModelReference } from "../../metadata";
@@ -50,6 +51,14 @@ class User extends Table {
   declare age: number;
 }
 class UserModel extends BasicDataModel(User, userTableName) {}
+
+const userRowSchema = z.looseObject({
+  _id: z.string().optional(),
+  email: z.string().optional(),
+  password: z.string().optional(),
+  name: z.string().optional(),
+  age: z.number().optional(),
+});
 let database: SchemaInstance<any>;
 
 const defaultUserDataset: Partial<User> = {
@@ -115,7 +124,7 @@ async function expectReadInReadWriteField() {
 
   const response = await getRequest(getFunctionName(), { id });
   expect(response.status).to.equal(200);
-  const data = await readJson<User>(response);
+  const data = await readJson(userRowSchema, response);
   expect(data.name).to.equal(defaultUserDataset.name);
   expect(data.age).to.equal(defaultUserDataset.age);
   expect(data.email).to.equal(defaultUserDataset.email);
@@ -147,7 +156,7 @@ async function expectReadInWriteOnlyField() {
 
   const response = await getRequest(getFunctionName(), { id });
   expect(response.status).to.equal(200);
-  const data = await readJson<User>(response);
+  const data = await readJson(userRowSchema, response);
   expect(data.password).to.equal(undefined);
 }
 
@@ -175,7 +184,7 @@ async function expectReadInReadOnlyField() {
 
   const response = await getRequest(getFunctionName(), { id });
   expect(response.status).to.equal(200);
-  const data = await readJson<User>(response);
+  const data = await readJson(userRowSchema, response);
   expect(data.email).to.equal(defaultUserDataset.email);
 }
 

src/tests/components/computed.test.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { expect } from "chai";
+import { z } from "zod";
 import { Controller } from "@antelopejs/interface-api";
 import { GetMetadata } from "@antelopejs/interface-core";
 import { Schema } from "@antelopejs/interface-database";
@@ -29,7 +30,7 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-import { readJson } from "../internal/http";
+import { listResponseSchema, readJson } from "../internal/http";
 import {
   editRequest,
   getFunctionName,
@@ -68,19 +69,19 @@ class Device extends Table {
 }
 class DeviceModel extends BasicDataModel(Device, deviceTableName) {}
 
-interface GroupListed {
-  _id: string;
-  name: string;
-  devices_count: number;
-  display_name: string;
-}
+const groupListedSchema = z.looseObject({
+  _id: z.string(),
+  name: z.string(),
+  devices_count: z.number(),
+  display_name: z.string(),
+});
 
-interface ListResponse {
-  results: GroupListed[];
-  total: number;
-  offset: number;
-  limit: number;
-}
+const listSchema = listResponseSchema(groupListedSchema);
+type GroupListedFields = Pick<
+  z.infer<typeof groupListedSchema>,
+  "name" | "devices_count" | "display_name"
+>;
+type ListResponse = z.infer<typeof listSchema>;
 
 const groupsDataset: Partial<Group>[] = [
   { name: "Alpha" },
@@ -187,7 +188,7 @@ async function _listGroups(
     const text = await response.text();
     throw new Error(`list failed (${response.status}): ${text}`);
   }
-  return await readJson<ListResponse>(response);
+  return await readJson(listSchema, response);
 }
 
 async function expectStoresComputedMetadata() {
@@ -229,7 +230,7 @@ async function expectGetsRowWithComputedValues() {
     const text = await response.text();
     throw new Error(`get failed (${response.status}): ${text}`);
   }
-  const group = await readJson<GroupListed>(response);
+  const group = await readJson(groupListedSchema, response);
   expect(group.name).to.equal("Alpha");
   expect(group.devices_count).to.equal(3);
   expect(group.display_name).to.equal("Alpha!");
@@ -309,9 +310,8 @@ async function expectIgnoresComputedFieldsOnEdit() {
   });
   expect(response.status).to.equal(200);
 
-  const updatedGroup: Partial<GroupListed> | undefined = await groupModel.get(
-    groupIds[0],
-  );
+  const updatedGroup: Partial<GroupListedFields> | undefined =
+    await groupModel.get(groupIds[0]);
   expect(updatedGroup?.name).to.equal("Alpha Prime");
   expect(updatedGroup?.devices_count).to.equal(undefined);
   expect(updatedGroup?.display_name).to.equal(undefined);

src/tests/components/filter_list_route.test.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { expect } from "chai";
+import { z } from "zod";
 import { Controller } from "@antelopejs/interface-api";
 import { Schema } from "@antelopejs/interface-database";
 import {
@@ -23,7 +24,7 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-import { readJson } from "../internal/http";
+import { listResponseSchema, readJson } from "../internal/http";
 import { getSchemaInstance, listRequest, request } from "../utils";
 
 const currentTestName = path
@@ -44,9 +45,9 @@ class Page extends Table {
 }
 class PageModel extends BasicDataModel(Page, pageTableName) {}
 
-interface ListResponse {
-  results: { title: string; url: string }[];
-}
+const listSchema = listResponseSchema(
+  z.looseObject({ title: z.string(), url: z.string() }),
+);
 
 async function seedPages() {
   await RegisterSchema(schemaName);
@@ -182,7 +183,7 @@ describe("List route - filter comparisons", () => {
     });
 
     expect(response.status, await response.clone().text()).to.equal(200);
-    const data = await readJson<ListResponse>(response);
+    const data = await readJson(listSchema, response);
     expect(data.results.map(({ title }) => title)).to.eql(["alpha"]);
   });
 
@@ -194,7 +195,7 @@ describe("List route - filter comparisons", () => {
     });
 
     expect(response.status, await response.clone().text()).to.equal(200);
-    const data = await readJson<ListResponse>(response);
+    const data = await readJson(listSchema, response);
     expect(data.results.map(({ title }) => title)).to.eql(["beta"]);
   });
 
@@ -206,7 +207,7 @@ describe("List route - filter comparisons", () => {
     });
 
     expect(response.status, await response.clone().text()).to.equal(200);
-    const data = await readJson<ListResponse>(response);
+    const data = await readJson(listSchema, response);
     expect(data.results.map(({ title }) => title)).to.eql(["alpha"]);
   });
 
@@ -218,7 +219,7 @@ describe("List route - filter comparisons", () => {
     });
 
     expect(response.status, await response.clone().text()).to.equal(200);
-    const data = await readJson<ListResponse>(response);
+    const data = await readJson(listSchema, response);
     expect(data.results.map(({ title }) => title)).to.eql(["alpha"]);
   });
 });

src/tests/components/foreign_computed.test.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { expect } from "chai";
+import { z } from "zod";
 import { Controller } from "@antelopejs/interface-api";
 import { Schema } from "@antelopejs/interface-database";
 import {
@@ -26,7 +27,7 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-import { readJson } from "../internal/http";
+import { listResponseSchema, readJson } from "../internal/http";
 import {
   getFunctionName,
   getRequest,
@@ -66,17 +67,15 @@ class Member extends Table {
 }
 class MemberModel extends BasicDataModel(Member, memberTableName) {}
 
-interface MemberListed {
-  _id: string;
-  label: string;
-  team: { _id: string; name: string };
-  teammates: number;
-}
+const memberListedSchema = z.looseObject({
+  _id: z.string(),
+  label: z.string(),
+  team: z.looseObject({ _id: z.string(), name: z.string() }),
+  teammates: z.number(),
+});
 
-interface ListResponse {
-  results: MemberListed[];
-  total: number;
-}
+const listSchema = listResponseSchema(memberListedSchema);
+type ListResponse = z.infer<typeof listSchema>;
 
 describe("Foreign and Computed fields on the same key", () => {
   it("lists the computed value read from the key and the resolved relation", async () =>
@@ -166,7 +165,7 @@ async function _list(
 ): Promise<ListResponse> {
   const response = await request(testName, "list", "GET", undefined, query);
   expect(response.status, await response.clone().text()).to.equal(200);
-  return await readJson<ListResponse>(response);
+  return await readJson(listSchema, response);
 }
 
 async function expectListsComputedFromForeignKey() {
@@ -188,7 +187,7 @@ async function expectGetsComputedFromForeignKey() {
 
   const response = await getRequest(getFunctionName(), { id: memberIds[3] });
   expect(response.status).to.equal(200);
-  const member = await readJson<MemberListed>(response);
+  const member = await readJson(memberListedSchema, response);
   expect(member.teammates).to.equal(1);
   expect(member.team).to.deep.equal({ _id: teamIds[1], name: "Blue" });
 }