carrick 0.3.82 → 0.3.83

package/sidecar/dist/src/capture/check-fields.js

@@ -0,0 +1,259 @@
+/**
+ * Field-level report for a pair the judge called incompatible
+ * (carrick-tools/carrick-cloud#1118).
+ *
+ * `tsc` decides. Its elaboration names ONE field and then elides the rest
+ * ("Type 'A' is not assignable to type 'B'. Property 'x' is missing"), which is
+ * not enough for a reader deciding what to change: a create endpoint that
+ * requires `username` while the client sends `userName` reads as one missing
+ * property with no hint that the sent object carries a near-neighbour.
+ *
+ * This walk enumerates the differing fields of the SAME two types the judge
+ * compared, in the SAME program, using the compiler's own assignability
+ * relation. It is not a second judge:
+ *   - it runs only after the bucket is decided and never changes one;
+ *   - it never contradicts: a difference is only named when the checker itself
+ *     says the two member types do not assign, and when it finds nothing it
+ *     adds nothing and the raw tsc text stands alone;
+ *   - it refuses the shapes where a member list is not an account of the type
+ *     (a union root, a receiver with an index signature), rather than guessing
+ *     about them.
+ *
+ * It reports one thing the judge structurally cannot: an optionality gap in the
+ * direction that still assigns (the sending side always provides a field the
+ * receiving side declares optional). That is a real drift between two sources
+ * — the receiver carries a branch that never runs — and no assignment error can
+ * exist for it. It is stated as an observation beside the verdict, never as the
+ * verdict.
+ *
+ * Seam: node builtins + `typescript` + this bundle only.
+ */
+import ts from 'typescript';
+/**
+ * Cap on named fields. A mismatch with more differing members than this is
+ * better described as two unrelated shapes than as a list, and the text says
+ * how many more there are rather than pretending the list is complete.
+ */
+export const MAX_NAMED_FIELDS = 8;
+/** Printed member types are for reading, not for re-parsing. */
+const MAX_TYPE_TEXT = 80;
+/** Depth cap on the structural descent. Deeper differences are reported at the
+ * deepest ancestor the walk reached, never dropped. */
+const MAX_FIELD_DEPTH = 4;
+function assignabilityOf(checker) {
+    const fn = checker.isTypeAssignableTo;
+    return typeof fn === 'function' ? fn.bind(checker) : undefined;
+}
+/**
+ * Field reports for every plan whose probe the program could read, keyed by
+ * pair id. A plan with no entry has no report, which is not a claim that its
+ * types agree.
+ */
+export function pairFieldReports(opened, plans) {
+    const results = new Map();
+    if (!opened)
+        return results;
+    const { program, checker, probesDir } = opened;
+    const isAssignableTo = assignabilityOf(checker);
+    if (!isAssignableTo)
+        return results;
+    for (const plan of plans) {
+        const file = program.getSourceFile(`${probesDir}/probes/${plan.fileName}`.split('\\').join('/'));
+        const source = file ??
+            program
+                .getSourceFiles()
+                .find((sf) => sf.fileName.endsWith(`/probes/${plan.fileName}`));
+        if (!source)
+            continue;
+        // Whatever the judge's decisive assignment actually sent: the GraphQL
+        // comparand where one exists, then the JSON wire form where one exists.
+        // Reading `sent` there instead would describe a type the judge did not
+        // compare, which is the one way this walk could contradict it.
+        const declared = declaredConstType(source, checker, 'sentComparand') ??
+            declaredConstType(source, checker, 'sent');
+        const expected = declaredConstType(source, checker, 'expected');
+        if (!declared || !expected)
+            continue;
+        const wire = declaredConstType(source, checker, 'sentWire');
+        const compared = wire ?? declared;
+        const report = diffReport(compared.type, expected.type, checker, isAssignableTo, expected.node);
+        report.wireApplied =
+            wire !== undefined &&
+                !(isAssignableTo(wire.type, declared.type) && isAssignableTo(declared.type, wire.type));
+        results.set(plan.pairId, report);
+    }
+    return results;
+}
+/** The type of one of the probe's declared consts, read where it is declared. */
+function declaredConstType(file, checker, name) {
+    for (const statement of file.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name)
+                continue;
+            const type = checker.getTypeAtLocation(declaration.name);
+            if (!type)
+                return undefined;
+            return { type, node: declaration.name };
+        }
+    }
+    return undefined;
+}
+function diffReport(sent, expected, checker, isAssignableTo, at) {
+    const found = [];
+    walk(sent, expected, '', 0, { checker, isAssignableTo, at, found });
+    found.sort((a, b) => a.path === b.path ? compareText(a.nature, b.nature) : compareText(a.path, b.path));
+    return {
+        differences: found.slice(0, MAX_NAMED_FIELDS),
+        truncated: Math.max(0, found.length - MAX_NAMED_FIELDS),
+        wireApplied: false,
+    };
+}
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * A shape whose members can be compared one by one without diverging from the
+ * whole-type relation.
+ *
+ * The object flag is the first and widest of these: a union or an intersection
+ * does not carry it, and neither does a primitive, so a root the judge compared
+ * as a whole is never taken apart into members one of its constituents happens
+ * to share.
+ *
+ * An index signature is excluded because it makes the member list an incomplete
+ * account of the type: a field the sender provides that the receiver's index
+ * signature accepts is not a field the receiver "declares no such field" for,
+ * and saying so would be false. Arrays and tuples carry a numeric one, so the
+ * same clause keeps `length` and `push` out of a field list; an element
+ * difference is reported at the field that holds the array.
+ */
+function isComparableObject(type, checker) {
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) {
+        return false;
+    }
+    if ((type.flags & ts.TypeFlags.Object) === 0)
+        return false;
+    if (checker.getIndexInfosOfType(type).length > 0)
+        return false;
+    return true;
+}
+function walk(sent, expected, path, depth, ctx) {
+    const { checker } = ctx;
+    if (!isComparableObject(sent, checker) || !isComparableObject(expected, checker)) {
+        return;
+    }
+    const sentProps = new Map(sent.getProperties().map((p) => [p.getName(), p]));
+    const expectedProps = new Map(expected.getProperties().map((p) => [p.getName(), p]));
+    /** Members the receiver declares and the sender has no member for, optional
+     * ones included. Only the REQUIRED ones are a difference; the rest still
+     * count here, because a receiver waiting on a member it never gets is what
+     * makes a sender-only member worth naming beside it. */
+    let absent = 0;
+    for (const [name, expectedProp] of expectedProps) {
+        const at = join(path, name);
+        const sentProp = sentProps.get(name);
+        if (!sentProp) {
+            absent += 1;
+            // An optional member the sender omits is what optional MEANS. Naming it
+            // would state that the receiver requires it, which is false, and it is
+            // not what the judge rejected the pair for.
+            if (!isOptional(expectedProp)) {
+                ctx.found.push({ path: at, nature: 'missing_in_sent' });
+            }
+            continue;
+        }
+        const sentOptional = isOptional(sentProp);
+        const expectedOptional = isOptional(expectedProp);
+        if (sentOptional && !expectedOptional) {
+            ctx.found.push({ path: at, nature: 'optional_in_sent' });
+        }
+        else if (!sentOptional && expectedOptional) {
+            // No assignment error exists for this direction, which is exactly why
+            // the judge cannot report it and this walk must.
+            ctx.found.push({ path: at, nature: 'optional_in_expected' });
+        }
+        const sentType = memberType(sentProp, ctx);
+        const expectedType = memberType(expectedProp, ctx);
+        if (ctx.isAssignableTo(sentType, expectedType))
+            continue;
+        const sentInner = checker.getNonNullableType(sentType);
+        const expectedInner = checker.getNonNullableType(expectedType);
+        if (depth + 1 < MAX_FIELD_DEPTH &&
+            isComparableObject(sentInner, checker) &&
+            isComparableObject(expectedInner, checker)) {
+            walk(sentInner, expectedInner, at, depth + 1, ctx);
+            continue;
+        }
+        ctx.found.push({
+            path: at,
+            nature: 'type_differs',
+            sentText: printType(sentType, ctx),
+            expectedText: printType(expectedType, ctx),
+        });
+    }
+    // A field the sender provides that the receiver does not declare is normal
+    // (a response carrying more than a call site reads), so it is only worth
+    // naming beside a member the receiver is waiting on and does not get: that
+    // pairing is what a renamed or relocated field looks like from the outside.
+    // On the common subset case — a call site reading fewer fields than the
+    // producer returns — nothing is absent and nothing is named.
+    if (absent === 0)
+        return;
+    for (const [name] of sentProps) {
+        if (expectedProps.has(name))
+            continue;
+        ctx.found.push({ path: join(path, name), nature: 'extra_in_sent' });
+    }
+}
+function join(path, name) {
+    return path === '' ? name : `${path}.${name}`;
+}
+function isOptional(symbol) {
+    return (symbol.flags & ts.SymbolFlags.Optional) !== 0;
+}
+function memberType(symbol, ctx) {
+    return ctx.checker.getTypeOfSymbolAtLocation(symbol, ctx.at);
+}
+function printType(type, ctx) {
+    const text = ctx.checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias);
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > MAX_TYPE_TEXT ? `${flat.slice(0, MAX_TYPE_TEXT - 1)}…` : flat;
+}
+/**
+ * The sentence appended to a mismatch diagnostic. Names the two sides as
+ * producer and consumer (never the probe's internal sent/expected), so the
+ * reader knows which repo to change.
+ */
+export function describeFieldReport(report, sentSide, expectedSide) {
+    const parts = [];
+    if (report.wireApplied) {
+        parts.push(`The ${sentSide}'s type is compared in the form JSON puts on the wire: a value with a toJSON() method (a Date, for example) travels as what it serialises to.`);
+    }
+    if (report.differences.length > 0) {
+        const named = report.differences
+            .map((d) => describeDifference(d, sentSide, expectedSide))
+            .join('; ');
+        const more = report.truncated > 0
+            ? `; and ${report.truncated} further field${report.truncated === 1 ? '' : 's'} differ${report.truncated === 1 ? 's' : ''} (${MAX_NAMED_FIELDS} named here)`
+            : '';
+        parts.push(`Fields that differ: ${named}${more}.`);
+    }
+    return parts.length === 0 ? '' : ` ${parts.join(' ')}`;
+}
+function describeDifference(difference, sentSide, expectedSide) {
+    const at = `'${difference.path}'`;
+    switch (difference.nature) {
+        case 'missing_in_sent':
+            return `${at} is required by the ${expectedSide} and the ${sentSide} does not send it`;
+        case 'extra_in_sent':
+            return `${at} is sent by the ${sentSide} and the ${expectedSide} declares no such field`;
+        case 'optional_in_sent':
+            return `${at} is optional on the ${sentSide} and required by the ${expectedSide}`;
+        case 'optional_in_expected':
+            return `${at} is always sent by the ${sentSide} and optional on the ${expectedSide}`;
+        case 'type_differs':
+            return `${at} is ${difference.sentText} on the ${sentSide} and ${difference.expectedText} on the ${expectedSide}`;
+    }
+}

