@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/status-contract.test.ts

@@ -316,6 +316,8 @@ describe("chant workspace status on built workspaces", () => {
         isolation: null,
         intent: null,
         services: [],
+        factory: null,
+        listing: null,
       },
     ]);
   });
@@ -451,6 +453,7 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         expiresAt: "2026-12-31T00:00:00.000Z",
         approvals: [{ principal: "alice", channel: "cli", at: "2026-09-20T01:00:00.000Z" }],
         needed: 1,
+        signed: null,
         approve: `chant approve web deploy --env staging --plan ${D("1")}`,
       },
       {
@@ -463,6 +466,7 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         expiresAt: "2026-12-31T00:00:00.000Z",
         approvals: [],
         needed: 1,
+        signed: null,
         approve: `chant approve web deploy --env prod --plan ${D("2")}`,
       },
       {
@@ -476,6 +480,7 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         // The agent's approval doesn't count toward the quorum.
         approvals: [{ principal: "bob", channel: "cli", at: "2026-09-20T02:00:00.000Z" }],
         needed: 2,
+        signed: null,
         approve: `chant approve web review --env staging --plan ${D("4")}`,
       },
     ]);

package/src/workspace/status-gates.ts

@@ -22,7 +22,7 @@ import { execFileSync } from "node:child_process";
 import { samePlanDigest } from "../lifecycle/plan-digest";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, parseGateLedger } from "../lifecycle/gate-ledger";
-import { tallyGateApprovals } from "../op/gate";
+import { tallyGateApprovals, type GateApprovalRule } from "../op/gate";
 import type { ReasonCode } from "./reason-codes";
 
 /** Why a member's gates can't be listed. Closed: a new code is a contract change. */
@@ -63,10 +63,20 @@ export interface StatusGate {
   approvals: StatusGateApproval[];
   /** How many human approvals the gate needs: its quorum's count, 1 without one. */
   needed: number;
+  /**
+   * The declaration's rule for the gate (#3163, ws-080): set when
+   * `identity.gates` names it, so only an approval sealed by a signer at
+   * base (from `class`, when it names one) counts, and `approve` carries
+   * `--sign`. Null when any approval counts.
+   */
+  signed: { class: string | null } | null;
   /** The command that approves it, run in the member's directory. */
   approve: string;
 }
 
