@pome-sh/checks 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @pome-sh/checks
 
+## 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
+`repositories[].files[].renamed_from`.** No check declaration moves, no criterion
+moves and `checksDigest` is unaffected — this package's other half is the seed
+schemas, and this is one of them.
+
+`renamed_from` names the path a file was MOVED from on `branch`, and it is the
+only way a seed can take a path away from a branch. A seeded branch is created
+from the default branch and inherits every path, and a plain `files[]` entry can
+add or overwrite but never remove — so `status: "renamed"`, which
+`PullRequestFileRow` has always declared, was reachable from no seed at all, and
+`GET /pulls/:n/files` could not be made to serve GitHub's `previous_filename` by
+any world. Registering that as an allowance would have been accepting a gap in
+the twin's core file model.
+
+`content` is refused alongside `renamed_from` and read from the source path
+instead. That is not ergonomics: the branch diff detects a move by pairing
+identical blobs, so a seed naming both a source and different content would be
+asking for a rename the diff would report as an add plus a remove — the same
+unreachability one level up. A seed that sets `renamed_from` with no `branch`, or
+whose source is not a file on the branch, or whose source is its own destination,
+is refused with a message naming the field.
+
+Every seed valid before this is valid now: `content` became optional in the
+object and required by refine wherever `renamed_from` is absent.
+
 ## 0.1.7
 
 A section a check's verdict reads is now measured HERE, where the worlds are

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/_types/twin-github/src/seed.d.ts

@@ -23,8 +23,9 @@ export declare const seedSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         files: z.ZodDefault<z.ZodArray<z.ZodObject<{
             path: z.ZodString;
-            content: z.ZodString;
+            content: z.ZodOptional<z.ZodString>;
             branch: z.ZodOptional<z.ZodString>;
+            renamed_from: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         milestones: z.ZodDefault<z.ZodArray<z.ZodObject<{
             number: z.ZodOptional<z.ZodNumber>;

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

@@ -24,8 +24,9 @@ export type SeedRepository = {
     }>;
     files?: Array<{
         path: string;
-        content: string;
+        content?: string;
         branch?: string;
+        renamed_from?: string;
     }>;
     milestones?: Array<{
         number?: number;
@@ -202,6 +203,7 @@ export type PullRequestFileRow = {
     raw_url: string;
     contents_url: string;
     patch: string;
+    previous_filename: string | null;
 };
 export type CommitStatusRow = {
     id: number;

package/dist/{chunk-JVCGWAZQ.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({
@@ -862,7 +933,52 @@ var seedSchema = z.object({
       color: z.string().default("ededed"),
       description: z.string().default("")
     })).default([]),
-    files: z.array(z.object({ path: z.string().min(1), content: z.string(), branch: z.string().optional() })).default([]),
+    // F-1500 — `renamed_from` is how a seed expresses a MOVE, and with it the
+    // `status: "renamed"` the row type has always declared and no world could
+    // reach. A seeded branch is created from the default branch and inherits
+    // every path, and a plain `files[]` entry can only add or overwrite, so
+    // before this there was no way to make a path ABSENT from the head branch
+    // — and `previous_filename` was therefore unreachable from any seed, not
+    // merely unemitted.
+    //
+    // `content` is refused alongside `renamed_from` rather than merged with
+    // it: the diff detects a move by pairing identical blobs (see
+    // `calculatePullFiles`), so a seed naming a source AND different content
+    // would be asking for a rename the diff would report as an add plus a
+    // remove. Refusing it keeps "the seed asked for a rename" and "the twin
+    // serves a rename" the same statement. The content comes from the source
+    // path, which the domain resolves on the branch the move happens on.
+    files: z.array(z.object({
+      path: z.string().min(1),
+      content: z.string().optional(),
+      branch: z.string().optional(),
+      renamed_from: z.string().min(1).optional()
+    }).superRefine((file, ctx) => {
+      if (file.renamed_from === void 0) {
+        if (file.content === void 0) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["content"],
+            message: "content is required on a file entry that declares no renamed_from"
+          });
+        }
+        return;
+      }
+      if (file.content !== void 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["content"],
+          message: `renamed_from carries the source file's content, so content must be omitted (${file.path})`
+        });
+      }
+      if (file.renamed_from === file.path) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["renamed_from"],
+          message: `renamed_from must name a different path than the file it moves to (${file.path})`
+        });
+      }
+    })).default([]),
     // F-1421 — milestones, tags and releases are repository-level entities the
     // twin already SERVES (`GET /milestones`, `/tags`, `/releases`,
     // `/releases/latest`, `/releases/tags/:tag`) and the seed could not

package/dist/github.js

@@ -1,2 +1,2 @@
-export { GITHUB_CHECKS, defaultSeedState, parseSeed, seedSchema } from './chunk-JVCGWAZQ.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-JVCGWAZQ.js';
-export { GITHUB_CHECKS, defaultSeedState as defaultGitHubSeed, seedSchema as githubSeedSchema, parseSeed as parseGitHubSeed } from './chunk-JVCGWAZQ.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.7",
+  "version": "0.2.0",
   "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",