@remnic/core 1.1.2 → 1.1.4

package/dist/chunk-LW2NMHDW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recall-explain-renderer.ts","../src/recall-xray-renderer.ts"],"sourcesContent":["/**\n * Renderers for RecallTierExplain (issue #518).\n *\n * Pure functions that format a `LastRecallSnapshot` and its\n * optional `tierExplain` field for human text and machine JSON\n * consumption.  CLI / HTTP / MCP surfaces consume these — they do\n * not format explain output themselves, so rendering is tested in\n * one place.\n */\n\nimport type { LastRecallSnapshot } from \"./recall-state.js\";\nimport type { RecallTierExplain } from \"./types.js\";\nimport { isRetrievalTier } from \"./retrieval-tiers.js\";\nimport type {\n  RecallXraySnapshot,\n  RecallFilterTrace,\n  RecallXrayResult,\n} from \"./recall-xray.js\";\nimport { renderXrayMarkdown } from \"./recall-xray-renderer.js\";\n\nfunction sanitizeString(v: unknown): string | null {\n  return typeof v === \"string\" && v.length > 0 ? v : null;\n}\n\nfunction sanitizeFiniteNumber(v: unknown): number | null {\n  return typeof v === \"number\" && Number.isFinite(v) ? v : null;\n}\n\n/**\n * `text` and `json` are the original formats (backwards-compatible\n * since issue #518).  `markdown` was added in issue #570 PR 7 and\n * delegates to the shared X-ray renderer so the three observability\n * surfaces stay in lock-step (CLAUDE.md rule 22).\n */\nexport type RecallExplainFormat = \"text\" | \"json\" | \"markdown\";\n\nexport interface RecallExplainJsonPayload {\n  hasExplain: boolean;\n  snapshotFound: boolean;\n  sessionKey: string | null;\n  recordedAt: string | null;\n  namespace: string | null;\n  memoryIds: string[];\n  source: string | null;\n  sourcesUsed: string[] | null;\n  latencyMs: number | null;\n  tierExplain: RecallTierExplain | null;\n}\n\nfunction normalizeTierExplain(value: unknown): RecallTierExplain | null {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return null;\n  const raw = value as Record<string, unknown>;\n  const filteredBy = Array.isArray(raw.filteredBy)\n    ? raw.filteredBy.filter((x): x is string => typeof x === \"string\")\n    : [];\n  const sourceAnchors = Array.isArray(raw.sourceAnchors)\n    ? raw.sourceAnchors\n        .filter(\n          (a): a is { path: string; lineRange?: unknown } =>\n            !!a && typeof a === \"object\" && typeof (a as { path?: unknown }).path === \"string\",\n        )\n        .map((a) => {\n          const lr = (a as { lineRange?: unknown }).lineRange;\n          const lineRange =\n            Array.isArray(lr) &&\n            lr.length === 2 &&\n            Number.isFinite(lr[0]) &&\n            Number.isFinite(lr[1])\n              ? ([lr[0] as number, lr[1] as number] as [number, number])\n              : undefined;\n          return lineRange\n            ? { path: (a as { path: string }).path, lineRange }\n            : { path: (a as { path: string }).path };\n        })\n    : undefined;\n  return {\n    tier: isRetrievalTier(raw.tier) ? raw.tier : \"hybrid\",\n    tierReason: typeof raw.tierReason === \"string\" ? raw.tierReason : \"\",\n    filteredBy,\n    candidatesConsidered: sanitizeFiniteNumber(raw.candidatesConsidered) ?? 0,\n    latencyMs: sanitizeFiniteNumber(raw.latencyMs) ?? 0,\n    ...(sourceAnchors !== undefined ? { sourceAnchors } : {}),\n  };\n}\n\nexport function toRecallExplainJson(\n  snapshot: LastRecallSnapshot | null,\n): RecallExplainJsonPayload {\n  if (!snapshot) {\n    return {\n      hasExplain: false,\n      snapshotFound: false,\n      sessionKey: null,\n      recordedAt: null,\n      namespace: null,\n      memoryIds: [],\n      source: null,\n      sourcesUsed: null,\n      latencyMs: null,\n      tierExplain: null,\n    };\n  }\n  const normalizedExplain = normalizeTierExplain(snapshot.tierExplain);\n  return {\n    hasExplain: normalizedExplain !== null,\n    snapshotFound: true,\n    sessionKey: sanitizeString(snapshot.sessionKey),\n    recordedAt: sanitizeString(snapshot.recordedAt),\n    namespace: sanitizeString(snapshot.namespace),\n    memoryIds: Array.isArray(snapshot.memoryIds)\n      ? snapshot.memoryIds.filter((x): x is string => typeof x === \"string\")\n      : [],\n    source: sanitizeString(snapshot.source),\n    sourcesUsed: Array.isArray(snapshot.sourcesUsed)\n      ? snapshot.sourcesUsed.filter((x): x is string => typeof x === \"string\")\n      : null,\n    latencyMs: sanitizeFiniteNumber(snapshot.latencyMs),\n    tierExplain: normalizedExplain,\n  };\n}\n\n/**\n * Render the shared \"--- tier explain ---\" text block used by both the\n * recall-explain surface and the Recall X-ray surface.  Callers provide\n * the normalized `RecallTierExplain` (or `null` for the\n * not-populated/disabled case) so the block stays character-for-character\n * identical across surfaces (CLAUDE.md rule 22).  The returned strings do\n * NOT include leading blank lines or headers — callers own that framing.\n */\nexport function renderTierExplainTextLines(\n  tierExplain: RecallTierExplain | null,\n): string[] {\n  const lines: string[] = [];\n  if (!tierExplain) {\n    lines.push(\n      \"(not populated — direct-answer tier disabled or did not fire)\",\n    );\n    return lines;\n  }\n  lines.push(`tier: ${tierExplain.tier}`);\n  lines.push(`reason: ${tierExplain.tierReason}`);\n  lines.push(`candidates-considered: ${tierExplain.candidatesConsidered}`);\n  lines.push(`latency-ms: ${tierExplain.latencyMs}`);\n  if (tierExplain.filteredBy.length > 0) {\n    lines.push(`filtered-by: ${tierExplain.filteredBy.join(\", \")}`);\n  } else {\n    lines.push(\"filtered-by: (none)\");\n  }\n  if (tierExplain.sourceAnchors && tierExplain.sourceAnchors.length > 0) {\n    lines.push(\"source-anchors:\");\n    for (const anchor of tierExplain.sourceAnchors) {\n      const range = anchor.lineRange\n        ? `:${anchor.lineRange[0]}-${anchor.lineRange[1]}`\n        : \"\";\n      lines.push(`  - ${anchor.path}${range}`);\n    }\n  }\n  return lines;\n}\n\nexport function toRecallExplainText(\n  snapshot: LastRecallSnapshot | null,\n): string {\n  const lines: string[] = [\"=== Recall Explain ===\"];\n\n  if (!snapshot) {\n    lines.push(\"No recall snapshot recorded yet.\");\n    return lines.join(\"\\n\");\n  }\n\n  const sessionKey = sanitizeString(snapshot.sessionKey);\n  const recordedAt = sanitizeString(snapshot.recordedAt);\n  const namespace = sanitizeString(snapshot.namespace);\n  const source = sanitizeString(snapshot.source);\n  lines.push(`session: ${sessionKey ?? \"(unknown)\"}`);\n  lines.push(`recorded: ${recordedAt ?? \"(unknown)\"}`);\n  if (namespace) lines.push(`namespace: ${namespace}`);\n  if (source) lines.push(`source: ${source}`);\n  const sourcesUsed = Array.isArray(snapshot.sourcesUsed)\n    ? snapshot.sourcesUsed.filter((x): x is string => typeof x === \"string\")\n    : [];\n  if (sourcesUsed.length > 0) {\n    lines.push(`sources-used: ${sourcesUsed.join(\", \")}`);\n  }\n  const latencyMs = sanitizeFiniteNumber(snapshot.latencyMs);\n  if (latencyMs !== null) {\n    lines.push(`latency-ms: ${latencyMs}`);\n  }\n  const memoryIds = Array.isArray(snapshot.memoryIds)\n    ? snapshot.memoryIds.filter((x): x is string => typeof x === \"string\")\n    : [];\n  if (memoryIds.length > 0) {\n    lines.push(`memories: ${memoryIds.join(\", \")}`);\n  }\n\n  const ex = normalizeTierExplain(snapshot.tierExplain);\n  if (!ex) {\n    lines.push(\"\");\n    lines.push(\n      \"tier-explain: (not populated — direct-answer tier disabled or did not fire)\",\n    );\n    return lines.join(\"\\n\");\n  }\n\n  lines.push(\"\");\n  lines.push(\"--- tier explain ---\");\n  for (const line of renderTierExplainTextLines(ex)) {\n    lines.push(line);\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Adapter: convert a `LastRecallSnapshot` into a best-effort\n * `RecallXraySnapshot` so the markdown renderer can produce a\n * consistent, richly-formatted document for callers that have asked\n * for `markdown` format.  The LastRecallSnapshot and the X-ray\n * snapshot share session/namespace/memoryIds; additional X-ray-only\n * fields (filters, score decomposition, graph path, audit id) are\n * left empty because the legacy snapshot doesn't carry them.  The\n * renderer handles missing fields gracefully.\n */\n/**\n * Strip backticks, pipes, and newlines from a host-provided value so it\n * cannot escape its enclosing markdown code span, break the surrounding\n * table row, or inject extra rows when it lands in\n * `renderXrayMarkdown`.  Applied at the adapter boundary because\n * `LastRecallSnapshot` is hydrated from on-disk JSON without schema\n * validation (codex P2 review on #605).\n *\n * Accepts `unknown` so non-string truthy values (numbers, objects,\n * booleans, arrays) coming from a corrupted snapshot are coerced to\n * the empty string rather than crashing on `.replace(...)`.  Callers\n * should treat an empty return as \"drop this field.\"\n */\nfunction sanitizeForMarkdownInline(value: unknown): string {\n  if (typeof value !== \"string\") return \"\";\n  return value.replace(/[`|\\r\\n]/g, \" \").trim();\n}\n\n/**\n * Map the legacy `LastRecallSnapshot.source` field to the\n * `RecallXrayServedBy` union used by the unified x-ray renderer.\n * Mirrors the `mapRecallSourceToXrayServedBy` helper inside\n * `orchestrator.ts` (which is private).  Keep the two in sync when a\n * new source lands — unknown values collapse to `\"hybrid\"` to preserve\n * backwards compatibility with older on-disk snapshots.\n */\nfunction mapLegacySourceToServedBy(\n  source: unknown,\n): \"hybrid\" | \"recent-scan\" {\n  if (source === \"recent_scan\") return \"recent-scan\";\n  return \"hybrid\";\n}\n\nexport function toRecallXraySnapshotFromLegacy(\n  snapshot: LastRecallSnapshot | null,\n): RecallXraySnapshot | null {\n  if (!snapshot) return null;\n  const capturedAt = (() => {\n    if (typeof snapshot.recordedAt !== \"string\") return 0;\n    const ms = Date.parse(snapshot.recordedAt);\n    return Number.isFinite(ms) && ms >= 0 ? ms : 0;\n  })();\n  const memoryIds = Array.isArray(snapshot.memoryIds)\n    ? snapshot.memoryIds.filter((x): x is string => typeof x === \"string\")\n    : [];\n  // Codex P2 + Cursor Medium on #605: every converted result used to\n  // be stamped with `servedBy: \"hybrid\"`, misattributing legacy\n  // snapshots that came from `recent_scan` (or any future source).\n  // Propagate the recorded `source` so markdown `recall-explain`\n  // output matches the `served-by=` string the native x-ray capture\n  // would emit for the same recall.\n  const servedBy = mapLegacySourceToServedBy(snapshot.source);\n  const results: RecallXrayResult[] = memoryIds.map((memoryId) => ({\n    memoryId,\n    path: \"\",\n    servedBy,\n    scoreDecomposition: { final: 0 },\n    admittedBy: [],\n  }));\n  const filters: RecallFilterTrace[] = [];\n  return {\n    schemaVersion: \"1\",\n    // `LastRecallSnapshot` does not preserve the original query text;\n    // synthesize a placeholder so the renderer has a non-empty\n    // string to print.  `queryHash` + `queryLen` stay in the JSON\n    // payload via `toRecallExplainJson` for callers that need them.\n    query:\n      snapshot.queryHash\n        ? `(legacy explain; queryHash=${snapshot.queryHash})`\n        : \"(legacy explain)\",\n    // `snapshotId` is synthesized here; `sessionKey` is already\n    // sanitized before it reaches the ID because we re-use the\n    // sanitized string below.\n    snapshotId: `legacy-${sanitizeForMarkdownInline(snapshot.sessionKey ?? \"unknown\") || \"unknown\"}-${capturedAt}`,\n    capturedAt,\n    // Run the raw on-disk value through the same normalizer the text\n    // and JSON paths use so the markdown adapter cannot render\n    // unvalidated tier-explain payloads (cursor / codex review on\n    // #605).  A malformed tierExplain is dropped to null, matching the\n    // behavior of the non-markdown surfaces.\n    tierExplain: normalizeTierExplain(snapshot.tierExplain) ?? null,\n    results,\n    filters,\n    budget: { chars: 0, used: 0 },\n    // Sanitize legacy session metadata at the adapter boundary so a\n    // malformed on-disk value (containing backticks, pipes, or\n    // newlines) cannot break the enclosing markdown table when\n    // `renderXrayMarkdown` prints it in a raw code-span cell (codex P2\n    // review on #605).\n    ...(snapshot.sessionKey\n      ? (() => {\n          const clean = sanitizeForMarkdownInline(snapshot.sessionKey);\n          return clean ? { sessionKey: clean } : {};\n        })()\n      : {}),\n    ...(snapshot.namespace\n      ? (() => {\n          const clean = sanitizeForMarkdownInline(snapshot.namespace);\n          return clean ? { namespace: clean } : {};\n        })()\n      : {}),\n  };\n}\n\nexport function renderRecallExplain(\n  snapshot: LastRecallSnapshot | null,\n  format: RecallExplainFormat,\n): string {\n  if (format === \"json\") {\n    return JSON.stringify(toRecallExplainJson(snapshot), null, 2);\n  }\n  if (format === \"markdown\") {\n    // Delegate to the shared X-ray renderer so CLI / HTTP / MCP\n    // markdown output all share one implementation (CLAUDE.md rule\n    // 22).  The JSON and text paths remain byte-for-byte\n    // backwards-compatible with pre-#570 behavior.\n    return renderXrayMarkdown(toRecallXraySnapshotFromLegacy(snapshot));\n  }\n  return toRecallExplainText(snapshot);\n}\n\nexport function parseRecallExplainFormat(value: unknown): RecallExplainFormat {\n  if (value === undefined || value === null) return \"text\";\n  if (typeof value !== \"string\") {\n    throw new Error(\n      `--format expects \"text\", \"json\", or \"markdown\", got ${typeof value}`,\n    );\n  }\n  const v = value.trim().toLowerCase();\n  if (v === \"text\" || v === \"json\" || v === \"markdown\") return v;\n  throw new Error(\n    `--format expects \"text\", \"json\", or \"markdown\", got ${JSON.stringify(value)}`,\n  );\n}\n","/**\n * Unified Recall X-ray renderer (issue #570, PR 2).\n *\n * Pure functions that format a `RecallXraySnapshot` for human text,\n * GitHub-flavored markdown, and machine JSON consumption.  CLI / HTTP\n * / MCP surfaces all call into this module — they do NOT format X-ray\n * output themselves, so rendering is tested in one place (CLAUDE.md\n * rule 22).\n *\n * Scope for PR 2 (this slice):\n *   - Pure rendering.  No IO, no transport, no capture.\n *   - `renderXray(snapshot, format)` with format ∈\n *     `{\"json\", \"text\", \"markdown\"}`.\n *   - `parseXrayFormat(value)` — input validator that rejects unknown\n *     formats with a listed-options error (CLAUDE.md rule 51).\n *   - Golden-file-style tests in `recall-xray-renderer.test.ts`.\n */\n\nimport type {\n  RecallFilterTrace,\n  RecallXrayResult,\n  RecallXraySnapshot,\n  RecallXrayServedBy,\n} from \"./recall-xray.js\";\nimport { summarizeDisclosureTokens } from \"./recall-xray.js\";\nimport { renderTierExplainTextLines } from \"./recall-explain-renderer.js\";\n\nexport type RecallXrayFormat = \"json\" | \"text\" | \"markdown\";\n\nexport const RECALL_XRAY_FORMATS: readonly RecallXrayFormat[] = [\n  \"json\",\n  \"text\",\n  \"markdown\",\n] as const;\n\n/**\n * Validate and coerce a user-provided `--format` / `format` argument to\n * `RecallXrayFormat`.  Unknown values throw an error listing valid\n * options (CLAUDE.md rule 51).  `undefined`/`null` defaults to `\"text\"`.\n */\nexport function parseXrayFormat(value: unknown): RecallXrayFormat {\n  if (value === undefined || value === null) return \"text\";\n  if (typeof value !== \"string\") {\n    throw new Error(\n      `--format expects one of ${RECALL_XRAY_FORMATS.join(\", \")}; got ${typeof value}`,\n    );\n  }\n  const v = value.trim().toLowerCase();\n  if (v === \"json\" || v === \"text\" || v === \"markdown\") return v;\n  throw new Error(\n    `--format expects one of ${RECALL_XRAY_FORMATS.join(\", \")}; got ${JSON.stringify(value)}`,\n  );\n}\n\n/**\n * Top-level dispatcher.  CLI / HTTP / MCP callers should always route\n * through this function so the three formats stay in lock-step.\n */\nexport function renderXray(\n  snapshot: RecallXraySnapshot | null,\n  format: RecallXrayFormat,\n): string {\n  if (format === \"json\") return renderXrayJson(snapshot);\n  if (format === \"markdown\") return renderXrayMarkdown(snapshot);\n  return renderXrayText(snapshot);\n}\n\n// ─── JSON ─────────────────────────────────────────────────────────────────\n\n/**\n * Deterministic JSON encoding of an X-ray snapshot.  Returns a stable\n * v1 envelope when the snapshot is absent so consumers can pattern-match\n * on `snapshotFound` rather than distinguishing `null` vs `{}`.\n */\nexport function renderXrayJson(snapshot: RecallXraySnapshot | null): string {\n  if (!snapshot) {\n    return JSON.stringify(\n      { schemaVersion: \"1\", snapshotFound: false },\n      null,\n      2,\n    );\n  }\n  // `snapshotFound` is injected *before* the rest so downstream JSON\n  // consumers see it near the top of the document.\n  return JSON.stringify(\n    { snapshotFound: true, ...snapshot },\n    null,\n    2,\n  );\n}\n\n// ─── Text ─────────────────────────────────────────────────────────────────\n\nexport function renderXrayText(snapshot: RecallXraySnapshot | null): string {\n  const lines: string[] = [\"=== Recall X-ray ===\"];\n  if (!snapshot) {\n    lines.push(\"No X-ray snapshot captured.\");\n    return lines.join(\"\\n\");\n  }\n\n  lines.push(`query: ${snapshot.query}`);\n  lines.push(`snapshot-id: ${snapshot.snapshotId}`);\n  lines.push(`captured-at: ${formatCapturedAt(snapshot.capturedAt)}`);\n  if (snapshot.sessionKey) lines.push(`session: ${snapshot.sessionKey}`);\n  if (snapshot.namespace) lines.push(`namespace: ${snapshot.namespace}`);\n  if (snapshot.traceId) lines.push(`trace-id: ${snapshot.traceId}`);\n  lines.push(\n    `budget: ${snapshot.budget.used} / ${snapshot.budget.chars} chars`,\n  );\n\n  lines.push(\"\");\n  lines.push(\"--- filters ---\");\n  if (snapshot.filters.length === 0) {\n    lines.push(\"(no filter traces recorded)\");\n  } else {\n    for (const f of snapshot.filters) {\n      lines.push(renderFilterTextLine(f));\n    }\n  }\n\n  lines.push(\"\");\n  lines.push(\"--- results ---\");\n  if (snapshot.results.length === 0) {\n    lines.push(\"(no results admitted)\");\n  } else {\n    snapshot.results.forEach((result, idx) => {\n      for (const line of renderResultTextLines(result, idx + 1)) {\n        lines.push(line);\n      }\n    });\n  }\n\n  lines.push(\"\");\n  lines.push(\"--- tier explain ---\");\n  for (const line of renderTierExplainTextLines(snapshot.tierExplain ?? null)) {\n    lines.push(line);\n  }\n\n  return lines.join(\"\\n\");\n}\n\nfunction renderFilterTextLine(f: RecallFilterTrace): string {\n  const base = `- ${f.name}: ${f.admitted}/${f.considered} admitted`;\n  return f.reason ? `${base} (${f.reason})` : base;\n}\n\nfunction renderResultTextLines(\n  result: RecallXrayResult,\n  rank: number,\n): string[] {\n  const lines: string[] = [];\n  lines.push(`[${rank}] ${result.memoryId} — ${servedByLabel(result.servedBy)}`);\n  if (result.path) lines.push(`    path: ${result.path}`);\n  lines.push(`    score: ${renderScoreDecomposition(result)}`);\n  if (result.admittedBy.length > 0) {\n    lines.push(`    admitted-by: ${result.admittedBy.join(\", \")}`);\n  }\n  if (result.rejectedBy) {\n    lines.push(`    rejected-by: ${result.rejectedBy}`);\n  }\n  if (result.graphPath && result.graphPath.length > 0) {\n    lines.push(`    graph-path: ${result.graphPath.join(\" -> \")}`);\n    // Issue #681 PR 3/3 — surface per-edge confidence inline so\n    // operators can attribute floor-pruning / PageRank ranking\n    // decisions to specific edges. Skipped when no confidences were\n    // recorded (legacy snapshot or single-node path).\n    if (\n      result.graphEdgeConfidences &&\n      result.graphEdgeConfidences.length > 0\n    ) {\n      lines.push(\n        `    edge-confidences: ${result.graphEdgeConfidences\n          .map((c) => c.toFixed(2))\n          .join(\", \")}`,\n      );\n    }\n  }\n  if (result.auditEntryId) {\n    lines.push(`    audit-entry: ${result.auditEntryId}`);\n  }\n  return lines;\n}\n\n// ─── Markdown ─────────────────────────────────────────────────────────────\n\nexport function renderXrayMarkdown(\n  snapshot: RecallXraySnapshot | null,\n): string {\n  const lines: string[] = [\"# Recall X-ray\"];\n  if (!snapshot) {\n    lines.push(\"\");\n    lines.push(\"_No X-ray snapshot captured._\");\n    return lines.join(\"\\n\");\n  }\n\n  lines.push(\"\");\n  lines.push(`**Query:** ${mdInlineCode(snapshot.query)}`);\n  lines.push(\"\");\n  lines.push(\"| Field | Value |\");\n  lines.push(\"| --- | --- |\");\n  lines.push(`| Snapshot ID | \\`${snapshot.snapshotId}\\` |`);\n  lines.push(`| Captured at | ${formatCapturedAt(snapshot.capturedAt)} |`);\n  if (snapshot.sessionKey) {\n    lines.push(`| Session | \\`${snapshot.sessionKey}\\` |`);\n  }\n  if (snapshot.namespace) {\n    lines.push(`| Namespace | \\`${snapshot.namespace}\\` |`);\n  }\n  if (snapshot.traceId) {\n    lines.push(`| Trace ID | \\`${snapshot.traceId}\\` |`);\n  }\n  lines.push(\n    `| Budget | ${snapshot.budget.used} / ${snapshot.budget.chars} chars |`,\n  );\n\n  lines.push(\"\");\n  lines.push(\"## Filters\");\n  if (snapshot.filters.length === 0) {\n    lines.push(\"\");\n    lines.push(\"_No filter traces recorded._\");\n  } else {\n    lines.push(\"\");\n    lines.push(\"| Filter | Considered | Admitted | Reason |\");\n    lines.push(\"| --- | ---: | ---: | --- |\");\n    for (const f of snapshot.filters) {\n      const reason = f.reason ? mdEscape(f.reason) : \"\";\n      lines.push(`| ${mdEscape(f.name)} | ${f.considered} | ${f.admitted} | ${reason} |`);\n    }\n  }\n\n  lines.push(\"\");\n  lines.push(\"## Results\");\n  if (snapshot.results.length === 0) {\n    lines.push(\"\");\n    lines.push(\"_No results admitted._\");\n  } else {\n    snapshot.results.forEach((result, idx) => {\n      for (const line of renderResultMarkdownLines(result, idx + 1)) {\n        lines.push(line);\n      }\n    });\n\n    // Per-disclosure token-spend summary (issue #677 PR 3/4).  Only\n    // emitted when at least one result carries a disclosure level so\n    // we don't pollute the snapshot for callers who haven't wired the\n    // depth knob through.  Counts and tokens default to 0 for buckets\n    // with no contributions.\n    const summary = summarizeDisclosureTokens(snapshot.results);\n    const hasAnyDisclosure =\n      summary.chunk.count + summary.section.count + summary.raw.count > 0;\n    if (hasAnyDisclosure) {\n      lines.push(\"\");\n      lines.push(\"### Token spend by disclosure\");\n      lines.push(\"\");\n      lines.push(\"| Disclosure | Results | Estimated tokens |\");\n      lines.push(\"| --- | ---: | ---: |\");\n      lines.push(\n        `| chunk | ${summary.chunk.count} | ${summary.chunk.estimatedTokens} |`,\n      );\n      lines.push(\n        `| section | ${summary.section.count} | ${summary.section.estimatedTokens} |`,\n      );\n      lines.push(\n        `| raw | ${summary.raw.count} | ${summary.raw.estimatedTokens} |`,\n      );\n      if (summary.unspecified.count > 0) {\n        lines.push(\n          `| _(unspecified)_ | ${summary.unspecified.count} | ${summary.unspecified.estimatedTokens} |`,\n        );\n      }\n    }\n  }\n\n  lines.push(\"\");\n  lines.push(\"## Tier Explain\");\n  if (!snapshot.tierExplain) {\n    lines.push(\"\");\n    lines.push(\n      \"_Not populated — direct-answer tier disabled or did not fire._\",\n    );\n  } else {\n    const te = snapshot.tierExplain;\n    lines.push(\"\");\n    lines.push(\"| Field | Value |\");\n    lines.push(\"| --- | --- |\");\n    lines.push(`| Tier | \\`${te.tier}\\` |`);\n    lines.push(`| Reason | ${mdEscape(te.tierReason)} |`);\n    lines.push(`| Candidates considered | ${te.candidatesConsidered} |`);\n    lines.push(`| Latency (ms) | ${te.latencyMs} |`);\n    lines.push(\n      `| Filtered by | ${\n        te.filteredBy.length > 0\n          ? te.filteredBy.map(mdInlineCode).join(\", \")\n          : \"_(none)_\"\n      } |`,\n    );\n    if (te.sourceAnchors && te.sourceAnchors.length > 0) {\n      lines.push(\"\");\n      lines.push(\"**Source anchors:**\");\n      for (const anchor of te.sourceAnchors) {\n        const range = anchor.lineRange\n          ? `:${anchor.lineRange[0]}-${anchor.lineRange[1]}`\n          : \"\";\n        lines.push(`- \\`${anchor.path}${range}\\``);\n      }\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\nfunction renderResultMarkdownLines(\n  result: RecallXrayResult,\n  rank: number,\n): string[] {\n  const lines: string[] = [];\n  lines.push(\"\");\n  lines.push(\n    `### ${rank}. \\`${result.memoryId}\\` — ${servedByLabel(result.servedBy)}`,\n  );\n  if (result.path) {\n    lines.push(\"\");\n    lines.push(`- **Path:** \\`${result.path}\\``);\n  } else {\n    lines.push(\"\");\n  }\n  lines.push(`- **Score:** ${renderScoreDecomposition(result)}`);\n  if (result.admittedBy.length > 0) {\n    lines.push(\n      `- **Admitted by:** ${result.admittedBy.map(mdInlineCode).join(\", \")}`,\n    );\n  }\n  if (result.rejectedBy) {\n    lines.push(`- **Rejected by:** ${mdInlineCode(result.rejectedBy)}`);\n  }\n  if (result.graphPath && result.graphPath.length > 0) {\n    lines.push(\n      `- **Graph path:** ${result.graphPath\n        .map(mdInlineCode)\n        .join(\" → \")}`,\n    );\n    // Issue #681 PR 3/3 — render per-edge confidences as a parallel\n    // markdown line so operators can correlate them with the path\n    // arrows above. Skipped when no confidences were recorded.\n    if (\n      result.graphEdgeConfidences &&\n      result.graphEdgeConfidences.length > 0\n    ) {\n      lines.push(\n        `- **Edge confidences:** ${result.graphEdgeConfidences\n          .map((c) => mdInlineCode(c.toFixed(2)))\n          .join(\", \")}`,\n      );\n    }\n  }\n  if (result.auditEntryId) {\n    lines.push(`- **Audit entry:** \\`${result.auditEntryId}\\``);\n  }\n  if (result.disclosure !== undefined) {\n    const tokenLine =\n      typeof result.estimatedTokens === \"number\"\n        ? ` (~${result.estimatedTokens} tokens)`\n        : \"\";\n    lines.push(`- **Disclosure:** \\`${result.disclosure}\\`${tokenLine}`);\n  } else if (typeof result.estimatedTokens === \"number\") {\n    // Disclosure unspecified but tokens recorded — still surface the\n    // budget so the operator can attribute spend.\n    lines.push(`- **Estimated tokens:** ${result.estimatedTokens}`);\n  }\n  return lines;\n}\n\n// ─── Shared helpers ───────────────────────────────────────────────────────\n\nfunction servedByLabel(servedBy: RecallXrayServedBy): string {\n  return `served-by=${servedBy}`;\n}\n\nfunction renderScoreDecomposition(result: RecallXrayResult): string {\n  const parts: string[] = [`final=${formatScore(result.scoreDecomposition.final)}`];\n  const s = result.scoreDecomposition;\n  if (s.vector !== undefined) parts.push(`vector=${formatScore(s.vector)}`);\n  if (s.bm25 !== undefined) parts.push(`bm25=${formatScore(s.bm25)}`);\n  if (s.importance !== undefined) {\n    parts.push(`importance=${formatScore(s.importance)}`);\n  }\n  if (s.mmrPenalty !== undefined) {\n    parts.push(`mmr_penalty=${formatScore(s.mmrPenalty)}`);\n  }\n  if (s.tierPrior !== undefined) {\n    parts.push(`tier_prior=${formatScore(s.tierPrior)}`);\n  }\n  if (s.reinforcementBoost !== undefined && s.reinforcementBoost > 0) {\n    parts.push(`reinforcement_boost=${formatScore(s.reinforcementBoost)}`);\n  }\n  return parts.join(\" \");\n}\n\nfunction formatScore(value: number): string {\n  // Deterministic 4-decimal formatting keeps golden files stable\n  // without printing spurious trailing zeros via toString().\n  if (!Number.isFinite(value)) return \"0.0000\";\n  return value.toFixed(4);\n}\n\nfunction formatCapturedAt(ts: number): string {\n  if (!Number.isFinite(ts) || ts < 0) return \"(unknown)\";\n  // `new Date(n).toISOString()` throws a RangeError for finite numbers\n  // outside the valid Date range (roughly |n| > 8.64e15).  That case\n  // can surface when snapshots are corrupted or captured with a\n  // custom clock, so coerce it to the same \"(unknown)\" fallback\n  // rather than crashing the renderer.\n  try {\n    return new Date(ts).toISOString();\n  } catch {\n    return \"(unknown)\";\n  }\n}\n\nfunction mdEscape(value: string): string {\n  // Pipe is the only character that breaks GFM table rendering; escape\n  // backslash first so we do not re-escape the escape character.\n  return value.replace(/\\\\/g, \"\\\\\\\\\").replace(/\\|/g, \"\\\\|\");\n}\n\nfunction mdInlineCode(value: string): string {\n  if (value.length === 0) return \"``\";\n  // Use exactly enough backticks to unambiguously wrap content that\n  // itself contains backticks (GFM rule).\n  const longestRun = /`+/g;\n  let maxLen = 0;\n  for (const match of value.matchAll(longestRun)) {\n    if (match[0].length > maxLen) maxLen = match[0].length;\n  }\n  const fence = \"`\".repeat(maxLen + 1);\n  const pad = value.startsWith(\"`\") || value.endsWith(\"`\") ? \" \" : \"\";\n  return `${fence}${pad}${value}${pad}${fence}`;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-MDYG7VI7.js

