refactor: port interfaces + source_span for drift pipeline

[jinhongkuan]

Summary

• Port interfaces (ports.py): DriftAnalyzerPort and CodeIntelligencePort Protocol types decouple handlers from concrete backends. Enables independent development of Phase 1 (collaboration), drift intelligence (AST + LLM), and CodeGenome integration.
• source_span table: Separates raw source text (meeting excerpt, PRD paragraph) from extracted decisions (intent). The yields edge links source_span → intent for extraction provenance. This is the input for L3 semantic compliance checking.
• HashDriftAnalyzer: L1 hash-only implementation of DriftAnalyzerPort. Wraps existing status.py functions — zero behavior change.
• Factory wiring: get_drift_analyzer() and get_code_intelligence() in adapters/ — swap backend by changing one factory return.

Drift Layer Status

Layer	What	Status
L1: Hash	SHA-256(old) == SHA-256(new)?	✅ Implemented (HashDriftAnalyzer)
L2: AST	tree-sitter structural diff — cosmetic or real?	⬜ Pending (collaborator)
L3: Semantic	LLM reads source_span.text + code → compliant?	⬜ Pending (needs L2 + source_span traversal)

Files changed

• ports.py — Protocol types + DriftResult dataclass
• ledger/drift.py — HashDriftAnalyzer (L1)
• ledger/schema.py — source_span table + yields edge
• ledger/queries.py — upsert_source_span, relate_yields
• ledger/adapter.py — ingest_commit() delegates to DriftAnalyzerPort, ingest_payload() creates source_span records
• adapters/ledger.py — get_drift_analyzer() factory
• adapters/code_locator.py — get_code_intelligence alias
• handlers/link_commit.py — wires drift_analyzer through factory

Test plan

• Phase 1 tests: 6/6 passed
• Phase 2 ledger tests: 13/13 passed
• Zero behavior change — same hash-only drift runs, just through protocol interface
• Pre-existing test_phase2_vc.py fixture errors confirmed on main (not a regression)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added drift analysis to detect and record content changes and update region status.
  • Linked source excerpts to intents to preserve provenance for analysis results.

• Infrastructure

  • Introduced formal interfaces for drift and code-intelligence integrations.
  • Database schema versioning and migration support to safely apply schema updates.

• Chore

  • Package version bumped to 0.3.0.

[coderabbitai]

Warning

Rate limit exceeded

@jinhongkuan has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 4 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 12 minutes and 4 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1d56fd26-6914-4b14-96cf-0dcdc64ce8e5

📥 Commits

Reviewing files that changed from the base of the PR and between 6a55c04 and 127be32.

📒 Files selected for processing (3)

• ledger/adapter.py
• ledger/queries.py
• ledger/schema.py

📝 Walkthrough

Walkthrough

Adds drift-analysis support: new ports and DriftResult, a HashDriftAnalyzer implementation, ledger schema/queries for source spans, ledger adapter integration to accept a drift analyzer, and factory exports; handlers now pass a drift analyzer into ledger ingestion. (48 words)

Changes

Cohort / File(s)	Summary
Public Ports & Models ports.py	Added DriftResult dataclass and runtime-checkable DriftAnalyzerPort and CodeIntelligencePort protocols.
Drift Analyzer Implementation ledger/drift.py	Added HashDriftAnalyzer with async analyze_region(...) that resolves symbol lines, computes content hash, and derives drift status.
Ledger Adapter & Persistence ledger/adapter.py, ledger/queries.py, ledger/schema.py	Extended SurrealDBLedgerAdapter.ingest_commit(..., drift_analyzer=None) to delegate drift checks, added upsert_source_span and relate_yields queries, introduced source_span table, yields edge, schema versioning, and migration entrypoint.
Factory Functions / Adapters adapters/code_locator.py, adapters/ledger.py	Added get_code_intelligence alias to get_code_locator; added get_drift_analyzer() factory returning HashDriftAnalyzer().
Handler Integration handlers/link_commit.py	handle_link_commit() now creates/uses drift_analyzer and passes it into ledger.ingest_commit(...).
Version Bump pyproject.toml, RECOMMENDED_VERSION	Package/project version updated from 0.2.16 → 0.3.0.

Sequence Diagram

sequenceDiagram
    participant Handler as Handler (link_commit)
    participant Adapter as SurrealDBLedgerAdapter
    participant Analyzer as HashDriftAnalyzer
    participant DB as SurrealDB

    Handler->>Adapter: ingest_commit(commit_hash, repo_path, drift_analyzer)
    Adapter->>Analyzer: analyze_region(file_path, symbol_name, start_line, end_line, stored_hash, repo_path, ref)
    Analyzer->>Analyzer: resolve_symbol_lines()/compute_content_hash()/derive_status()
    Analyzer-->>Adapter: DriftResult(status, content_hash, confidence)
    Adapter->>DB: upsert_source_span(text, source_type, source_ref)
    DB-->>Adapter: span_id
    Adapter->>DB: relate_yields(span_id, intent_id)
    Adapter->>DB: update region (content_hash, start_line, end_line)
    Adapter-->>Handler: ingest result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I dug a tunnel through the code tonight,
