@pome-sh/checks 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @pome-sh/checks
 
+## 0.1.7
+
+A section a check's verdict reads is now measured HERE, where the worlds are
+authored, instead of being left to an instrument that cannot see it (F-1437).
+
+pome-cloud's `findVacuousStateSectionReaders` derives its candidate sections
+from what DIFFERS between a check's two discriminating worlds. That rule is what
+stops it reporting every section a world carries for realism, and it is also a
+blind spot it has documented rather than folded into its zero: a section
+IDENTICAL in both worlds is never a candidate, so it is never deleted, so a
+verdict that reads it vacuously is invisible there. No widening fixes that — with
+both worlds carrying the same value there is no failing value to swap in, hence
+no proof the verdict reads the section at all.
+
+`test/section-read-sweep.test.ts` reaches it from the other side. It hands
+`evaluate` a recording view of the state tree, so every top-level section the
+predicate ASKS FOR is on the record whether or not the worlds disagree about it;
+then, for exactly the sections the worlds agree on, it runs the detector's own
+step 3 — delete from the passing world, re-evaluate — and a verdict that stays a
+bare `passed` is named. Both trees, `seed` as well as `final`, because the
+detector probes `final` only. Over the shipped vocabulary: 38 state
+declarations and 34 agreed-on section reads (28 on `final`, 6 on `seed`), of
+which 26 are discharged by measurement — 22 return `state_incomplete` and 4 fail
+honestly — and 8 are declared exceptions where the twin reads an absent section
+as a VALUE: the
+`exportBounds` block, whose absence `isTruncated` deliberately answers as "not
+truncated" so an export predating the cap is not skipped wholesale, and
+`gmail.mailbox-label-count`'s `mailboxes`, where an absent collection means
+"count by `mailboxEmail`" and the evidence collections are guarded by name one
+line above. The exception list is pinned in both directions, so a row that stops
+being needed fails the same way an unexplained finding does.
+
+**ONE DECLARATION MOVED, AND IT IS A FIXTURE, NOT A VERDICT.**
+`gmail.message-has-label`'s discriminating worlds built their user label as
+`userLabel(label, label)` — an `id === name` shape only a SYSTEM label has. With
+it, `labelIdsFor`'s bare-display-name fallback answered the join unaided, so
+deleting `labels` from the passing world changed nothing and the verdict stayed
+`passed`: a section the verdict demonstrably reads, proven unread by the only
+world that speaks for it. The label now carries a minted id (`Label_1`) and the
+`messageLabels` rows carry that id, so the deletion moves the verdict to
+`failed` and the read is on the record.
+
+Nothing in any `evaluate` changed. No check id, template, params, polarity,
+subject or vacuity mutant moved, and no criterion changes from bound to unbound
+or from passing to failing on any real export. `discriminatingWorlds` is a
+fixture the probes run; a run's grade does not read it.
+
+`labelIdsFor`'s comment counted TWO callers that must guard `state.labels`. There
+are three — `messageCarriesLabel` in the same file is the third, reached by
+`gmail.message-has-label`, and it answers `false` rather than refusing. That is
+the safe direction for a check whose polarity is always positive, so it is left
+alone and the comment now says which caller does which, with the sweep as the
+thing that keeps it measured rather than assumed.
+
+**What pome-cloud must do.** Pin `0.1.7` in `apps/control-plane` AND `apps/mcp`
+— they must move together or `save_task` accepts criteria the grader cannot
+bind — and restate the blind spot in `findVacuousStateSectionReaders`' doc
+comment as a property of the declarations rather than of the detector, with
+`docs/grading/a3-bucket-ledger.md` §5 item 9 following it. `declared-pin.test.ts`
+needs no other edit: the detector's finding set over the new declarations is
+byte-identical, because `gmail.message-has-label`'s worlds still differ on
+`messageLabels` alone and deleting it still returns `state_incomplete`.
+
+## 0.1.6
+
+`gmail.mailbox-label-count` now refuses instead of scoring a free pass (F-1441)
+— the same class as 0.1.5's `slack.no-reaction-added`, found live in twin-gmail
+on a worse criterion. Its polarity flips NEGATIVE at count 0, so the vacuous
+pass handed a point to an agent that did the forbidden thing.
+
+`labelIdsFor` read `state.labels ?? []` with no absence guard. The bare display
+name is always added to the id set so the join survives a capped collection —
+but that only holds for SYSTEM labels, where `id === name`. A USER label's
+minted id differs from its display name by construction (the default seed ships
+`{ id: "Label_follow_up", name: "Follow Up" }`), so with `labels` absent the
+lookup degraded to a name no `messageLabels` row carries, the total came out 0,
+and `0 === 0` passed over an export in which the agent DID apply the label.
+
+`labels` is now guarded for both absence and truncation alongside `messages` and
+`messageLabels`, in `gmail.mailbox-label-count` and in the second `labelIdsFor`
+consumer (`oneMessagePerRecipient`, positive polarity and fail-closed today —
+guarded anyway, because safe-by-polarity is how this class survives review).
+`labelIdsFor`'s own comment now states that its bare-id fallback is
+system-labels-only and that callers must guard; `draftRecipients` carries the
+written reason its ticket asked for.
+
 ## 0.1.5
 
 `slack.no-reaction-added` now refuses instead of scoring a free pass (F-1159).

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