@@ -0,0 +1,48 @@
+// src/temporal-validity.ts
+function effectiveValidAt(fm) {
+  const explicit = fm.valid_at?.trim();
+  if (explicit && explicit.length > 0) return explicit;
+  return fm.created;
+}
+function effectiveInvalidAt(fm) {
+  const explicit = fm.invalid_at?.trim();
+  if (explicit && explicit.length > 0) return explicit;
+  if (fm.status === "superseded") {
+    const legacy = fm.supersededAt?.trim();
+    if (legacy && legacy.length > 0) return legacy;
+  }
+  return void 0;
+}
+function isValidAsOf(fm, asOfMs) {
+  if (!Number.isFinite(asOfMs)) return true;
+  const validAtMs = Date.parse(effectiveValidAt(fm));
+  if (!Number.isFinite(validAtMs)) return false;
+  if (validAtMs > asOfMs) return false;
+  const invalidAt = effectiveInvalidAt(fm);
+  if (invalidAt === void 0) return true;
+  const invalidAtMs = Date.parse(invalidAt);
+  if (!Number.isFinite(invalidAtMs)) return true;
+  return invalidAtMs > asOfMs;
+}
+function parseAsOfTimestamp(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    throw new RangeError(
+      `as_of must be a non-empty ISO 8601 timestamp string (got: ${typeof raw === "string" ? `"${raw}"` : typeof raw})`
+    );
+  }
+  const ms = Date.parse(raw);
+  if (!Number.isFinite(ms)) {
+    throw new RangeError(
+      `as_of must be a parseable ISO 8601 timestamp (got: "${raw}")`
+    );
+  }
+  return ms;
+}
+
+export {
+  effectiveValidAt,
+  effectiveInvalidAt,
+  isValidAsOf,
+  parseAsOfTimestamp
+};
+//# sourceMappingURL=chunk-MDYG7VI7.js.map