package/sidecar/dist/src/capture/check-probe.d.ts

@@ -7,6 +7,12 @@
  * conditional-type relation diverges around `any`, and because the compiler's
  * elaborated assignment error is the user-facing mismatch report.
  *
+ * An `http` pair carries a SECOND assignment of the same value in the form JSON
+ * puts on the wire, and that one decides the bucket (see `wireAssignmentLine`):
+ * a payload is serialised before it travels, so the declared types are not what
+ * meet each other. Both questions go to the same judge; nothing here decides a
+ * verdict.
+ *
  * GraphQL pairs additionally unwrap the producer's resolver-return ENVELOPE
  * before the assignment (see the `graphql` branch in `buildProbe`): a GraphQL
  * producer's captured type is the resolver function's return type with
@@ -59,9 +65,23 @@ export interface ProbePlan {
     importLines: number[];
     /** 1-based line -> gate name. TS2344 here => baked-any / unverifiable. */
     gateLines: Map<number, GateName>;
-    /** 1-based line of the value-level assignment. Errors here => incompatible. */
+    /** 1-based line of the value-level assignment of the DECLARED sent type. */
     assignmentLine: number;
+    /**
+     * 1-based line of the second assignment, which sends the same value in the
+     * form JSON puts on the wire (carrick-tools/carrick-cloud#1119). Present for
+     * `http` pairs, whose payload is serialised; absent for every other
+     * protocol, where the declared form is what travels.
+     *
+     * This is the DECISIVE line when present: the comparand short-circuits to
+     * the declared type whenever that already assigns, so an error here means
+     * the shapes disagree in both forms, and no error here means they agree in
+     * the form that actually travels.
+     */
+    wireAssignmentLine?: number;
 }
