carrick 0.3.93 → 0.3.95

package/README.md

@@ -182,7 +182,8 @@ for the machine-readable shape, pinned in
 ## Where the answers land
 
 - **Claude Code**: the hooks `carrick init` writes deliver on the edit itself.
-  `claude --plugin-dir <carrick checkout>/plugin` adds the language server too.
+  `claude plugin marketplace add carrick-tools/carrick` then
+  `claude plugin install carrick@carrick` adds the language server too.
 - **VS Code, Cursor, Windsurf**: the `carrick-tools.carrick` extension is a
   client on `carrick lsp --stdio` and publishes diagnostics in the Problems
   panel. Whether an editor-hosted agent reads those diagnostics depends on its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carrick",
-  "version": "0.3.93",
+  "version": "0.3.95",
   "description": "The API contract index for a TypeScript workspace: what the other services do with the routes and calls in the file you are editing, in your editor and in your agent's context",
   "keywords": [
     "typescript",
@@ -58,11 +58,11 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@carrick-tools/cli-darwin-arm64": "0.3.93",
-    "@carrick-tools/cli-darwin-x64": "0.3.93",
-    "@carrick-tools/cli-linux-arm64": "0.3.93",
-    "@carrick-tools/cli-linux-x64": "0.3.93",
-    "@carrick-tools/cli-win32-x64": "0.3.93"
+    "@carrick-tools/cli-darwin-arm64": "0.3.95",
+    "@carrick-tools/cli-darwin-x64": "0.3.95",
+    "@carrick-tools/cli-linux-arm64": "0.3.95",
+    "@carrick-tools/cli-linux-x64": "0.3.95",
+    "@carrick-tools/cli-win32-x64": "0.3.95"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,21 @@
 {
   "name": "carrick",
-  "description": "Puts the workspace index's answer about the file you just edited into the session: its routes and calls, who is on the other side of them, and any contract that no longer holds",
-  "version": "0.0.1",
-  "homepage": "https://carrick.tools"
+  "description": "Claude Code plugin for Carrick, which indexes TypeScript codebases across service and repository boundaries. After each edit it adds the file's routes, calls, and cross-service type mismatches to the session, and it registers Carrick's language server. It pairs with the Carrick MCP server, which lets agents search functions by intent rather than name.",
+  "version": "0.3.95",
+  "author": {
+    "name": "Carrick",
+    "email": "hello@carrick.tools"
+  },
+  "homepage": "https://carrick.tools",
+  "repository": "https://github.com/carrick-tools/carrick",
+  "license": "Elastic-2.0",
+  "keywords": [
+    "typescript",
+    "mcp",
+    "api-contracts",
+    "monorepo",
+    "microservices",
+    "coding-agents",
+    "language-server"
+  ]
 }

package/sidecar/dist/src/retype.d.ts

@@ -57,6 +57,11 @@ export declare class Retyper {
      */
     run(items: RetypeItem[], budgetMs: number): RetypeOutcome[];
     private runOne;
+    /**
+     * The rewrite that states the producer's UNWIDENED return (carrick#1516),
+     * when the item carries one that can be stated at this call.
+     */
+    private unwidenedPlan;
     /**
      * How to state the producer's type at this call, or why it cannot be done.
      * Returns a builder so the wire and the declared form share one decision.

package/sidecar/dist/src/retype.js

@@ -25,6 +25,7 @@
  * project other requests read is the project the scan loaded.
  */
 import { Node, SyntaxKind, ts } from 'ts-morph';
+import { fileDiagnostics } from './unwidened.js';
 /** Names appended to a file that is not ours carry this prefix. */
 const PREFIX = '__carrick_';
 const WIRE = `${PREFIX}Wire`;
@@ -96,6 +97,8 @@ export class Retyper {
         const plan = this.plan(call, producer, item.wire);
         if (typeof plan === 'string')
             return abstain(item, plan);
+        // Planned now: a check forgets every node of the file, `call` included.
+        const unwidened = this.unwidenedPlan(call, item);
         const original = sourceFile.getFullText();
         let pre = before.get(sourceFile);
         if (!pre) {
@@ -122,10 +125,21 @@ export class Retyper {
                 messages = new Map(plain.added.map((d) => [key(d), d.message]));
             }
         }
+        // carrick#1516: the published type is what the compiler inferred, with
+        // any literal the handler returns widened. When the handler's own return,
+        // read before that widening, raises nothing, the producer's type is wider
+        // than what it sends: its own verdict class, not a break. Anything short
+        // of a clean check (a diagnostic, an abstain) leaves the mismatch.
+        let outcome = 'mismatch';
+        if (unwidened) {
+            const narrowed = this.check(sourceFile, original, unwidened(true), pre);
+            if (narrowed.kind === 'checked' && narrowed.added.length === 0)
+                outcome = 'wider';
+        }
         const lineOf = lineIndex(original);
         return {
             item_id: item.item_id,
-            outcome: 'mismatch',
+            outcome,
             diagnostics: decisive.added.map((d) => ({
                 line: lineOf(d.start),
                 code: d.code,
@@ -133,6 +147,17 @@ export class Retyper {
             })),
         };
     }
+    /**
+     * The rewrite that states the producer's UNWIDENED return (carrick#1516),
+     * when the item carries one that can be stated at this call.
+     */
+    unwidenedPlan(call, item) {
+        const text = oneLine(item.producer_unwidened_type ?? '');
+        if (!text || text.includes('//') || text.includes('/*'))
+            return undefined;
+        const plan = this.plan(call, text, item.wire);
+        return typeof plan === 'string' ? undefined : plan;
+    }
     /**
      * How to state the producer's type at this call, or why it cannot be done.
      * Returns a builder so the wire and the declared form share one decision.
@@ -830,16 +855,6 @@ function bodyReadEdit(read) {
 function declaresTypeParameters(call) {
     return (resolvedDeclaration(call)?.typeParameters?.length ?? 0) > 0;
 }
-function fileDiagnostics(sourceFile) {
-    const program = sourceFile.getProject().getProgram().compilerObject;
-    const node = sourceFile.compilerNode;
-    return [...program.getSyntacticDiagnostics(node), ...program.getSemanticDiagnostics(node)]
-        .filter((d) => d.file === node && d.start !== undefined)
-        .map((d) => ({ start: d.start, code: d.code, message: flatten(d.messageText) }));
-}
-function flatten(text) {
-    return ts.flattenDiagnosticMessageText(text, ' ');
-}
 function key(d) {
     return `${d.start}:${d.code}`;
 }

package/sidecar/dist/src/type-inferrer.d.ts

@@ -57,6 +57,11 @@ export interface TypeInferrerOptions {
      * `node_modules` symlink from an installed dependency (carrick#1264).
      */
     repoRoot: string;
+    /**
+     * How long the unwidened reading of one `infer` batch may take
+     * (carrick#1516). Defaults to `UNWIDENED_BUDGET_MS`.
+     */
+    unwidenedBudgetMs?: number;
 }
 /**
  * TypeInferrer - Extracts types from source code, both explicit and inferred
@@ -69,6 +74,13 @@ export declare class TypeInferrer {
     private readonly project;
     private readonly packageOf;
     private readonly repoRoot;
+    /**
+     * The node each inferred type was read from, keyed by the location object
+     * `getNodeLocation` built for it (the one an `InferredType` carries). The
+     * unwidened reading re-reads from here (carrick#1516).
+     */
+    private readonly readNodes;
+    private readonly unwidenedBudgetMs;
     constructor(options: TypeInferrerOptions);
     /**
      * What the structural printer needs to tell the user's own declarations from
@@ -85,6 +97,27 @@ export declare class TypeInferrer {
      * @returns InferResult with inferred types or errors
      */
     infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig): InferResult;
+    /**
+     * carrick#1516: read each response inference again with the literals on its
+     * handler's path marked `as const`, and record the narrower type the handler
+     * really returns beside the published one (`unwidened_type_string`). See
+     * `unwidened.ts` for what is marked and why the reading is sound.
+     *
+     * One rewrite for the whole batch: every file on any request's path is
+     * rewritten once, type-checked before and after, the requests re-inferred,
+     * and every file restored before returning, so the project other requests
+     * read is the project the scan loaded.
+     *
+     * Nothing is read past `deadline`: a batch that runs out keeps the readings
+     * it made and publishes none for the rest.
+     */
+    private addUnwidenedReadings;
+    /**
+     * The request as it locates in the rewritten files: a span moved past the
+     * insertions before it, an expression text replaced by the rewritten text of
+     * the node it named. Lines do not move (an insertion holds no newline).
+     */
+    private mappedRequest;
     /**
      * Infer a single type from a request
      */

package/sidecar/dist/src/type-inferrer.js

@@ -21,6 +21,7 @@ import * as path from 'node:path';
 import { Node, SyntaxKind, ts, } from 'ts-morph';
 import { validateInferRequestItem } from './validators.js';
 import { isExternalOrigin } from './origin.js';
+import { addedDiagnostics, applyInsertions, fileDiagnostics, literalInsertions, mapBack, mapForward, normalise, pathOf, } from './unwidened.js';
 import { expandTypeStructural, } from './type-structural-expander.js';
 /**
  * TS/lib globals and primitives that must never be emitted as a deterministic
@@ -230,6 +231,18 @@ const TYPE_TEXT_FLAGS = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InT
 function typeText(type, enclosingNode) {
     return type.getText(enclosingNode, TYPE_TEXT_FLAGS);
 }
+/**
+ * How long the unwidened reading of one batch may take by default. The
+ * reading adds a field and never an answer, so running out costs only the
+ * readings not yet made; the rewrite is always undone.
+ */
+const UNWIDENED_BUDGET_MS = 120_000;
+/**
+ * No reading starts or continues past this long after the batch began: the
+ * scanner's read deadline for one request is 900s, and the inferences the
+ * batch already made must reach it.
+ */
+const UNWIDENED_LATEST_MS = 600_000;
 /**
  * TypeInferrer - Extracts types from source code, both explicit and inferred
  *
@@ -241,10 +254,18 @@ export class TypeInferrer {
     project;
     packageOf;
     repoRoot;
+    /**
+     * The node each inferred type was read from, keyed by the location object
+     * `getNodeLocation` built for it (the one an `InferredType` carries). The
+     * unwidened reading re-reads from here (carrick#1516).
+     */
+    readNodes = new WeakMap();
+    unwidenedBudgetMs;
     constructor(options) {
         this.project = options.project;
         this.packageOf = options.packageOf;
         this.repoRoot = options.repoRoot;
+        this.unwidenedBudgetMs = options.unwidenedBudgetMs ?? UNWIDENED_BUDGET_MS;
     }
     /**
      * What the structural printer needs to tell the user's own declarations from
@@ -266,8 +287,11 @@ export class TypeInferrer {
      * @returns InferResult with inferred types or errors
      */
     infer(requests, extractionConfig) {
+        const started = performance.now();
         const inferredTypes = [];
         const errors = [];
+        /** Response inferences the unwidened reading re-reads (carrick#1516). */
+        const responses = [];
         for (const request of requests) {
             // Plain JavaScript has no type annotations to extract, and `checkJs` is
             // off, so inferring against a `.js` file yields nothing useful — it only
@@ -287,6 +311,9 @@ export class TypeInferrer {
                 const result = this.inferSingle(request, extractionConfig);
                 if (result) {
                     inferredTypes.push(result);
+                    if (request.infer_kind === 'response_body' || request.infer_kind === 'function_return') {
+                        responses.push({ request, result });
+                    }
                 }
                 else {
                     errors.push(`Could not infer type at ${request.file_path}:${loc} (${request.infer_kind})`);
@@ -298,12 +325,193 @@ export class TypeInferrer {
                 errors.push(`Error inferring type at ${request.file_path}:${loc}: ${error}`);
             }
         }
+        try {
+            const deadline = Math.min(performance.now() + this.unwidenedBudgetMs, started + UNWIDENED_LATEST_MS);
+            this.addUnwidenedReadings(responses, extractionConfig, deadline);
+        }
+        catch (err) {
+            // The reading only ever adds a field; it never costs an answer.
+            this.logError(`Unwidened reading failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
         return {
             success: errors.length === 0 || inferredTypes.length > 0,
             inferred_types: inferredTypes.length > 0 ? inferredTypes : undefined,
             errors: errors.length > 0 ? errors : undefined,
         };
     }
+    /**
+     * carrick#1516: read each response inference again with the literals on its
+     * handler's path marked `as const`, and record the narrower type the handler
+     * really returns beside the published one (`unwidened_type_string`). See
+     * `unwidened.ts` for what is marked and why the reading is sound.
+     *
+     * One rewrite for the whole batch: every file on any request's path is
+     * rewritten once, type-checked before and after, the requests re-inferred,
+     * and every file restored before returning, so the project other requests
+     * read is the project the scan loaded.
+     *
+     * Nothing is read past `deadline`: a batch that runs out keeps the readings
+     * it made and publishes none for the rest.
+     */
+    addUnwidenedReadings(responses, extractionConfig, deadline) {
+        const outOfTime = (stage) => {
+            if (performance.now() <= deadline)
+                return false;
+            this.log(`Unwidened reading stopped ${stage}: it ran out of its budget`);
+            return true;
+        };
+        const plans = [];
+        const insertionsByFile = new Map();
+        const checkedFiles = new Set();
+        // Every position is read before the first rewrite: a rewrite forgets
+        // every node of its file.
+        for (const { request, result } of responses) {
+            // A declared return type is the contract; nothing was widened.
+            if (result.is_explicit)
+                continue;
+            const read = this.readNodes.get(result.source_location);
+            if (!read)
+                continue;
+            const functions = pathOf(read);
+            let marked = 0;
+            for (const fn of functions) {
+                const insertions = literalInsertions(fn);
+                marked += insertions.length;
+                if (insertions.length === 0)
+                    continue;
+                const file = fn.getSourceFile();
+                insertionsByFile.set(file, [...(insertionsByFile.get(file) ?? []), ...insertions]);
+            }
+            // Nothing on the path to mark: the reading would equal the published type.
+            if (marked === 0)
+                continue;
+            const path = functions.map((fn) => ({
+                file: fn.getSourceFile(),
+                start: fn.getStart(),
+                end: fn.getEnd(),
+            }));
+            for (const fn of path)
+                checkedFiles.add(fn.file);
+            let locatedByText;
+            if (request.expression_text && request.span_start === undefined) {
+                const sourceFile = this.getSourceFile(request.file_path);
+                const located = sourceFile
+                    ? this.findNodeByText(sourceFile, request.expression_text, request.expression_line)
+                    : undefined;
+                if (located)
+                    locatedByText = { start: located.getStart(), end: located.getEnd() };
+            }
+            plans.push({
+                request,
+                result,
+                read: { file: read.getSourceFile(), start: read.getStart(), end: read.getEnd() },
+                path,
+                locatedByText,
+            });
+        }
+        if (plans.length === 0)
+            return;
+        const insertions = new Map();
+        for (const [file, list] of insertionsByFile)
+            insertions.set(file, normalise(list));
+        const before = new Map();
+        for (const file of checkedFiles) {
+            if (outOfTime('before the rewrite'))
+                return;
+            before.set(file, fileDiagnostics(file));
+        }
+        const originals = new Map();
+        for (const file of insertions.keys())
+            originals.set(file, file.getFullText());
+        try {
+            for (const [file, list] of insertions) {
+                file.replaceWithText(applyInsertions(originals.get(file), list));
+            }
+            // A diagnostic the marking added sits in a function on some request's
+            // path (or elsewhere in that function's file): every request whose path
+            // holds it loses its reading.
+            const tainted = new Set();
+            for (const file of checkedFiles) {
+                if (outOfTime('while checking the rewrite'))
+                    return;
+                const list = insertions.get(file) ?? [];
+                for (const at of addedDiagnostics(before.get(file), fileDiagnostics(file), list)) {
+                    const holders = plans.flatMap((plan) => plan.path).filter((fn) => fn.file === file && fn.start <= at && at < fn.end);
+                    for (const plan of plans) {
+                        const onPath = plan.path.some((fn) => holders.length > 0 ? holders.includes(fn) : fn.file === file);
+                        if (onPath)
+                            tainted.add(plan);
+                    }
+                }
+            }
+            for (const plan of plans) {
+                if (outOfTime('while re-reading'))
+                    return;
+                if (tainted.has(plan)) {
+                    this.log(`Unwidened reading for ${plan.request.file_path}:${plan.request.line_number} ` +
+                        'dropped: marking its literals added a diagnostic on its path');
+                    continue;
+                }
+                const request = this.mappedRequest(plan.request, plan.locatedByText, insertions);
+                let again = null;
+                try {
+                    again = this.inferSingle(request, extractionConfig);
+                }
+                catch {
+                    again = null;
+                }
+                if (!again || again.type_string === plan.result.type_string)
+                    continue;
+                // An invariant, not a case: `mappedRequest` is what keeps the re-read
+                // on the node the inference read, so no fixture reaches this. It is
+                // what turns a locator the mapping got wrong into no reading instead
+                // of another node's type published as this handler's.
+                const readAgain = this.readNodes.get(again.source_location);
+                const list = insertions.get(plan.read.file) ?? [];
+                const sameNode = readAgain !== undefined &&
+                    readAgain.getSourceFile() === plan.read.file &&
+                    mapBack(readAgain.getStart(), list) === plan.read.start &&
+                    mapBack(readAgain.getEnd(), list) === plan.read.end;
+                if (!sameNode) {
+                    this.log(`Unwidened reading for ${plan.request.file_path}:${plan.request.line_number} ` +
+                        'dropped: the re-read did not read the node the inference read');
+                    continue;
+                }
+                plan.result.unwidened_type_string = again.type_string;
+            }
+        }
+        finally {
+            for (const [file, text] of originals)
+                file.replaceWithText(text);
+        }
+    }
+    /**
+     * The request as it locates in the rewritten files: a span moved past the
+     * insertions before it, an expression text replaced by the rewritten text of
+     * the node it named. Lines do not move (an insertion holds no newline).
+     */
+    mappedRequest(request, locatedByText, insertions) {
+        const sourceFile = this.getSourceFile(request.file_path);
+        const list = sourceFile ? insertions.get(sourceFile) ?? [] : [];
+        if (list.length === 0)
+            return request;
+        if (request.span_start !== undefined && request.span_end !== undefined) {
+            return {
+                ...request,
+                span_start: mapForward(request.span_start, list, 'start'),
+                span_end: mapForward(request.span_end, list, 'end'),
+            };
+        }
+        if (locatedByText && sourceFile) {
+            return {
+                ...request,
+                expression_text: sourceFile
+                    .getFullText()
+                    .slice(mapForward(locatedByText.start, list, 'start'), mapForward(locatedByText.end, list, 'end')),
+            };
+        }
+        return request;
+    }
     /**
      * Infer a single type from a request
      */
@@ -5421,13 +5629,15 @@ export class TypeInferrer {
     getNodeLocation(node) {
         const startLinePos = node.getStartLineNumber();
         const endLinePos = node.getEndLineNumber();
-        return {
+        const location = {
             file_path: node.getSourceFile().getFilePath(),
             start_line: startLinePos,
             end_line: endLinePos,
             start_column: node.getStart() - node.getStartLinePos(),
             end_column: node.getEnd() - node.getStartLinePos(),
         };
+        this.readNodes.set(location, node);
+        return location;
     }
     createInferredType(request, typeString, isExplicit, sourceLocation, payloadTypeString, primaryTypeSymbol, arrayDepth, primaryTypeSymbolSource) {
         const alias = request.alias ||

package/sidecar/dist/src/types.d.ts

@@ -300,6 +300,12 @@ export interface RetypeItem {
     expression_line?: number;
     /** The producer's response type as TypeScript text, fully inlined. */
     producer_type: string;
+    /**
+     * The producer's response as its handler returns it, literals read before
+     * TypeScript widens them (carrick#1516), when that differs from
+     * `producer_type`. Asked only when `producer_type` raised diagnostics.
+     */
+    producer_unwidened_type?: string;
     /** Judge the form JSON puts on the wire (an `http` response). */
     wire: boolean;
 }
@@ -511,11 +517,14 @@ export interface RetypeDiagnostic {
  * - `mismatch`: the rewrite added diagnostics; each is a place the consumer
  *   uses something the producer's response does not provide.
  * - `agrees`: it added none.
+ * - `wider`: the published type added diagnostics and the handler's
+ *   unwidened return added none (carrick#1516): the producer's type is wider
+ *   than what it sends. `diagnostics` are the published type's.
  * - `abstain`: the check could not be made; `reason` says why.
  */
 export interface RetypeOutcome {
     item_id: string;
-    outcome: 'mismatch' | 'agrees' | 'abstain';
+    outcome: 'mismatch' | 'agrees' | 'wider' | 'abstain';
     diagnostics: RetypeDiagnostic[];
     reason?: string;
 }
@@ -615,6 +624,16 @@ export interface InferredType {
      * Sorted by `path`; absent (not empty) when the type carries no top type.
      */
     any_provenance?: TypeProvenance[];
+    /**
+     * carrick#1516, response inferences only: the same inference re-read with
+     * every literal on the handler's path kept at its literal type
+     * (`unwidened.ts`). `type_string` is what the compiler infers and what the
+     * index publishes; this is what the handler actually sends when TypeScript
+     * widened a literal in it (`scope: string` published, `scope: 'all' |
+     * 'specific'` sent). Absent when the two are the same, or when the reading
+     * was dropped as unsound.
+     */
+    unwidened_type_string?: string;
 }
 /**
  * Why a type carries `any`/`unknown` at a position, and where.

package/sidecar/dist/src/unwidened.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The unwidened reading of a producer's response (carrick#1516).
+ *
+ * A handler that returns `{ scope: row.parentId ? 'specific' : 'all' }` sends
+ * one of two strings, but its inferred return type says `scope: string`:
+ * TypeScript widens a literal that lands in a mutable position (an object
+ * property, an array element, a function's return). The index publishes that
+ * widened type, so a consumer declaring `scope: 'all' | 'specific'` is judged
+ * against a `string` the handler never sends.
+ *
+ * The published type stays what the compiler inferred. Beside it, this reads
+ * the SAME inference again with every literal on the handler's path marked
+ * `as const`, which is the compiler's own way of saying "keep this literal's
+ * type". A const-asserted literal is a regular literal type, and only fresh
+ * literal types widen, so the re-read inference is the handler's return with
+ * nothing widened: `'all' | 'specific'` for the conditional, `true`/`false`
+ * for a discriminant, `2 | 1` for a numeric choice. No rule of ours decides
+ * what a literal becomes; the compiler infers the return again.
+ *
+ * The judge uses the reading only to classify a mismatch the published type
+ * already raised: when this narrower type fits the consumer, the pair is
+ * reported as the producer's type being wider than what it sends, not as a
+ * break.
+ *
+ * Soundness rests on three things:
+ *
+ * - **A literal that feeds a mutable binding keeps its widening.** `let s =
+ *   'a'` can later hold `'b'`, so its type really is `string`; the literals
+ *   that initialise a `let`/`var` are never marked. Nor is a parameter's
+ *   default: it decides what callers may pass, and a caller the path does not
+ *   reach could pass another value.
+ * - **No new diagnostic on the handler's path.** A marked literal that is
+ *   later changed (an object built with `'a'` and then assigned `'b'`) makes
+ *   the compiler report the assignment. Every file holding a function on the
+ *   path is type-checked before and after, and any diagnostic the marking adds
+ *   drops the reading for every request whose path includes that function.
+ * - **The re-read came from the same place.** The inference is re-run from
+ *   the request, so its locator runs again; the reading is kept only when it
+ *   read the same node it read the first time.
+ *
+ * The path is the function the inference read (or the function around the
+ * payload expression it read), plus every source function it calls whose
+ * return type is inferred rather than declared, transitively: a controller
+ * that returns `this.service.list()` sends what `list` returns. A callee with
+ * a declared return type is not followed; that declaration is the contract.
+ */
+import { Node } from 'ts-morph';
+import type { SourceFile } from 'ts-morph';
+/** One insertion into a file's ORIGINAL text. */
+export interface Insertion {
+    pos: number;
+    text: string;
+    /**
+     * An opener sits before the literal it wraps, a closer after it. At one
+     * position a closer (ending the previous literal) comes before an opener.
+     */
+    closes: boolean;
+}
+/** A function on a request's path, by its original span. */
+export interface PathFunction {
+    file: SourceFile;
+    start: number;
+    end: number;
+}
+/** One diagnostic a file's type-check reported. */
+export interface FileDiagnostic {
+    /** Start position in the file it was reported on. */
+    start: number;
+    code: number;
+    message: string;
+}
+/**
+ * The functions on the path of a read node: the function it is (or sits in),
+ * then every un-annotated source function called from those, breadth first.
+ * A read node outside any function is its own path.
+ */
+export declare function pathOf(read: Node): Node[];
+/**
+ * The insertions that mark every literal inside `fn` whose widening the
+ * reading drops. Positions are original-file positions.
+ */
+export declare function literalInsertions(fn: Node): Insertion[];
+/** Deduplicated, in text order (a closer before an opener at one position). */
+export declare function normalise(insertions: Insertion[]): Insertion[];
+export declare function applyInsertions(text: string, insertions: Insertion[]): string;
+/**
+ * Where an original position lands in the rewritten text. A START keeps an
+ * opener at its own position outside (so a span starting on a marked literal
+ * covers its parentheses); an END takes every insertion at its position in.
+ */
+export declare function mapForward(pos: number, insertions: Insertion[], side: 'start' | 'end'): number;
+/** The original position a rewritten one came from; inside an insertion, its position. */
+export declare function mapBack(pos: number, insertions: Insertion[]): number;
+/** Syntactic and semantic diagnostics reported in this file. */
+export declare function fileDiagnostics(sourceFile: SourceFile): FileDiagnostic[];
+/**
+ * Original positions of the diagnostics `after` holds that `before` does not,
+ * matched by original position and code. A diagnostic whose message changed
+ * because a type narrowed is the same diagnostic.
+ */
+export declare function addedDiagnostics(before: FileDiagnostic[], after: FileDiagnostic[], insertions: Insertion[]): number[];

package/sidecar/dist/src/unwidened.js

@@ -0,0 +1,272 @@
+/**
+ * The unwidened reading of a producer's response (carrick#1516).
+ *
+ * A handler that returns `{ scope: row.parentId ? 'specific' : 'all' }` sends
+ * one of two strings, but its inferred return type says `scope: string`:
+ * TypeScript widens a literal that lands in a mutable position (an object
+ * property, an array element, a function's return). The index publishes that
+ * widened type, so a consumer declaring `scope: 'all' | 'specific'` is judged
+ * against a `string` the handler never sends.
+ *
+ * The published type stays what the compiler inferred. Beside it, this reads
+ * the SAME inference again with every literal on the handler's path marked
+ * `as const`, which is the compiler's own way of saying "keep this literal's
+ * type". A const-asserted literal is a regular literal type, and only fresh
+ * literal types widen, so the re-read inference is the handler's return with
+ * nothing widened: `'all' | 'specific'` for the conditional, `true`/`false`
+ * for a discriminant, `2 | 1` for a numeric choice. No rule of ours decides
+ * what a literal becomes; the compiler infers the return again.
+ *
+ * The judge uses the reading only to classify a mismatch the published type
+ * already raised: when this narrower type fits the consumer, the pair is
+ * reported as the producer's type being wider than what it sends, not as a
+ * break.
+ *
+ * Soundness rests on three things:
+ *
+ * - **A literal that feeds a mutable binding keeps its widening.** `let s =
+ *   'a'` can later hold `'b'`, so its type really is `string`; the literals
+ *   that initialise a `let`/`var` are never marked. Nor is a parameter's
+ *   default: it decides what callers may pass, and a caller the path does not
+ *   reach could pass another value.
+ * - **No new diagnostic on the handler's path.** A marked literal that is
+ *   later changed (an object built with `'a'` and then assigned `'b'`) makes
+ *   the compiler report the assignment. Every file holding a function on the
+ *   path is type-checked before and after, and any diagnostic the marking adds
+ *   drops the reading for every request whose path includes that function.
+ * - **The re-read came from the same place.** The inference is re-run from
+ *   the request, so its locator runs again; the reading is kept only when it
+ *   read the same node it read the first time.
+ *
+ * The path is the function the inference read (or the function around the
+ * payload expression it read), plus every source function it calls whose
+ * return type is inferred rather than declared, transitively: a controller
+ * that returns `this.service.list()` sends what `list` returns. A callee with
+ * a declared return type is not followed; that declaration is the contract.
+ */
+import { Node, SyntaxKind, ts } from 'ts-morph';
+/** How many calls deep the path follows an un-annotated callee. */
+const MAX_FOLLOW_DEPTH = 3;
+/** Functions one request's path may hold before following stops. */
+const MAX_PATH_FUNCTIONS = 32;
+const OPEN = '(';
+const CLOSE = ' as const)';
+/**
+ * The functions on the path of a read node: the function it is (or sits in),
+ * then every un-annotated source function called from those, breadth first.
+ * A read node outside any function is its own path.
+ */
+export function pathOf(read) {
+    const root = isFunctionWithBody(read) ? read : read.getFirstAncestor(isFunctionWithBody) ?? read;
+    const seen = new Set([root]);
+    const out = [root];
+    let frontier = [root];
+    for (let depth = 0; depth < MAX_FOLLOW_DEPTH && frontier.length > 0; depth++) {
+        const next = [];
+        for (const fn of frontier) {
+            for (const callee of calleesOf(fn)) {
+                if (seen.has(callee) || out.length >= MAX_PATH_FUNCTIONS)
+                    continue;
+                seen.add(callee);
+                out.push(callee);
+                next.push(callee);
+            }
+        }
+        frontier = next;
+    }
+    return out;
+}
+/**
+ * The source functions `fn` calls whose return type the compiler inferred. A
+ * declared return type is the callee's contract: nothing in it was widened,
+ * and marking its literals could only cost the reading a diagnostic.
+ */
+function calleesOf(fn) {
+    const out = [];
+    for (const call of fn.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const node = call.getProject().getTypeChecker().getResolvedSignature(call)?.getDeclaration();
+        if (!node || !isFunctionWithBody(node) || hasDeclaredReturn(node))
+            continue;
+        const file = node.getSourceFile();
+        if (file.isDeclarationFile() || file.isFromExternalLibrary() || file.isInNodeModules())
+            continue;
+        out.push(node);
+    }
+    return out;
+}
+function isFunctionWithBody(node) {
+    return ((Node.isFunctionDeclaration(node) ||
+        Node.isMethodDeclaration(node) ||
+        Node.isArrowFunction(node) ||
+        Node.isFunctionExpression(node)) &&
+        node.getBody() !== undefined);
+}
+function hasDeclaredReturn(node) {
+    return ((Node.isFunctionDeclaration(node) ||
+        Node.isMethodDeclaration(node) ||
+        Node.isArrowFunction(node) ||
+        Node.isFunctionExpression(node)) &&
+        node.getReturnTypeNode() !== undefined);
+}
+/**
+ * The insertions that mark every literal inside `fn` whose widening the
+ * reading drops. Positions are original-file positions.
+ */
+export function literalInsertions(fn) {
+    const out = [];
+    const visit = (node) => {
+        // A type states no value, and a parameter's default decides what its
+        // callers may pass, not what the function returns.
+        if (Node.isTypeNode(node) || Node.isParameterDeclaration(node))
+            return;
+        if (isMarkableLiteral(node)) {
+            out.push({ pos: node.getStart(), text: OPEN, closes: false });
+            out.push({ pos: node.getEnd(), text: CLOSE, closes: true });
+            return;
+        }
+        node.forEachChild(visit);
+    };
+    visit(fn);
+    return out;
+}
+/** Whether `node` is a literal value the reading marks `as const`. */
+function isMarkableLiteral(node) {
+    const kind = node.getKind();
+    const literal = kind === SyntaxKind.StringLiteral ||
+        kind === SyntaxKind.NumericLiteral ||
+        kind === SyntaxKind.BigIntLiteral ||
+        kind === SyntaxKind.NoSubstitutionTemplateLiteral ||
+        kind === SyntaxKind.TrueKeyword ||
+        kind === SyntaxKind.FalseKeyword ||
+        // `-1` is marked whole: `-(1 as const)` is a `number`, and the visit
+        // never reaches the `1` inside it.
+        (Node.isPrefixUnaryExpression(node) &&
+            node.getOperatorToken() === SyntaxKind.MinusToken &&
+            (Node.isNumericLiteral(node.getOperand()) || Node.isBigIntLiteral(node.getOperand())));
+    if (!literal)
+        return false;
+    const parent = node.getParent();
+    if (!parent)
+        return false;
+    // Syntax, not a value: a quoted property name, a tagged template's text.
+    if (parent.getNameNode?.() === node)
+        return false;
+    if (Node.isTaggedTemplateExpression(parent))
+        return false;
+    return !initialisesMutableBinding(node);
+}
+/**
+ * Whether the literal becomes the value of a `let`/`var` binding, which can
+ * later hold another one, so its type really is the widened one. Reached
+ * through the expressions that pass a value through unchanged.
+ */
+function initialisesMutableBinding(literal) {
+    let node = literal;
+    for (;;) {
+        const parent = node.getParent();
+        if (!parent)
+            return false;
+        if (Node.isParenthesizedExpression(parent) ||
+            (Node.isConditionalExpression(parent) && parent.getCondition() !== node) ||
+            (Node.isBinaryExpression(parent) && passesOperandThrough(parent.getOperatorToken().getKind()))) {
+            node = parent;
+            continue;
+        }
+        if (!Node.isVariableDeclaration(parent) || parent.getInitializer() !== node)
+            return false;
+        const list = parent.getParent();
+        return Node.isVariableDeclarationList(list) && (list.getFlags() & ts.NodeFlags.Const) === 0;
+    }
+}
+/** Binary operators whose value is one of their operands. */
+function passesOperandThrough(kind) {
+    return (kind === SyntaxKind.BarBarToken ||
+        kind === SyntaxKind.QuestionQuestionToken ||
+        kind === SyntaxKind.AmpersandAmpersandToken ||
+        kind === SyntaxKind.CommaToken);
+}
+/** Deduplicated, in text order (a closer before an opener at one position). */
+export function normalise(insertions) {
+    const seen = new Set();
+    const out = [];
+    for (const insertion of insertions) {
+        const k = `${insertion.pos}:${insertion.closes}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(insertion);
+    }
+    return out.sort((a, b) => a.pos - b.pos || Number(b.closes) - Number(a.closes));
+}
+export function applyInsertions(text, insertions) {
+    let out = '';
+    let cursor = 0;
+    for (const insertion of insertions) {
+        out += text.slice(cursor, insertion.pos) + insertion.text;
+        cursor = insertion.pos;
+    }
+    return out + text.slice(cursor);
+}
+/**
+ * Where an original position lands in the rewritten text. A START keeps an
+ * opener at its own position outside (so a span starting on a marked literal
+ * covers its parentheses); an END takes every insertion at its position in.
+ */
+export function mapForward(pos, insertions, side) {
+    let shift = 0;
+    for (const insertion of insertions) {
+        if (insertion.pos < pos || (insertion.pos === pos && (side === 'end' || insertion.closes))) {
+            shift += insertion.text.length;
+        }
+    }
+    return pos + shift;
+}
+/** The original position a rewritten one came from; inside an insertion, its position. */
+export function mapBack(pos, insertions) {
+    let shift = 0;
+    for (const insertion of insertions) {
+        const at = insertion.pos + shift;
+        if (pos < at)
+            break;
+        if (pos < at + insertion.text.length)
+            return insertion.pos;
+        shift += insertion.text.length;
+    }
+    return pos - shift;
+}
+/** Syntactic and semantic diagnostics reported in this file. */
+export function fileDiagnostics(sourceFile) {
+    const program = sourceFile.getProject().getProgram().compilerObject;
+    const node = sourceFile.compilerNode;
+    return [...program.getSyntacticDiagnostics(node), ...program.getSemanticDiagnostics(node)]
+        .filter((d) => d.file === node && d.start !== undefined)
+        .map((d) => ({
+        start: d.start,
+        code: d.code,
+        message: ts.flattenDiagnosticMessageText(d.messageText, ' '),
+    }));
+}
+/**
+ * Original positions of the diagnostics `after` holds that `before` does not,
+ * matched by original position and code. A diagnostic whose message changed
+ * because a type narrowed is the same diagnostic.
+ */
+export function addedDiagnostics(before, after, insertions) {
+    const remaining = new Map();
+    for (const d of before) {
+        const k = `${d.start}:${d.code}`;
+        remaining.set(k, (remaining.get(k) ?? 0) + 1);
+    }
+    const added = [];
+    for (const d of after) {
+        const start = mapBack(d.start, insertions);
+        const k = `${start}:${d.code}`;
+        const left = remaining.get(k) ?? 0;
+        if (left > 0) {
+            remaining.set(k, left - 1);
+            continue;
+        }
+        added.push(start);
+    }
+    return added;
+}

package/sidecar/dist/src/validators.d.ts

@@ -1142,6 +1142,7 @@ export declare const RetypeCheckRequestSchema: z.ZodObject<{
         expression_text: z.ZodOptional<z.ZodString>;
         expression_line: z.ZodOptional<z.ZodNumber>;
         producer_type: z.ZodString;
+        producer_unwidened_type: z.ZodOptional<z.ZodString>;
         wire: z.ZodBoolean;
     }, "strip", z.ZodTypeAny, {
         wire: boolean;
@@ -1153,6 +1154,7 @@ export declare const RetypeCheckRequestSchema: z.ZodObject<{
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }, {
         wire: boolean;
         file_path: string;
@@ -1163,6 +1165,7 @@ export declare const RetypeCheckRequestSchema: z.ZodObject<{
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }>, "many">;
     budget_ms: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
@@ -1178,6 +1181,7 @@ export declare const RetypeCheckRequestSchema: z.ZodObject<{
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }[];
     budget_ms?: number | undefined;
 }, {
@@ -1193,6 +1197,7 @@ export declare const RetypeCheckRequestSchema: z.ZodObject<{
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }[];
     budget_ms?: number | undefined;
 }>;
@@ -2247,6 +2252,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         expression_text: z.ZodOptional<z.ZodString>;
         expression_line: z.ZodOptional<z.ZodNumber>;
         producer_type: z.ZodString;
+        producer_unwidened_type: z.ZodOptional<z.ZodString>;
         wire: z.ZodBoolean;
     }, "strip", z.ZodTypeAny, {
         wire: boolean;
@@ -2258,6 +2264,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }, {
         wire: boolean;
         file_path: string;
@@ -2268,6 +2275,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }>, "many">;
     budget_ms: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
@@ -2283,6 +2291,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }[];
     budget_ms?: number | undefined;
 }, {
@@ -2298,6 +2307,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         span_end?: number | undefined;
         expression_text?: string | undefined;
         expression_line?: number | undefined;
+        producer_unwidened_type?: string | undefined;
     }[];
     budget_ms?: number | undefined;
 }>, z.ZodObject<{

package/sidecar/dist/src/validators.js

@@ -292,6 +292,7 @@ const RetypeItemSchema = z.object({
     expression_text: z.string().optional(),
     expression_line: z.number().int().positive().optional(),
     producer_type: z.string().min(1),
+    producer_unwidened_type: z.string().min(1).optional(),
     wire: z.boolean(),
 });
 export const RetypeCheckRequestSchema = BaseRequestSchema.extend({