package/dist/chunk-MDYG7VI7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/temporal-validity.ts"],"sourcesContent":["/**\n * Temporal validity helpers (issue #680).\n *\n * `valid_at` / `invalid_at` are explicit ISO 8601 timestamps that mark when a\n * fact begins and ends being authoritative.  These helpers centralize the\n * read-time defaulting rules so every call site (recall filter, supersession\n * write, tests) agrees on the canonical semantics:\n *\n *   - `effectiveValidAt(fm)` — the moment this fact starts being true.\n *     Falls back to `created` when `valid_at` is absent so legacy memories\n *     written before #680 still participate in `as_of` filtering without\n *     a backfill migration.\n *   - `effectiveInvalidAt(fm)` — the moment this fact stops being true.\n *     Returns `undefined` when no `invalid_at` is set; supersession logic\n *     populates it on the older fact when a newer one replaces it.\n *   - `isValidAsOf(fm, asOfMs)` — true when the fact was authoritative at\n *     `asOfMs` (a numeric timestamp in ms).  Half-open interval semantics:\n *     `valid_at <= asOf < invalid_at`.  Strings are parsed via\n *     `Date.parse()` so timezone-suffixed ISO strings compare correctly\n *     (CLAUDE.md gotcha — never compare ISO strings lexicographically).\n *\n * Boundary case: when `invalid_at === asOf`, the fact is treated as NOT\n * valid (the upper bound is exclusive), which matches the supersession\n * model — at the instant a successor's `valid_at` fires, the predecessor\n * is no longer authoritative.\n */\nimport type { MemoryFrontmatter } from \"./types.js\";\n\nexport function effectiveValidAt(fm: Pick<MemoryFrontmatter, \"valid_at\" | \"created\">): string {\n  // `created` is required on every memory (see types.ts), so the fallback\n  // chain always terminates.  Trimming guards against whitespace-only\n  // overrides written by legacy tooling.\n  const explicit = fm.valid_at?.trim();\n  if (explicit && explicit.length > 0) return explicit;\n  return fm.created;\n}\n\nexport function effectiveInvalidAt(\n  fm: Pick<MemoryFrontmatter, \"invalid_at\" | \"supersededAt\" | \"status\">,\n): string | undefined {\n  const explicit = fm.invalid_at?.trim();\n  if (explicit && explicit.length > 0) return explicit;\n  // Cursor Medium rounds 1+2 on PR #713: legacy data written before\n  // #680 has `status: superseded` and `supersededAt` populated, but\n  // no `invalid_at`. With the new `as_of` filter bypassing the\n  // supersession status check, those legacy predecessors would\n  // otherwise be treated as \"always valid\" and surface alongside\n  // their successors at every historical pin. Fall back to\n  // `supersededAt` so the half-open `[valid_at, invalid_at)`\n  // interval still terminates for legacy supersedes without\n  // requiring a backfill migration.\n  //\n  // BOUNDARY APPROXIMATION: `supersededAt` is when the supersession\n  // write fired, which may post-date the successor's true\n  // `valid_at` (consolidation runs on its own cadence). So the\n  // legacy predecessor stays visible from `valid_at` through\n  // `supersededAt` rather than the tighter `valid_at` through\n  // successor-`valid_at` window. We accept this intentionally: the\n  // alternative — successor-aware coordination — would require\n  // threading the successor through every call site, and \"show the\n  // legacy fact a bit too long\" is a clear win over \"drop legacy\n  // facts entirely from `as_of`\". New data (post-#680) writes\n  // `invalid_at` directly and is unaffected.\n  if (fm.status === \"superseded\") {\n    const legacy = fm.supersededAt?.trim();\n    if (legacy && legacy.length > 0) return legacy;\n  }\n  return undefined;\n}\n\n/**\n * Returns true when the fact was authoritative at `asOfMs` (parsed\n * milliseconds since epoch).  Half-open semantics: a fact is valid in\n * `[valid_at, invalid_at)`.\n *\n * If `valid_at` cannot be parsed, the fact is conservatively treated as\n * NOT valid at the requested point — we never silently default a corrupt\n * timestamp to \"always true\" because that would let bad data leak past\n * the historical filter (CLAUDE.md gotcha #34: distinguish empty from\n * malformed).\n */\nexport function isValidAsOf(\n  fm: Pick<\n    MemoryFrontmatter,\n    \"valid_at\" | \"invalid_at\" | \"created\" | \"supersededAt\" | \"status\"\n  >,\n  asOfMs: number,\n): boolean {\n  if (!Number.isFinite(asOfMs)) return true;\n  const validAtMs = Date.parse(effectiveValidAt(fm));\n  if (!Number.isFinite(validAtMs)) return false;\n  if (validAtMs > asOfMs) return false;\n  const invalidAt = effectiveInvalidAt(fm);\n  if (invalidAt === undefined) return true;\n  const invalidAtMs = Date.parse(invalidAt);\n  // Unparseable invalid_at — conservatively keep the fact (we can read\n  // valid_at, so we know the fact was at some point true; corrupt\n  // invalid_at is not a reason to hide it).\n  if (!Number.isFinite(invalidAtMs)) return true;\n  // Half-open: at exactly invalid_at, the fact is no longer valid.\n  return invalidAtMs > asOfMs;\n}\n\n/**\n * Parse and validate an `as_of` value supplied at an input boundary\n * (CLI flag, HTTP query param, MCP field).  Returns parsed milliseconds\n * on success; throws a `RangeError` with a helpful message on malformed\n * input.  CLAUDE.md rule 51 — never silently default invalid input.\n */\nexport function parseAsOfTimestamp(raw: unknown): number {\n  if (typeof raw !== \"string\" || raw.trim().length === 0) {\n    throw new RangeError(\n      `as_of must be a non-empty ISO 8601 timestamp string (got: ${typeof raw === \"string\" ? `\"${raw}\"` : typeof raw})`,\n    );\n  }\n  const ms = Date.parse(raw);\n  if (!Number.isFinite(ms)) {\n    throw new RangeError(\n      `as_of must be a parseable ISO 8601 timestamp (got: \"${raw}\")`,\n    );\n  }\n  return ms;\n}\n"],"mappings":";AA4BO,SAAS,iBAAiB,IAA6D;AAI5F,QAAM,WAAW,GAAG,UAAU,KAAK;AACnC,MAAI,YAAY,SAAS,SAAS,EAAG,QAAO;AAC5C,SAAO,GAAG;AACZ;AAEO,SAAS,mBACd,IACoB;AACpB,QAAM,WAAW,GAAG,YAAY,KAAK;AACrC,MAAI,YAAY,SAAS,SAAS,EAAG,QAAO;AAsB5C,MAAI,GAAG,WAAW,cAAc;AAC9B,UAAM,SAAS,GAAG,cAAc,KAAK;AACrC,QAAI,UAAU,OAAO,SAAS,EAAG,QAAO;AAAA,EAC1C;AACA,SAAO;AACT;AAaO,SAAS,YACd,IAIA,QACS;AACT,MAAI,CAAC,OAAO,SAAS,MAAM,EAAG,QAAO;AACrC,QAAM,YAAY,KAAK,MAAM,iBAAiB,EAAE,CAAC;AACjD,MAAI,CAAC,OAAO,SAAS,SAAS,EAAG,QAAO;AACxC,MAAI,YAAY,OAAQ,QAAO;AAC/B,QAAM,YAAY,mBAAmB,EAAE;AACvC,MAAI,cAAc,OAAW,QAAO;AACpC,QAAM,cAAc,KAAK,MAAM,SAAS;AAIxC,MAAI,CAAC,OAAO,SAAS,WAAW,EAAG,QAAO;AAE1C,SAAO,cAAc;AACvB;AAQO,SAAS,mBAAmB,KAAsB;AACvD,MAAI,OAAO,QAAQ,YAAY,IAAI,KAAK,EAAE,WAAW,GAAG;AACtD,UAAM,IAAI;AAAA,MACR,6DAA6D,OAAO,QAAQ,WAAW,IAAI,GAAG,MAAM,OAAO,GAAG;AAAA,IAChH;AAAA,EACF;AACA,QAAM,KAAK,KAAK,MAAM,GAAG;AACzB,MAAI,CAAC,OAAO,SAAS,EAAE,GAAG;AACxB,UAAM,IAAI;AAAA,MACR,uDAAuD,GAAG;AAAA,IAC5D;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/{chunk-VDX363PS.js → chunk-MUELDH4F.js}