Sniffed hashes, found where functions shifted slight,
I stitched source spans where meanings play,
Ledger kept trace of every hop and stray,
Hooray — the drift is caught, the map feels right!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'refactor: port interfaces + source_span for drift pipeline' accurately and specifically summarizes the two main changes: introducing port interfaces and adding source_span support for the drift pipeline.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch port-interfaces-source-span

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ledger/adapter.py`:
- Around line 178-187: ingest_commit is calling drift_analyzer.analyze_region
without passing source_context/source_span, so any SemanticDriftAnalyzer will
receive empty text; update the call site in ingest_commit to extract the
region's source_span.text (or the region.intent/description if text missing)
from the output of get_regions_for_files (the same structure that stores
source_span) and pass it as the new source_context/source_span (use the
parameter name expected by analyze_region) when invoking
drift_analyzer.analyze_region; ensure you reference the region object returned
by get_regions_for_files, read region.source_span.text (falling back to
intent/description), and include that value in the analyze_region call so
semantic comparison can run.

In `@ledger/queries.py`:
- Around line 470-473: The fallback CREATE for source_span in the code path
after the UPSERT (where rows is empty) omits provenance fields and loses
metadata; update the fallback query in ledger/queries.py (the CREATE source_span
statement executed when rows == []) to include the speakers and meeting_date
fields and pass their values in the params dict (same keys used in the UPSERT
branch, e.g., "speakers" and "meeting_date" or whatever variable names are
declared in the surrounding function) so both branches preserve the same
metadata.

In `@ledger/schema.py`:
- Around line 64-71: The schema lacks a unique index for the deduplication key
used by upsert_source_span(), causing possible duplicates; add a UNIQUE index on
source_span that covers source_type, source_ref and text (in addition to or
replacing idx_span_ref) so the DB enforces uniqueness across those three fields
and aligns with the UPSERT WHERE clause in upsert_source_span().

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 56757df4-7f65-496d-936e-8d931ddc6c8f

📥 Commits

Reviewing files that changed from the base of the PR and between 904f3f0 and f8a6251.

📒 Files selected for processing (8)

• adapters/code_locator.py
• adapters/ledger.py
• handlers/link_commit.py
• ledger/adapter.py
• ledger/drift.py
• ledger/queries.py
• ledger/schema.py
• ports.py

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (2)

ledger/adapter.py (1)

179-188: ⚠️ Potential issue | 🟠 Major

Plumb source_context into the analyzer call.

The new port was expanded specifically for L3 semantic checks, but this call still relies on the default "". A future semantic analyzer swapped in via get_drift_analyzer() will never see the source_span.text this PR stores. Please extend get_regions_for_files() to return the related source text (or at least the intent description as fallback) and pass it through here.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@ledger/adapter.py` around lines 179 - 188, The call to
drift_analyzer.analyze_region currently omits the source context so L3 semantic
analyzers won't receive source_span.text; update get_regions_for_files() (the
producer) to include the source text (or fall back to the intent description) in
each region tuple/object and then pass that value as the source_context (or
similar named param) into drift_analyzer.analyze_region in ledger.adapter (where
drift_result is created), ensuring analyze_region/source_context and any calls
via get_drift_analyzer() consistently accept and forward the source text to
downstream analyzers.

ledger/schema.py (1)

79-86: ⚠️ Potential issue | 🟠 Major

Add a DB-enforced unique key for source_span dedupe.

upsert_source_span() deduplicates on (source_type, source_ref, text), but the schema only indexes (source_type, source_ref). If two ingests race past the lookup path, identical excerpts can still be persisted twice. Please add a unique index that matches the full dedupe key.

Suggested schema change

     "DEFINE FIELD meeting_date   ON source_span TYPE string DEFAULT ''",
     "DEFINE FIELD created_at     ON source_span TYPE datetime DEFAULT time::now()",
     "DEFINE INDEX idx_span_ref   ON source_span FIELDS source_type, source_ref",