@@ -243,6 +243,10 @@ export type ReleaseRow = {
     prerelease: 0 | 1;
     author_login: string;
     created_at: string;
+    /** F-1459 — GitHub's release `updated_at`. Equal to `created_at` on a release
+     * that has never been edited, which is every release this twin serves: it has
+     * no release-update route. */
+    updated_at: string;
     published_at: string | null;
 };
 export type CheckRunRow = {

package/dist/_types/twin-gmail/src/check-state.d.ts

@@ -108,6 +108,36 @@ export declare function resolveMessage(state: GmailCheckState, id: string): Reso
  * The bare `wanted` is always included so the join still works when the `labels`
  * collection was capped away — a `messageLabels` row carries the bare id
  * regardless.
+ *
+ * ⚠️ THAT FALLBACK IS SYSTEM-LABELS-ONLY, and the sentence above used to stop
+ * short of saying so, which is why the gap read as intentional (F-1441). It
+ * holds when `id === name` — `INBOX`, `UNREAD`, `STARRED`. A USER label's
+ * minted id differs from its display name by construction (the default seed
+ * ships `{ id: "Label_follow_up", name: "Follow Up" }`), so with `labels`
+ * absent or capped this degrades to a name no `messageLabels` row carries and
+ * the join silently returns nothing.
+ *
+ * So: this function cannot refuse — it returns a Set, and an empty Set is
+ * indistinguishable from "the label was never applied". **Every caller must
+ * decide what an absent or capped `labels` collection means before calling**.
+ *
+ * THERE ARE THREE CALLERS, not the two F-1441 counted, and the third is in this
+ * very file:
+ *   * `gmail.mailbox-label-count` and `gmail.one-message-per-recipient` in
+ *     check-messages.ts REFUSE — `state_incomplete` / `collection_truncated` —
+ *     because the first flips NEGATIVE at count 0, where an empty Set is a free
+ *     point for an agent that did the forbidden thing.
+ *   * `messageCarriesLabel` below, reached by `gmail.message-has-label`, does
+ *     NOT refuse: it answers `false`, so an absent `labels` costs that check's
+ *     agent a point rather than gifting one. Its polarity is always positive, so
+ *     the direction is safe — but safe-by-polarity is how this class survives
+ *     review, so it is measured rather than assumed. `section-read-sweep.test.ts`
+ *     in @pome-sh/checks deletes `labels` from that check's own passing world on
+ *     every run and asserts the verdict MOVES; before F-1437 it did not, because
+ *     that world minted the label with `id === name` and the fallback above
+ *     answered the join unaided.
+ *
+ * A fourth caller must pick one of those two and say which.
  */
 export declare function labelIdsFor(state: GmailCheckState, wanted: string): Set<string>;
 /**
@@ -134,5 +164,13 @@ export declare function resolveLabelByName(state: GmailCheckState, name: string)
  * alone would answer "no draft is addressed to anyone", always. A draft whose
  * message did not survive the export contributes nothing rather than throwing;
  * the caller decides whether that emptiness is answerable.
+ *
+ * ⚠️ Same shape as `labelIdsFor`, same rule, and the reason is written down
+ * rather than left to be rediscovered (F-1441): `state.messages ?? []` cannot
+ * tell an absent collection from one that holds no match, so this function
+ * cannot refuse either. It is safe TODAY only because its sole caller
+ * null-checks `final.messages` first (`check-drafts.ts:63`) — safe-by-caller,
+ * which is precisely how this class survives review. A second caller must
+ * guard, or this must be changed to return a `Resolved`.
  */
 export declare function draftRecipients(state: GmailCheckState, draft: GmailCheckStateDraft): string[];

package/dist/_types/wire/index.d.ts

@@ -5,16 +5,35 @@
  * and the CLI reads (`recorder-events.ts`), the OpenTelemetry-native extension
  * of that union (`otel/`), and the secret redactor applied on the way to disk
  * (`redaction.ts`). Every twin, the sdk, the adapter and the CLI depend on this
- * package; NOTHING here knows about sessions, tasks, runs or the cloud REST
- * surface — those live in `cli/src/contract/` (F-942).
+ * package; NOTHING ON THIS BARREL knows about sessions, tasks, runs or the
+ * cloud REST surface — those live in `cli/src/contract/` (F-942).
  *
- * Two SUBPATH-ONLY surfaces are deliberately absent from this barrel, because
- * only some consumers should pay to load them: `@pome-sh/wire/otel/fixtures`
- * (the golden-fixture corpus, a test/dev artifact) and
- * `@pome-sh/wire/correlation` (F-950 — the agent-side AsyncLocalStorage +
- * fetch-patching plumbing that stamps `x-pome-correlation-id`; importing it
- * constructs an AsyncLocalStorage, and no twin is the agent side of that
- * protocol). `test/export-surface.test.ts` pins both halves of that call.
+ * F-1416 NARROWED THAT CLAIM ONCE, and this is the whole of the narrowing: the
+ * package now also ships `@pome-sh/wire/run-completeness`, four symbols that
+ * read two fields of a `criteria_results` row (`skipped`, `reason`) and return
+ * whether a finished run has a verdict to state. That is the one predicate
+ * pome-cloud's dashboard and control plane and this repo's CLI all have to
+ * agree on, and until F-1416 the CLI's agreement test kept a hand-written copy
+ * of it that went stale green. It is run-ADJACENT, so the sentence above would
+ * be false if it said "this package"; it is not run vocabulary, because it
+ * names no session, task, run id, REST route or column, imports nothing, and
+ * takes structural inputs so no cloud type crosses with it. Keeping it OFF this
+ * barrel is what keeps the sentence above enforceable rather than merely
+ * written down — see below.
+ *
+ * Three SUBPATH-ONLY surfaces are deliberately absent from this barrel.
+ * `@pome-sh/wire/otel/fixtures` (the golden-fixture corpus, a test/dev
+ * artifact) and `@pome-sh/wire/correlation` (F-950 — the agent-side
+ * AsyncLocalStorage + fetch-patching plumbing that stamps
+ * `x-pome-correlation-id`) are absent because only some consumers should pay to
+ * LOAD them: importing correlation constructs an AsyncLocalStorage, and no twin
+ * is the agent side of that protocol. `@pome-sh/wire/run-completeness` (F-1416)
+ * is absent for a different reason — SCOPE, not cost. The five twins, the sdk
+ * and the adapter import this barrel and not one of them has a run to ask
+ * about, so a symbol they cannot use has no business in their namespace, and an
+ * opt-in subpath is what makes the F-942 boundary above a thing CI can check.
+ * `test/export-surface.test.ts` pins all three: each subpath's own surface, and
+ * its absence from the snapshot below.
  *
  * This file is a THIN BARREL: it re-exports only.
  */

package/dist/{chunk-SA23X6PB.js → chunk-KTTJCEDH.js}

@@ -373,10 +373,14 @@ var messageHasLabel = defineCheck({
   // lookup rather than the assertion. The label is the scanned literal.
   vacuityMutant: (args) => ({ ...args, label: VACUITY_SENTINEL }),
   discriminatingWorlds: ({ message: id2, label }) => {
-    const labels = [systemLabel("INBOX"), userLabel(label, label)];
+    const labelId = "Label_1";
+    const labels = [systemLabel("INBOX"), userLabel(labelId, label)];
     const base = { messages: [message(id2)], labels };
     return {
-      passing: finalWorld(gmailState({ ...base, messageLabels: [messageLabel(id2, "INBOX"), messageLabel(id2, label)] })),
+      passing: finalWorld(gmailState({
+        ...base,
+        messageLabels: [messageLabel(id2, "INBOX"), messageLabel(id2, labelId)]
+      })),
       failing: finalWorld(gmailState({ ...base, messageLabels: [messageLabel(id2, "INBOX")] }))
     };
   },
@@ -430,10 +434,10 @@ var mailboxLabelCount = defineCheck({
   },
   evaluate({ mailbox, count, label }, { final }) {
     const wanted = Number(count);
-    if (final.messages == null || final.messageLabels == null) {
+    if (final.messages == null || final.messageLabels == null || final.labels == null) {
       return { passed: false, status: "skipped", reason: "state_incomplete" };
     }
-    if (isTruncated(final, "messages") || isTruncated(final, "messageLabels")) {
+    if (isTruncated(final, "messages") || isTruncated(final, "messageLabels") || isTruncated(final, "labels")) {
       return { passed: false, status: "skipped", reason: "collection_truncated" };
     }
     if (final.mailboxes != null && !final.mailboxes.some((mb) => (mb.email ?? "").toLowerCase() === mailbox.toLowerCase())) {
@@ -490,10 +494,10 @@ var oneMessagePerRecipient = defineCheck({
   },
   evaluate({ label, count }, { final }) {
     const wanted = parseCount(count);
-    if (final.messages == null || final.messageLabels == null) {
+    if (final.messages == null || final.messageLabels == null || final.labels == null) {
       return { passed: false, status: "skipped", reason: "state_incomplete" };
     }
-    if (isTruncated(final, "messages") || isTruncated(final, "messageLabels")) {
+    if (isTruncated(final, "messages") || isTruncated(final, "messageLabels") || isTruncated(final, "labels")) {
       return { passed: false, status: "skipped", reason: "collection_truncated" };
     }
     const ids = labelIdsFor(final, label);

package/dist/gmail.js

@@ -1,2 +1,2 @@
-export { GMAIL_CHECKS, defaultSeedState, gmailSeedSchema, parseSeed } from './chunk-SA23X6PB.js';
+export { GMAIL_CHECKS, defaultSeedState, gmailSeedSchema, parseSeed } from './chunk-KTTJCEDH.js';
 import './chunk-W2JNYULF.js';

package/dist/index.js

@@ -1,8 +1,8 @@
 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 { GMAIL_CHECKS } from './chunk-SA23X6PB.js';
-export { GMAIL_CHECKS, defaultSeedState as defaultGmailSeed, gmailSeedSchema, parseSeed as parseGmailSeed } from './chunk-SA23X6PB.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';
 export { LINEAR_CHECKS, defaultSeedState as defaultLinearSeed, linearSeedSchema, parseSeed as parseLinearSeed } from './chunk-THOSO63W.js';
 import { SLACK_CHECKS } from './chunk-MJOHK2NI.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pome-sh/checks",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",