Classes
class	CodeSite
class	Receipt
class	ReceiptFile
class	LexiconEntry
class	ConfigError
class	AuditResult

Functions
str	code_fingerprint (list[str] lines, int start, int end)
str	claim_fingerprint (str claim_text)
tuple[str, list[tuple[int, int]]]	relocate_site (list[str] lines, CodeSite site)
list[LexiconEntry]	load_lexicon (Path root)
tuple[str, bool]	_strip_code_and_comments (str line, bool in_html_comment)
dict[str, int]	find_tags (list[str] lines)
list[str]	find_all_tag_ids (list[str] lines)
bool	_line_is_tagged (list[str] lines, int idx)
set[str]	_waived_tokens (list[str] lines, int idx)
list[dict[str, object]]	scan_untagged_triggers (list[str] lines, list[LexiconEntry] lexicon, str rel)
str	render_markdown (ReceiptFile receipt_file)
str	canonical_json (ReceiptFile receipt_file)
ReceiptFile	load_receipts (Path root)
list[str]	_read_lines (Path root, str rel)
AuditResult	run_audit (Path root, bool allow_disputed)
int	refresh (Path root, bool only_relocations, str\|None claim_id)
str	_format_report (AuditResult result)
int	check (Path root, bool allow_disputed, bool as_json)
int	main (list[str]\|None argv=None)

Variables
tuple	GOVERNED_DOCS
str	RECEIPTS_JSON = "oc_chat/docs/architecture/orchestration/audits/registry_v0_24_valid_claims.json"
str	RECEIPTS_MD = "oc_chat/docs/architecture/orchestration/audits/registry_v0_24_valid_claims.md"
str	LEXICON_FILE = "tools/valid_audit_lexicon.txt"
str	FP_SCHEMA = "vald1"
int	RECEIPTS_SCHEMA_VERSION = 1
	_TAG_RE = re.compile(r"<!--\s@claim:\s(VC-\d{4})\s*-->")
	_EXEMPT_RE = re.compile(r"<!--\s@claim-exempt:\s([A-Za-z0-9_,-]+?)\s(?:—\|--)\s.+?-->")

Detailed Description

V-A-L-I-D — Verified Against Live Implementation Details.

Purpose
-------
The committed, CI-gated claim-vs-code audit for the registry spec
([OP-6], REGISTRY_SOURCE_AND_STORAGE_SPEC_V0_24.md §0.3 as amended by
[OP-8] + erratum). It keeps every present-tense, code-facing current-state
claim in the governed docs honest by construction: each tagged claim binds
to a committed receipt whose per-site code fingerprints must re-locate in
the live tree and whose claim text must still be verbatim-present at its tag.

Responsibilities
----------------
- Parse the committed receipts JSON (the system-of-record) through a
  pydantic-strict schema and check it agrees with the rendered markdown view.
- Enforce the tag<->receipt bijection (both-ways orphan check).
- Re-locate every `resolved_code_sites` fingerprint (hint range, then a
  sliding same-line-count window): 0 = drift (fail), 1 = mechanical
  relocation (reported, non-fatal in check mode), >=2 = ambiguous (fail).
- Assert each receipt's `claim_text` is verbatim-present at its tag; report a
  stale `spec_line` as a non-fatal mechanical provenance update.
- Scan the governed docs for untagged current-state trigger lines
  (fence/comment-aware) against `tools/valid_audit_lexicon.txt`, honouring
  token-scoped inline `@claim-exempt` waivers.
- Fail closed on any `DISPUTED` receipt unless `--allow-disputed` (a
  pre-flip-only relaxation that touches ONLY the `DISPUTED` gate).
- refresh mode rewrites mechanical relocations / stale `spec_line`s (and
  regenerates the markdown view) after a human re-verifies real drift.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - lifecycle events
    L3 - semantic details
    L4 - deep tracing

Contracts
---------
- check mode is read-only and MUST NOT mutate the receipts file.
- Exit 0 clean (a reported pending relocation / stale spec_line is NOT a
  violation), 1 audit violations, 2 usage/config error.
- No `oc_chat` imports (never import the package under development from a
  tools/-launched script); stdlib + pydantic + oc_diagnostics only.

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- pydantic (strict receipt schema at the audit boundary)
- argparse (the --check, --refresh and --refresh-relocations modes and their options)
- hashlib (SHA-256 code and claim fingerprints)
- json (reads the receipts file and writes its canonical JSON and the --json report)
- re (the claim tag and waiver patterns and the lexicon trigger patterns)
- pathlib (Path - the audit root and the governed doc, receipt and code site paths)

Function Documentation