+/** The rule for a gate, by name, as `identity.gates` at base sets it (#3163). Null when it sets none. */
+export type GateRuleLookup = (gate: string) => GateApprovalRule | null;
+
 export interface StatusGateLedger {
   /** `members` for `_members/<member>/_gates`, `flat` for `_gates`. */
   layout: "members" | "flat";
@@ -110,15 +120,17 @@ export const defaultGateLedgerReader: GateLedgerReader = async (dir, commit, cwd
  * plan this read showed and not whatever happens to be pending by the time
  * someone runs it.
  */
-export function approveCommand(component: string, gate: string, env: string | null, planDigest?: string | null): string {
-  return `chant approve ${component} ${gate}${env !== null ? ` --env ${env}` : ""}${planDigest ? ` --plan ${planDigest}` : ""}`;
+export function approveCommand(component: string, gate: string, env: string | null, planDigest?: string | null, signed = false): string {
+  return `chant approve ${component} ${gate}${env !== null ? ` --env ${env}` : ""}${planDigest ? ` --plan ${planDigest}` : ""}${signed ? " --sign" : ""}`;
 }
 
 const approvalOf = (r: GateResolutionRecord): StatusGateApproval => ({ principal: r.resolvedBy, channel: r.origin ?? null, at: r.timestamp });
 
 /** One gate in one environment, decided against its newest pending fact. */
-function decide(component: string, standing: PendingGateRecord, resolutions: GateResolutionRecord[], now: string): StatusGate {
+function decide(component: string, standing: PendingGateRecord, all: GateResolutionRecord[], now: string, rule: GateApprovalRule | null): StatusGate {
   const gate = standing.gate;
+  // #3163: under identity.gates, an unsigned approval, or one from outside the class, doesn't count, as a run reads it.
+  const resolutions = rule === null ? all : all.filter((r) => r.gate !== gate || rule.refuses(r) === null);
   const env = standing.environment ?? null;
   const since = standing.timestamp;
   const planDigest = standing.planDigest;
@@ -156,7 +168,8 @@ function decide(component: string, standing: PendingGateRecord, resolutions: Gat
     expiresAt: standing.expiresAt,
     approvals: approvals.map(approvalOf),
     needed,
-    approve: approveCommand(component, gate, env, planDigest),
+    signed: rule === null ? null : { class: rule.requirement.class },
+    approve: approveCommand(component, gate, env, planDigest, rule !== null),
   };
 }
 
@@ -167,7 +180,7 @@ function decide(component: string, standing: PendingGateRecord, resolutions: Gat
  * gate whose other facts have one is left out, as a run leaves it out: such a
  * line binds no environment, and `chant approve --expire` writes one.
  */
-export function gatesInLedger(component: string, content: string, envs: readonly string[], now: string): { gates: StatusGate[]; malformed: number } {
+export function gatesInLedger(component: string, content: string, envs: readonly string[], now: string, rules: GateRuleLookup = () => null): { gates: StatusGate[]; malformed: number } {
   const { pending, resolutions, malformed } = parseGateLedger(content);
   const gates: StatusGate[] = [];
   for (const gate of [...new Set(pending.map((p) => p.gate))].sort()) {
@@ -181,7 +194,7 @@ export function gatesInLedger(component: string, content: string, envs: readonly
       byEnv.set(env, [...(byEnv.get(env) ?? []), p]);
     }
     for (const env of [...byEnv.keys()].sort((a, b) => envs.indexOf(a ?? "") - envs.indexOf(b ?? ""))) {
-      gates.push(decide(component, latestPendingGate(byEnv.get(env)!, gate)!, resolutions, now));
+      gates.push(decide(component, latestPendingGate(byEnv.get(env)!, gate)!, resolutions, now, rules(gate)));
     }
   }
   return { gates, malformed };
@@ -196,6 +209,7 @@ export async function readMemberGates(
   cwd: string,
   now: string,
   read: GateLedgerReader = defaultGateLedgerReader,
+  rules: GateRuleLookup = () => null,
 ): Promise<{ gates: StatusGate[]; ledger: StatusGateLedger }> {
   const ledger: StatusGateLedger = { layout, path: dir, shared: false, malformed: 0, reason: null };
   if (commit === null) {
@@ -213,7 +227,7 @@ export async function readMemberGates(
   }
   const gates: StatusGate[] = [];
   for (const component of [...files.keys()].sort()) {
-    const read = gatesInLedger(component, files.get(component)!, envs, now);
+    const read = gatesInLedger(component, files.get(component)!, envs, now, rules);
     gates.push(...read.gates);
     ledger.malformed += read.malformed;
   }

package/src/workspace/status.schema.json

@@ -31,6 +31,25 @@
             }
           }
         },
+        "checkout": {
+          "description": "Added in contract 1 by #3160. The branch, head and base of the checkout status ran in. records --uncommitted --json lists the records that working tree holds modified or new against head.",
+          "type": "object",
+          "required": ["branch", "head", "base", "baseFrom"],
+          "properties": {
+            "branch": { "type": ["string", "null"], "description": "The checked-out branch's short name, such as chant/work/w-12, or null when HEAD is detached." },
+            "head": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit id HEAD names, or null before the first commit." },
+            "base": {
+              "type": ["string", "null"],
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The merge base of head and the target branch tip (origin/HEAD, else main, else master), the commit the branch forked from. Null without a head, a target, or common history."
+            },
+            "baseFrom": { "enum": ["origin/HEAD", "main", "master", null], "description": "Where the target branch was found; null when there is none." }
+          }
+        },
+        "plantable": {
+          "description": "Added in contract 1 by #3146. Whether a host such as a studio's planter can plant the workspace as one box: exactly one member's box block declares services. Not a check: a records-only or infra workspace is valid and simply not plantable.",
+          "$ref": "#/$defs/plantable"
+        },
         "workspace": {
           "type": "object",
           "required": ["name", "root", "file"],
@@ -470,6 +489,14 @@
       "type": "object",
       "required": ["capabilities", "isolation", "intent", "services"],
       "properties": {
+        "factory": {
+          "description": "Added in contract 1 by #3146. What the box builds and how (ws-077), with every default filled in, or null when the block declares no factory. At most one member's box has one.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/factory" }]
+        },
+        "listing": {
+          "description": "Added in contract 1 by #3146. What the box shows of itself on a home site, or null when the block declares no listing.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/listing" }]
+        },
         "services": {
           "description": "The services the box block declares (#2880), in declaration order, or empty when it declares none. A reader has them before any converge tick; a steward's ConvergeOp's lastTick carries each one's verdict. cmd is as declared: its ${VAR} references are left for the process that applies it to expand. Added by chant 0.95.0.",
           "type": "array",
@@ -510,6 +537,91 @@
         }
       }
     },
+    "plantable": {
+      "type": "object",
+      "required": ["plantable", "box", "reason"],
+      "properties": {
+        "plantable": { "type": "boolean" },
+        "box": { "type": ["string", "null"], "description": "The member whose box block declares services, or null when the workspace isn't plantable." },
+        "reason": {
+          "description": "Why the workspace isn't plantable, or null when it is.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["box-none", "box-several"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "factory": {
+      "type": "object",
+      "required": ["builds", "check", "checks", "builders", "publish"],
+      "properties": {
+        "builds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>." },
+        "check": {
+          "description": "The verdict command, run from the workspace root, and what it is; null when none is declared.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["run", "kind"],
+              "properties": {
+                "run": { "type": "string" },
+                "kind": { "enum": ["test", "build", "lint", "plan", "conformance"] }
+              }
+            }
+          ]
+        },
+        "checks": { "type": ["string", "null"], "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice." },
+        "builders": { "type": ["string", "null"], "description": "The member that declares the builder agents, or null." },
+        "publish": {
+          "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["forge", "repo", "base", "branchPrefix", "head"],
+              "properties": {
+                "forge": { "const": "github" },
+                "repo": { "type": "string", "description": "owner/name: where the pull request is opened." },
+                "base": { "type": ["string", "null"], "description": "The branch the pull request targets, or null for the repository's default branch." },
+                "branchPrefix": { "type": "string", "description": "What the published branch's name starts with, before the work item's id. chant/work/ unless declared." },
+                "head": { "type": ["string", "null"], "description": "owner/name of the fork the branch is pushed to, or null to push to repo." }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "required": ["published", "title", "line", "cover"],
+      "properties": {
+        "published": { "type": "boolean", "description": "Whether the box is listed; true unless declared otherwise." },
+        "title": { "type": "string", "description": "Empty when not declared: a reader shows a name of its own." },
+        "line": { "type": "string", "description": "Empty when not declared." },
+        "cover": {
+          "description": "The cover image, or null when none is declared.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["path", "sha256"],
+              "properties": {
+                "path": { "type": "string", "description": "From the workspace root." },
+                "sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "The sha256 of the file's bytes in the working tree, or null when it can't be read." }
+              }
+            }
+          ]
+        }
+      }
+    },
     "isolation": {
       "type": "object",
       "required": ["host", "slot", "portRange", "ports", "stateDir", "state", "cookies"],
@@ -571,7 +683,7 @@
     },
     "gate": {
       "type": "object",
-      "required": ["component", "name", "env", "planDigest", "state", "recordedAt", "expiresAt", "approvals", "needed", "approve"],
+      "required": ["component", "name", "env", "planDigest", "state", "recordedAt", "expiresAt", "approvals", "needed", "signed", "approve"],
       "properties": {
         "component": { "type": "string", "description": "The ledger file's key: the component, or the op for a gate an Op run reached." },
         "name": { "type": "string", "description": "The gate's name." },
@@ -600,7 +712,20 @@
           }
         },
         "needed": { "type": "integer", "minimum": 1, "description": "The human approvals the gate needs: its quorum's count, 1 without one." },
-        "approve": { "type": "string", "description": "The chant approve line for the gate, run in the member's directory: chant approve <component> <gate>, with --env <env> when env is not null and --plan <planDigest> when planDigest is not null (#2832), so the line approves the plan this read showed." }
+        "signed": {
+          "description": "Added in contract 1 by #3163. The declaration's rule for the gate, read at base (identity.gates, ws-080): only an approval sealed with chant approve --sign by a key the signers file at base lists for its approver counts, and when class is not null, only one whose approver the role grants at base put in that class. Approvals that don't meet it are left out of approvals and state. Null when any approval counts.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["class"],
+              "properties": {
+                "class": { "type": ["string", "null"], "description": "The principal class the signer must be in, or null for any listed signer." }
+              }
+            }
+          ]
+        },
+        "approve": { "type": "string", "description": "The chant approve line for the gate, run in the member's directory: chant approve <component> <gate>, with --env <env> when env is not null and --plan <planDigest> when planDigest is not null (#2832), so the line approves the plan this read showed, and --sign when signed is not null (#3163). The caller adds --actor <principal>." }
       }
     },
     "environment": {

package/src/workspace/status.ts

@@ -41,11 +41,15 @@ import { readPathSha } from "../lifecycle/git";
 import { latestPerComponent, readReleaseLedger, type ReleaseRecord } from "../lifecycle/release-ledger";
 import { readReleasePlan, type ReleasePlan } from "../lifecycle/plan-ledger";
 import { listWorkLeases, type WorkLeaseState } from "../lifecycle/work-lease";
+import { readCheckoutHead, type CheckoutHead } from "./records-checkout";
 import { findWorkspaceRoot } from "../project-root";
 import { resolveBoxes, type ResolvedIsolation } from "./box-isolation";
 import { resolveBoxIntents, unresolvedIntent, type BoxIntent } from "./box-intent";
+import { factoryView, listingView, plantability, treeBytes, type FactoryView, type ListingView, type Plantable } from "./box-factory";
 import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
+import { gateAdmissionFrom } from "./identity";
+import { scopeSource } from "./write-scope";
 import { GATE_REASON_CODES, readMemberGates, type GateLedgerReader, type StatusGate, type StatusGateLedger } from "./status-gates";
 import { STEWARD_REASON_CODES, readMemberStewards, type StatusSteward, type StewardReasonCode } from "./status-stewards";
 import { gitTop, workingTree } from "./tree";
@@ -188,6 +192,10 @@ export interface StatusBox {
   intent: BoxIntent | null;
   /** The services the block declares (#2880), in file order, so a reader has them before any converge tick. Empty when it declares none. */
   services: StatusBoxService[];
+  /** What the box builds and how, with defaults filled in (#3146, ws-077), or null when the block declares no factory. */
+  factory: FactoryView | null;
+  /** What the box shows of itself on a home site, with the cover's sha256 (#3146), or null when the block declares no listing. */
+  listing: ListingView | null;
 }
 
 /** A declared box service as `status --json` prints it (#2880): every field present, null or false when not declared. */
@@ -234,7 +242,11 @@ export type StatusDocument =
       env: string;
       compareTo: string | null;
       lifecycle: { ref: string; commit: string | null };
+      /** The branch, head and base of the checkout read (#3160). `records --uncommitted` lists the records it holds uncommitted. */
+      checkout: CheckoutHead;
       workspace: { name: string; root: string; file: string };
+      /** Whether a host can plant the workspace as one box (#3146): exactly one member's box block declares services. */
+      plantable: Plantable;
       members: StatusMember[];
       /** Every work lease in the workspace's ledgers, active and expired, by member then item (#2732). A released lease has no ref and is not listed. */
       leases: StatusLease[];
@@ -399,12 +411,16 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
 
     const isolation = new Map(resolveBoxes(declaration).map((b) => [b.member.name, b.isolation]));
     const intents = new Map((await resolveBoxIntents(declaration, found.dir)).map((i) => [i.member, i.record?.intent ?? unresolvedIntent(i.id)]));
+    const coverBytes = treeBytes(workingTree(found.dir));
+    // #3163: the declaration's identity.gates at base, read once for every member's gates.
+    const ruleSource = scopeSource(found.dir);
+    const rules = (gate: string) => gateAdmissionFrom(ruleSource, gate);
     const members: StatusMember[] = [];
     for (const m of declaration.members) {
       const environments: StatusEnvironment[] = [];
       for (const env of envs) environments.push(await readEnvironment(m, env, found.dir, read));
       const own = await hasMemberLedger(m, found.dir);
-      const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates);
+      const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates, rules);
       const stewards = await (query.readStewards ?? readMemberStewards)(resolve(found.dir, m.dir), query.env, now, m.kind, m.box);
       members.push({
         name: m.name,
@@ -431,6 +447,8 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
                   health: s.health,
                   optional: s.optional,
                 })),