+    "DEFINE INDEX idx_span_dedupe ON source_span FIELDS source_type, source_ref, text UNIQUE",

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@ledger/schema.py` around lines 79 - 86, The schema currently only indexes
(source_type, source_ref) so concurrent upserts can insert duplicate excerpts;
add a DB-enforced unique index on the full dedupe key to match
upsert_source_span()’s logic by defining a unique index such as "DEFINE INDEX
idx_span_unique ON source_span FIELDS source_type, source_ref, text UNIQUE"
(leave existing idx_span_ref if desired) so identical (source_type, source_ref,
text) rows cannot be persisted concurrently.

🧹 Nitpick comments (1)

ledger/adapter.py (1)

195-203: Avoid resolving symbol lines twice per region.

HashDriftAnalyzer.analyze_region() already does resolve_symbol_lines(), then this block does the same work again just to persist the updated bounds. On larger commits this doubles the tree-sitter/git lookup cost on the hot path. Consider returning the resolved span in DriftResult, or moving all line-resolution responsibility into the adapter.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@ledger/adapter.py` around lines 195 - 203, The adapter is re-calling
resolve_symbol_lines() for each region even though
HashDriftAnalyzer.analyze_region() already resolves spans; change the data flow
so the analyzer returns the resolved span (e.g., add resolved_span or
resolved_start/resolved_end fields to DriftResult from
HashDriftAnalyzer.analyze_region()) and then in the adapter (where you currently
call resolve_symbol_lines() and run the UPDATE via self._client.query) use the
resolved values from the returned DriftResult instead of re-invoking
resolve_symbol_lines(); alternatively, centralize line-resolution in the adapter
by removing resolve_symbol_lines() from analyze_region and having analyze_region
return only raw drift info—update the code paths that consume DriftResult and
the DB UPDATE logic in the adapter (the region_id/start_line/end_line update
block) accordingly so no duplicate tree-sitter/git lookups occur.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ledger/schema.py`:
- Around line 120-122: Make the yields relation idempotent so replayed ingest
doesn't create duplicate source_span→intent edges: either add a uniqueness
constraint to the yields relation (unique on its endpoints) in the schema for
the yields table, or change the write path to dedupe before creating edges —
update ledger/schema.py to enforce uniqueness on yields endpoints (the yields
relation) OR modify ledger/queries.py where RELATE is used (and the
relate_yields() call in ledger/adapter.py) to perform a conditional/merge-style
create (check existence first or use a RELATE/MERGE-unique variant) so duplicate
edges are not inserted.

---

Duplicate comments:
In `@ledger/adapter.py`:
- Around line 179-188: The call to drift_analyzer.analyze_region currently omits
the source context so L3 semantic analyzers won't receive source_span.text;
update get_regions_for_files() (the producer) to include the source text (or
fall back to the intent description) in each region tuple/object and then pass
that value as the source_context (or similar named param) into
drift_analyzer.analyze_region in ledger.adapter (where drift_result is created),
ensuring analyze_region/source_context and any calls via get_drift_analyzer()
consistently accept and forward the source text to downstream analyzers.

In `@ledger/schema.py`:
- Around line 79-86: The schema currently only indexes (source_type, source_ref)
so concurrent upserts can insert duplicate excerpts; add a DB-enforced unique
index on the full dedupe key to match upsert_source_span()’s logic by defining a
unique index such as "DEFINE INDEX idx_span_unique ON source_span FIELDS
source_type, source_ref, text UNIQUE" (leave existing idx_span_ref if desired)
so identical (source_type, source_ref, text) rows cannot be persisted
concurrently.

---

Nitpick comments:
In `@ledger/adapter.py`:
- Around line 195-203: The adapter is re-calling resolve_symbol_lines() for each
region even though HashDriftAnalyzer.analyze_region() already resolves spans;
change the data flow so the analyzer returns the resolved span (e.g., add
resolved_span or resolved_start/resolved_end fields to DriftResult from
HashDriftAnalyzer.analyze_region()) and then in the adapter (where you currently
call resolve_symbol_lines() and run the UPDATE via self._client.query) use the
resolved values from the returned DriftResult instead of re-invoking
resolve_symbol_lines(); alternatively, centralize line-resolution in the adapter
by removing resolve_symbol_lines() from analyze_region and having analyze_region
return only raw drift info—update the code paths that consume DriftResult and
the DB UPDATE logic in the adapter (the region_id/start_line/end_line update
block) accordingly so no duplicate tree-sitter/git lookups occur.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 12affbaa-f92c-4307-8724-4f7da291b13c

📥 Commits

Reviewing files that changed from the base of the PR and between f8a6251 and 6a55c04.

📒 Files selected for processing (10)

• RECOMMENDED_VERSION
• adapters/code_locator.py
• adapters/ledger.py
• handlers/link_commit.py
• ledger/adapter.py
• ledger/drift.py
• ledger/queries.py
• ledger/schema.py
• ports.py
• pyproject.toml

✅ Files skipped from review due to trivial changes (5)

• RECOMMENDED_VERSION
• pyproject.toml
• adapters/ledger.py
• ledger/queries.py
• ports.py

🚧 Files skipped from review as they are similar to previous changes (2)

• adapters/code_locator.py
• handlers/link_commit.py