/**
 * Cursor provenance: which repository did a ledger entry's usage actually come from?
 *
 * Every priced ledger entry carries a `cursor` — the uuid of the transcript record
 * it was extracted from. That makes provenance *checkable* rather than inferred:
 * find the transcript file containing that uuid and ask which repo it belongs to.
 *
 * This exists because `transcriptRoot` is one directory holding every project this
 * machine has ever worked on, and `sync.ts:locateByInterval` walked all of them
 * matching on file mtime with no repository check. The measured result was 711
 * entries (262.5M tokens) from an unrelated repository sitting in two instance
 * ledgers — one instance's entire cost figure was another project's work.
 * `projectClaudeCodeRecords` already scopes *forward* correctly; this scopes
 * *backward*, over entries already written.
 *
 * Two properties are deliberate and load-bearing:
 *
 * 1. **A uuid is not guaranteed unique across files.** `/branch` copies a
 *    transcript, so the same uuid can appear in several. Measured here: 102 uuids
 *    in two files each, 0 crossing a repository boundary. So a uuid resolving into
 *    more than one repo is `ambiguous`, never `foreign` — the purge must not delete
 *    on a coin flip that happens to be safe today.
 * 2. **Unknown is not foreign.** A cursor absent from every transcript (2,065 here,
 *    from rotated or deleted files) and a cwd whose git identity cannot be read are
 *    both `unknown`. Under-recovering is the safe direction, the same choice
 *    `projectClaudeCodeRecords` documents.
 *
 * Requirements: turn-scoped-cost/AC-34, AC-43
 * Design: design.md Part 0 (D0.1, D0.3, D0.4, D0.7)
 */
import type { ProviderEnv } from './providers/provider.js';
/**
 * Where a cursor's usage came from, relative to this repository.
 *
 * `ambiguous` and `unknown` are distinct because they mean different things to a
 * reader even though both forbid purging: `ambiguous` is "found, in more than one
 * repo", `unknown` is "not found at all".
 */
export type CursorOrigin = 'local' | 'foreign' | 'ambiguous' | 'unknown';
/** Cursor uuid → the repo identities of every transcript file containing it. */
export type ProvenanceIndex = Map<string, Set<string>>;
/**
 * A directory's git common dir, as an absolute path — the identity every worktree
 * of one repository shares.
 *
 * Same expression as `sync.ts:repoCommonDir`, kept separate for the same reason
 * that one is kept separate from `sessions.ts:repoIdentity`: `git rev-parse
 * --git-common-dir` answers relatively from a primary checkout and absolutely from
 * a linked worktree, so the `resolve` is required, and callers with the opposite
 * requirement must not share it.
 */
export declare function repoCommonDir(cwd: string): string | null;
/**
 * Index every uuid in every local transcript to the repo identity of its file.
 *
 * One pass over the transcript root, because the alternative — resolving each
 * cursor on demand — rescans every file per lookup. A transcript whose cwd or git
 * identity cannot be read contributes its uuids under no identity at all, which
 * makes them `unknown` rather than silently `foreign`.
 */
export declare function buildProvenanceIndex(env: ProviderEnv, 
/**
 * What to record per uuid. Defaults to the repo identity, which is what purging
 * needs; re-derivation passes the file path instead, because a split has to open
 * the transcript. One walk, two callers — the alternative was a second traversal
 * that could disagree with this one about which file holds a uuid.
 */
valueOf?: (path: string, identity: string) => string): ProvenanceIndex;
/**
 * Classify one cursor against this repository.
 *
 * `null`/empty cursor is `unknown`: an entry with nothing to trace cannot be shown
 * to be foreign. A cursor found under this repo's identity is `local` even if it
 * also appears elsewhere — the local sighting is positive evidence that this repo
 * produced it, which is exactly what a `/branch` copy looks like.
 */
export declare function classifyCursor(cursor: string | null, index: ProvenanceIndex, hereIdentity: string | null): CursorOrigin;
/** Is this cursor safe to purge — i.e. positively shown to be another repo's? */
export declare function isPurgeable(origin: CursorOrigin): boolean;
//# sourceMappingURL=provenance.d.ts.map