+                factory: factoryView(m.box.factory),
+                listing: listingView(m.box.listing, coverBytes),
               },
         stewards: stewards.stewards,
         stewardReasons: stewards.reasons,
@@ -451,7 +469,9 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       env: query.env,
       compareTo: query.compareTo ?? null,
       lifecycle: { ref: LIFECYCLE_REF, commit },
+      checkout: readCheckoutHead(top),
       workspace: { name: declaration.name, root: rootDir === "" ? "." : rootDir, file: declaration.file },
+      plantable: plantability(declaration),
       members,
       leases,
       acceptance,

package/src/workspace/symbols.ts

@@ -0,0 +1,180 @@
+/**
+ * Symbol regions for the intent walk (#3034): `graph --intent <path>#<symbol>`
+ * names a function, class, method, type or constant instead of a line range,
+ * because a line range means something else once the file is edited.
+ *
+ * A resolver turns a symbol into its current lines in the tree read, and the
+ * walk follows those lines through history as it follows any line range
+ * (`git log -L`). Resolvers are chosen by file extension. Core ships one for
+ * TypeScript and JavaScript, parsed with the TypeScript compiler chant already
+ * depends on; a file with no resolver is refused with
+ * `intent-symbol-unsupported`, and a line range still works for it.
+ *
+ * A symbol is a name, or a dotted path through classes, namespaces,
+ * interfaces, enums and object literals bound to a constant, such as
+ * `createApp` or `Server.listen`. A bare name is looked up among the
+ * file's top-level declarations first, then among every nested one; when it
+ * matches more than one declaration it is refused as ambiguous, with the
+ * qualified names that would pick one. The lines run from the declaration's
+ * doc comment, when it has one, to its last line.
+ */
+
+import * as ts from "typescript";
+import type { LineRange } from "./intent";
+
+/** One declaration a resolver found. */
+export interface SymbolDeclaration {
+  /** The dotted path from the file's top level, such as `Server.listen`. */
+  qualified: string;
+  /** What declares it: function, class, method, property, interface, type, enum, namespace, variable, member. */
+  kind: string;
+  lines: LineRange;
+}
+
+export type SymbolResolution =
+  | { ok: true; declaration: SymbolDeclaration }
+  | { ok: false; reason: "unsupported" | "unknown" | "ambiguous"; message: string; candidates: string[] };
+
+/** A language-aware resolver: every declaration in a file, by qualified name. */
+export interface SymbolResolver {
+  /** The language it reads, for messages. */
+  language: string;
+  extensions: readonly string[];
+  declarations(path: string, text: string): SymbolDeclaration[];
+}
+
+// ── TypeScript and JavaScript ────────────────────────────────────────────────
+
+function scriptKind(path: string): ts.ScriptKind {
+  if (/\.tsx$/.test(path)) return ts.ScriptKind.TSX;
+  if (/\.jsx$/.test(path)) return ts.ScriptKind.JSX;
+  if (/\.[cm]?js$/.test(path)) return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+}
+
+function nameText(name: ts.PropertyName | ts.BindingName | ts.ModuleName | undefined): string | undefined {
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+  return undefined;
+}
+
+const typescriptResolver: SymbolResolver = {
+  language: "TypeScript and JavaScript",
+  extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
+  declarations(path, text) {
+    const sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path));
+    const out: SymbolDeclaration[] = [];
+    const lineOf = (pos: number) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+    // The span: from the doc comment (or the statement holding a lone variable) to the node's end.
+    const push = (qualified: string, kind: string, node: ts.Node) => {
+      out.push({ qualified, kind, lines: { start: lineOf(node.getStart(sf, true)), end: lineOf(node.getEnd()) } });
+    };
+    const visitMembers = (prefix: string, members: ts.NodeArray<ts.Node>) => {
+      for (const m of members) {
+        const name = nameText((m as ts.NamedDeclaration).name as ts.PropertyName | undefined);
+        if (name === undefined) {
+          if (ts.isConstructorDeclaration(m)) push(`${prefix}.constructor`, "method", m);
+          continue;
+        }
+        const q = `${prefix}.${name}`;
+        if (ts.isMethodDeclaration(m) || ts.isMethodSignature(m) || ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) push(q, "method", m);
+        else if (ts.isPropertyDeclaration(m) || ts.isPropertySignature(m)) {
+          push(q, "property", m);
+          if (ts.isPropertyDeclaration(m) && m.initializer) visitValue(q, m.initializer);
+        } else if (ts.isEnumMember(m)) push(q, "member", m);
+        else if (ts.isPropertyAssignment(m)) {
+          push(q, "property", m);
+          visitValue(q, m.initializer);
+        } else if (ts.isShorthandPropertyAssignment(m)) push(q, "property", m);
+      }
+    };
+    // A class expression or object literal bound to a name has members of its own.
+    const visitValue = (prefix: string, value: ts.Expression) => {
+      let v = value;
+      while (ts.isParenthesizedExpression(v) || ts.isAsExpression(v) || ts.isSatisfiesExpression(v)) v = v.expression;
+      if (ts.isClassExpression(v)) visitMembers(prefix, v.members);
+      else if (ts.isObjectLiteralExpression(v)) visitMembers(prefix, v.properties);
+    };
+    const visitStatements = (prefix: string, statements: ts.NodeArray<ts.Statement>) => {
+      const q = (name: string) => (prefix ? `${prefix}.${name}` : name);
+      for (const s of statements) {
+        if (ts.isFunctionDeclaration(s) && s.name) push(q(s.name.text), "function", s);
+        else if (ts.isClassDeclaration(s) && s.name) {
+          push(q(s.name.text), "class", s);
+          visitMembers(q(s.name.text), s.members);
+        } else if (ts.isInterfaceDeclaration(s)) {
+          push(q(s.name.text), "interface", s);
+          visitMembers(q(s.name.text), s.members);
+        } else if (ts.isTypeAliasDeclaration(s)) push(q(s.name.text), "type", s);
+        else if (ts.isEnumDeclaration(s)) {
+          push(q(s.name.text), "enum", s);
+          visitMembers(q(s.name.text), s.members);
+        } else if (ts.isModuleDeclaration(s)) {
+          const name = nameText(s.name);
+          if (name === undefined) continue;
+          push(q(name), "namespace", s);
+          let body = s.body;
+          let inner = q(name);
+          while (body && ts.isModuleDeclaration(body)) {
+            inner = `${inner}.${nameText(body.name)}`;
+            body = body.body;
+          }
+          if (body && ts.isModuleBlock(body)) visitStatements(inner, body.statements);
+        } else if (ts.isVariableStatement(s)) {
+          const lone = s.declarationList.declarations.length === 1;
+          for (const d of s.declarationList.declarations) {
+            const name = nameText(d.name);
+            if (name === undefined) continue;
+            // A lone declaration takes its statement's lines, so `export const x = ...` and its doc comment are in the region.
+            push(q(name), "variable", lone ? s : d);
+            if (d.initializer) visitValue(q(name), d.initializer);
+          }
+        } else if (ts.isExportAssignment(s) && !s.isExportEquals) {
+          push(q("default"), "variable", s);
+          visitValue(q("default"), s.expression);
+        }
+      }
+    };
+    visitStatements("", sf.statements);
+    return out;
+  },
+};
+
+/** The resolvers core ships, chosen by the file's extension. */
+export const SYMBOL_RESOLVERS: readonly SymbolResolver[] = [typescriptResolver];
+
+/** The resolver for a path, or undefined when none reads its language. */
+export function symbolResolverFor(path: string): SymbolResolver | undefined {
+  const lower = path.toLowerCase();
+  return SYMBOL_RESOLVERS.find((r) => r.extensions.some((e) => lower.endsWith(e)));
+}
+
+/** Resolve `symbol` in the file `path` holding `text`: its current lines, or why it can't be. */
+export function resolveSymbol(path: string, text: string, symbol: string): SymbolResolution {
+  const resolver = symbolResolverFor(path);
+  if (!resolver) {
+    const known = SYMBOL_RESOLVERS.flatMap((r) => r.extensions).join(", ");
+    return { ok: false, reason: "unsupported", message: `${path} has no symbol resolver: symbols resolve in ${known} files. Give a line range, ${path}:<start>-<end>, instead`, candidates: [] };
+  }
+  const all = resolver.declarations(path, text);
+  const exact = all.filter((d) => d.qualified === symbol);
+  // A name declared twice at one path, such as an overload or a merged declaration, is one region from the first to the last.
+  if (exact.length > 0) {
+    const start = Math.min(...exact.map((d) => d.lines.start));
+    const end = Math.max(...exact.map((d) => d.lines.end));
+    return { ok: true, declaration: { qualified: symbol, kind: exact[0].kind, lines: { start, end } } };
+  }
+  const nested = [...new Set(all.filter((d) => d.qualified.endsWith(`.${symbol}`)).map((d) => d.qualified))];
+  if (nested.length === 1) return resolveSymbol(path, text, nested[0]);
+  if (nested.length > 1) {
+    return { ok: false, reason: "ambiguous", message: `${symbol} names ${nested.length} declarations in ${path}: ${nested.join(", ")}. Give the qualified name`, candidates: nested };
+  }
+  const top = [...new Set(all.filter((d) => !d.qualified.includes(".")).map((d) => d.qualified))];
+  const shown = top.slice(0, 20);
+  return {
+    ok: false,
+    reason: "unknown",
+    message: `${path} declares no ${symbol}${top.length > 0 ? `; its top-level declarations are ${shown.join(", ")}${top.length > shown.length ? `, and ${top.length - shown.length} more` : ""}` : ", and no top-level declaration a resolver reads"}`,
+    candidates: shown,
+  };
+}