# Legal Source Provenance & Trust Registry

## PURPOSE
If an AI-drafted clause says "the limitation of liability follows our standard position", a lawyer must be able to prove where that position came from before signing. This project is the service layer that makes that possible: a registry of trusted sources (matter files, clause libraries, internal and external advisors, the systems behind Counsel Legal and HiQu) plus an append-only provenance ledger linking every generated claim to the source that justified it.

## WHY THIS MATTERS
The clip frames it as an obligation, not a feature: "We have a fiduciary obligation to legal professionals to deliver a message that they can trust and put their name on." Trust here is architectural — a citation that cannot be resolved to a registered, current source must be rejected, and every verification must be recorded so the audit trail exists months later.

## HOW TO BUILD
1. `pip install -r requirements.txt` (SQLAlchemy for persistence, httpx for calling the external advisory/connector APIs).
2. Declare four tables: `sources` (kind, office, uri, version, retrieved_at, checksum), `citations` (claim_id, source_id, quote, verified), `advisors`, and `audit_events` (who/what/when, immutable).
3. Build a `SourceRegistry` with `register_source()` and `resolve(source_id, quote)` — resolution re-fetches the source over httpx, hashes it, and compares the checksum to detect drift.
4. Expose `POST /citations/verify` that returns `verified` only when the quote is present in the live source text and its checksum still matches.
5. Record an `audit_events` row for every verification attempt, successful or not.
6. Never delete: corrections add a new source version and supersede the old row.

```python
class Source(Base):
    __tablename__ = "sources"
    id = Column(String, primary_key=True)
    kind = Column(String, nullable=False)      # matter_file | clause_library | advisor
    office = Column(String, nullable=False)
    uri = Column(String, nullable=False)
    version = Column(Integer, default=1)
    checksum = Column(String, nullable=False)
    retrieved_at = Column(DateTime, default=datetime.utcnow)

def resolve(session, source_id, quote) -> bool:
    src = session.get(Source, source_id)
    if src is None:
        return False
    body = fetch_source(src.uri)               # httpx; TODO: plug in TR connectors
    if sha256(body.encode()).hexdigest() != src.checksum:
        log_event(session, "source_drift", source_id=source_id)  # stale -> reject
        return False
    return quote.strip()[:80] in body
```

## WHEN TO USE IN PRODUCTION
Use it whenever AI output must survive review: contract generation, diligence summaries, regulatory Q&A, and any workflow where a professional "puts their name on" the result. It is also the right substrate for monitoring source drift after a clause library is updated. Do NOT route free-form chat through it, do not store privileged text without your security review, and avoid it as a document store — it holds provenance metadata, not the corpus itself.

## HOW IT HELPS STUDENTS
Students implement real SQLAlchemy modelling, checksum-based drift detection, an append-only audit trail and an httpx integration boundary — the unglamorous plumbing that turns "trustworthy AI" from a slogan into an enforceable contract.

## STARTER CODE
`starter/main.py` defines the schema, the checksum resolver, the audit-event writer and a deterministic `fetch_source` stub, with `# TODO` markers for live Counsel Legal / HiQu / external-advisor connectors.
