chainlesschain 0.162.162 → 0.162.164

package/src/lib/capability-manifest.js

@@ -0,0 +1,319 @@
+/**
+ * Canonical capability manifest — the single source the CLI capability output,
+ * the VS Code / JetBrains negotiation, the protocol docs, the compatibility
+ * fixture, the behavior matrix and the release-notes capability diff all project
+ * from (P1-9 "Capability Manifest 与脱敏诊断包" of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md).
+ *
+ * Today the wire-protocol capability surface is hand-authored in THREE places
+ * that can silently drift:
+ *   - [[capability-negotiation.js]]: `PROTOCOL_FEATURES`, `FEATURE_MIN_VERSION`,
+ *     and the private `FEATURE_TO_FIELD` map.
+ *   - [[headless-manifest.js]]: `buildAgentCapabilities().features` (the
+ *     `cc agent --capabilities` output).
+ *   - the Java twin + the shared negotiation fixture.
+ * A new v2 field added to one list but not the others parses wrong on the peer
+ * that missed it. This module is the ONE definition; every other shape is a pure
+ * projection of it, and a drift-guard test asserts the live hand-authored
+ * constants still equal the projection (see capability-manifest.test.js).
+ *
+ * Pure: no fs / process / clock. Projections are deterministic so a caller can
+ * regenerate docs/fixtures and diff them against the checked-in copies in CI.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * THE canonical manifest. `wireFeatures` is the negotiable additive per-line
+ * field set (order mirrors capability-negotiation.js `PROTOCOL_FEATURES`);
+ * `runtimeFeatures` are the boolean capability flags that change what the CLI
+ * can DO (not the shape of a line the client must parse) and are NOT negotiated.
+ */
+export const CAPABILITY_MANIFEST = Object.freeze({
+  name: "chainlesschain-cli",
+  protocolVersion: 1,
+  minProtocolVersion: 1,
+
+  wireFeatures: Object.freeze([
+    Object.freeze({
+      key: "event_seq",
+      field: "seq",
+      minVersion: 1,
+      description:
+        "every stream-json stdout line carries a monotonic per-run `seq`",
+    }),
+    Object.freeze({
+      key: "tool_use_id",
+      field: "tool_use_id",
+      minVersion: 1,
+      description:
+        'tool_use / tool_result lines carry a pairing `id` ("tu-<n>")',
+    }),
+    Object.freeze({
+      key: "trace_id",
+      field: "trace_id",
+      minVersion: 1,
+      description:
+        "each line carries a run-scoped, caller-injectable `trace_id` for IDE ↔ CLI correlation",
+    }),
+  ]),
+
+  // Boolean capability flags (buildAgentCapabilities().features truthy keys).
+  runtimeFeatures: Object.freeze([
+    "bare",
+    "safe_mode",
+    "ephemeral",
+    "background",
+    "worktree",
+    "checkpoint",
+    "json_schema_output",
+    "partial_messages",
+    "interactive_approvals",
+    "permission_prompt_tool",
+    "remote_control",
+  ]),
+
+  mcpFeatures: Object.freeze([
+    "config_file",
+    "registry",
+    "tool_search",
+    "oauth",
+    "managed_allowlist",
+  ]),
+  sandboxEngines: Object.freeze(["docker", "bubblewrap"]),
+
+  permissionModes: Object.freeze([
+    "default",
+    "manual",
+    "auto",
+    "dontAsk",
+    "plan",
+    "acceptEdits",
+    "bypassPermissions",
+  ]),
+  outputFormats: Object.freeze(["text", "json", "stream-json"]),
+  inputFormats: Object.freeze(["text", "stream-json"]),
+});
+
+const manifestOr = (m) =>
+  m && typeof m === "object" ? m : CAPABILITY_MANIFEST;
+const wireFeaturesOf = (m) =>
+  Array.isArray(manifestOr(m).wireFeatures) ? manifestOr(m).wireFeatures : [];
+
+/**
+ * The negotiable wire feature keys, in canonical declared order — the value
+ * capability-negotiation.js `PROTOCOL_FEATURES` must equal.
+ * @returns {string[]}
+ */
+export function toProtocolFeatures(m = CAPABILITY_MANIFEST) {
+  return wireFeaturesOf(m).map((f) => f.key);
+}
+
+/**
+ * Feature → minimum protocol version, ONLY for features gated above the base
+ * version (a v1-additive field is absent, matching an empty
+ * `FEATURE_MIN_VERSION` today). Adding a v2 feature here flows the gate to the
+ * negotiator automatically.
+ * @returns {Record<string, number>}
+ */
+export function toFeatureMinVersion(m = CAPABILITY_MANIFEST) {
+  const out = {};
+  for (const f of wireFeaturesOf(m)) {
+    if (Number(f.minVersion) > 1) out[f.key] = Number(f.minVersion);
+  }
+  return out;
+}
+
+/**
+ * Feature → the stream line field it gates (the value of the private
+ * `FEATURE_TO_FIELD` map in capability-negotiation.js).
+ * @returns {Record<string, string>}
+ */
+export function toFieldGate(m = CAPABILITY_MANIFEST) {
+  const out = {};
+  for (const f of wireFeaturesOf(m)) out[f.key] = f.field;
+  return out;
+}
+
+/**
+ * The server negotiation offer shape consumed by
+ * capability-negotiation.js `negotiateProtocol(server, …)`.
+ * @returns {{protocolVersion:number, minProtocolVersion:number, features:string[]}}
+ */
+export function toServerOffer(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  return {
+    protocolVersion: Number(mm.protocolVersion) || 1,
+    minProtocolVersion: Number(mm.minProtocolVersion) || 1,
+    features: toProtocolFeatures(mm),
+  };
+}
+
+/**
+ * The `features` object of `cc agent --capabilities`
+ * (buildAgentCapabilities().features): every runtime flag true, every wire
+ * feature true, plus the nested `mcp` object and `sandbox_engines` list. A test
+ * asserts the live buildAgentCapabilities().features deep-equals this.
+ * @returns {object}
+ */
+export function toAgentFeatureFlags(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const flags = {};
+  for (const key of mm.runtimeFeatures || []) flags[key] = true;
+  for (const f of wireFeaturesOf(mm)) flags[f.key] = true;
+  flags.mcp = {};
+  for (const key of mm.mcpFeatures || []) flags.mcp[key] = true;
+  flags.sandbox_engines = [...(mm.sandboxEngines || [])];
+  return flags;
+}
+
+/**
+ * A deterministic capability fixture the VS Code / JetBrains twins can pin and
+ * assert against (the "Compatibility Fixture" the gap doc asks for). Order- and
+ * clock-independent; a `digest` lets a peer detect any change in one compare.
+ * @returns {object}
+ */
+export function buildCompatFixture(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const body = {
+    protocolVersion: Number(mm.protocolVersion) || 1,
+    minProtocolVersion: Number(mm.minProtocolVersion) || 1,
+    features: toProtocolFeatures(mm),
+    featureFields: toFieldGate(mm),
+    featureMinVersion: toFeatureMinVersion(mm),
+    permissionModes: [...(mm.permissionModes || [])],
+    outputFormats: [...(mm.outputFormats || [])],
+    inputFormats: [...(mm.inputFormats || [])],
+  };
+  return { ...body, digest: capabilityDigest(mm) };
+}
+
+/**
+ * A stable digest of the whole capability surface (no RNG/clock) — one string
+ * that changes iff any projected capability changed. Handy as a CI drift check.
+ * @returns {string} 16-hex-char sha256 prefix
+ */
+export function capabilityDigest(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const canonical = {
+    protocolVersion: Number(mm.protocolVersion) || 1,
+    minProtocolVersion: Number(mm.minProtocolVersion) || 1,
+    wire: wireFeaturesOf(mm)
+      .map((f) => [f.key, f.field, Number(f.minVersion) || 1])
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)),
+    runtime: [...(mm.runtimeFeatures || [])].sort(),
+    mcp: [...(mm.mcpFeatures || [])].sort(),
+    sandbox: [...(mm.sandboxEngines || [])].sort(),
+    permissionModes: [...(mm.permissionModes || [])].sort(),
+    outputFormats: [...(mm.outputFormats || [])].sort(),
+    inputFormats: [...(mm.inputFormats || [])].sort(),
+  };
+  return createHash("sha256")
+    .update(JSON.stringify(canonical))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/**
+ * A behavior matrix row per wire feature — feature × min version × gated field ×
+ * negotiable × description. Consumed by renderProtocolDoc and by a test that a
+ * doc table matches the code.
+ * @returns {Array<{feature:string, minVersion:number, field:string, negotiable:boolean, description:string}>}
+ */
+export function renderBehaviorMatrix(m = CAPABILITY_MANIFEST) {
+  return wireFeaturesOf(m).map((f) => ({
+    feature: f.key,
+    minVersion: Number(f.minVersion) || 1,
+    field: f.field,
+    negotiable: true,
+    description: String(f.description || ""),
+  }));
+}
+
+/**
+ * Render the protocol capability section as Markdown (a generated doc a CI job
+ * diffs against the checked-in copy). Deterministic; ends with a trailing
+ * newline so a byte compare is stable.
+ * @returns {string}
+ */
+export function renderProtocolDoc(m = CAPABILITY_MANIFEST) {
+  const mm = manifestOr(m);
+  const lines = [];
+  lines.push("# Agent Protocol Capability Manifest (generated)");
+  lines.push("");
+  lines.push(
+    `Protocol version **${mm.protocolVersion}** (negotiates down to **${mm.minProtocolVersion}**).`,
+  );
+  lines.push("");
+  lines.push("## Negotiable wire features");
+  lines.push("");
+  lines.push("| Feature | Min version | Line field | Description |");
+  lines.push("| ------- | ----------- | ---------- | ----------- |");
+  for (const row of renderBehaviorMatrix(mm)) {
+    lines.push(
+      `| \`${row.feature}\` | ${row.minVersion} | \`${row.field}\` | ${row.description} |`,
+    );
+  }
+  lines.push("");
+  lines.push("## Permission modes");
+  lines.push("");
+  lines.push((mm.permissionModes || []).map((x) => `\`${x}\``).join(", "));
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Capability diff for release notes: what changed between a previous and a next
+ * manifest (or a manifest and the current canonical one). Additive vs removed vs
+ * min-version/field changes, plus any protocol-version bump.
+ *
+ * @param {object} prev  a manifest (or its compat fixture)
+ * @param {object} [next=CAPABILITY_MANIFEST]
+ * @returns {{protocolChange:{from:number,to:number}|null,
+ *            addedWireFeatures:string[], removedWireFeatures:string[],
+ *            changedWireFeatures:Array<{feature:string, from:object, to:object}>,
+ *            addedRuntimeFeatures:string[], removedRuntimeFeatures:string[]}}
+ */
+export function diffCapabilities(prev, next = CAPABILITY_MANIFEST) {
+  const wireMap = (m) => {
+    const out = new Map();
+    for (const f of wireFeaturesOf(m)) {
+      out.set(f.key, {
+        field: f.field,
+        minVersion: Number(f.minVersion) || 1,
+      });
+    }
+    return out;
+  };
+  const runtimeSet = (m) => new Set(manifestOr(m).runtimeFeatures || []);
+
+  const p = wireMap(prev);
+  const n = wireMap(next);
+  const addedWireFeatures = [...n.keys()].filter((k) => !p.has(k)).sort();
+  const removedWireFeatures = [...p.keys()].filter((k) => !n.has(k)).sort();
+  const changedWireFeatures = [];
+  for (const [key, nv] of n) {
+    const pv = p.get(key);
+    if (pv && (pv.field !== nv.field || pv.minVersion !== nv.minVersion)) {
+      changedWireFeatures.push({ feature: key, from: pv, to: nv });
+    }
+  }
+
+  const pr = runtimeSet(prev);
+  const nr = runtimeSet(next);
+  const addedRuntimeFeatures = [...nr].filter((k) => !pr.has(k)).sort();
+  const removedRuntimeFeatures = [...pr].filter((k) => !nr.has(k)).sort();
+
+  const pVer = Number(manifestOr(prev).protocolVersion) || 1;
+  const nVer = Number(manifestOr(next).protocolVersion) || 1;
+  const protocolChange = pVer === nVer ? null : { from: pVer, to: nVer };
+
+  return {
+    protocolChange,
+    addedWireFeatures,
+    removedWireFeatures,
+    changedWireFeatures,
+    addedRuntimeFeatures,
+    removedRuntimeFeatures,
+  };
+}

package/src/lib/capability-negotiation.js

@@ -36,31 +36,42 @@
  * fixture __tests__/fixtures/capability-negotiation-cases.json.
  */
 
+import {
+  CAPABILITY_MANIFEST,
+  toProtocolFeatures,
+  toFeatureMinVersion,
+  toFieldGate,
+} from "./capability-manifest.js";
+
 /** The current protocol version the CLI speaks (mirror of PROTOCOL_VERSION). */
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = CAPABILITY_MANIFEST.protocolVersion;
 
 /**
  * The oldest protocol version the CLI can still speak end-to-end (the N-1 in
  * "N / N-1"). At v1 there is no older line shape, so min === current; once v2
  * ships this drops to 1 so a v1-only client negotiates a v1 session.
  */
-export const PROTOCOL_MIN_VERSION = 1;
+export const PROTOCOL_MIN_VERSION = CAPABILITY_MANIFEST.minProtocolVersion;
 
 /**
  * The wire-protocol features subject to negotiation — the additive per-line
  * fields a client may or may not understand. Runtime capabilities (bare,
  * worktree, mcp, …) are NOT negotiated: they change what the CLI can do, not
  * the shape of a line the client must parse.
+ *
+ * P1-9: projected from the single canonical [[capability-manifest.js]] so the
+ * negotiator, `cc agent --capabilities`, the protocol docs and the Java twin can
+ * no longer drift — add a v2 field to the manifest ONCE and it flows here.
  */
-export const PROTOCOL_FEATURES = ["event_seq", "tool_use_id", "trace_id"];
+export const PROTOCOL_FEATURES = toProtocolFeatures();
 
 /**
  * Minimum protocol version a feature requires. Empty today (every current
- * feature is a v1 additive field). When a v2 field lands, add it here so an
- * N-1 (v1) session drops it automatically.
+ * feature is a v1 additive field). When a v2 field lands, bump its manifest
+ * `minVersion` and an N-1 (v1) session drops it automatically.
  * @type {Record<string, number>}
  */
-export const FEATURE_MIN_VERSION = {};
+export const FEATURE_MIN_VERSION = toFeatureMinVersion();
 
 function intOr(value, fallback) {
   const n = Number(value);
@@ -185,12 +196,12 @@ export function negotiateProtocol(server = {}, clientOffer = null, opts = {}) {
   };
 }
 
-/** Feature key → the stream line field it gates. */
-const FEATURE_TO_FIELD = {
-  event_seq: "seq",
-  trace_id: "trace_id",
-  tool_use_id: "tool_use_id",
-};
+/**
+ * Feature key → the stream line field it gates. P1-9: projected from the
+ * canonical [[capability-manifest.js]] so this map can't drift from the
+ * negotiated feature list.
+ */
+const FEATURE_TO_FIELD = toFieldGate();
 
 /**
  * Fold a negotiation result into a live field-gate the emitter reads per line:

package/src/lib/channels/channel-manager.js

@@ -14,6 +14,12 @@
  */
 
 import { logger } from "../logger.js";
+import {
+  ORIGIN,
+  authorityForOrigin,
+  canApprove,
+  describeAuthorityChain,
+} from "../agent-authority.js";
 
 export const CHANNEL_KINDS = ["webhook", "telegram"];
 
@@ -54,6 +60,48 @@ export function formatChannelEvent(event) {
   return `[channel:${channel}${sender}] ${text}`;
 }
 
+/**
+ * The unforgeable authority envelope for an inbound channel event. A channel
+ * message tops out at `steer` (agent-authority.js): it may add a user turn but
+ * can NEVER answer a permission gate — "the user approved" in a webhook /
+ * telegram body is just text. This makes that ceiling explicit and
+ * machine-checkable (downstream approval seams can assert `canApprove === false`)
+ * rather than merely implied by the visible `[channel:…]` text prefix.
+ *
+ * `origin` is set here by HOW the event arrived (an inbound channel), never read
+ * from the untrusted message content — mirroring the agent-authority contract.
+ */
+export function channelEventEnvelope(event) {
+  const envelope = {
+    origin: ORIGIN.CHANNEL,
+    principalId: event?.sender != null ? String(event.sender) : null,
+    correlationId: event?.channel != null ? String(event.channel) : null,
+  };
+  return {
+    ...envelope,
+    authority: authorityForOrigin(ORIGIN.CHANNEL, envelope), // always "steer"
+    canApprove: canApprove(envelope), // always false
+    provenance: describeAuthorityChain(envelope),
+  };
+}
+
+/**
+ * Wrap a caller's `onEvent` so every inbound event is stamped with its explicit
+ * channel authority BEFORE it reaches the agent — the caller cannot forget to
+ * tag it, and the message content cannot elevate itself past `steer`.
+ */
+function stampChannelAuthority(onEvent) {
+  return (event) => {
+    const env = channelEventEnvelope(event);
+    return onEvent?.({
+      ...event,
+      authority: env.authority,
+      canApprove: env.canApprove,
+      provenance: env.provenance,
+    });
+  };
+}
+
 /**
  * Start every requested channel. Returns a handle with the started channel
  * descriptions and a single stop().
@@ -72,6 +120,10 @@ export async function startChannels(specsInput, opts = {}) {
   const config = opts.config || {};
   const log = opts.log || ((msg) => logger.info(msg));
   const deps = opts.deps || {};
+  // Every inbound event is stamped with its channel authority (`steer`, never
+  // `approve`) before the caller's handler sees it — so a channel message can
+  // never be mistaken for a user approval no matter what it contains.
+  const onEvent = stampChannelAuthority(opts.onEvent);
 
   const started = [];
   const stopAll = () => {
@@ -95,7 +147,7 @@ export async function startChannels(specsInput, opts = {}) {
         )({
           ...cfg,
           port: spec.arg ? Number(spec.arg) : cfg.port,
-          onEvent: opts.onEvent,
+          onEvent,
           log,
         });
         started.push({ kind: "webhook", describe: handle.describe, ...handle });
@@ -107,7 +159,7 @@ export async function startChannels(specsInput, opts = {}) {
           deps.telegram?.startTelegramChannel || startTelegramChannel
         )({
           ...cfg,
-          onEvent: opts.onEvent,
+          onEvent,
           log,
         });
         started.push({

package/src/lib/cli-context-engineering.js

@@ -46,11 +46,17 @@ export class CLIContextEngineering {
    * @param {string} [options.scope.taskId] - Task/sub-agent ID
    * @param {string} [options.scope.role] - Sub-agent role
    * @param {string} [options.scope.parentObjective] - Parent task objective
+   * @param {boolean} [options.memoryEnabled=true] - When false, hierarchical
+   *   memory recall is suppressed even if a `db` is present. The subagent
+   *   contract's `memory` boolean drives this for spawned children so a child
+   *   denied memory physically cannot recall it (defense-in-depth beyond the
+   *   spawn simply withholding the db).
    */
-  constructor({ db, permanentMemory, scope } = {}) {
+  constructor({ db, permanentMemory, scope, memoryEnabled = true } = {}) {
     this.db = db || null;
     this.permanentMemory = permanentMemory || null;
     this.scope = scope || null;
+    this.memoryEnabled = memoryEnabled !== false;
     this.errorHistory = [];
     this.taskContext = null;
     this._bm25 = null;
@@ -121,7 +127,8 @@ export class CLIContextEngineering {
     }
 
     // 3. Memory injection (scoped: higher threshold, namespace-aware)
-    if (this.db && userQuery) {
+    // Suppressed when memoryEnabled is false (subagent contract memory:false).
+    if (this.memoryEnabled && this.db && userQuery) {
       try {
         const memoryQuery = this.scope
           ? `[${this.scope.role}] ${userQuery}`

package/src/lib/context-breakdown.js

@@ -0,0 +1,116 @@
+/**
+ * Per-source token attribution for `cc context --sources` — the P1
+ * large-monorepo "/context 按来源分解" lever. The base `cc context` view buckets
+ * a session's stored messages by ROLE; this adds a BY-SOURCE view that also
+ * attributes the project-memory instruction files (cc.md / CLAUDE.md / rules /
+ * @imports) that would be loaded for the current working directory, each with
+ * its own token cost and provenance — so a user can see WHICH instruction file
+ * (or message class) fills the context window.
+ *
+ * Pure: token counting for instruction files is delegated to the injected
+ * estimator (the same CJK-aware `estimateTokens` the window sizing uses);
+ * message-role buckets already arrive pre-counted. No I/O.
+ *
+ * Scope note: skills and MCP tool schemas are runtime tool definitions loaded
+ * when an agent actually runs — they are NOT part of a persisted transcript nor
+ * of the project-instruction set, so they are intentionally not attributed here.
+ */
+
+import path from "path";
+
+/**
+ * Display path for an instruction source: relative-to-cwd when the file lives
+ * inside cwd, else the absolute path (a `~/.claude/…` user-scope file, or an
+ * @import that escaped the tree, is clearer shown in full).
+ */
+export function relativizeInstructionPath(absPath, cwd) {
+  if (!absPath) return "";
+  if (!cwd) return absPath;
+  try {
+    const rel = path.relative(cwd, absPath);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return absPath;
+    return rel.split(path.sep).join("/");
+  } catch {
+    return absPath;
+  }
+}
+
+/**
+ * Per-file instruction sources from `loadProjectInstructions().files`.
+ *
+ * @param {Array<{path,scope,content,truncated}>} files
+ * @param {(t:string)=>number} estimateTokens
+ * @param {string} [cwd]
+ * @returns {{ sources: Array<{scope,source,path,tokens,truncated}>, total:number }}
+ */
+export function breakdownInstructionSources(files, estimateTokens, cwd) {
+  const est = typeof estimateTokens === "function" ? estimateTokens : () => 0;
+  const list = Array.isArray(files) ? files : [];
+  const sources = list.map((f) => ({
+    scope: f?.scope || "project",
+    source: relativizeInstructionPath(f?.path, cwd),
+    path: f?.path || "",
+    tokens: est(typeof f?.content === "string" ? f.content : ""),
+    truncated: Boolean(f?.truncated),
+  }));
+  const total = sources.reduce((s, x) => s + x.tokens, 0);
+  return { sources, total };
+}
+
+// role bucket key → { label, kind } for the ranked source list.
+const MESSAGE_SOURCE_ROWS = [
+  ["system", "system messages", "message"],
+  ["user", "user messages", "message"],
+  ["assistant", "assistant messages", "message"],
+  ["tool", "tool results", "message"],
+  ["toolCalls", "tool calls", "tool_calls"],
+];
+
+/**
+ * Merge the project-memory instruction total with the per-role message buckets
+ * into ONE ranked source list (largest first) with each source's share of the
+ * combined by-source total. The message buckets are the same ones
+ * `categorizeContext` produces; instructions are folded in as a single group so
+ * the ranked view stays readable (per-file detail lives in the instructions
+ * breakdown).
+ *
+ * @param {object} args
+ * @param {number} [args.instructionTotal=0]  Σ instruction-file tokens
+ * @param {object} [args.buckets={}]           categorizeContext buckets
+ * @param {object} [args.counts={}]            categorizeContext counts
+ * @returns {{ sources: Array<{kind,source,tokens,count,share}>, total:number }}
+ */
+export function rankContextSources({
+  instructionTotal = 0,
+  buckets = {},
+  counts = {},
+} = {}) {
+  const rows = [];
+  if (instructionTotal > 0) {
+    rows.push({
+      kind: "instructions",
+      source: "project memory (instructions)",
+      tokens: instructionTotal,
+      count: null,
+    });
+  }
+  for (const [key, label, kind] of MESSAGE_SOURCE_ROWS) {
+    const tok = buckets[key] || 0;
+    if (tok > 0) {
+      rows.push({
+        kind,
+        source: label,
+        tokens: tok,
+        count: counts[key] ?? null,
+      });
+    }
+  }
+  const total = rows.reduce((s, x) => s + x.tokens, 0);
+  // Stable sort: tokens desc, then source name for deterministic ties.
+  rows.sort((a, b) => b.tokens - a.tokens || a.source.localeCompare(b.source));
+  const sources = rows.map((r) => ({
+    ...r,
+    share: total ? r.tokens / total : 0,
+  }));
+  return { sources, total };
+}