@rubytech/create-realagent-code 0.1.615 → 0.1.616

package/payload/premium-plugins/real-agent/plugins/loop/mcp/src/__tests__/read-fidelity.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Read fidelity and API version provenance (Task 2792).
+ *
+ * Two defects these tests pin:
+ *
+ *   1. A prose formatter guards on truthiness, so a value of 0, false, "" or
+ *      "None" renders identically to a field nobody entered. A pre-flight that
+ *      must chase a missing service charge cannot be built on that.
+ *   2. Nothing named the API version, so a capability audit recorded "we are on
+ *      v1" against a client that has always been v2.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LOOP_API_VERSION, formatAggregationResult, formatSingleTeamRead } from '../lib/loop-api.js';
+import type { AggregationResult } from '../lib/loop-api.js';
+import { LOOP_SCHEMA_KEYS } from '../lib/loop-schema-keys.js';
+import {
+  censusRecords,
+  falsyPresentKeys,
+  matchPathPattern,
+  normalisePath,
+  wireKeys,
+} from '../lib/field-census.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function emptyResult<T>(over: Partial<AggregationResult<T>> = {}): AggregationResult<T> {
+  return { results: [], failures: [], skipped: [], totalTeams: 0, ...over };
+}
+
+describe('API version provenance', () => {
+  it('matches the vendored swagger snapshot', () => {
+    const snapshot = JSON.parse(
+      readFileSync(resolve(__dirname, 'loop-swagger.snapshot.json'), 'utf-8'),
+    ) as { info: { title: string } };
+    // "Loop API V2 Documentation" -> v2
+    const fromSnapshot = /\bV(\d+)\b/.exec(snapshot.info.title);
+    expect(fromSnapshot, 'snapshot info.title carries no version token').not.toBeNull();
+    expect(LOOP_API_VERSION).toBe(`v${fromSnapshot![1]}`);
+  });
+
+  it('names the version on the no-teams branch', () => {
+    const out = formatAggregationResult(emptyResult(), () => '', 'properties');
+    expect(out).toContain(LOOP_API_VERSION);
+  });
+
+  it('names the version on the all-failed branch', () => {
+    const out = formatAggregationResult(
+      emptyResult({ totalTeams: 1, failures: [{ teamName: 'A', reason: 'boom', kind: 'other' }] }),
+      () => '',
+      'properties',
+    );
+    expect(out).toContain(LOOP_API_VERSION);
+  });
+
+  it('names the version on the no-results branch', () => {
+    const out = formatAggregationResult(
+      emptyResult({ totalTeams: 1, results: [{ teamName: 'A', data: [] }] }),
+      () => '',
+      'properties',
+    );
+    expect(out).toContain(LOOP_API_VERSION);
+  });
+
+  it('names the version on the records branch', () => {
+    const out = formatAggregationResult(
+      emptyResult({ totalTeams: 1, results: [{ teamName: 'A', data: [{ id: 1 }] }] }),
+      (r: { id: number }) => `- ${r.id}`,
+      'properties',
+    );
+    expect(out).toContain(LOOP_API_VERSION);
+  });
+});
+
+describe('generated schema key map', () => {
+  const MAP_PATH = resolve(__dirname, '../lib/loop-schema-keys.ts');
+  const GENERATOR = resolve(__dirname, '../../scripts/generate-loop-schema-keys.mjs');
+
+  it('is byte-identical to what the generator produces from the current snapshot', () => {
+    // Written to a temp path, never over the committed map: a check that
+    // destroys the file it is checking cannot report what it found.
+    const tmp = join(tmpdir(), `loop-schema-keys-${process.pid}.ts`);
+    try {
+      execFileSync('node', [GENERATOR], {
+        stdio: 'pipe',
+        env: { ...process.env, LOOP_SCHEMA_KEYS_OUT: tmp },
+      });
+      expect(readFileSync(tmp, 'utf-8')).toBe(readFileSync(MAP_PATH, 'utf-8'));
+    } finally {
+      rmSync(tmp, { force: true });
+    }
+  });
+
+  it('carries the property detail path with the fields the audit called absent', () => {
+    const keys = LOOP_SCHEMA_KEYS['/property/residential/sales/{id}'];
+    expect(keys, 'sales property detail path missing from map').toBeDefined();
+    for (const field of ['tenure', 'serviceCharge', 'groundRent', 'saleBy', 'amlVerified']) {
+      expect(keys).toContain(field);
+    }
+  });
+
+  it('stays small enough for the runtime to import', () => {
+    // The runtime imports this module on every read; the 711KB snapshot it
+    // derives from is a test fixture and must never be what gets parsed.
+    // (Whether the bundle also copies __tests__ into the payload is Task 2795
+    // and does not bear on this.)
+    expect(statSync(MAP_PATH).size).toBeLessThan(100_000);
+  });
+});
+
+describe('raw mode', () => {
+  const result = {
+    results: [{ teamName: 'A', data: [{ id: 1, serviceCharge: 0, undeclaredByAnyInterface: 'x' }] }],
+    failures: [],
+    skipped: [],
+    totalTeams: 1,
+  };
+
+  it('emits keys the prose formatter drops', () => {
+    const out = formatAggregationResult(result, () => '- prose only', 'properties', { raw: true });
+    expect(out).toContain('serviceCharge');
+    expect(out).toContain('0');
+  });
+
+  it('emits a key no interface declares', () => {
+    // Raw serialises the wire payload, not the TypeScript interface.
+    const out = formatAggregationResult(result, () => '- prose only', 'properties', { raw: true });
+    expect(out).toContain('undeclaredByAnyInterface');
+  });
+
+  it('leaves default output as prose', () => {
+    const out = formatAggregationResult(result, () => '- prose only', 'properties');
+    expect(out).toContain('- prose only');
+    expect(out).not.toContain('undeclaredByAnyInterface');
+  });
+
+  it('still names the version in raw mode', () => {
+    const out = formatAggregationResult(result, () => '- prose only', 'properties', { raw: true });
+    expect(out).toContain(LOOP_API_VERSION);
+  });
+});
+
+describe('every Loop read names its API version', () => {
+  // The coverage set is "tools that read from Loop", not "tools routed through
+  // formatAggregationResult". Defining it the second way is what left four
+  // reads behind: the withTeamKey tools format their own output and named no
+  // version at all, and a test enumerating only the twelve stayed green over
+  // the gap.
+  const SINGLE_TEAM_READS = [
+    { tool: 'loop-feedback-get', source: 'tools/feedback.ts' },
+    { tool: 'loop-auto-responder', source: 'tools/auto-responder.ts' },
+    { tool: 'loop-supplier', source: 'tools/supplier.ts' },
+    { tool: 'loop-customer-preferences', source: 'tools/customer-preferences.ts' },
+  ];
+
+  it.each(SINGLE_TEAM_READS)('$tool stamps the version on its read output', ({ source }) => {
+    const src = readFileSync(resolve(__dirname, '..', source), 'utf-8');
+    expect(src, `${source} returns un-versioned output`).toContain('formatSingleTeamRead(');
+  });
+
+  it('leaves no read returning bare JSON.stringify output', () => {
+    for (const { source } of SINGLE_TEAM_READS) {
+      const src = readFileSync(resolve(__dirname, '..', source), 'utf-8');
+      expect(src, `${source} still returns an unstamped payload`).not.toMatch(
+        /return JSON\.stringify\(result, null, 2\);/,
+      );
+    }
+  });
+
+  it('stamps the version in both raw and prose form', () => {
+    expect(formatSingleTeamRead({ a: 0 }, 'prose')).toContain(LOOP_API_VERSION);
+    expect(formatSingleTeamRead({ a: 0 }, 'prose', { raw: true })).toContain(LOOP_API_VERSION);
+  });
+
+  it('shows a zero in raw form that the prose dropped', () => {
+    const raw = formatSingleTeamRead({ rating: 0 }, 'no rating given', { raw: true });
+    expect(raw).toContain('rating');
+    expect(raw).toContain('0');
+  });
+});
+
+describe('raw parameter coverage', () => {
+  // Every read routed through formatAggregationResult must offer the mode.
+  // A read that cannot return its raw field set is a read the pre-flight
+  // cannot trust, and the gap would be silent without this.
+  const READ_TOOLS = [
+    'loop-feedback-get',
+    'loop-property-detail',
+    'loop-property-search',
+    'loop-property-listed',
+    'loop-property-sold',
+    'loop-people-detail',
+    'loop-people-search',
+    'loop-viewing-detail',
+    'loop-viewing-search',
+    'loop-marketing-match',
+    'loop-marketing-match-batch',
+    'loop-team-info',
+    'loop-team-availability',
+  ];
+
+  it.each(READ_TOOLS)('%s declares the raw parameter', (tool) => {
+    const src = readFileSync(resolve(__dirname, '../index.ts'), 'utf-8');
+    const start = src.indexOf(`"${tool}"`);
+    expect(start, `${tool} not registered`).toBeGreaterThan(-1);
+    // Bound on this tool's own registration, not a character count: a fixed
+    // window spills into the next lifelineTool call and a missing declaration
+    // reads as present because its neighbour has one.
+    const next = src.indexOf('lifelineTool(server,', start);
+    const block = src.slice(start, next === -1 ? src.length : next);
+    expect(block, `${tool} has no raw parameter`).toContain('raw: z.boolean().optional()');
+  });
+});
+
+describe('property detail field fidelity', () => {
+  // The renderer is a closure inside propertyDetail, so the guards are
+  // asserted at their source. They are the defect.
+  const SRC_PATH = resolve(__dirname, '../tools/property-detail.ts');
+
+  it('does not gate the money fields on truthiness', () => {
+    const src = readFileSync(SRC_PATH, 'utf-8');
+    expect(src, 'serviceCharge still behind a truthiness guard').not.toContain(
+      'if (p.serviceCharge)',
+    );
+    expect(src, 'groundRent still behind a truthiness guard').not.toContain('if (p.groundRent)');
+    expect(src, 'tenure still dropped when None').not.toContain('p.tenure !== "None"');
+  });
+
+  it('declares and renders the two fields the audit called unavailable', () => {
+    const src = readFileSync(SRC_PATH, 'utf-8');
+    expect(src, 'sale method not declared').toContain('saleBy');
+    expect(src, 'money-laundering check status not declared').toContain('amlVerified');
+  });
+});
+
+describe('field census primitives', () => {
+  it('strips the query string before matching', () => {
+    expect(normalisePath('/property/residential/sales?MinPrice=1')).toBe(
+      '/property/residential/sales',
+    );
+  });
+
+  it('matches a live id-bearing path to its swagger pattern', () => {
+    const patterns = ['/property/residential/sales/{id}', '/property/residential/sales'];
+    expect(matchPathPattern('/property/residential/sales/4821', patterns)).toBe(
+      '/property/residential/sales/{id}',
+    );
+  });
+
+  it('prefers the literal pattern over the templated one', () => {
+    const patterns = ['/property/residential/sales/{id}', '/property/residential/sales'];
+    expect(matchPathPattern('/property/residential/sales', patterns)).toBe(
+      '/property/residential/sales',
+    );
+  });
+
+  it('matches a searched list path carrying a query string', () => {
+    const patterns = ['/property/residential/sales/{id}', '/property/residential/sales'];
+    expect(matchPathPattern('/property/residential/sales?SearchTerm=oak', patterns)).toBe(
+      '/property/residential/sales',
+    );
+  });
+
+  it('returns null for a path no pattern covers', () => {
+    expect(matchPathPattern('/nope/at/all', ['/property/residential/sales'])).toBeNull();
+  });
+
+  it('names every falsy-but-present key and no absent one', () => {
+    const rec = {
+      serviceCharge: 0,
+      groundRent: 0,
+      tenure: 'None',
+      alarm: false,
+      features: [],
+      price: 250000,
+    };
+    const found = falsyPresentKeys(rec);
+    expect(found).toEqual(['alarm', 'features', 'groundRent', 'serviceCharge', 'tenure']);
+    expect(found).not.toContain('price');
+    expect(found).not.toContain('saleBy');
+  });
+
+  it('treats null as absent, not falsy-present', () => {
+    // Loop saying nothing is a different fact from Loop saying zero.
+    expect(falsyPresentKeys({ serviceCharge: null })).toEqual([]);
+  });
+
+  it('unions keys across records', () => {
+    expect(wireKeys([{ a: 1 }, { b: 2 }])).toEqual(['a', 'b']);
+  });
+
+  it('normalises a single object, an array, and a non-object payload', () => {
+    expect(censusRecords({ a: 1 })).toEqual([{ a: 1 }]);
+    expect(censusRecords([{ a: 1 }])).toEqual([{ a: 1 }]);
+    expect(censusRecords('nope')).toEqual([]);
+    expect(censusRecords(null)).toEqual([]);
+  });
+});

