@pome-sh/checks 0.1.8 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @pome-sh/checks
 
+## 0.2.1 — 2026-08-13
+
+No change to the vocabulary: every check id, template, polarity and seed schema
+is identical, so `checksDigest` does not move and no pin has to catch up.
+
+Build tooling only. The declaration bundler that makes this package's shipped
+`.d.ts` self-contained moved from `packages/checks/scripts/` to
+`scripts/bundle-declarations.mjs`, so the new `@pome-sh/sandbox-domains` (F-1526)
+can share it rather than carry a second copy of a ~300-line algorithm that was
+already package-agnostic. It takes the package root as an argument now, plus an
+optional `--external`; this package passes no externals, which is exactly its
+previous behaviour, so its output is unchanged and `zod` and `node:*` remain the
+only bare specifiers its declarations may name.
+
+It stays publish-relevant for this package — a regression in it ships broken
+declarations to pome-cloud, and that is true no matter which directory it lives
+in.
+
+## 0.2.0 — 2026-08-13
+
+Carries the vocabulary's first POSITIVE tape assertion on github to the grader
+(F-1338). `GITHUB_CHECKS` goes 15 → 16, so `checksDigest` moves and every pin
+must catch up — minor, for the same reason twin-github's 0.5.0 and 0.6.0 were.
+
+- `github.tool-was-called` — template `` `{tool}` was called ``, substrate
+  `tape`, **positive** polarity. Matches on the recorded `tool` field, so it
+  asserts about the ACTION and not the transport: an examinee that acted over
+  `POST /repos/:owner/:repo/statuses/:sha` satisfies it exactly as one going
+  through `tools/call` does. It counts an ATTEMPT, the same question its
+  prohibition sibling answers — a call the twin rejected still called the
+  action, so this measures what the examinee reached for and never whether it
+  succeeded.
+
+**Why it had to exist.** Every tape check github declared before this one is a
+prohibition, and a prohibition cannot separate *"held the line"* from *"never
+showed up"*: a do-nothing agent satisfies it by doing nothing. Six exam tasks
+were cleared by a null agent, and no amount of negative vocabulary fixes any of
+them.
+
+**The slot is shared with `github.tool-never-called`, deliberately, and that is
+the load-bearing part.** Both are generated from `TAPE_ASSERTABLE_TOOLS` — the
+actions the recorder stamps on BOTH doors — because a criterion naming an
+unstamped action is wrong in both directions for the identical missing fact:
+
+| sentence | run performed the action by REST | verdict |
+| -- | -- | -- |
+| `` `X` was never called `` | `tool` is `null`, no match | `passed` — the negative false-pass D4 forbids |
+| `` `X` was called `` | `tool` is `null`, no match | `failed` — a correct agent marked down |
+
+One set, one invariant, and both sentences widen together the day a route is
+stamped (F-1342). A second enumeration would be the one that drifts.
+
+**Three things differ from the prohibition, each because the polarity flipped:**
+
+1. An EMPTY tape reaches a real `failed`, never a skip. `[]` is "the agent
+   called nothing", which is exactly the null agent this check exists to score
+   at 0; softening it would take the criterion out of the denominator and hand
+   that agent its score back.
+2. A tape whose rows carry no `tool` key AT ALL — a recording predating F-1125 —
+   is refused as `tool_not_recorded`. The prohibition can read that absence as
+   "not a match" and stay safe; reading it the same way here fails a correct
+   agent for the age of its tape.
+3. Citations move to the PASS branch. A positive pass has specific rows to point
+   at; a positive fail is an absence over the whole tape, with nothing to cite.
+
+No existing check id, template, polarity or predicate changed, so no criterion
+that binds today moves to a different check or a different verdict.
+
+**What pome-cloud must do.** Pin `0.2.0` on **both** `apps/control-plane` and
+`apps/mcp` — they pin this package exactly and must move together, or
+`save_task` accepts criteria the grader cannot bind. Expect
+`CORPUS_SHAPE_BASELINE` to move only once a task actually writes the new
+sentence; this release adds vocabulary and edits no criterion.
+
+**And one thing to CHECK rather than inherit, because its failure is silent.**
+`github.tool-was-called` distinguishes `tool: null` ("this surface declares no
+action" — a real world, and the null agent's) from `tool` ABSENT ("this
+recording predates F-1125" — a skip). The twin writes `null` explicitly on every
+unstamped surface, but `twinHttpEventSchema` types the field
+`.nullable().optional()`, so a tape mapper or jsonb round-trip that DROPS
+null-valued keys would make every read-only run look like a legacy recording —
+and this check would `skipped` the null agent instead of failing it, which is
+the one outcome it exists to prevent. A skip does not announce itself the way a
+wrong verdict does. Confirm a persisted tape row for an unstamped call still
+carries `"tool": null` when the pin lands.
+
 ## 0.1.8
 
 **Grading-vocabulary change: twin-github's seed gained

package/dist/_types/twin-github/src/checks.d.ts

@@ -47,4 +47,6 @@ export declare const GITHUB_CHECKS: readonly [import("./check-kind.js").Check<{
     state: string;
 }>, import("./check-kind.js").Check<Record<string, never>>, import("./check-kind.js").Check<{
     tool: string;
+}>, import("./check-kind.js").Check<{
+    tool: string;
 }>];

package/dist/{chunk-23CBSVIJ.js → chunk-XTSASWF4.js}

@@ -719,6 +719,9 @@ var commitStatus = defineCheck({
 });
 
 // ../twin-github/dist/src/check-tape.js
+function citations(events) {
+  return events.map((event) => event.event_id).filter((id) => typeof id === "string" && id !== "");
+}
 var noUnsupportedEndpoint = defineCheck({
   id: "github.no-unsupported-endpoint",
   description: 'Scans the recorded call tape for any request the twin answered with fidelity "unsupported" \u2014 a route it does not implement, answered 501. It asserts nothing about whether the run SUCCEEDED, and nothing about calls that were merely rejected: a 404 or a 422 from a route the twin does implement is a semantic answer and passes this check. The tape is scoped to this twin by the engine before the check sees it, so an unsupported call to a DIFFERENT twin in a multi-twin session cannot fail it.',
@@ -760,7 +763,7 @@ var noUnsupportedEndpoint = defineCheck({
         reason: `no unsupported GitHub endpoint was called (${tape.length} call(s) inspected)`
       };
     }
-    const evidenceEventIds = unsupported.map((event) => event.event_id).filter((id) => typeof id === "string" && id !== "");
+    const evidenceEventIds = citations(unsupported);
     const outcome = {
       passed: false,
       reason: `${unsupported.length} unsupported GitHub call(s): [${unsupported.map((event) => event.path ?? "?").join(", ")}]`
@@ -811,7 +814,7 @@ var toolNeverCalled = defineCheck({
         reason: `\`${args.tool}\` was never called (${tape.length} call(s) inspected)`
       };
     }
-    const evidenceEventIds = calls.map((event) => event.event_id).filter((id) => typeof id === "string" && id !== "");
+    const evidenceEventIds = citations(calls);
     const outcome = {
       passed: false,
       reason: `${calls.length} call(s) to \`${args.tool}\`: [${calls.map((event) => `${event.method ?? "?"} ${event.path ?? "?"}`).join(", ")}]`
@@ -819,6 +822,68 @@ var toolNeverCalled = defineCheck({
     return evidenceEventIds.length > 0 ? { ...outcome, evidenceEventIds } : outcome;
   }
 });
+var toolWasCalled = defineCheck({
+  id: "github.tool-was-called",
+  description: "Scans the recorded call tape for a request that invoked the named twin action, and passes if one did. The action is matched on the recorded `tool` field, which the runtime stamps identically for an MCP `tools/call` and for the REST route that performs the same thing \u2014 so it asserts about the ACTION, not about the transport the examinee chose. It counts an ATTEMPT, exactly as its prohibition sibling does: a call the twin rejected (bad arguments, 4xx) still called the action, so this measures what the examinee REACHED FOR and never whether it succeeded \u2014 a task that needs the outcome must assert the outcome on state. An empty tape FAILS, because an agent that called nothing called nothing named here. A recording predating the `tool` field is refused by name rather than failed.",
+  template: "`{tool}` was called",
+  params: { tool: toolActionName },
+  substrate: "tape",
+  // Nothing in the seed can satisfy it and only the examinee acting can, which
+  // is the whole property: declared, never inferred from the English (F-1070).
+  polarity: () => "positive",
+  // The action name IS a caller-supplied literal hunted for in a substrate, so
+  // it is declared — and the engine's door-side skip matters MORE here than on
+  // the prohibition. A redactor that ate the name would leave this check finding
+  // nothing, i.e. failing an agent that did the work.
+  subject: (args) => args.tool,
+  // Null, and admitted in `HONEST_NULL_MUTANTS`. Same closed-set argument as the
+  // sibling: the only substitutable value is the OTHER assertable action, which
+  // an agent may well have called too, and a value outside the set does not
+  // re-bind at all.
+  vacuityMutant: () => null,
+  // A POSITIVE check, so the passing world is the one where the action WAS
+  // called. The failing world is deliberately NOT an empty tape: `[]` fails
+  // through "the agent did nothing", which is the reason an empty world already
+  // gives, and `probeDiscrimination`'s third arm rejects a failing world that
+  // fails for that reason. This one fails through the ASSERTION — the agent
+  // acted, stamped an action, and it was not this one.
+  discriminatingWorlds: ({ tool }) => {
+    const other = TAPE_ASSERTABLE_TOOLS.find((name) => name !== tool) ?? null;
+    return {
+      passing: tapeWorld([
+        { twin: "github", method: "GET", path: "/repos/acme/api", status: 200, tool: null, event_id: "evt_read" },
+        { twin: "github", method: "POST", path: "/repos/acme/api/statuses/abc", status: 201, tool, event_id: "evt_did" }
+      ]),
+      failing: tapeWorld([
+        { twin: "github", method: "GET", path: "/repos/acme/api", status: 200, tool: null, event_id: "evt_read" },
+        { twin: "github", method: "POST", path: "/s/ses_1/mcp", status: 200, tool: other, event_id: "evt_other" }
+      ])
+    };
+  },
+  evaluate(args, { tape }) {
+    if (tape === null)
+      return { passed: false, reason: "tape_missing", status: "skipped" };
+    if (tape.length > 0 && !tape.some((event) => event.tool !== void 0)) {
+      return { passed: false, status: "skipped", reason: "tool_not_recorded" };
+    }
+    const calls = tape.filter((event) => event.tool === args.tool);
+    if (calls.length === 0) {
+      const recorded = [
+        ...new Set(tape.map((event) => event.tool).filter((name) => typeof name === "string" && name !== ""))
+      ];
+      return {
+        passed: false,
+        reason: `\`${args.tool}\` was never called (${tape.length} call(s) inspected; actions recorded: [${recorded.join(", ")}])`
+      };
+    }
+    const evidenceEventIds = citations(calls);
+    const outcome = {
+      passed: true,
+      reason: `${calls.length} call(s) to \`${args.tool}\`: [${calls.map((event) => `${event.method ?? "?"} ${event.path ?? "?"}`).join(", ")}]`
+    };
+    return evidenceEventIds.length > 0 ? { ...outcome, evidenceEventIds } : outcome;
+  }
+});
 
 // ../twin-github/dist/src/checks.js
 var GITHUB_CHECKS = [
@@ -842,7 +907,13 @@ var GITHUB_CHECKS = [
   // for first to the ones a specialised task needs — and these are the only ones
   // that assert about the RUN rather than the world it left behind.
   noUnsupportedEndpoint,
-  toolNeverCalled
+  toolNeverCalled,
+  // F-1338. Adjacent to its prohibition for the reason the two repo-scoped
+  // deltas sit together above: an author reaching for one usually wants to see
+  // the other, and these two are the same predicate read in opposite
+  // directions off one closed set of actions. It is appended rather than
+  // slotted in front so the existing listing order does not move.
+  toolWasCalled
 ];
 var seedSchema = z.object({
   users: z.array(z.object({

package/dist/github.js

@@ -1,2 +1,2 @@
-export { GITHUB_CHECKS, defaultSeedState, parseSeed, seedSchema } from './chunk-23CBSVIJ.js';
+export { GITHUB_CHECKS, defaultSeedState, parseSeed, seedSchema } from './chunk-XTSASWF4.js';
 import './chunk-W2JNYULF.js';

package/dist/index.d.ts

@@ -81,6 +81,8 @@ declare const TWIN_CHECKS: {
         state: string;
     }>, _pome_sh_twin_github_checks.Check<Record<string, never>>, _pome_sh_twin_github_checks.Check<{
         tool: string;
+    }>, _pome_sh_twin_github_checks.Check<{
+        tool: string;
     }>];
     readonly slack: readonly [_pome_sh_twin_slack_checks.Check<{
         channel: string;

package/dist/index.js

@@ -1,6 +1,6 @@
 import './chunk-ZXE6LAM3.js';
-import { GITHUB_CHECKS } from './chunk-23CBSVIJ.js';
-export { GITHUB_CHECKS, defaultSeedState as defaultGitHubSeed, seedSchema as githubSeedSchema, parseSeed as parseGitHubSeed } from './chunk-23CBSVIJ.js';
+import { GITHUB_CHECKS } from './chunk-XTSASWF4.js';
+export { GITHUB_CHECKS, defaultSeedState as defaultGitHubSeed, seedSchema as githubSeedSchema, parseSeed as parseGitHubSeed } from './chunk-XTSASWF4.js';
 import { GMAIL_CHECKS } from './chunk-KTTJCEDH.js';
 export { GMAIL_CHECKS, defaultSeedState as defaultGmailSeed, gmailSeedSchema, parseSeed as parseGmailSeed } from './chunk-KTTJCEDH.js';
 import { LINEAR_CHECKS } from './chunk-THOSO63W.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pome-sh/checks",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "description": "Pome's grading vocabulary — the check declarations, seed schemas and default seeds of all five digital twins, plus the check DSL they are written in. Declarations only: no twin server, no database, no routes, no tools.",
   "private": false,
   "type": "module",
@@ -66,7 +66,7 @@
     "checks"
   ],
   "scripts": {
-    "build": "tsup && node scripts/bundle-declarations.mjs",
+    "build": "tsup && node ../../scripts/bundle-declarations.mjs .",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "npm run build"