feat(sources): OpenCode adapter on RFC 002 contract

[jphein]

Summary

Adds OpenCodeSourceAdapter — an RFC 002 BaseSourceAdapter that ingests OpenCode AI-coding-CLI session transcripts from OpenCode's local SQLite store (~/.local/share/opencode/opencode.db) into the palace, formatted to match convo_miner's exchange-pair drawer shape.

What's included

• mempalace/sources/opencode.py — 482-line adapter:
  • Yields SourceItemMetadata then DrawerRecords per session
  • One source_file per session shaped as opencode://<absolute-db-path>#session=<sid>
  • Chunks via convo_miner.chunk_exchanges exchange-pair shape
  • Declares 8 transformations (6 opencode-namespaced + 2 reserved); every name resolves to a reference implementation on mempalace.sources.transforms per RFC 002 §7.3
  • Schema fields: session_id, session_title, project_dir, session_created_at, message_count, extract_mode, opencode_db_path
  • supports_incremental + adapter_owns_routing; default_privacy_class = "pii_potential"
  • Routes wing from session.directory basename (or explicit options["wing"]); room from detect_convo_room; hall from _detect_hall_cached
• mempalace/sources/transforms.py — +141 lines adding the 6 opencode-namespaced reference transformations
• pyproject.toml — entry-point registration under [project.entry-points."mempalace.sources"] as opencode = "mempalace.sources.opencode:OpenCodeSourceAdapter"
• tests/test_sources_opencode.py — 28 tests covering identity, capabilities, schema, ingest, route hints, transforms round-trip (RFC 002 §7.3 byte-equivalence), edge cases
• tests/fixtures/opencode/sample_session_2026_05_12/build_fixture.py — SQLite-schema-verbatim fixture builder (mirrors opencode-ai 1.14.39's schema captured live from ~/.local/share/opencode/opencode.db); no recorded .db ships because real-session content is unsanitizable

Coordination

This work originated from the OpenCode SQLite spadework in @JakobSachs's #23 (DB-schema reverse engineering, session/message/part traversal, tool-input/tool-output stripping primitives) — rebuilt on the RFC 002 contract so OpenCode support can ship as a registered adapter rather than a normalize.py branch. Coordination thread at #23, comment posted offering three paths forward; pushing this PR as the working code per @JakobSachs's choice of how to land (see #23#issuecomment-4436116396). Co-authored credit on the commit.

Complementary to #297 (Milofax) which adds the consumer-side JS plugin (examples/opencode_auto_plugin.js) that auto-initializes MemPalace in OpenCode sessions. Together: this adapter ingests OpenCode sessions into the palace; #297's plugin queries the palace from OpenCode at runtime. Different layers, no overlap.

Built on top of #1014 (RFC 002 scaffolding by @igorls).

Test plan

• 28/28 OpenCode adapter tests pass in 1.53s
• Full suite 1876 passed / 7 skipped / 106 deselected — zero regressions (+22 net vs pre-adapter baseline)
• Adapter conformance via RFC 002 §7.3 declared-transformation round-trip (drawer content reproducible from transformations)
• Real-OpenCode-session smoke (deferred — fixture is schema-verbatim from a real install but doesn't ship recorded content; configuring an OpenCode provider for a billable real-session capture is non-blocking)

Notes

• The 7 fork-only-on-jphein/main files (CLAUDE.md, README.md, FORK_CHANGELOG.md, docs/fork-changes.yaml, .claude-plugin/, docs/internal/, docs/research/*) are intentionally NOT in this diff — branch was rebuilt off upstream/develop carrying only commit 9030f06 so no fork-specific narrative leaks.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[gemini-code-assist]

Code Review

This pull request adds the OpenCodeSourceAdapter for ingesting SQLite-based CLI session transcripts, including custom text transformations and a synthetic fixture-based test suite. The review feedback recommends adding a missing version field to metadata for functional incremental ingests, respecting encapsulation of the PalaceContext, ensuring consistent timestamps across session chunks, and adhering to PEP 8 import standards.

[gemini-code-assist]

The metadata dictionary is missing the opencode_session_version field. This field is required by the is_current method (line 391) to perform stable version comparisons for incremental ingests. Without it, is_current will always fall back to returning True if any metadata exists, preventing the adapter from detecting and ingesting updates to existing sessions.

                    metadata = {
                        # Universal §5.1 fields
                        "source_file": src_file,
                        "chunk_index": chunk_index,
                        "filed_at": datetime.now(timezone.utc)
                        .replace(microsecond=0)
                        .isoformat()
                        .replace("+00:00", "Z"),
                        "added_by": "opencode-adapter",
                        "wing": wing,
                        "room": room,
                        "hall": _detect_hall(content),
                        "ingest_mode": "chunked_content",
                        "extract_mode": "exchange",
                        "privacy_class": self.default_privacy_class,
                        # Adapter-declared fields (§5.2)
                        "session_id": sid,
                        "session_title": title or "",
                        "project_dir": directory or "",
                        "session_created_at": created_iso,
                        "message_count": len(messages),
                        "opencode_db_path": db_path,
                        "opencode_session_version": str(time_updated or time_created or 0),
                    }

[gemini-code-assist]

Accessing and modifying a private attribute (_skip_requested) of the PalaceContext violates encapsulation. If the adapter needs to check if the current item should be skipped (e.g., after a call to palace.skip_current_item()), the context should expose a public property or method for this purpose.

[gemini-code-assist]

The filed_at timestamp is generated inside the chunk loop. For consistency across all chunks of the same session, it is better to generate this timestamp once per session (outside the for chunk in chunks: loop).

                created_iso = _utc_iso(time_created or 0)
                filed_at = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
                for chunk in chunks:
                    content = chunk["content"]
                    chunk_index = int(chunk["chunk_index"])
                    metadata = {
                        # Universal §5.1 fields
                        "source_file": src_file,
                        "chunk_index": chunk_index,
                        "filed_at": filed_at,

[gemini-code-assist]

According to PEP 8, imports should always be put at the top of the file, just after any module comments and docstrings, and before module globals and constants. Moving this import to the top of the module improves maintainability and follows standard Python conventions.

References

1. Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants. ^(link)

[jphein]

Addressed all 4 items from @gemini-code-assist's review in commit faee2b9:

1. ✅ Added opencode_session_version to the chunk metadata so is_current() can do real version comparisons (was always falling back to "exists → current")
2. ✅ Removed direct access to PalaceContext._skip_requested; added a small companion change — PalaceContext.is_skip_requested() public method — so adapters can short-circuit without touching the private flag. The spec's "core checks between yields" pattern doesn't hold for Python generators (the adapter's code runs between yields, not core's), so adapters need a way to query the flag. Read-only access only; core still owns the reset
3. ✅ Hoisted filed_at (and session_version) outside the chunk loop — every chunk of the same session now shares the same filed_at timestamp
4. ✅ Moved import json as _json to the top of transforms.py per PEP 8

Bonus: removed an unused import json from opencode.py that ruff caught.

Tests: 57 pass (28 opencode + 29 base sources); ruff clean.

[igorls]

Nice adapter — solid RFC 002 conformance, good test coverage, and the fixture-builder approach (no recorded .db) is the right privacy call.

Two things to address before merge:

1. CI lint is red — two ruff violations in tests/test_sources_opencode.py:

tests/test_sources_opencode.py:17:8: F401 `os` imported but unused
tests/test_sources_opencode.py:43:1: E402 Module level import not at top of file

The E402 comes from the sys.path.insert(0, ...) / import build_fixture pattern. Consider importlib.util.spec_from_file_location + module_from_spec to load the fixture builder without mutating sys.path at module scope (which also fixes the E402).

2. Route-hint wing mismatch — _route_hint_for() (called at the SourceItemMetadata stage) computes the wing purely from directory, but _wing_for() (called at the DrawerRecord stage) respects source.options["wing"] first (RFC 002 §2.5 precedence). When a user passes options={"wing": "Custom Wing"}, the metadata hint says "frontend" while the actual drawers say "custom_wing". This could cause core to make wrong skip/routing decisions.

Fix: have _route_hint_for accept the source parameter and delegate to _wing_for, or inline the same precedence logic.

Minor (non-blocking): the AuthRequiredError import on line 62 has a # noqa: F401 claiming re-export, but nothing in __all__ or the module surface actually re-exports it — the suppression is unjustified.

[jphein]

Thanks @igorls — addressed all four in commit 13353d9:

1. ✅ Dropped unused os import (F401)
2. ✅ Refactored the fixture builder loader to importlib.util.spec_from_file_location + module_from_spec per your suggestion. No more sys.path mutation at module scope; E402 gone. Also registers the loaded module in sys.modules so dataclasses/typing introspection inside build_fixture can resolve cls.__module__ (without that registration, dataclass collection fails at test-collection time — found out the hard way).
3. ✅ _route_hint_for(source, directory) now delegates to _wing_for so both stages apply identical RFC 002 §2.5 precedence. The metadata hint and drawer wing will agree when callers pass options={"wing": ...}.
4. ✅ Dropped the AuthRequiredError import + unjustified # noqa: F401 — __all__ was never going to re-export it.

Tests: 57 pass (28 opencode + 29 base sources); ruff clean on all touched files.

[jphein]

Hi @igorls — friendly nudge on this one when you have a moment. I addressed everything from your review in 13353d9:

• Dropped the unused os import (F401) and refactored the fixture-builder loader to importlib.util.spec_from_file_location + module_from_spec — no more sys.path mutation at module scope, E402 gone.
• _route_hint_for(source, directory) now delegates to _wing_for, so the metadata hint and the drawer wing apply identical RFC 002 §2.5 precedence when callers pass options={"wing": ...}.
• Removed the unjustified AuthRequiredError # noqa: F401.

57 tests pass, ruff clean, and it still merges cleanly on current develop. I've had a few PRs land since (e.g. #1769 into develop on the 22nd), so I'm around to iterate quickly if anything's drifted. Would love another look.