package/payload/premium-plugins/real-agent/plugins/loop/mcp/src/__tests__/swagger-write-coverage.test.ts

@@ -5,7 +5,7 @@
  *
  *   1. Loop adds a new POST/PUT/PATCH/DELETE → no mapping → test fails
  *      and names the orphan endpoint.
- *   2. A tool's `server.tool("…")` registration is renamed or removed →
+ *   2. A tool's `lifelineTool(server, "…")` registration is renamed or removed →
  *      the name lookup against `index.ts` source fails.
  *   3. A tool's source file is refactored such that the swagger path
  *      family no longer appears literally → the path-fragment lookup
@@ -120,15 +120,15 @@ describe('Loop swagger write coverage', () => {
   });
 
   // 2. Every mapping's tool is registered in index.ts (catches deregistration).
-  //    Match by quoted tool name in proximity to a `server.tool(` call —
-  //    each registration is `server.tool(\n  "<name>", ...)` or single-line.
+  //    Match by quoted tool name in proximity to a `lifelineTool(` call —
+  //    each registration is `lifelineTool(server,\n  "<name>", ...)` or single-line.
   //    A tool name that appears only in a comment or unrelated string doesn't
   //    match because we require it to be the first non-whitespace argument
-  //    of a server.tool( invocation within ~32 chars.
+  //    of a lifelineTool( invocation within ~32 chars.
   it.each(ENDPOINT_MAP)('$method $path → tool $tool registered in index.ts', ({ tool }) => {
-    const registrationRe = new RegExp(`server\\.tool\\(\\s*"${tool.replace(/[.*+?^${}()|[\\\]\\\\]/g, '\\\\$&')}"`);
+    const registrationRe = new RegExp(`lifelineTool\\(\\s*server\\s*,\\s*"${tool.replace(/[.*+?^${}()|[\\\]\\\\]/g, '\\\\$&')}"`);
     const isRegistered = registrationRe.test(indexSrc);
-    expect(isRegistered, `tool "${tool}" not registered as server.tool("${tool}", ...) in src/index.ts`).toBe(true);
+    expect(isRegistered, `tool "${tool}" not registered as lifelineTool(server, "${tool}", ...) in src/index.ts`).toBe(true);
   });
 
   // 3. Every mapping's path fragment appears in the named source file

