fix(snapshot): a null body stays a shape violation; service hooks are left out

A whole-section read answering a null 200 body kept reading as "nothing exists" and the section vanished from the document; the projection now leaves a rejected root value in place so the engine's validation names the body as outside the shape, and pages proves its body is a mapping first, since its nullable slice would otherwise read a null body as the declaration that disables the site. A legacy service hook (name other than "web") projected a name the schema refuses and failed the whole webhooks snapshot; it is now noted and left out, after the duplicate check that still counts it, because the planner matches a declared url against every live hook.

Author: settings-as-code-release

src/sections/pages/index.ts

@@ -3,8 +3,10 @@
  * declares Pages OFF (mirroring branches' `protection: null`).
  */
 
+import { z } from "zod";
 import { subsetDiff } from "../../engine/diff.js";
 import type { EndpointDecl } from "../contract/endpoints.js";
+import { parseLive } from "../contract/live.js";
 import { loosen, type SectionModule } from "../contract/module.js";
 import type { SectionPermission } from "../contract/permissions.js";
 import { hasDrift, type PlannedOp, plainData, type SectionPlan } from "../contract/plan.js";
@@ -154,6 +156,9 @@ export const pagesSection = {
     if ("missing" in probe) {
       return { value: undefined, notes: [] };
     }
-    return { value: projectOntoSchema(PagesConfig, probe.data), notes: [] };
+    // A site body must be a mapping: PagesConfig accepts null (the declared "Pages off"), so a
+    // null 200 would otherwise read back as a declaration that DISABLES the site.
+    const site = parseLive(this, ENDPOINTS.get, z.looseObject({}), probe.data);
+    return { value: projectOntoSchema(PagesConfig, site), notes: [] };
   },
 } satisfies SectionModule<"pages", typeof ENDPOINTS>;

src/sections/shared/snapshot-helpers.ts

@@ -43,17 +43,17 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 }
 
 /**
- * A live value projected onto a schema slice: an object keeps exactly the keys the slice's shape
- * names (a loose object keeps its passthrough keys too), each child projected in turn; a list
- * projects its items; a union projects through its first option accepting the value.
- * A `null` the slice cannot hold is GitHub's "no value" (a not-configured setup's null
- * runner_type), so the key is omitted rather than emitted as an invalid declaration; every other
- * value the slice rejects is left in place for the document validation to name.
- * A passthrough slice (a catchall other than never) keeps every live key by design, so server
- * fields cannot fall away there: a section on such a slice names the keys it reads back itself.
- * The one cast is the boundary: the engine validates the assembled document before returning it.
+ * A live value projected onto a schema slice, so server-assigned fields fall away without a hand
+ * list per section. A nested `null` the slice cannot hold is GitHub's "no value" (a not-configured
+ * setup's runner_type) and its key is omitted; a value the slice rejects at the root stays, so the
+ * engine's validation names a body outside the shape instead of the section vanishing. A
+ * passthrough slice (a catchall other than never) keeps every live key by design, so a section on
+ * one names the keys it reads back itself. The casts are the boundary the engine validates behind.
  */
 export function projectOntoSchema<T>(schema: z.ZodType<T>, live: unknown): T {
+  if (live === null && !schema.safeParse(null).success) {
+    return live as T;
+  }
   return project(schema, live) as T;
 }
 

src/sections/webhooks/index.ts

@@ -317,12 +317,13 @@ export const webhooksSection = {
     return plan;
   },
   // A live hook reports a set secret as "********": the entry carries a `$WEBHOOK_SECRET_<id>`