@@ -1,6 +1,6 @@
 import {
   StorageManager
-} from "./chunk-F5VP6YCB.js";
+} from "./chunk-Y4A6M3B6.js";
 
 // src/semantic-rule-promotion.ts
 function normalizeRuleWhitespace(value) {
@@ -63,6 +63,13 @@ async function promoteSemanticRuleFromMemory(options) {
     });
     return report;
   }
+  if (sourceMemory.frontmatter.status === "forgotten") {
+    report.skipped.push({
+      sourceMemoryId: options.sourceMemoryId,
+      reason: "source-memory-forgotten"
+    });
+    return report;
+  }
   if (sourceMemory.frontmatter.status === "archived" || sourceMemory.frontmatter.memoryKind !== "episode") {
     report.skipped.push({
       sourceMemoryId: options.sourceMemoryId,
@@ -80,7 +87,7 @@ async function promoteSemanticRuleFromMemory(options) {
   }
   const ruleKey = canonicalizeRuleKey(content);
   const existingRule = (await storage.readAllMemories()).find(
-    (memory) => memory.frontmatter.category === "rule" && memory.frontmatter.status !== "archived" && canonicalizeRuleKey(memory.content) === ruleKey
+    (memory) => memory.frontmatter.category === "rule" && memory.frontmatter.status !== "archived" && memory.frontmatter.status !== "forgotten" && canonicalizeRuleKey(memory.content) === ruleKey
   );
   if (existingRule) {
     report.skipped.push({
@@ -125,4 +132,4 @@ async function promoteSemanticRuleFromMemory(options) {
 export {
   promoteSemanticRuleFromMemory
 };
-//# sourceMappingURL=chunk-VDX363PS.js.map
+//# sourceMappingURL=chunk-MUELDH4F.js.map

package/dist/chunk-MUELDH4F.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/semantic-rule-promotion.ts"],"sourcesContent":["import { StorageManager } from \"./storage.js\";\nimport type { MemoryFile, MemoryLink } from \"./types.js\";\n\nexport interface SemanticRulePromotionCandidate {\n  id: string;\n  sourceMemoryId: string;\n  content: string;\n  confidence: number;\n  tags: string[];\n  memoryKind: \"note\";\n  lineage: string[];\n}\n\nexport interface SemanticRulePromotionSkip {\n  sourceMemoryId: string;\n  reason:\n    | \"disabled\"\n    | \"source-memory-missing\"\n    | \"source-memory-forgotten\"\n    | \"source-memory-not-episode\"\n    | \"no-explicit-rule\"\n    | \"duplicate-rule\";\n  existingRuleId?: string;\n}\n\nexport interface SemanticRulePromotionReport {\n  enabled: boolean;\n  dryRun: boolean;\n  promoted: SemanticRulePromotionCandidate[];\n  skipped: SemanticRulePromotionSkip[];\n}\n\nfunction normalizeRuleWhitespace(value: string): string {\n  return value.replace(/\\s+/g, \" \").trim();\n}\n\nfunction stripTrailingClausePunctuation(value: string): string {\n  return value.replace(/[,:;]+$/g, \"\").trim();\n}\n\nfunction canonicalizeRuleContent(value: string): string {\n  return extractExplicitIfThenRule(value) ?? normalizeRuleWhitespace(value);\n}\n\nfunction canonicalizeRuleKey(value: string): string {\n  return canonicalizeRuleContent(value).toLowerCase();\n}\n\nfunction extractExplicitIfThenRule(content: string): string | null {\n  const match = content.match(/\\bif\\b([\\s\\S]+?)\\bthen\\b([\\s\\S]+?)(?:[.!?](?:\\s|$)|$)/i);\n  if (!match) return null;\n  const condition = stripTrailingClausePunctuation(normalizeRuleWhitespace(match[1] ?? \"\"));\n  const outcome = stripTrailingClausePunctuation(normalizeRuleWhitespace(match[2] ?? \"\"));\n  if (condition.length === 0 || outcome.length === 0) return null;\n  return `IF ${condition} THEN ${outcome}.`;\n}\n\nfunction promotionConfidence(memory: MemoryFile): number {\n  const base = Number.isFinite(memory.frontmatter.confidence) ? memory.frontmatter.confidence : 0.8;\n  return Math.max(0.6, Math.min(0.98, base));\n}\n\nfunction promotionTags(memory: MemoryFile): string[] {\n  return Array.from(new Set([...(memory.frontmatter.tags ?? []), \"semantic-rule\", \"promoted-rule\"]));\n}\n\nfunction buildSupportLinks(sourceMemoryId: string, confidence: number): MemoryLink[] {\n  return [\n    {\n      targetId: sourceMemoryId,\n      linkType: \"supports\",\n      strength: confidence,\n      reason: \"Promoted from verified episodic memory\",\n    },\n  ];\n}\n\nexport async function promoteSemanticRuleFromMemory(options: {\n  memoryDir: string;\n  enabled: boolean;\n  sourceMemoryId: string;\n  dryRun?: boolean;\n}): Promise<SemanticRulePromotionReport> {\n  const report: SemanticRulePromotionReport = {\n    enabled: options.enabled,\n    dryRun: options.dryRun === true,\n    promoted: [],\n    skipped: [],\n  };\n  if (!options.enabled) {\n    report.skipped.push({\n      sourceMemoryId: options.sourceMemoryId,\n      reason: \"disabled\",\n    });\n    return report;\n  }\n\n  const storage = new StorageManager(options.memoryDir);\n  const sourceMemory = await storage.getMemoryById(options.sourceMemoryId);\n  if (!sourceMemory) {\n    report.skipped.push({\n      sourceMemoryId: options.sourceMemoryId,\n      reason: \"source-memory-missing\",\n    });\n    return report;\n  }\n  if (sourceMemory.frontmatter.status === \"forgotten\") {\n    report.skipped.push({\n      sourceMemoryId: options.sourceMemoryId,\n      reason: \"source-memory-forgotten\",\n    });\n    return report;\n  }\n  if (\n    sourceMemory.frontmatter.status === \"archived\" ||\n    sourceMemory.frontmatter.memoryKind !== \"episode\"\n  ) {\n    report.skipped.push({\n      sourceMemoryId: options.sourceMemoryId,\n      reason: \"source-memory-not-episode\",\n    });\n    return report;\n  }\n\n  const content = extractExplicitIfThenRule(sourceMemory.content);\n  if (!content) {\n    report.skipped.push({\n      sourceMemoryId: options.sourceMemoryId,\n      reason: \"no-explicit-rule\",\n    });\n    return report;\n  }\n\n  const ruleKey = canonicalizeRuleKey(content);\n  const existingRule = (await storage.readAllMemories()).find(\n    (memory) =>\n      memory.frontmatter.category === \"rule\" &&\n      memory.frontmatter.status !== \"archived\" &&\n      memory.frontmatter.status !== \"forgotten\" &&\n      canonicalizeRuleKey(memory.content) === ruleKey,\n  );\n  if (existingRule) {\n    report.skipped.push({\n      sourceMemoryId: options.sourceMemoryId,\n      reason: \"duplicate-rule\",\n      existingRuleId: existingRule.frontmatter.id,\n    });\n    return report;\n  }\n\n  const confidence = promotionConfidence(sourceMemory);\n  const candidateBase = {\n    sourceMemoryId: options.sourceMemoryId,\n    content,\n    confidence,\n    tags: promotionTags(sourceMemory),\n    memoryKind: \"note\" as const,\n    lineage: [options.sourceMemoryId],\n  };\n\n  if (options.dryRun === true) {\n    report.promoted.push({\n      id: `dry-run:${options.sourceMemoryId}`,\n      ...candidateBase,\n    });\n    return report;\n  }\n\n  const id = await storage.writeMemory(\"rule\", content, {\n    confidence,\n    tags: candidateBase.tags,\n    source: \"semantic-rule-promotion\",\n    lineage: candidateBase.lineage,\n    sourceMemoryId: options.sourceMemoryId,\n    memoryKind: \"note\",\n    links: buildSupportLinks(options.sourceMemoryId, confidence),\n  });\n  report.promoted.push({\n    id,\n    ...candidateBase,\n  });\n  return report;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-MXC3AP5I.js

@@ -0,0 +1,74 @@
+// src/resolve-auth-token.ts
+var resolvedCache = /* @__PURE__ */ new Map();
+function cacheKeyForSecretRef(ref) {
+  const sortedKeys = Object.keys(ref).sort();
+  const stable = {};
+  for (const key of sortedKeys) {
+    stable[key] = ref[key];
+  }
+  return JSON.stringify(stable);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function resolveAgentAccessAuthToken(value, options = {}) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  if (!isPlainObject(value)) {
+    throw new Error(
+      "unsupported SecretRef shape for agentAccessHttp.authToken \u2014 expected a string or an object with a `source` field (see https://github.com/joshuaswarren/remnic/issues/757)"
+    );
+  }
+  const ref = value;
+  if (typeof ref.source !== "string" || ref.source.trim().length === 0) {
+    throw new Error(
+      "unsupported SecretRef shape for agentAccessHttp.authToken \u2014 missing required `source` field (see https://github.com/joshuaswarren/remnic/issues/757)"
+    );
+  }
+  const cacheKey = cacheKeyForSecretRef(ref);
+  const cached = resolvedCache.get(cacheKey);
+  if (cached !== void 0) return cached;
+  const resolver = options.resolveSecretRef ?? null;
+  if (!resolver) {
+    throw new Error(
+      `cannot resolve agentAccessHttp.authToken SecretRef (source="${ref.source}") \u2014 a SecretRef resolver was not provided. Use a literal string or \${ENV_VAR} expansion in standalone Remnic, or have the host adapter resolve SecretRef objects through its native secret resolver (see https://github.com/joshuaswarren/remnic/issues/757).`
+    );
+  }
+  let resolved;
+  try {
+    const out = await resolver(ref);
+    if (typeof out === "string") {
+      const trimmed = out.trim();
+      if (trimmed.length > 0) resolved = trimmed;
+    }
+  } catch (err) {
+    throw new Error(
+      `failed to resolve agentAccessHttp.authToken SecretRef (source="${ref.source}"): ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!resolved) {
+    throw new Error(
+      `agentAccessHttp.authToken SecretRef resolved to empty value (source="${ref.source}", provider="${ref.provider ?? ""}") \u2014 refusing to start the HTTP bridge with an empty bearer token.`
+    );
+  }
+  resolvedCache.set(cacheKey, resolved);
+  return resolved;
+}
+function isAgentAccessSecretRef(value) {
+  if (!isPlainObject(value)) return false;
+  const ref = value;
+  return typeof ref.source === "string" && ref.source.trim().length > 0;
+}
+function clearAuthTokenSecretCache() {
+  resolvedCache.clear();
+}
+
+export {
+  resolveAgentAccessAuthToken,
+  isAgentAccessSecretRef,
+  clearAuthTokenSecretCache
+};
+//# sourceMappingURL=chunk-MXC3AP5I.js.map

package/dist/chunk-MXC3AP5I.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve-auth-token.ts"],"sourcesContent":["import type { AgentAccessAuthToken, SecretRef } from \"./types.js\";\n\n/**\n * Resolve `agentAccessHttp.authToken` (issue #757).\n *\n * Two shapes are accepted:\n *\n *   1. Plain string — returned unchanged. This is the only shape supported\n *      in standalone Remnic; it preserves backward compatibility with every\n *      pre-#757 config.\n *\n *   2. SecretRef-like object (`{source, provider?, id?, command?, ...}`) —\n *      resolved only through a resolver supplied by the host adapter. Core\n *      stays host-agnostic and never scans OpenClaw, Hermes, or any other\n *      runtime directly.\n *\n * Resolution flow for SecretRef objects:\n *\n *   - Plain strings short-circuit before any host work.\n *   - Host adapters pass their native SecretRef resolver in `options`.\n *   - If no resolver is provided, throw a clear, actionable error rather\n *     than silently leaving the bridge open or starting with no auth.\n *\n * Lessons baked in from PRs #316–#319:\n *\n *   - Successful resolutions are cached for the process lifetime; failures\n *     are not cached so transient issues (Keychain unlocked late, agent\n *     restarts) recover automatically.\n */\n\nexport type ResolveSecretRefFn = (\n  ref: SecretRef,\n  context?: unknown,\n) => Promise<string | undefined> | string | undefined;\n\ntype ResolveAgentAccessAuthTokenOptions = {\n  resolveSecretRef?: ResolveSecretRefFn | null;\n};\n\nconst resolvedCache = new Map<string, string>();\n\n/**\n * SecretRef objects are stable per (source, provider, id, command) tuple.\n * Sort keys before serializing so semantically-identical refs hit the same\n * cache slot regardless of authoring order (Lesson 38 in CLAUDE.md).\n */\nfunction cacheKeyForSecretRef(ref: SecretRef): string {\n  const sortedKeys = Object.keys(ref).sort();\n  const stable: Record<string, unknown> = {};\n  for (const key of sortedKeys) {\n    stable[key] = ref[key];\n  }\n  return JSON.stringify(stable);\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Resolve an `agentAccessHttp.authToken` value to a literal bearer string.\n *\n * @returns the resolved string, or `undefined` if input was undefined/empty.\n * @throws if the input is a SecretRef and no resolver is provided, if the\n *         resolver returns no value, or if the input shape is malformed.\n */\nexport async function resolveAgentAccessAuthToken(\n  value: AgentAccessAuthToken | undefined,\n  options: ResolveAgentAccessAuthTokenOptions = {},\n): Promise<string | undefined> {\n  if (value === undefined || value === null) return undefined;\n\n  if (typeof value === \"string\") {\n    const trimmed = value.trim();\n    return trimmed.length > 0 ? trimmed : undefined;\n  }\n\n  if (!isPlainObject(value)) {\n    throw new Error(\n      \"unsupported SecretRef shape for agentAccessHttp.authToken — \" +\n        \"expected a string or an object with a `source` field \" +\n        \"(see https://github.com/joshuaswarren/remnic/issues/757)\",\n    );\n  }\n\n  const ref = value as SecretRef;\n  if (typeof ref.source !== \"string\" || ref.source.trim().length === 0) {\n    throw new Error(\n      \"unsupported SecretRef shape for agentAccessHttp.authToken — \" +\n        \"missing required `source` field \" +\n        \"(see https://github.com/joshuaswarren/remnic/issues/757)\",\n    );\n  }\n\n  const cacheKey = cacheKeyForSecretRef(ref);\n  const cached = resolvedCache.get(cacheKey);\n  if (cached !== undefined) return cached;\n\n  const resolver = options.resolveSecretRef ?? null;\n  if (!resolver) {\n    throw new Error(\n      `cannot resolve agentAccessHttp.authToken SecretRef (source=\"${ref.source}\") — ` +\n        \"a SecretRef resolver was not provided. Use a literal string or \" +\n        \"${ENV_VAR} expansion in standalone Remnic, or have the host adapter \" +\n        \"resolve SecretRef objects through its native secret resolver \" +\n        \"(see https://github.com/joshuaswarren/remnic/issues/757).\",\n    );\n  }\n\n  let resolved: string | undefined;\n  try {\n    const out = await resolver(ref);\n    if (typeof out === \"string\") {\n      const trimmed = out.trim();\n      if (trimmed.length > 0) resolved = trimmed;\n    }\n  } catch (err) {\n    throw new Error(\n      `failed to resolve agentAccessHttp.authToken SecretRef (source=\"${ref.source}\"): ${\n        err instanceof Error ? err.message : String(err)\n      }`,\n    );\n  }\n\n  if (!resolved) {\n    throw new Error(\n      `agentAccessHttp.authToken SecretRef resolved to empty value (source=\"${ref.source}\", provider=\"${\n        ref.provider ?? \"\"\n      }\") — refusing to start the HTTP bridge with an empty bearer token.`,\n    );\n  }\n\n  resolvedCache.set(cacheKey, resolved);\n  return resolved;\n}\n\n/**\n * Returns true if the value is a SecretRef object (issue #757). Useful for\n * surfaces (CLI flags, doctor checks) that want to render a redacted\n * placeholder instead of leaking the unresolved object shape.\n */\nexport function isAgentAccessSecretRef(value: unknown): value is SecretRef {\n  if (!isPlainObject(value)) return false;\n  const ref = value as Record<string, unknown>;\n  return typeof ref.source === \"string\" && ref.source.trim().length > 0;\n}\n\n/** Test/operations hook: drop the cache and force resolver rediscovery. */\nexport function clearAuthTokenSecretCache(): void {\n  resolvedCache.clear();\n}\n"],"mappings":";AAuCA,IAAM,gBAAgB,oBAAI,IAAoB;AAO9C,SAAS,qBAAqB,KAAwB;AACpD,QAAM,aAAa,OAAO,KAAK,GAAG,EAAE,KAAK;AACzC,QAAM,SAAkC,CAAC;AACzC,aAAW,OAAO,YAAY;AAC5B,WAAO,GAAG,IAAI,IAAI,GAAG;AAAA,EACvB;AACA,SAAO,KAAK,UAAU,MAAM;AAC9B;AAEA,SAAS,cAAc,OAAkD;AACvE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AASA,eAAsB,4BACpB,OACA,UAA8C,CAAC,GAClB;AAC7B,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAElD,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,UAAU,MAAM,KAAK;AAC3B,WAAO,QAAQ,SAAS,IAAI,UAAU;AAAA,EACxC;AAEA,MAAI,CAAC,cAAc,KAAK,GAAG;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,IAGF;AAAA,EACF;AAEA,QAAM,MAAM;AACZ,MAAI,OAAO,IAAI,WAAW,YAAY,IAAI,OAAO,KAAK,EAAE,WAAW,GAAG;AACpE,UAAM,IAAI;AAAA,MACR;AAAA,IAGF;AAAA,EACF;AAEA,QAAM,WAAW,qBAAqB,GAAG;AACzC,QAAM,SAAS,cAAc,IAAI,QAAQ;AACzC,MAAI,WAAW,OAAW,QAAO;AAEjC,QAAM,WAAW,QAAQ,oBAAoB;AAC7C,MAAI,CAAC,UAAU;AACb,UAAM,IAAI;AAAA,MACR,+DAA+D,IAAI,MAAM;AAAA,IAK3E;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,UAAM,MAAM,MAAM,SAAS,GAAG;AAC9B,QAAI,OAAO,QAAQ,UAAU;AAC3B,YAAM,UAAU,IAAI,KAAK;AACzB,UAAI,QAAQ,SAAS,EAAG,YAAW;AAAA,IACrC;AAAA,EACF,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,kEAAkE,IAAI,MAAM,OAC1E,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CACjD;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,UAAU;AACb,UAAM,IAAI;AAAA,MACR,wEAAwE,IAAI,MAAM,gBAChF,IAAI,YAAY,EAClB;AAAA,IACF;AAAA,EACF;AAEA,gBAAc,IAAI,UAAU,QAAQ;AACpC,SAAO;AACT;AAOO,SAAS,uBAAuB,OAAoC;AACzE,MAAI,CAAC,cAAc,KAAK,EAAG,QAAO;AAClC,QAAM,MAAM;AACZ,SAAO,OAAO,IAAI,WAAW,YAAY,IAAI,OAAO,KAAK,EAAE,SAAS;AACtE;AAGO,SAAS,4BAAkC;AAChD,gBAAc,MAAM;AACtB;","names":[]}

package/dist/chunk-NN3TS5BM.js

@@ -0,0 +1,147 @@
+import {
+  expandTildePath
+} from "./chunk-IXEJRKCZ.js";
+import {
+  launchProcessSync
+} from "./chunk-OR64ZGRZ.js";
+
+// src/coding/git-context.ts
+import path from "path";
+var DEFAULT_GIT_TIMEOUT_MS = 2e3;
+function defaultGitInvoker() {
+  return (cwd, args) => {
+    const result = launchProcessSync("git", args, {
+      cwd,
+      encoding: "utf-8",
+      timeout: DEFAULT_GIT_TIMEOUT_MS,
+      shell: false
+    });
+    if (result.error) {
+      return { stdout: "", exitCode: 127 };
+    }
+    return {
+      stdout: typeof result.stdout === "string" ? result.stdout : "",
+      exitCode: typeof result.status === "number" ? result.status : 1
+    };
+  };
+}
+function stableHash(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+function normalizeOriginUrl(rawUrl) {
+  let url = rawUrl.trim();
+  if (!url) return "";
+  if (/\.git$/i.test(url)) url = url.slice(0, -4);
+  if (/^[A-Za-z]:[\\/]/.test(url)) {
+    return url.toLowerCase();
+  }
+  const protoMatch = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?(\[[^\]]+\]|[^/:]*)(?::(\d+))?(\/.*)?$/i.exec(url);
+  if (protoMatch) {
+    let host = protoMatch[1] ?? "";
+    const wasBracketed = host.startsWith("[") && host.endsWith("]");
+    if (wasBracketed) host = host.slice(1, -1);
+    const port = protoMatch[2];
+    const repoPath = (protoMatch[3] ?? "").replace(/^\/+/, "");
+    const hostPort = port ? wasBracketed ? `[${host}]:${port}` : `${host}:${port}` : host;
+    const prefix = hostPort.length > 0 ? hostPort : "localhost";
+    return `${prefix}/${repoPath}`.toLowerCase();
+  }
+  const scpMatch = /^(?:([^@\s/]+)@)?(\[[^\]]+\]|[^:@\s/]+):(.+)$/.exec(url);
+  if (scpMatch) {
+    let host = scpMatch[2] ?? "";
+    if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+    const repoPath = scpMatch[3] ?? "";
+    if (repoPath.startsWith("//")) {
+      return url.toLowerCase();
+    }
+    return `${host}/${repoPath.replace(/^\/+/, "")}`.toLowerCase();
+  }
+  return url.toLowerCase();
+}
+async function resolveGitContext(cwd, options = {}) {
+  try {
+    if (typeof cwd !== "string" || cwd.length === 0) return null;
+    const expanded = expandTildePath(cwd);
+    if (!path.isAbsolute(expanded)) return null;
+    const invoker = options.invoker ?? defaultGitInvoker();
+    const topLevel = invoker(expanded, ["rev-parse", "--show-toplevel"]);
+    if (topLevel.exitCode !== 0) return null;
+    const rootPath = topLevel.stdout.trim();
+    if (!rootPath) return null;
+    const branchResult = invoker(rootPath, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    let branch = null;
+    if (branchResult.exitCode === 0) {
+      const raw = branchResult.stdout.trim();
+      branch = raw && raw !== "HEAD" ? raw : null;
+    } else {
+      const unbornRef = invoker(rootPath, ["symbolic-ref", "--quiet", "HEAD"]);
+      if (unbornRef.exitCode === 0) {
+        const raw = unbornRef.stdout.trim();
+        const prefix = "refs/heads/";
+        if (raw.startsWith(prefix)) {
+          const candidate = raw.slice(prefix.length);
+          if (candidate) branch = candidate;
+        }
+      }
+    }
+    const originResult = invoker(rootPath, ["remote", "get-url", "origin"]);
+    let projectId;
+    if (originResult.exitCode === 0) {
+      const normalized = normalizeOriginUrl(originResult.stdout);
+      projectId = normalized ? `origin:${stableHash(normalized)}` : `root:${stableHash(rootPath)}`;
+    } else {
+      projectId = `root:${stableHash(rootPath)}`;
+    }
+    const headRef = invoker(rootPath, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]);
+    let defaultBranch = null;
+    if (headRef.exitCode === 0) {
+      const raw = headRef.stdout.trim();
+      const prefix = "refs/remotes/origin/";
+      if (raw.startsWith(prefix)) {
+        const candidate = raw.slice(prefix.length);
+        if (candidate) defaultBranch = candidate;
+      }
+    }
+    return {
+      projectId,
+      branch,
+      rootPath,
+      defaultBranch
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/procedural/reinforcement-core.ts
+function clusterByKey(items, keyFn) {
+  const clusters = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = keyFn(item);
+    if (typeof key !== "string") {
+      throw new TypeError(
+        `clusterByKey: keyFn must return a string, got ${key === null ? "null" : typeof key}`
+      );
+    }
+    const existing = clusters.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      clusters.set(key, [item]);
+    }
+  }
+  return clusters;
+}
+
+export {
+  clusterByKey,
+  stableHash,
+  normalizeOriginUrl,
+  resolveGitContext
+};
+//# sourceMappingURL=chunk-NN3TS5BM.js.map

package/dist/chunk-NN3TS5BM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/coding/git-context.ts","../src/procedural/reinforcement-core.ts"],"sourcesContent":["/**\n * GitContextResolver — pure module for detecting the git project + branch\n * a session is operating in.\n *\n * Introduced by issue #569 (coding-agent project/branch-scoped namespaces).\n *\n * This module is deliberately pure:\n *   - no orchestrator references\n *   - no config side-effects\n *   - no namespace wiring\n *\n * Downstream slices (PR 2+ of #569) wire `resolveGitContext` into the\n * `NamespaceResolver` / `Orchestrator` so that memories are scoped to a\n * detected project / branch without leaking across repos.\n *\n * CLAUDE.md rule 17 (expand `~`): the `rootPath` returned here is always an\n * absolute, tilde-expanded path. Callers must not re-expand.\n *\n * CLAUDE.md rule 51 (reject invalid input): `cwd` must be an absolute path\n * and must exist. `resolveGitContext` returns `null` — rather than throwing —\n * when the directory is not inside a git worktree, because being outside a\n * repo is a normal runtime state (e.g. agent opened in a scratch dir).\n */\nimport path from \"node:path\";\n\nimport { expandTildePath } from \"../utils/path.js\";\nimport { launchProcessSync } from \"../runtime/child-process.js\";\n\n// Re-export so existing callers / tests that imported `expandTildePath` from\n// this module keep working. CLAUDE.md #17 requires consistent `~` expansion\n// across every user-facing path input; the canonical implementation now\n// lives in `utils/path.ts`.\nexport { expandTildePath };\n\n// ──────────────────────────────────────────────────────────────────────────\n// Public types\n// ──────────────────────────────────────────────────────────────────────────\n\nexport interface GitContext {\n  /**\n   * Stable identifier for the project. Derived from `git remote get-url origin`\n   * when an origin remote is configured, otherwise from the repo root path.\n   *\n   * Formatted as `origin:<hex>` or `root:<hex>` so that the source is visible\n   * to operators (see `remnic doctor`, issue #569 acceptance criteria).\n   */\n  projectId: string;\n  /**\n   * Current branch, e.g. `main`, `feat/foo`. `null` only in detached-HEAD\n   * state (e.g. rebase in progress). Callers should treat `null` as \"no\n   * branch-scope overlay applies\" without erroring.\n   */\n  branch: string | null;\n  /**\n   * Absolute path to the repository root (the directory containing `.git`).\n   * Tilde-expanded per CLAUDE.md #17.\n   */\n  rootPath: string;\n  /**\n   * Best-effort default branch (usually `main` or `master`). Derived from the\n   * `refs/remotes/origin/HEAD` symbolic ref. `null` when not available (e.g.\n   * fresh clone without a default branch symref, or no origin remote).\n   */\n  defaultBranch: string | null;\n}\n\n/**\n * Injectable git-invocation surface. Only the commands `resolveGitContext`\n * actually needs are exposed. Tests inject a mock implementation to avoid\n * spawning a real git process.\n */\nexport interface GitInvoker {\n  /**\n   * Run `git <args>` with `cwd` as the working directory. Must return\n   * `{ stdout, exitCode }` with `stdout` trimmed by the caller as needed.\n   * Implementations should NOT throw for non-zero exit codes — they should\n   * return the exit code so the resolver can decide how to recover.\n   */\n  (cwd: string, args: string[]): { stdout: string; exitCode: number };\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Default git invoker — spawns real `git` via the shared child-process helper\n// ──────────────────────────────────────────────────────────────────────────\n\nconst DEFAULT_GIT_TIMEOUT_MS = 2_000;\n\nexport function defaultGitInvoker(): GitInvoker {\n  return (cwd: string, args: string[]) => {\n    const result = launchProcessSync(\"git\", args, {\n      cwd,\n      encoding: \"utf-8\",\n      timeout: DEFAULT_GIT_TIMEOUT_MS,\n      shell: false,\n    });\n    if (result.error) {\n      // Spawn failure (git not on PATH, timeout, etc.). Surface as non-zero.\n      return { stdout: \"\", exitCode: 127 };\n    }\n    return {\n      stdout: typeof result.stdout === \"string\" ? result.stdout : \"\",\n      exitCode: typeof result.status === \"number\" ? result.status : 1,\n    };\n  };\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Stable hashing\n// ──────────────────────────────────────────────────────────────────────────\n\n/**\n * Non-cryptographic stable hash. Used only to derive a deterministic\n * `projectId` from either the origin URL or the root path. The hash does not\n * need to be collision-resistant against adversarial input — it is purely a\n * namespace discriminator.\n *\n * Uses FNV-1a 32-bit so we don't pull in `node:crypto` for a simple bucket\n * key. Output is lowercase hex, zero-padded to 8 characters.\n */\nexport function stableHash(input: string): string {\n  let hash = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    hash ^= input.charCodeAt(i);\n    hash = Math.imul(hash, 0x01000193) >>> 0;\n  }\n  return hash.toString(16).padStart(8, \"0\");\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Origin URL normalization\n// ──────────────────────────────────────────────────────────────────────────\n\n/**\n * Normalize a git remote URL so that equivalent SSH / HTTPS forms of the\n * same repo produce the same `projectId`. Handles:\n *   - `git@github.com:foo/bar.git`  → `github.com/foo/bar`\n *   - `https://github.com/foo/bar`  → `github.com/foo/bar`\n *   - `https://github.com/foo/bar.git` → `github.com/foo/bar`\n *   - `ssh://git@github.com/foo/bar` → `github.com/foo/bar`\n *   - `ssh://git@github.com:2222/foo/bar` → `github.com/foo/bar` (port stripped)\n *\n * Case-insensitive (remote hostnames and most repo paths on major forges are\n * case-insensitive in practice).\n */\nexport function normalizeOriginUrl(rawUrl: string): string {\n  let url = rawUrl.trim();\n  if (!url) return \"\";\n\n  // Strip trailing `.git` case-insensitively — the whole result is\n  // lowercased at the end, so `.GIT` / `.Git` must be treated the same as\n  // `.git`. Previously the `.endsWith(\".git\")` check let `.GIT` leak\n  // through and appear in the output.\n  if (/\\.git$/i.test(url)) url = url.slice(0, -4);\n\n  // Windows drive-letter local path (e.g. `C:/repos/app`): detect here\n  // so the scp matcher below can accept single-character SSH host aliases\n  // (`h:foo/bar` from `.ssh/config`). A drive letter is exactly one ASCII\n  // letter followed by `:/` or `:\\`; SSH aliases never have a slash\n  // immediately after the colon.\n  if (/^[A-Za-z]:[\\\\/]/.test(url)) {\n    return url.toLowerCase();\n  }\n\n  // Protocol-prefixed: ssh://, https://, http://, git://, file://\n  // Must be tried FIRST so that scp-style detection below doesn't\n  // incorrectly swallow an ssh:// URL that happens to contain `:port/`.\n  //\n  // Matches:\n  //   1: host — bracketed IPv6 `[2001:db8::1]`, plain host with no `:` / `/`,\n  //      OR empty (for `file:///path` which has no host component).\n  //   2: port (optional) — preserved in the output so two repos on the same\n  //      host under different ports get distinct project namespaces.\n  //      Losing the port risked false-coalescing separate repos on custom\n  //      SSH mesh setups.\n  //   3: path (optional)\n  const protoMatch =\n    /^[a-z][a-z0-9+.-]*:\\/\\/(?:[^@/]+@)?(\\[[^\\]]+\\]|[^/:]*)(?::(\\d+))?(\\/.*)?$/i.exec(url);\n  if (protoMatch) {\n    let host = protoMatch[1] ?? \"\";\n    // Detect IPv6 via the bracketed input form BEFORE stripping brackets,\n    // so that when we later re-attach a port we can preserve the\n    // `[host]:port` boundary. Without the brackets, `host:2222` is\n    // ambiguous with a longer bare IPv6 address like `2001:db8::1:2222`.\n    const wasBracketed =\n      host.startsWith(\"[\") && host.endsWith(\"]\");\n    if (wasBracketed) host = host.slice(1, -1);\n    const port = protoMatch[2];\n    const repoPath = (protoMatch[3] ?? \"\").replace(/^\\/+/, \"\");\n    const hostPort = port\n      ? wasBracketed\n        ? `[${host}]:${port}`\n        : `${host}:${port}`\n      : host;\n    // For protocols without a host component (file:///path), fall back to\n    // a stable prefix so distinct local paths don't collapse to \"/path\".\n    const prefix = hostPort.length > 0 ? hostPort : \"localhost\";\n    return `${prefix}/${repoPath}`.toLowerCase();\n  }\n\n  // scp-like syntax: [user@]host:path. Protocol-prefixed URLs (`scheme://`)\n  // are handled above, so the scp branch below guards against them: a\n  // matched `host` of `scheme` followed by a path starting with `//` is\n  // a protocol URL that fell through and must NOT be parsed here.\n  // `user@` is optional — git also accepts userless scp forms like\n  // `host:org/repo`. Valid scp paths may start with digits (e.g.\n  // `git@host:123/repo.git`), so no numeric guard is needed: port-bearing\n  // URLs have the `://` prefix and match the protocol branch above before\n  // reaching here.\n  //\n  // Windows drive letters were filtered above, so single-character SSH\n  // host aliases (`h:foo/bar`) are accepted here.\n  //\n  // Bracketed IPv6 (`[2001:db8::1]`) is supported: the host alternative\n  // matches the bracketed literal up to `]` without splitting on internal\n  // `:`. Brackets are stripped in the normalised form so the scp and\n  // `ssh://` forms of the same IPv6 remote produce identical projectIds.\n  const scpMatch =\n    /^(?:([^@\\s/]+)@)?(\\[[^\\]]+\\]|[^:@\\s/]+):(.+)$/.exec(url);\n  if (scpMatch) {\n    let host = scpMatch[2] ?? \"\";\n    if (host.startsWith(\"[\") && host.endsWith(\"]\")) host = host.slice(1, -1);\n    const repoPath = scpMatch[3] ?? \"\";\n    // Reject protocol-like leftovers (e.g. `file:///path` where the scp\n    // regex greedily matched `file` as host and `///path` as path).\n    if (repoPath.startsWith(\"//\")) {\n      return url.toLowerCase();\n    }\n    return `${host}/${repoPath.replace(/^\\/+/, \"\")}`.toLowerCase();\n  }\n\n  // Fallback: use raw lowercased\n  return url.toLowerCase();\n}\n\n// ──────────────────────────────────────────────────────────────────────────\n// Resolver\n// ──────────────────────────────────────────────────────────────────────────\n\nexport interface ResolveGitContextOptions {\n  /** Inject a git invoker (tests). Defaults to spawning real `git`. */\n  invoker?: GitInvoker;\n}\n\n/**\n * Detect the git project + branch for `cwd`.\n *\n * Returns `null` when:\n *   - `cwd` is not an absolute path (invalid input, CLAUDE.md #51)\n *   - `cwd` is not inside a git worktree\n *   - `git` is not available on PATH\n *\n * Never throws.\n */\nexport async function resolveGitContext(\n  cwd: string,\n  options: ResolveGitContextOptions = {},\n): Promise<GitContext | null> {\n  // Wrap the whole body so the documented \"Never throws\" contract is\n  // enforced. Possible throw sites include:\n  //   - `expandTildePath` → `resolveHomeDir()` → `os.homedir()` when HOME\n  //     is unset (e.g. minimal containers)\n  //   - a custom `options.invoker` that raises instead of returning a\n  //     non-zero exitCode\n  //   - any future helper added to this chain\n  // All of those map to \"not in a repo\" / `null`.\n  try {\n    // Validate input: must be a non-empty string.\n    if (typeof cwd !== \"string\" || cwd.length === 0) return null;\n\n    // Expand `~` per CLAUDE.md #17, then require absolute path.\n    const expanded = expandTildePath(cwd);\n    if (!path.isAbsolute(expanded)) return null;\n\n    const invoker = options.invoker ?? defaultGitInvoker();\n\n    // 1. Locate the repo root.\n    const topLevel = invoker(expanded, [\"rev-parse\", \"--show-toplevel\"]);\n    if (topLevel.exitCode !== 0) return null;\n    const rootPath = topLevel.stdout.trim();\n    if (!rootPath) return null;\n\n    // 2. Current branch. `--abbrev-ref HEAD` returns `HEAD` in detached\n    //    state, which we normalize to `null`. On a fresh `git init` the\n    //    HEAD ref is unborn and `--abbrev-ref HEAD` fails, but\n    //    `symbolic-ref HEAD` still returns the target branch. Fall back\n    //    so newly-initialized repos get a sensible branch name.\n    const branchResult = invoker(rootPath, [\"rev-parse\", \"--abbrev-ref\", \"HEAD\"]);\n    let branch: string | null = null;\n    if (branchResult.exitCode === 0) {\n      const raw = branchResult.stdout.trim();\n      branch = raw && raw !== \"HEAD\" ? raw : null;\n    } else {\n      const unbornRef = invoker(rootPath, [\"symbolic-ref\", \"--quiet\", \"HEAD\"]);\n      if (unbornRef.exitCode === 0) {\n        const raw = unbornRef.stdout.trim();\n        const prefix = \"refs/heads/\";\n        if (raw.startsWith(prefix)) {\n          const candidate = raw.slice(prefix.length);\n          if (candidate) branch = candidate;\n        }\n      }\n    }\n\n    // 3. Origin URL — optional. Used to derive a stable `projectId`.\n    const originResult = invoker(rootPath, [\"remote\", \"get-url\", \"origin\"]);\n    let projectId: string;\n    if (originResult.exitCode === 0) {\n      const normalized = normalizeOriginUrl(originResult.stdout);\n      projectId = normalized ? `origin:${stableHash(normalized)}` : `root:${stableHash(rootPath)}`;\n    } else {\n      projectId = `root:${stableHash(rootPath)}`;\n    }\n\n    // 4. Default branch — best effort.\n    const headRef = invoker(rootPath, [\"symbolic-ref\", \"--quiet\", \"refs/remotes/origin/HEAD\"]);\n    let defaultBranch: string | null = null;\n    if (headRef.exitCode === 0) {\n      const raw = headRef.stdout.trim();\n      const prefix = \"refs/remotes/origin/\";\n      if (raw.startsWith(prefix)) {\n        const candidate = raw.slice(prefix.length);\n        if (candidate) defaultBranch = candidate;\n      }\n    }\n\n    return {\n      projectId,\n      branch,\n      rootPath,\n      defaultBranch,\n    };\n  } catch {\n    // Never throws — any unexpected error falls back to \"not in a repo\".\n    return null;\n  }\n}\n","/**\n * Generic reinforcement-core primitives extracted from `procedure-miner.ts`\n * (issue #687 PR 1/4). Procedure-specific scoring (success rate, step\n * normalization) intentionally stays in the miner — this module only\n * exposes category-agnostic clustering and cluster summarization helpers\n * so future PRs can run reinforcement across non-procedural categories.\n *\n * Pure refactor — no behavior change.\n */\n\n/**\n * Group `items` into clusters keyed by `keyFn(item)`.\n *\n * - Preserves the original input order within each cluster's array.\n * - The returned `Map` insertion order matches first-seen key order, so\n *   downstream iteration is deterministic for a given input.\n * - Throws `TypeError` if `keyFn` returns a non-string (e.g. `undefined`,\n *   `null`, or a number). Callers must produce a stable string key.\n */\nexport function clusterByKey<T>(items: readonly T[], keyFn: (item: T) => string): Map<string, T[]> {\n  const clusters = new Map<string, T[]>();\n  for (const item of items) {\n    const key = keyFn(item);\n    if (typeof key !== \"string\") {\n      throw new TypeError(\n        `clusterByKey: keyFn must return a string, got ${key === null ? \"null\" : typeof key}`,\n      );\n    }\n    const existing = clusters.get(key);\n    if (existing) {\n      existing.push(item);\n    } else {\n      clusters.set(key, [item]);\n    }\n  }\n  return clusters;\n}\n\nexport interface ClusterSummary {\n  /** Number of items in the cluster. */\n  count: number;\n  /** Earliest timestamp seen in the cluster (string min via `localeCompare`). */\n  firstSeen: string;\n  /** Latest timestamp seen in the cluster (string max via `localeCompare`). */\n  lastSeen: string;\n}\n\n/**\n * Summarize a cluster by counting items and tracking earliest/latest\n * timestamps. Timestamp comparison uses `String#localeCompare`, which is\n * correct for ISO-8601 strings (lexicographic order matches chronological\n * order).\n *\n * - Throws `RangeError` on empty clusters — `firstSeen`/`lastSeen` are not\n *   meaningful without at least one item.\n * - When all timestamps are equal, `firstSeen === lastSeen`.\n */\nexport function summarizeCluster<T>(\n  cluster: readonly T[],\n  extractTimestamp: (item: T) => string,\n): ClusterSummary {\n  if (cluster.length === 0) {\n    throw new RangeError(\"summarizeCluster: cluster must contain at least one item\");\n  }\n  let firstSeen = extractTimestamp(cluster[0]);\n  let lastSeen = firstSeen;\n  for (let i = 1; i < cluster.length; i += 1) {\n    const ts = extractTimestamp(cluster[i]);\n    if (ts.localeCompare(firstSeen) < 0) firstSeen = ts;\n    if (ts.localeCompare(lastSeen) > 0) lastSeen = ts;\n  }\n  return { count: cluster.length, firstSeen, lastSeen };\n}\n"],"mappings":"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","names":[]}