package/payload/premium-plugins/real-agent/plugins/loop/mcp/src/index.ts

@@ -149,6 +149,7 @@ lifelineTool(server,
     endDate: z.string().optional().describe("End date filter (sellers/landlords)"),
     teamName: z.string().optional().describe("Query a specific team only"),
     limit: z.number().int().optional().describe("Max results (default 200)"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => peopleSearch(p as Parameters<typeof peopleSearch>[0]))
 );
@@ -160,6 +161,7 @@ lifelineTool(server,
     personId: z.number().int().describe("Person ID"),
     role: z.enum(["buyers", "sellers", "renters", "landlords"]).optional().describe("Role for role-specific detail view"),
     teamName: z.string().optional().describe("Query a specific team only"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => peopleDetail(p as Parameters<typeof peopleDetail>[0]))
 );
@@ -182,6 +184,7 @@ lifelineTool(server,
     propertyTypes: z.string().optional().describe("Comma-separated property types"),
     teamName: z.string().optional().describe("Query a specific team only"),
     limit: z.number().int().optional().describe("Max results (default 200)"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => propertySearch(p as Parameters<typeof propertySearch>[0]))
 );
@@ -194,6 +197,7 @@ lifelineTool(server,
     department: z.enum(["sales", "lettings"]).describe("sales or lettings"),
     previewHash: z.number().int().optional().describe("Preview hash for public preview URL"),
     teamName: z.string().optional().describe("Query a specific team only"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => propertyDetail(p as Parameters<typeof propertyDetail>[0]))
 );
