@saasontools/strauss-kb 0.1.14 → 0.1.15

package/dist/index.d.cts

@@ -187,12 +187,14 @@ type KbRecord = {
     body: string;
 };
 
+/** Where bare mirrors live. Overridable so a test never writes to `$HOME`. */
+declare function repoCacheDir(override?: string): string;
+
 /**
- * Resolves symbolic anchors to text and detects drift against stored hashes.
+ * The vocabulary anchor resolution is reported in.
  *
- * Resolvers are pure — source string in, range out; only the file readers touch
- * disk. Any shape the lexer cannot handle confidently returns `null` and is
- * reported `unresolved` rather than guessed at.
+ * Every failure is a finding with a reason, never a throw: a record pointing
+ * at code that moved is information, not a broken run.
  */
 type ResolvedSymbol = {
     text: string;
@@ -206,36 +208,22 @@ interface AnchorResolver {
 }
 /** Why an anchor could not be compared. Never an error — always a finding. */
 type AnchorUnresolvedReason = "file-missing" | "symbol-not-found" | "outside-repo" | "file-too-large" | "file-unreadable"
-/**
- * The anchor names a repository this root is not. Expected rather than
- * wrong — a base describing several repositories resolves against one tree
- * at a time — so it is never a drift finding and never reaches a reader as
- * a warning. Multi-root resolution is SAA-709.
- */
- | "foreign-repo";
-/**
- * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
- * its last segment, with the parent used to scope the search: a candidate
- * counts only if the parent name appears in the fifty lines above it, when any
- * candidate satisfies that at all.
- *
- * Deterministic, and ambiguity is not resolved by guessing — two lines of
- * equally good shape mean the resolver cannot tell which one the record meant,
- * and it says so by returning `null`.
- */
-declare const regexResolver: AnchorResolver;
-/** CRLF normalized to LF before hashing, so checkout style cannot read as drift. */
-declare function hashAnchorText(text: string): string;
-/**
- * An anchor without a symbol is about the whole file; with one, the resolver
- * decides. Source newlines are normalized first so line counts and hashes
- * agree with `hashAnchorText`.
- *
- * A file's last line is the last line with content: a trailing newline is a
- * terminator, not an empty line, and counting it would have made every
- * whole-file anchor's `lines` one larger than the file.
- */
-declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
+/** The remote could not be fetched, or `--offline` found nothing cached. */
+ | "remote-unreachable"
+/** The anchor's `ref` is not on the remote any more. */
+ | "ref-not-found" | "repo-unauthorized"
+/** No default branch, so there is no "current" to compare against. */
+ | "default-branch-unknown"
+/** The anchor's `ref` is not a name git may safely be handed. */
+ | "ref-invalid"
+/** The anchor's `repo` is not a remote we will fetch from. */
+ | "repo-invalid";
+/**
+ * How a ref-pinned foreign anchor stands. `drifted-on-default` is the one a
+ * working-tree anchor has no equivalent of: the evidence is still true at the
+ * commit it was taken from, and the code has moved since.
+ */
+type RemoteAnchorState = "matches-ref" | "drifted-from-ref" | "drifted-on-default";
 type KbAnchorDriftEntry = {
     file: string;
     symbol?: string;
@@ -245,17 +233,10 @@ type KbAnchorDriftEntry = {
     /** `null` when the anchor recorded no `lines` — size unknown, not zero. */
     diffSize: number | null;
     reason?: AnchorUnresolvedReason;
+    /** Set only when the anchor was resolved against another repository. */
+    repo?: string;
+    remoteState?: RemoteAnchorState;
 };
-/**
- * An anchor's `file` must stay inside the repository root — a record points
- * at code, not at arbitrary files on the machine reading it. Bundles are
- * data, so a traversal or absolute path here is untrusted input, not a bug
- * in the caller. Returns the resolved path, or `null` when it escapes.
- *
- * Lexical only, and therefore not the whole containment check: see
- * `readAnchorFile`, which re-tests the real path after following symlinks.
- */
-declare function anchorFilePath(repoRoot: string, file: string): string | null;
 type AnchorRead = {
     ok: true;
     source: string;
@@ -264,26 +245,109 @@ type AnchorRead = {
     reason: AnchorUnresolvedReason;
 };
 type AnchorFileReader = (file: string) => Promise<AnchorRead>;
+
 /**
- * Re-resolves every hash-carrying anchor and compares against the stored hash.
- *
- * Anchors without a `hash` are skipped; one naming another repository is
- * reported `foreign-repo` and never read, and `origin` is asked for once per
- * run, only when some anchor declares a `repo`. A missing file or unresolvable
- * symbol is a finding (`unresolved`), never a throw. Each distinct file is read
- * once per run; all checked entries are returned per record, callers filter.
+ * A foreign anchor's file at one rev. `ref` absent means the remote's default
+ * branch — the "current" side of a ref-pinned comparison.
+ */
+type RemoteWant = {
+    repo: string;
+    ref?: string;
+    file: string;
+};
+type RemoteRead = {
+    ok: true;
+    source: string;
+} | {
+    ok: false;
+    reason: AnchorUnresolvedReason;
+};
+type RemoteOptions = {
+    /** Cache only: no `fetch`, no `ls-remote`. */
+    offline?: boolean;
+    cacheDir?: string;
+    fetchTimeoutMs?: number;
+    /** Repositories worked on at once; fetches within one repo stay serial. */
+    concurrency?: number;
+};
+
+/**
+ * Reads each wanted (repo, rev, file) out of a bare cache under
+ * `~/.strauss/repo-cache`, fetching once per (repo, rev) and never per anchor.
  *
- * Three phases: collect the checkable anchors, read their distinct files with
- * a bounded pool, then resolve and hash in record order — so the output does
- * not depend on which read finished first.
+ * Every failure lands as an `unresolved` reason on the wants it affects; no
+ * path is read from disk, so containment does not apply here.
  */
-declare function detectAnchorDrift(records: KbRecord[], options?: {
+declare function readRemoteAnchors(wants: readonly RemoteWant[], options?: RemoteOptions): Promise<Map<string, RemoteRead>>;
+
+type AnchorDriftOptions = {
     repoRoot?: string;
     resolver?: AnchorResolver;
     concurrency?: number;
     /** Test seam: replaces the disk reader. */
     reader?: AnchorFileReader;
-}): Promise<Map<string, KbAnchorDriftEntry[]>>;
+    /** Remote resolution of foreign anchors; `offline` keeps a run off the wire. */
+    remote?: RemoteOptions;
+    /** Test seam: replaces the remote blob reader. */
+    readRemote?: typeof readRemoteAnchors;
+};
+/**
+ * Re-resolves every hash-carrying anchor and compares against the stored hash.
+ *
+ * An anchor naming another repository is read from that repository's remote
+ * through a bare cache; everything else is read from the working tree. A
+ * missing file, an unreachable remote, or an unresolvable symbol is a finding
+ * (`unresolved`), never a throw.
+ *
+ * Four phases: collect the checkable anchors, read the working tree's distinct
+ * files and the remotes' distinct (repo, rev, file) blobs, then resolve and
+ * hash in record order — so the output never depends on which read finished
+ * first.
+ */
+declare function detectAnchorDrift(records: KbRecord[], options?: AnchorDriftOptions): Promise<Map<string, KbAnchorDriftEntry[]>>;
+
+/**
+ * An anchor's `file` must stay inside the repository root — a record points
+ * at code, not at arbitrary files on the machine reading it. Bundles are
+ * data, so a traversal or absolute path here is untrusted input, not a bug
+ * in the caller. Returns the resolved path, or `null` when it escapes.
+ *
+ * Lexical only, and therefore not the whole containment check: see
+ * `readAnchorFile`, which re-tests the real path after following symlinks.
+ */
+declare function anchorFilePath(repoRoot: string, file: string): string | null;
+
+/**
+ * Does this spelling say where the repository lives?
+ *
+ * Only a full URL can be fetched from. A short form still matches this root's
+ * own origin, which is why `validate` warns rather than rejects.
+ */
+declare function isCanonicalRepoUrl(value: string): boolean;
+
+/**
+ * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
+ * its last segment, with the parent used to scope the search: a candidate
+ * counts only if the parent name appears in the fifty lines above it, when any
+ * candidate satisfies that at all.
+ *
+ * Deterministic, and ambiguity is not resolved by guessing — two lines of
+ * equally good shape mean the resolver cannot tell which one the record meant,
+ * and it says so by returning `null`.
+ */
+declare const regexResolver: AnchorResolver;
+/** CRLF normalized to LF before hashing, so checkout style cannot read as drift. */
+declare function hashAnchorText(text: string): string;
+/**
+ * An anchor without a symbol is about the whole file; with one, the resolver
+ * decides. Source newlines are normalized first so line counts and hashes
+ * agree with `hashAnchorText`.
+ *
+ * A file's last line is the last line with content: a trailing newline is a
+ * terminator, not an empty line, and counting it would have made every
+ * whole-file anchor's `lines` one larger than the file.
+ */
+declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
 
 /**
  * Why a matched record must not be read as a plain answer.
@@ -334,13 +398,23 @@ type KbWarning =
  *  the record may describe code that no longer exists in that form. */
  | {
     kind: "drifted";
-    anchors: {
-        file: string;
-        symbol?: string;
-        /** `null` when the anchor recorded no line count — size unknown. */
-        diffSize: number | null;
-        reason?: string;
-    }[];
+    anchors: KbWarningAnchor[];
+}
+/** A foreign anchor nothing could check: the remote was unreachable, refused,
+ *  or the run was offline. Neither drift nor a clean match. */
+ | {
+    kind: "unchecked";
+    anchors: KbWarningAnchor[];
+};
+type KbWarningAnchor = {
+    file: string;
+    symbol?: string;
+    /** `null` when the anchor recorded no line count — size unknown. */
+    diffSize: number | null;
+    reason?: string;
+    /** Set only for an anchor resolved against another repository. */
+    repo?: string;
+    remoteState?: string;
 };
 type KbStanding = "current" | "superseded" | "rejected" | "unsettled" | "open";
 type KbAdjudicated = {
@@ -858,7 +932,8 @@ declare class KbStore {
      * at the repo root, and the MCP server's cwd is the workspace.
      *
      * Public because `doctor` needs the same map with the same degradation: a
-     * sweep that failed to read the tree should report no drift, not fail.
+     * sweep that failed to read the tree should report no drift, not fail — and
+     * `offline: false` there, because a sweep is worth a fetch.
      *
      * When no root was given and not one anchored file was found, the finding is
      * discarded. A base read from somewhere other than the tree it describes
@@ -870,7 +945,9 @@ declare class KbStore {
      * plausible, and the misses become findings again; an explicit `repoRoot` is
      * taken at its word either way.
      */
-    detectDrift(records: KbRecord[], repoRoot?: string): Promise<Map<string, KbAnchorDriftEntry[]> | undefined>;
+    detectDrift(records: KbRecord[], repoRoot?: string, options?: {
+        offline?: boolean;
+    }): Promise<Map<string, KbAnchorDriftEntry[]> | undefined>;
     /**
      * The whole base, adjudicated, when it is small enough to hand over.
      *
@@ -1727,7 +1804,7 @@ declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
 declare const DEFAULT_EXPIRING_DAYS = 30;
 declare const DEFAULT_UNVERIFIED_DAYS = 90;
 declare const DEFAULT_AGING_DAYS = 90;
-declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited", "drifted"];
+declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited", "drifted", "unchecked"];
 type KbDoctorCheck = (typeof KB_DOCTOR_CHECKS)[number];
 type KbDoctorFinding = {
     conceptId: string;
@@ -2071,4 +2148,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, impact, inboundIndex, indexIsStale, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };
+export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type RemoteAnchorState, type RemoteOptions, type RemoteRead, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, impact, inboundIndex, indexIsStale, isCanonicalRepoUrl, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, readRemoteAnchors, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };

package/dist/index.d.ts

@@ -187,12 +187,14 @@ type KbRecord = {
     body: string;
 };
 
+/** Where bare mirrors live. Overridable so a test never writes to `$HOME`. */
+declare function repoCacheDir(override?: string): string;
+
 /**
- * Resolves symbolic anchors to text and detects drift against stored hashes.
+ * The vocabulary anchor resolution is reported in.
  *
- * Resolvers are pure — source string in, range out; only the file readers touch
- * disk. Any shape the lexer cannot handle confidently returns `null` and is
- * reported `unresolved` rather than guessed at.
+ * Every failure is a finding with a reason, never a throw: a record pointing
+ * at code that moved is information, not a broken run.
  */
 type ResolvedSymbol = {
     text: string;
@@ -206,36 +208,22 @@ interface AnchorResolver {
 }
 /** Why an anchor could not be compared. Never an error — always a finding. */
 type AnchorUnresolvedReason = "file-missing" | "symbol-not-found" | "outside-repo" | "file-too-large" | "file-unreadable"
-/**
- * The anchor names a repository this root is not. Expected rather than
- * wrong — a base describing several repositories resolves against one tree
- * at a time — so it is never a drift finding and never reaches a reader as
- * a warning. Multi-root resolution is SAA-709.
- */
- | "foreign-repo";
-/**
- * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
- * its last segment, with the parent used to scope the search: a candidate
- * counts only if the parent name appears in the fifty lines above it, when any
- * candidate satisfies that at all.
- *
- * Deterministic, and ambiguity is not resolved by guessing — two lines of
- * equally good shape mean the resolver cannot tell which one the record meant,
- * and it says so by returning `null`.
- */
-declare const regexResolver: AnchorResolver;
-/** CRLF normalized to LF before hashing, so checkout style cannot read as drift. */
-declare function hashAnchorText(text: string): string;
-/**
- * An anchor without a symbol is about the whole file; with one, the resolver
- * decides. Source newlines are normalized first so line counts and hashes
- * agree with `hashAnchorText`.
- *
- * A file's last line is the last line with content: a trailing newline is a
- * terminator, not an empty line, and counting it would have made every
- * whole-file anchor's `lines` one larger than the file.
- */
-declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
+/** The remote could not be fetched, or `--offline` found nothing cached. */
+ | "remote-unreachable"
+/** The anchor's `ref` is not on the remote any more. */
+ | "ref-not-found" | "repo-unauthorized"
+/** No default branch, so there is no "current" to compare against. */
+ | "default-branch-unknown"
+/** The anchor's `ref` is not a name git may safely be handed. */
+ | "ref-invalid"
+/** The anchor's `repo` is not a remote we will fetch from. */
+ | "repo-invalid";
+/**
+ * How a ref-pinned foreign anchor stands. `drifted-on-default` is the one a
+ * working-tree anchor has no equivalent of: the evidence is still true at the
+ * commit it was taken from, and the code has moved since.
+ */
+type RemoteAnchorState = "matches-ref" | "drifted-from-ref" | "drifted-on-default";
 type KbAnchorDriftEntry = {
     file: string;
     symbol?: string;
@@ -245,17 +233,10 @@ type KbAnchorDriftEntry = {
     /** `null` when the anchor recorded no `lines` — size unknown, not zero. */
     diffSize: number | null;
     reason?: AnchorUnresolvedReason;
+    /** Set only when the anchor was resolved against another repository. */
+    repo?: string;
+    remoteState?: RemoteAnchorState;
 };
-/**
- * An anchor's `file` must stay inside the repository root — a record points
- * at code, not at arbitrary files on the machine reading it. Bundles are
- * data, so a traversal or absolute path here is untrusted input, not a bug
- * in the caller. Returns the resolved path, or `null` when it escapes.
- *
- * Lexical only, and therefore not the whole containment check: see
- * `readAnchorFile`, which re-tests the real path after following symlinks.
- */
-declare function anchorFilePath(repoRoot: string, file: string): string | null;
 type AnchorRead = {
     ok: true;
     source: string;
@@ -264,26 +245,109 @@ type AnchorRead = {
     reason: AnchorUnresolvedReason;
 };
 type AnchorFileReader = (file: string) => Promise<AnchorRead>;
+
 /**
- * Re-resolves every hash-carrying anchor and compares against the stored hash.
- *
- * Anchors without a `hash` are skipped; one naming another repository is
- * reported `foreign-repo` and never read, and `origin` is asked for once per
- * run, only when some anchor declares a `repo`. A missing file or unresolvable
- * symbol is a finding (`unresolved`), never a throw. Each distinct file is read
- * once per run; all checked entries are returned per record, callers filter.
+ * A foreign anchor's file at one rev. `ref` absent means the remote's default
+ * branch — the "current" side of a ref-pinned comparison.
+ */
+type RemoteWant = {
+    repo: string;
+    ref?: string;
+    file: string;
+};
+type RemoteRead = {
+    ok: true;
+    source: string;
+} | {
+    ok: false;
+    reason: AnchorUnresolvedReason;
+};
+type RemoteOptions = {
+    /** Cache only: no `fetch`, no `ls-remote`. */
+    offline?: boolean;
+    cacheDir?: string;
+    fetchTimeoutMs?: number;
+    /** Repositories worked on at once; fetches within one repo stay serial. */
+    concurrency?: number;
+};
+
+/**
+ * Reads each wanted (repo, rev, file) out of a bare cache under
+ * `~/.strauss/repo-cache`, fetching once per (repo, rev) and never per anchor.
  *
- * Three phases: collect the checkable anchors, read their distinct files with
- * a bounded pool, then resolve and hash in record order — so the output does
- * not depend on which read finished first.
+ * Every failure lands as an `unresolved` reason on the wants it affects; no
+ * path is read from disk, so containment does not apply here.
  */
-declare function detectAnchorDrift(records: KbRecord[], options?: {
+declare function readRemoteAnchors(wants: readonly RemoteWant[], options?: RemoteOptions): Promise<Map<string, RemoteRead>>;
+
+type AnchorDriftOptions = {
     repoRoot?: string;
     resolver?: AnchorResolver;
     concurrency?: number;
     /** Test seam: replaces the disk reader. */
     reader?: AnchorFileReader;
-}): Promise<Map<string, KbAnchorDriftEntry[]>>;
+    /** Remote resolution of foreign anchors; `offline` keeps a run off the wire. */
+    remote?: RemoteOptions;
+    /** Test seam: replaces the remote blob reader. */
+    readRemote?: typeof readRemoteAnchors;
+};
+/**
+ * Re-resolves every hash-carrying anchor and compares against the stored hash.
+ *
+ * An anchor naming another repository is read from that repository's remote
+ * through a bare cache; everything else is read from the working tree. A
+ * missing file, an unreachable remote, or an unresolvable symbol is a finding
+ * (`unresolved`), never a throw.
+ *
+ * Four phases: collect the checkable anchors, read the working tree's distinct
+ * files and the remotes' distinct (repo, rev, file) blobs, then resolve and
+ * hash in record order — so the output never depends on which read finished
+ * first.
+ */
+declare function detectAnchorDrift(records: KbRecord[], options?: AnchorDriftOptions): Promise<Map<string, KbAnchorDriftEntry[]>>;
+
+/**
+ * An anchor's `file` must stay inside the repository root — a record points
+ * at code, not at arbitrary files on the machine reading it. Bundles are
+ * data, so a traversal or absolute path here is untrusted input, not a bug
+ * in the caller. Returns the resolved path, or `null` when it escapes.
+ *
+ * Lexical only, and therefore not the whole containment check: see
+ * `readAnchorFile`, which re-tests the real path after following symlinks.
+ */
+declare function anchorFilePath(repoRoot: string, file: string): string | null;
+
+/**
+ * Does this spelling say where the repository lives?
+ *
+ * Only a full URL can be fetched from. A short form still matches this root's
+ * own origin, which is why `validate` warns rather than rejects.
+ */
+declare function isCanonicalRepoUrl(value: string): boolean;
+
+/**
+ * v1 heuristic resolver. A dotted symbol like `OrderService.cancel` matches on
+ * its last segment, with the parent used to scope the search: a candidate
+ * counts only if the parent name appears in the fifty lines above it, when any
+ * candidate satisfies that at all.
+ *
+ * Deterministic, and ambiguity is not resolved by guessing — two lines of
+ * equally good shape mean the resolver cannot tell which one the record meant,
+ * and it says so by returning `null`.
+ */
+declare const regexResolver: AnchorResolver;
+/** CRLF normalized to LF before hashing, so checkout style cannot read as drift. */
+declare function hashAnchorText(text: string): string;
+/**
+ * An anchor without a symbol is about the whole file; with one, the resolver
+ * decides. Source newlines are normalized first so line counts and hashes
+ * agree with `hashAnchorText`.
+ *
+ * A file's last line is the last line with content: a trailing newline is a
+ * terminator, not an empty line, and counting it would have made every
+ * whole-file anchor's `lines` one larger than the file.
+ */
+declare function resolveAnchor(source: string, anchor: KbAnchor, resolver?: AnchorResolver): ResolvedSymbol | null;
 
 /**
  * Why a matched record must not be read as a plain answer.
@@ -334,13 +398,23 @@ type KbWarning =
  *  the record may describe code that no longer exists in that form. */
  | {
     kind: "drifted";
-    anchors: {
-        file: string;
-        symbol?: string;
-        /** `null` when the anchor recorded no line count — size unknown. */
-        diffSize: number | null;
-        reason?: string;
-    }[];
+    anchors: KbWarningAnchor[];
+}
+/** A foreign anchor nothing could check: the remote was unreachable, refused,
+ *  or the run was offline. Neither drift nor a clean match. */
+ | {
+    kind: "unchecked";
+    anchors: KbWarningAnchor[];
+};
+type KbWarningAnchor = {
+    file: string;
+    symbol?: string;
+    /** `null` when the anchor recorded no line count — size unknown. */
+    diffSize: number | null;
+    reason?: string;
+    /** Set only for an anchor resolved against another repository. */
+    repo?: string;
+    remoteState?: string;
 };
 type KbStanding = "current" | "superseded" | "rejected" | "unsettled" | "open";
 type KbAdjudicated = {
@@ -858,7 +932,8 @@ declare class KbStore {
      * at the repo root, and the MCP server's cwd is the workspace.
      *
      * Public because `doctor` needs the same map with the same degradation: a
-     * sweep that failed to read the tree should report no drift, not fail.
+     * sweep that failed to read the tree should report no drift, not fail — and
+     * `offline: false` there, because a sweep is worth a fetch.
      *
      * When no root was given and not one anchored file was found, the finding is
      * discarded. A base read from somewhere other than the tree it describes
@@ -870,7 +945,9 @@ declare class KbStore {
      * plausible, and the misses become findings again; an explicit `repoRoot` is
      * taken at its word either way.
      */
-    detectDrift(records: KbRecord[], repoRoot?: string): Promise<Map<string, KbAnchorDriftEntry[]> | undefined>;
+    detectDrift(records: KbRecord[], repoRoot?: string, options?: {
+        offline?: boolean;
+    }): Promise<Map<string, KbAnchorDriftEntry[]> | undefined>;
     /**
      * The whole base, adjudicated, when it is small enough to hand over.
      *
@@ -1727,7 +1804,7 @@ declare function validateBundle(records: KbRecord[]): KbValidationProblem[];
 declare const DEFAULT_EXPIRING_DAYS = 30;
 declare const DEFAULT_UNVERIFIED_DAYS = 90;
 declare const DEFAULT_AGING_DAYS = 90;
-declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited", "drifted"];
+declare const KB_DOCTOR_CHECKS: readonly ["expired", "expiring", "unverified", "aging", "orphaned", "broken-supersession", "superseded-but-cited", "drifted", "unchecked"];
 type KbDoctorCheck = (typeof KB_DOCTOR_CHECKS)[number];
 type KbDoctorFinding = {
     conceptId: string;
@@ -2071,4 +2148,4 @@ declare function parseMarkdownWithFrontmatter<S extends z.ZodType>(text: string,
     frontmatter: ReturnType<S["safeParse"]>;
 };
 
-export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, impact, inboundIndex, indexIsStale, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };
+export { type AnchorResolver, BaseError, CONTEXT_BEGIN, CONTEXT_END, CONTEXT_PROFILES, type ComposeInput, type ComposeLink, type ComposedRecord, DECISION_TYPE, DEFAULT_AGING_DAYS, DEFAULT_EXPIRING_DAYS, DEFAULT_LOAD_BUDGET, DEFAULT_PACK_HOPS, DEFAULT_PACK_MAX_NODES, DEFAULT_TYPED_LINK_RELS, DEFAULT_UNVERIFIED_DAYS, type DecisionInput, type DiffFile, type DiffHunk, type DiffMatch, type ErrorDetails, type ErrorProps, ErrorTypes, Fault, INDEX_FILE, KB_CAUSAL_LINK_RELS, KB_COMMANDS, KB_COMMANDS_BY_NAME, KB_CONCEPT_ID_PATTERN, KB_CONFIDENCES, KB_DIR, KB_DOCTOR_CHECKS, KB_EDGE_KINDS, KB_LINK_RELS, KB_MATERIALITIES, KB_RECORD_STATUSES, KB_RECORD_TYPES, KB_SLUG_PATTERN, type KbActorStamp, type KbAdjudicated, type KbAnchor, type KbAnchorDriftEntry, type KbBacklink, type KbBacklinksResult, KbBaseFrozenError, type KbCatalogEntry, type KbCatalogResult, type KbCommand, type KbCommandContext, type KbContextBudgets, type KbContextOptions, type KbContextResult, type KbDoctorCheck, type KbDoctorFinding, type KbDoctorGroup, type KbDoctorOptions, type KbDoctorReport, type KbDoctorThresholds, type KbEdgeKind, type KbImpactOptions, type KbImpactResult, type KbImpactedRecord, type KbInboundEdge, KbInvalidConceptIdError, type KbLink, type KbLinkEdge, type KbLinkRel, type KbLinkRelSpec, type KbLoadResult, type KbLogEntry, type KbLogReadResult, type KbLogger, type KbMergedPin, type KbMergedPins, KbMissingFlagValueError, type KbNeighbour, KbPackBudgetExceededError, type KbPackOptions, type KbPackResult, type KbPackedRecord, type KbPin, type KbPinLayer, type KbPinOptions, type KbPinResult, type KbPinStatus, KbPinsMalformedError, type KbPinsManifest, type KbRecord, KbRecordAlreadyExistsError, type KbRecordFrontmatter, KbRecordNotFoundError, type KbRecordStatus, type KbRecordType, type KbRecordTypeSpec, type KbSearchLogger, KbSelfVerificationError, type KbSource, type KbStanding, KbStore, type KbSupersededStub, type KbSyncResult, type KbTraceEdge, type KbTraceOptions, type KbTraceStep, KbUnknownLinkRelError, type KbValidationProblem, type KbValidationSeverity, type KbVerifiedEvent, type KbWarning, KbWriteConflictError, type KbWriteInput, LINK_RELS, LOG_FILE, type MatchOptions, NO_DECISION_SLUG, PINS_FILE, PINS_LOCAL_FILE, PIN_LAYERS, type QmdModule, RECORD_TYPES, type RemoteAnchorState, type RemoteOptions, type RemoteRead, type ResolvedSymbol, SEARCH_INDEX_FILE, type SearchHit, type SearchOptions, type SymbolRange, TRACE_EDGES, adjudicate, anchorFilePath, assertBaseNotFrozen, backlinks, buildContext, catalog, composeDecisionRecord, composeInputSchema, composeLinkSchema, composeNoDecisionRecord, composeRecord, contextProfileBudgets, createKbMcpServer, decisionInputSchema, detectAnchorDrift, doctor, edgeNeighbours, hashAnchorText, impact, inboundIndex, indexIsStale, isCanonicalRepoUrl, isKbLinkRel, isKbRecordType, isNoDecisionRecord, kbActorStampSchema, kbAnchorSchema, kbConceptIdSchema, kbJsonSchemas, kbLinkSchema, kbLogEntrySchema, kbRecordFrontmatterSchema, kbSourceSchema, kbVerifiedEventSchema, listPins, loadQmd, matchToDiff, mergedContextBudgets, neighbours, pack, parseLog, parseMarkdownWithFrontmatter, pinBase, readMergedPins, readPinsLayer, readRemoteAnchors, regexResolver, renderCatalogLine, renderIndex, renderIndexLine, renderLogEntry, repoCacheDir, resolveAnchor, resolveHeads, resolveHits, resolvePinPath, runKbCli, runKbMcpServer, searchBase, selectDecisions, splitMarkdownFrontmatter, stringifyMarkdownWithFrontmatter, syncInstructions, toHookJson, trace, unpinBase, validateBundle };

package/dist/index.js

@@ -1,10 +1,10 @@
 import {
   runKbCli
-} from "./chunk-MBXNCZ4V.js";
+} from "./chunk-MK7GU4DX.js";
 import {
   createKbMcpServer,
   runKbMcpServer
-} from "./chunk-PYA5E7FL.js";
+} from "./chunk-LACCRB2Y.js";
 import {
   BaseError,
   CONTEXT_BEGIN,
@@ -74,6 +74,7 @@ import {
   impact,
   inboundIndex,
   indexIsStale,
+  isCanonicalRepoUrl,
   isKbLinkRel,
   isKbRecordType,
   isNoDecisionRecord,
@@ -96,11 +97,13 @@ import {
   pinBase,
   readMergedPins,
   readPinsLayer,
+  readRemoteAnchors,
   regexResolver,
   renderCatalogLine,
   renderIndex,
   renderIndexLine,
   renderLogEntry,
+  repoCacheDir,
   resolveAnchor,
   resolveHeads,
   resolveHits,
@@ -114,7 +117,7 @@ import {
   trace,
   unpinBase,
   validateBundle
-} from "./chunk-43KALLFU.js";
+} from "./chunk-KNIUBCZY.js";
 
 // src/match-diff.ts
 function matchToDiff(files, records, options = {}) {
@@ -265,6 +268,7 @@ export {
   impact,
   inboundIndex,
   indexIsStale,
+  isCanonicalRepoUrl,
   isKbLinkRel,
   isKbRecordType,
   isNoDecisionRecord,
@@ -288,11 +292,13 @@ export {
   pinBase,
   readMergedPins,
   readPinsLayer,
+  readRemoteAnchors,
   regexResolver,
   renderCatalogLine,
   renderIndex,
   renderIndexLine,
   renderLogEntry,
+  repoCacheDir,
   resolveAnchor,
   resolveHeads,
   resolveHits,