-  // reference in its place, and a note asks for the value. A hook without a config.url has no
-  // identity this section can declare, so it is noted and left out.
+  // reference in its place, and a note asks for the value. A legacy service hook (name other
+  // than "web") and a hook without a config.url are outside what this section manages, so each is
+  // noted and left out.
   async snapshot(ctx) {
     const live = parseLive(this, ENDPOINTS.list, z.array(LiveHook), await ctx.read.list.listAll());
     const notes: string[] = [];
-    const addressable = live.filter((hook) => {
+    const withUrl = live.filter((hook) => {
       if (typeof hook.config?.url === "string" && hook.config.url !== "") {
         return true;
       }
@@ -331,13 +332,24 @@ export const webhooksSection = {
       );
       return false;
     });
+    // Over every url-bearing hook, service hooks included: the planner matches a declared url
+    // against ALL live hooks, so a web hook sharing a url with a service hook cannot converge.
     rejectLiveDuplicates(
       this,
       "webhook",
-      addressable,
+      withUrl,
       (hook) => String(hook.config?.url),
       (hook) => `${String(hook.config?.url)} (id ${hook.id})`,
     );
+    const addressable = withUrl.filter((hook) => {
+      if (hook.name === undefined || hook.name === "web") {
+        return true;
+      }
+      notes.push(
+        `webhooks[${describeHook(hook)}]: a "${hook.name}" service hook is not a web hook this section manages, so it is left out of the snapshot`,
+      );
+      return false;
+    });
     if (addressable.length === 0) {
       return { value: undefined, notes };
     }

test/engine/snapshot.test.ts

@@ -275,6 +275,66 @@ describe("snapshotRepository", () => {
   });
 });
 
+describe("snapshotRepository shape guard", () => {
+  test("a null 200 body on a whole-section read fails the section as a body outside the shape, never an omitted section", async () => {
+    const fake = registryFake(LIVE);
+    const nulling: GithubClient = {
+      tryRequest: (method, path, payload, options) =>
+        method === "GET" && path === "/repos/o/r/code-scanning/default-setup"
+          ? Promise.resolve({ data: null })
+          : fake.tryRequest(method, path, payload, options),
+      tryGraphql: (op, variables, slug) => fake.tryGraphql(op, variables, slug),
+    };
+    const result = await snapshotRepository(
+      nulling,
+      { ...opts(), onlySections: new Set(["code_scanning_default_setup", "labels"]) },
+      captureIo().io,
+    );
+    expect(result.result).toBe("failed");
+    expect(result.settings).toBeUndefined();
+    expect(result.outcomes.map((o) => [o.key, o.status])).toEqual([
+      ["labels", "snapshot"],
+      ["code_scanning_default_setup", "failed"],
+    ]);
+    expect(result.outcomes[1]?.detail).toEqual([
+      expect.stringMatching(
+        /^BUG: code_scanning_default_setup produced a snapshot its own schema rejects - .*code_scanning_default_setup: Invalid input: expected object, received null/,
+      ),
+    ]);
+  });
+});
+
+describe("pages null body", () => {
+  test("a null 200 on the Pages GET fails the section as a body outside the shape, never `pages: null`", async () => {
+    const fake = registryFake(LIVE);
+    const nulling: GithubClient = {
+      tryRequest: (method, path, payload, options) =>
+        method === "GET" && path === "/repos/o/r/pages"
+          ? Promise.resolve({ data: null })
+          : fake.tryRequest(method, path, payload, options),
+      tryGraphql: (op, variables, slug) => fake.tryGraphql(op, variables, slug),
+    };
+    const result = await snapshotRepository(
+      nulling,
+      { ...opts(), onlySections: new Set(["pages"]) },
+      captureIo().io,
+    );
+    expect(result.result).toBe("partial");
+    expect(Object.keys(result.settings ?? {})).toEqual([]);
+    expect(result.outcomes).toEqual([
+      {
+        key: "pages",
+        status: "failed",
+        detail: [
+          expect.stringMatching(
+            /^pages: GET \/repos\/\{owner\}\/\{repo\}\/pages returned a body outside the documented shape - \(body\): Invalid input: expected object, received null/,
+          ),
+        ],
+      },
+    ]);
+  });
+});
+
 describe("renderSnapshotYaml", () => {
   test("a message spanning several lines is commented line by line, so the file still parses", async () => {
     const stubbed = spyOn(labelsSection, "snapshot").mockRejectedValue(

test/sections/snapshot-roundtrip.test.ts

@@ -105,6 +105,16 @@ describe("snapshot round trip", () => {
         { id: 2, config: { url: "https://ci.example.com/hook" }, events: ["release"] },
       ],
     });
+    // A service hook on the same url counts too: the planner matches against every live hook.
+    const mixed = registryFake({
+      hooks: [
+        { id: 1, config: { url: "https://ci.example.com/hook" } },
+        { id: 2, name: "slack", config: { url: "https://ci.example.com/hook" } },
+      ],
+    });
+    await expect(
+      webhooksSection.snapshot(planContext(webhooksSection, mixed, REPO)),
+    ).rejects.toThrow(/webhooks: GitHub holds webhooks that resolve to one identity/);
     await expect(
       webhooksSection.snapshot(planContext(webhooksSection, hooks, REPO)),
     ).rejects.toThrow(

test/sections/snapshot-rows/webhooks.ts

@@ -16,6 +16,7 @@ export const row: Row = {
         },
       },
       { id: 602, active: false, config: { url: "https://deploy.example.com/hook" } },
+      { id: 603, name: "slack", config: { url: "https://hooks.slack.example/T0/B0" } },
     ],
   },
   expected: {
@@ -42,6 +43,7 @@ export const row: Row = {
       ],
     },
     notes: [
+      'webhooks["https://hooks.slack.example/T0/B0"]: a "slack" service hook is not a web hook this section manages, so it is left out of the snapshot',
       'webhooks["https://ci.example.com/hook"].config.secret: the webhook secret is not readable; export a value as WEBHOOK_SECRET_601 into the environment before apply',
     ],
   },