@@ -206,6 +210,7 @@ lifelineTool(server,
     department: z.enum(["sales", "lettings", "both"]).optional().describe("Department (default: both)"),
     teamName: z.string().optional().describe("Query a specific team only"),
     limit: z.number().int().optional().describe("Max results (default 200)"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => propertyListed(p as Parameters<typeof propertyListed>[0]))
 );
@@ -217,6 +222,7 @@ lifelineTool(server,
     channel: z.enum(["rightmove", "onTheMarket", "zoopla", "website"]).describe("Listing channel"),
     teamName: z.string().optional().describe("Query a specific team only"),
     limit: z.number().int().optional().describe("Max results (default 200)"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => propertySold(p as Parameters<typeof propertySold>[0]))
 );
@@ -285,6 +291,7 @@ lifelineTool(server,
     status: z.string().optional().describe("Viewing status filter"),
     teamName: z.string().optional().describe("Query a specific team only"),
     limit: z.number().int().optional().describe("Max results (default 200)"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => viewingSearch(p as Parameters<typeof viewingSearch>[0]))
 );
@@ -296,6 +303,7 @@ lifelineTool(server,
     viewingId: z.number().int().describe("Viewing ID"),
     department: z.enum(["sales", "lettings"]).describe("sales or lettings"),
     teamName: z.string().optional().describe("Query a specific team only"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => viewingDetail(p as Parameters<typeof viewingDetail>[0]))
 );