+/** The assignment line whose diagnostic decides the bucket. */
+export declare function decisiveAssignmentLine(plan: ProbePlan): number;
 /**
  * Build one probe, recording the exact line of every gate and the assignment so
  * the classifier never depends on hard-coded offsets. `packageOf` maps a

package/sidecar/dist/src/capture/check-probe.js

@@ -7,6 +7,12 @@
  * conditional-type relation diverges around `any`, and because the compiler's
  * elaborated assignment error is the user-facing mismatch report.
  *
+ * An `http` pair carries a SECOND assignment of the same value in the form JSON
+ * puts on the wire, and that one decides the bucket (see `wireAssignmentLine`):
+ * a payload is serialised before it travels, so the declared types are not what
+ * meet each other. Both questions go to the same judge; nothing here decides a
+ * verdict.
+ *
  * GraphQL pairs additionally unwrap the producer's resolver-return ENVELOPE
  * before the assignment (see the `graphql` branch in `buildProbe`): a GraphQL
  * producer's captured type is the resolver function's return type with
@@ -63,6 +69,10 @@ export function pairId(spec) {
     ].join('|');
     return fnv1a(key);
 }
+/** The assignment line whose diagnostic decides the bucket. */
+export function decisiveAssignmentLine(plan) {
+    return plan.wireAssignmentLine ?? plan.assignmentLine;
+}
 /**
  * Build one probe, recording the exact line of every gate and the assignment so
  * the classifier never depends on hard-coded offsets. `packageOf` maps a
@@ -148,6 +158,34 @@ export function buildProbe(spec, packageOf) {
     else {
         assignmentLine = push(`const expected: Expected = sent;`);
     }
+    // The JSON wire line (carrick-tools/carrick-cloud#1119). An `http` payload is
+    // serialised before it travels, and `JSON.stringify` writes a value's
+    // `toJSON()` RESULT: a producer's `Date` arrives at the consumer as the
+    // string it serialises to, so comparing the DECLARED `Date` against a
+    // correctly-declared `string` reports a drift that cannot happen. The
+    // transform is applied to the SENT side in BOTH directions, which is where
+    // serialisation happens: a consumer that sends a `Date` in a request body
+    // likewise delivers a string, so a producer declaring `Date` there is a real
+    // mismatch and stays one.
+    //
+    // `WireSent` short-circuits to the declared type when that already assigns,
+    // so a pair that agrees as declared never instantiates the mapped type (no
+    // cost, and no way for the transform to turn an agreeing pair into a
+    // disagreeing one). tsc stays the judge of both forms.
+    let wireAssignmentLine;
+    if (spec.protocol === 'http') {
+        push(`type JsonWireDepth = [never, 0, 1, 2, 3, 4, 5, 6];`);
+        push(`type JsonWire<T, D extends number = 6> = [D] extends [never] ? T : T extends { toJSON: (...args: any[]) => infer R } ? JsonWire<R, JsonWireDepth[D]> : T extends (...args: any[]) => any ? T : T extends object ? { [K in keyof T]: JsonWire<T[K], JsonWireDepth[D]> } : T;`);
+        // Keep the DECLARED type whenever serialising changes nothing observable,
+        // so the compiler's headline still names the real surface alias (the probe
+        // prints `Sent`, which the scrub rewrites) instead of expanding a mapped
+        // type structurally. Only a pair whose payload really is transformed loses
+        // that name — and there the declared name no longer describes what travels.
+        push(`type JsonWireSame<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;`);
+        push(`type WireSent = [Sent] extends [Expected] ? Sent : (JsonWireSame<JsonWire<Sent>, Sent> extends true ? Sent : JsonWire<Sent>);`);
+        push(`declare const sentWire: WireSent;`);
+        wireAssignmentLine = push(`const expectedWire: Expected = sentWire;`);
+    }
     return {
         pairId: id,
         spec,
@@ -159,5 +197,6 @@ export function buildProbe(spec, packageOf) {
         importLines,
         gateLines,
         assignmentLine,
+        wireAssignmentLine,
     };
 }

package/sidecar/dist/src/capture/check.js

@@ -24,7 +24,8 @@ import { classifyPair, parseTscOutput, } from './check-classify.js';
 import { scrubPaths } from './check-scrub.js';
 import { assembleWorkspace, writeProbes, } from './check-workspace.js';
 import { buildPoisonIndexes } from './check-poison.js';
-import { probeDeepFindings } from './check-deep.js';
+import { openProbeProgram, probeDeepFindings } from './check-deep.js';
+import { pairFieldReports } from './check-fields.js';
 function runProcess(command, args, cwd) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
@@ -279,7 +280,12 @@ export async function runCheck(opts, onProgress) {
     // carries a member-level any/unknown HERE — after install, where the capture
     // could not look (carrick#450). It sets `resolved` and nothing else; no
     // bucket depends on it.
-    const deepByPair = probeDeepFindings(ws.probesDir, probing);
+    const probeProgram = openProbeProgram(ws.probesDir, probing);
+    const deepByPair = probeDeepFindings(probeProgram, probing);
+    // The same program answers which FIELDS differ on a pair the judge called
+    // incompatible (carrick-tools/carrick-cloud#1118). It names what the verdict
+    // is about; it never decides one.
+    const fieldsByPair = pairFieldReports(probeProgram, probing);
     const verdicts = sortVerdicts([
         ...probing.map((plan) => classifyPair({
             plan,
@@ -287,6 +293,7 @@ export async function runCheck(opts, onProgress) {
             poisonReason,
             scrubCtx,
             deepFindings: deepByPair.get(plan.pairId),
+            fieldReport: fieldsByPair.get(plan.pairId),
         })),
         ...preGated,
         ...unresolved,

package/templates/skills/carrick-census.md

@@ -12,31 +12,37 @@ does.
 
 ## 1. Two wordings
 
-Search twice. One query says what the code is for, the other says how it does
+Ask in two wordings. One says what the code is for, the other says how it does
 it. A purpose wording misses a helper whose description names only its
 mechanism, and a mechanism wording misses one described only by its job.
 
 ```
-search_by_intent({{SCOPE}}, query: "<what it is for>", compact: true, top_k: 20)
-search_by_intent({{SCOPE}}, query: "<how it does it>", compact: true, top_k: 20)
+search_by_intent({{SCOPE}}, query: "<what it is for>", also_phrased_as: ["<how it does it>"], compact: true, top_k: 20)
 ```
 
 `compact: true` returns locator-only rows, which is the shape a census needs.
-Page each query while `has_more` is true:
+One answer holds both wordings, deduped, with `phrasings` naming them and
+`matched_phrasings` on each row saying which ones reached it. Page it while
+`has_more` is true:
 
 ```
-search_by_intent({{SCOPE}}, query: "<the same query>", compact: true, top_k: 20, offset: <next_offset>)
+search_by_intent({{SCOPE}}, query: "<the same query>", also_phrased_as: ["<the same second wording>"], compact: true, top_k: 20, offset: <next_offset>)
 ```
 
+Where the answer carries no `phrasings`, or the field comes back refused, the
+server answering takes one wording per call. Run the second wording as its own
+paged search.
+
 Stop when `has_more` is false. Lower `similarity_threshold` where the tail of a
 page is still on topic.
 
 ## 2. Union
 
-Join the two result sets on `file_path` and `line_number`. A row both wordings
-found is one row. Keep `retrieved_by` and `similarity` on each row, and keep
-which wording found it: a row only one wording reached is the row a single
-search would have lost.
+One answer over both wordings is already deduped, and `matched_phrasings` says
+which wordings reached each row. Two answers are joined here, on `file_path` and
+`line_number`, and a row both wordings found is one row. Either way keep
+`retrieved_by` and `similarity`, and keep which wording found each row. A row
+only one wording reached is the row a single search would have lost.
 
 ## 3. Receipt
 
@@ -44,6 +50,9 @@ Report these numbers before the list, per query where the field is per query:
 
 - rows read, which is the count you paged to;
 - `total_candidates`, the exact size of the ranked list for that query;
+- `hidden_by_threshold` where the answer carries it: how many rows the floor
+  removed, and `best` where it names the closest of them. A count above zero is
+  the case for one more search at a lower `similarity_threshold`;
 - `total_without_intent`, which is index-wide: functions carrying no intent
   text, which no search looked at;
 - `total_intent_carried_forward` where the response states it, which are intents

package/templates/skills/carrick-drift.md

@@ -74,7 +74,13 @@ against a `string` on the other is not a difference.
 | POST /api/orders | UNRESOLVED | NewOrder | OrderDraft | web/src/orders.ts:52 | unresolved; type texts differ on `note` |
 
 Class words, and only these: MATCH, DRIFT, UNRESOLVED, NOT JUDGED, CONSUMER
-UNTYPED, PRODUCER UNTYPED. A reading of the two type texts goes in the verdict
+UNTYPED, PRODUCER UNTYPED. Every operation the answer returned carries one of
+them, the class column is never empty, and the report states operations returned
+against operations classed. Where more than one word fits an operation, the row
+takes the first that applies of DRIFT, PRODUCER UNTYPED, CONSUMER UNTYPED,
+UNRESOLVED, NOT JUDGED, MATCH, because a stored incompatible verdict is the
+finding and a side carrying no type is why nothing past it could be judged.
+A reading of the two type texts goes in the verdict
 column beside the stored state, in the words "type texts differ", so nothing in
 the table reads as a verdict the index did not give you.
 

package/templates/skills/carrick-impact.md

@@ -83,7 +83,9 @@ One table, then the detail.
 | admin-ui | src/api/orders.ts:44 | INCOMPATIBLE | fact |
 
 Verdict words, and only these: COMPATIBLE, INCOMPATIBLE, UNRESOLVED,
-NOT COMPARED. In the same message, state:
+NOT COMPARED. Every consumer call site the answers returned carries one of them
+and the verdict column is never empty, and the report states call sites returned
+against call sites given a verdict. In the same message, state:
 
 - the producers, with file and line;
 - unmatched calls and near misses, listed apart from consumers;

package/templates/skills/carrick-reuse.md

@@ -7,8 +7,8 @@ description: Use at the end of a task that added or changed functions, and whene
 
 {{SCOPE_NOTE}}
 
-`find_similar` does the comparison. Your work is to read both spans and class
-each pair.
+`find_similar` does the comparison. Your work is to read the spans it names
+and class every row it returned.
 
 ## Targeted: the functions this task added or changed
 
@@ -26,10 +26,13 @@ An entry is either a `name` with a `file` for a function the index holds, or a
 the other in an entry, never both. A `name` that matches more than one
 definition comes back with its candidates on that entry's `error`.
 
-The two kinds are scored on different scales and the response states both
-floors: 0.85 between two indexed functions, 0.45 for a description. A stored
-vector carries the function's name in front of its intent and a bare sentence
-does not, so a description scoring 0.5 is a hit worth reading.
+The two kinds are scored on different scales, and each result states the floor
+it was ranked against. `vector_basis` says what the cosines are over. On
+`intent` the vector is the intent sentence alone, and a copy somebody renamed
+scores as close as one that kept its name. On `name_anchored` the function's
+name sits in front of the sentence, a renamed copy scores lower, and
+`intent_text` is the signal that still finds it. Read every score against the
+floor and the basis in the answer you got.
 
 ## Audit: the whole project
 
@@ -38,9 +41,8 @@ find_similar({{SCOPE}})
 ```
 
 `clusters` groups functions that describe the same behaviour, ordered by size.
-Page with `offset: <next_offset>` while `has_more` is true. A group is
-transitive, so `lowest_similarity` can sit under the floor and a large group can
-hold more than one idea.
+Call again with `offset: <next_offset>` for as long as the response carries
+`has_more`, and class what every page returned.
 
 Where the project is larger than one pass, the response carries `error` in place
 of clusters and names the two routes under the ceiling: a `service`, or a higher
@@ -48,15 +50,28 @@ of clusters and names the two routes under the ceiling: a `service`, or a higher
 `truncated` is present the audit is partial, and its `scanned_functions` of `of`
 says by how much.
 
-## Class each pair
-
-Read both spans in source, then class:
-
-- **DUPLICATE**: the same behaviour, and one call site could use the other.
-- **VARIANT**: near neighbours that cannot share an implementation. Say in one
-  line why they cannot.
-- **FALSE POSITIVE**: the index describes them alike and the code does different
-  work.
+## Class every row
+
+Every row the answer returned is classed here. In an audit the first member of a
+cluster is what the rest of that cluster is classed against; in a targeted call
+it is the function you asked about. Read that span at the file and line the
+response gave, read each other row the same way, and take the first of these
+that holds:
+
+- **FALSE POSITIVE**: the two contracts differ. Different inputs, a different
+  result, or a different effect, and the intent sentences alone brought them
+  together.
+- **VARIANT**: one contract, and a behavioural difference you can name in a
+  clause. A different normalisation, a different error path, a different
+  default. Write the clause in the row. Where a comment on the member or at the
+  head of its file names the file it mirrors, the clause is "documented
+  mirror".
+- **DUPLICATE**: one contract, and nothing left to name. Two bodies that run
+  the same once the identifiers are renamed land here.
+
+A cluster is transitive, so `lowest_similarity` can sit under the floor and a
+large group can hold more than one idea. A member that shares no contract with
+the first is FALSE POSITIVE on its own row, and stays in the table.
 
 `matched_on` says which signal joined a row. `similarity` is the intent vectors;
 `intent_text` is two identical intent sentences, which is the signal that still
@@ -64,17 +79,19 @@ finds a copy somebody renamed.
 
 ## Report
 
-| class | function | file:line | pair | why |
+One row per match, and per cluster member beyond the first. The class column
+carries one of the three words and is never empty.
+
+| class | member | file:line | against | why |
 |---|---|---|---|---|
-| DUPLICATE | slugify | src/text.ts:12 | src/util/url.ts:4 | same replacement rules |
+| DUPLICATE | slugify | src/util/url.ts:4 | src/text.ts:12 | same replacement rules |
+| VARIANT | slugTag | src/tags.ts:20 | src/text.ts:12 | documented mirror |
 
-Then relay the counts the response stated, in its numbers:
+State `total_clusters` from the response against the number of clusters carrying
+rows above. Where the two differ, name the clusters left out.
 
-- `compared_functions`, and `total_clusters` on an audit;
-- `not_compared`: `without_intent`, `intent_not_embedded`, `awaiting_embedding`,
-  `model_mismatch`;
-- `excluded`: `below_min_lines`, `tests`, `generated`, `callbacks`,
-  `other_service`.
+Then relay the counts the response stated, in its numbers: `compared_functions`,
+and every key the answer carries under `not_compared` and under `excluded`.
 
 Rows outside the comparison were not looked at, so an empty answer covers what
 was compared and nothing further.