@@ -341,6 +349,7 @@ lifelineTool(server,
     teamName: z.string().min(1).describe("Team that owns the viewing"),
     viewingId: z.number().int().describe("Viewing ID"),
     department: z.enum(["sales", "lettings"]).describe("sales or lettings"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => feedbackGet(p as Parameters<typeof feedbackGet>[0]))
 );
@@ -366,6 +375,7 @@ lifelineTool(server,
   "Get team details from Loop CRM. Returns team name, address, phone, and email.",
   {
     teamName: z.string().optional().describe("Query a specific team only (omit for all teams)"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => teamInfo(p as Parameters<typeof teamInfo>[0]))
 );
@@ -377,6 +387,7 @@ lifelineTool(server,
     agentId: z.string().describe("Agent GUID identifier"),
     searchDate: z.string().describe("Date to check availability (YYYY-MM-DD)"),
     teamName: z.string().optional().describe("Query a specific team only"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => teamAvailability(p as Parameters<typeof teamAvailability>[0]))
 );
@@ -393,6 +404,7 @@ lifelineTool(server,
     department: z.enum(["sales", "lettings"]).describe("sales or lettings"),
     includeTeamProfile: z.boolean().optional().describe("Include the team profile for this match (default: false)"),
     teamName: z.string().optional().describe("Query a specific team only"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => marketingMatchDetail(p as Parameters<typeof marketingMatchDetail>[0]))
 );
@@ -404,6 +416,7 @@ lifelineTool(server,
     propertyIds: z.array(z.number().int()).describe("Array of property IDs to match"),
     department: z.enum(["sales", "lettings"]).describe("sales or lettings"),
     teamName: z.string().optional().describe("Query a specific team only"),
+    raw: z.boolean().optional().describe("Return the raw field set received from Loop instead of prose. Use when a decision turns on whether a field was supplied at all: a key present carrying 0 is a zero, a key absent is one Loop did not send."),
   },
   toolHandler(async (p) => marketingMatchBatch(p as Parameters<typeof marketingMatchBatch>[0]))
 );

package/payload/premium-plugins/real-agent/plugins/loop/mcp/src/lib/field-census.ts

@@ -0,0 +1,86 @@
+// Per-request read fidelity signals.
+//
+// A truthiness guard in a formatter drops any value that is 0, false, "" or
+// "None", so a caller cannot tell a zero service charge from one nobody
+// entered. `falsyPresentKeys` names exactly that set, which is what makes the
+// loss visible without guessing what a formatter emitted.
+//
+// Guessing was the alternative and all three forms of it are worse. Tracking
+// key access with a proxy gives the wrong answer by construction, because
+// `if (p.serviceCharge)` reads the key and then discards it. Searching the
+// output string for each value is fragile, since 1250000 prints as £1,250,000.
+// Rewriting all twelve formatters around a shared emitter would be exact and
+// is far outside this change.
+
+export function normalisePath(path: string): string {
+  const q = path.indexOf("?");
+  return q === -1 ? path : path.slice(0, q);
+}
+
+function patternToRegExp(pattern: string): RegExp {
+  const escaped = pattern
+    .split("/")
+    .map((seg) =>
+      /^\{.+\}$/.test(seg) ? "[^/]+" : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    )
+    .join("/");
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Resolve a live request path to the swagger pattern that describes it.
+ * Literal patterns win over templated ones, so a concrete path never resolves
+ * to a templated sibling that also happens to match.
+ */
+export function matchPathPattern(path: string, patterns: string[]): string | null {
+  const live = normalisePath(path);
+  const exact = patterns.find((p) => p === live);
+  if (exact) return exact;
+  for (const p of patterns.filter((c) => c.includes("{"))) {
+    if (patternToRegExp(p).test(live)) return p;
+  }
+  return null;
+}
+
+/**
+ * Normalise a payload to the records the census walks. A Loop read returns
+ * either one object or an array of them; anything else carries no fields to
+ * census and yields nothing rather than a misleading zero-key record.
+ */
+export function censusRecords(payload: unknown): Record<string, unknown>[] {
+  if (Array.isArray(payload)) {
+    return payload.filter(
+      (r): r is Record<string, unknown> =>
+        r !== null && typeof r === "object" && !Array.isArray(r)
+    );
+  }
+  if (payload !== null && typeof payload === "object") {
+    return [payload as Record<string, unknown>];
+  }
+  return [];
+}
+
+export function wireKeys(payload: unknown): string[] {
+  const out = new Set<string>();
+  for (const r of censusRecords(payload)) {
+    for (const k of Object.keys(r)) out.add(k);
+  }
+  return [...out].sort();
+}
+
+/**
+ * A key is falsy-present when it arrived carrying a value every truthiness
+ * guard discards. `null` and `undefined` are NOT included: those are Loop
+ * saying nothing, which is a different fact from Loop saying zero, and
+ * collapsing the two would rebuild the defect this exists to expose.
+ */
+export function falsyPresentKeys(payload: unknown): string[] {
+  const out = new Set<string>();
+  for (const r of censusRecords(payload)) {
+    for (const [k, v] of Object.entries(r)) {
+      if (v === 0 || v === false || v === "" || v === "None") out.add(k);
+      else if (Array.isArray(v) && v.length === 0) out.add(k);
+    }
+  }
+  return [...out].sort();
+}