Tracking: session-lattice implementation roadmap, work this top to bottom #2

New issue

Closed

opened 2026-05-23 20:55:33 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-05-23 20:55:33 +00:00

Owner

Originally filed by @coilysiren on 2026-05-20T08:00:04Z - https://github.com/coilysiren/session-lattice/issues/34

What this is

Tracking issue / reading guide for a fresh session about to do a batch of session-lattice implementation work. Read this top to bottom, then start at the first open issue in the order below.

Where we are right now (2026-05-20)

Three-service mental model (mcporter slots, ref docs/architecture.md):

dev = coily exec watch from checkout, port 7781, points at repo-recall-dev 7780.
staging = brew services, port 7778, points at repo-recall 7777 (loopback).
prod = kai-server tailnet (k3s deploy lives in coilysiren/infrastructure, not configured for session-lattice yet).

Live state in staging right now: puller pulled 1391 sessions, materialized 138-row tool_sessions view. GET /healthz returns {"status":"ok","version":"0.0.0"} (0.0.0 is the #26 bug, not a real version).

Inside the service today: one process, one serve subcommand, reads + puller share a uvicorn worker. serve-reads and serve-puller subcommands also exist as no-op refactor (#28). The brew formula still calls serve. Splitting the formula into two service blocks is #33.

Work order

Do these in this order. Dependencies are noted; the order respects them.

coilysiren/session-lattice#23 - tighten AGENTS.md no-uv-run wording so it exempts the dev path. Smallest possible commit. Sets the mental model straight for everything below.
coilysiren/session-lattice#24 - one-line comment above each service do block naming the mcporter staging slot it binds. Same shape lands in coilysiren/repo-recall#218.
coilysiren/session-lattice#26 - switch to hatch-vcs so __version__ derives from the git tag. Every release-verify step after this becomes meaningful instead of decorative.
coilysiren/session-lattice#31 - drive GET /views off the session_lattice.views.ALL registry instead of every non-meta_ table in the main schema. Prereq for surfacing per-view metadata cleanly.
coilysiren/session-lattice#33 - split the formula into two service do blocks (session-lattice-reads, session-lattice-puller), retire serve from the CLI. This is the structural goal of #27.
coilysiren/session-lattice#32 - per-view refresh cadence. Each view module declares REFRESH_INTERVAL_SECONDS; tick becomes a fan-out keyed on per-view watermarks. Parallel to coilysiren/repo-recall#146 on the upstream side.

After this batch lands, the next batch is the second materialized view (architecture targets 18-25 views) and the cross-repo end-to-end test where session-lattice queries an upgraded repo-recall and luca queries session-lattice. Out of scope here.

Per-commit contract

Every commit closes a same-repo GitHub issue. File first, commit with closes #N, push.
Conventional Commits 1.0.0 subject required (feat:, fix:, refactor:, style:, docs:).
coily exec lint and coily exec test must pass before push. coily exec fmt first to dodge formatter-only follow-up commits (the #29 pattern).
Push triggers release: mathieudutour/github-tag-action tags, bump-formula rewrites url+tag+revision via the Contents API with [skip ci]. Verify CI at +300s. For staging-affecting changes, coily pkg brew upgrade coilysiren/session-lattice/session-lattice --allow-untapped then restart.
Don't write the literal [skip ci] token in commit bodies.

Gotchas the next session should know

coily pkg brew install/services needs --allow-untapped for coilysiren/session-lattice/ (tap allow-list is pinned to coilysiren/tap/*, ref coilysiren/coily#268).
Issue titles with ( or ) fail coily's metacharacter gate. Use - instead.
GitHub's Actions API (gh run list) has a secondary rate limit not reflected in gh api rate_limit. Polling more than ~3 times per minute on the same repo trips a 403 with "rate limit exceeded" wording. Don't poll tight loops.
The formula has depends_on "rust" => :build (since coilysiren/session-lattice#22). Don't drop it - pydantic_core needs maturin from sdist.
--version lies about the version (#26 above). Use git describe against the checkout for the real number.
pyright in this checkout flags Import "httpx" could not be resolved etc. - those are venv-state false positives. The actual lint via coily exec lint (ruff + mypy) is authoritative.

Open issues, full inventory

Implementation (above order): #23, #24, #26, #31, #33, #32.
Closed-and-shipped this session: #21 (make watch), #22 (rust build dep), #25 (working_dir), #28 (step 1 split), #29 (config fmt), #30 (step 2 puller), #20 (release infra prior session).
Adjacent and not in this batch: #27 (the parent design issue; closes when #33 + #32 land), upstream coilysiren/repo-recall#220 (the GET /api/sessions endpoint, shipped, what the puller consumes).

_Originally filed by @coilysiren on 2026-05-20T08:00:04Z - [https://github.com/coilysiren/session-lattice/issues/34](https://github.com/coilysiren/session-lattice/issues/34)_ **What this is** Tracking issue / reading guide for a fresh session about to do a batch of session-lattice implementation work. Read this top to bottom, then start at the first open issue in the order below. **Where we are right now (2026-05-20)** Three-service mental model (mcporter slots, ref docs/architecture.md): - dev = `coily exec watch` from checkout, port 7781, points at repo-recall-dev 7780. - staging = brew services, port 7778, points at repo-recall 7777 (loopback). - prod = kai-server tailnet (k3s deploy lives in coilysiren/infrastructure, not configured for session-lattice yet). Live state in staging right now: puller pulled 1391 sessions, materialized 138-row `tool_sessions` view. `GET /healthz` returns `{"status":"ok","version":"0.0.0"}` (0.0.0 is the #26 bug, not a real version). Inside the service today: one process, one `serve` subcommand, reads + puller share a uvicorn worker. `serve-reads` and `serve-puller` subcommands also exist as no-op refactor (#28). The brew formula still calls `serve`. Splitting the formula into two service blocks is #33. **Work order** Do these in this order. Dependencies are noted; the order respects them. 1. coilysiren/session-lattice#23 - tighten AGENTS.md no-uv-run wording so it exempts the dev path. Smallest possible commit. Sets the mental model straight for everything below. 2. coilysiren/session-lattice#24 - one-line comment above each `service do` block naming the mcporter staging slot it binds. Same shape lands in coilysiren/repo-recall#218. 3. coilysiren/session-lattice#26 - switch to hatch-vcs so `__version__` derives from the git tag. Every release-verify step after this becomes meaningful instead of decorative. 4. coilysiren/session-lattice#31 - drive `GET /views` off the `session_lattice.views.ALL` registry instead of every non-`meta_` table in the main schema. Prereq for surfacing per-view metadata cleanly. 5. coilysiren/session-lattice#33 - split the formula into two `service do` blocks (`session-lattice-reads`, `session-lattice-puller`), retire `serve` from the CLI. This is the structural goal of #27. 6. coilysiren/session-lattice#32 - per-view refresh cadence. Each view module declares `REFRESH_INTERVAL_SECONDS`; tick becomes a fan-out keyed on per-view watermarks. Parallel to coilysiren/repo-recall#146 on the upstream side. After this batch lands, the next batch is the second materialized view (architecture targets 18-25 views) and the cross-repo end-to-end test where session-lattice queries an upgraded repo-recall and luca queries session-lattice. Out of scope here. **Per-commit contract** - Every commit closes a same-repo GitHub issue. File first, commit with `closes #N`, push. - Conventional Commits 1.0.0 subject required (`feat:`, `fix:`, `refactor:`, `style:`, `docs:`). - `coily exec lint` and `coily exec test` must pass before push. `coily exec fmt` first to dodge formatter-only follow-up commits (the #29 pattern). - Push triggers release: `mathieudutour/github-tag-action` tags, `bump-formula` rewrites url+tag+revision via the Contents API with `[skip ci]`. Verify CI at +300s. For staging-affecting changes, `coily pkg brew upgrade coilysiren/session-lattice/session-lattice --allow-untapped` then restart. - Don't write the literal `[skip ci]` token in commit bodies. **Gotchas the next session should know** - `coily pkg brew install/services` needs `--allow-untapped` for `coilysiren/session-lattice/` (tap allow-list is pinned to `coilysiren/tap/*`, ref coilysiren/coily#268). - Issue titles with `(` or `)` fail coily's metacharacter gate. Use ` - ` instead. - GitHub's Actions API (`gh run list`) has a secondary rate limit not reflected in `gh api rate_limit`. Polling more than ~3 times per minute on the same repo trips a 403 with "rate limit exceeded" wording. Don't poll tight loops. - The formula has `depends_on "rust" => :build` (since coilysiren/session-lattice#22). Don't drop it - pydantic_core needs maturin from sdist. - `--version` lies about the version (#26 above). Use `git describe` against the checkout for the real number. - pyright in this checkout flags `Import "httpx" could not be resolved` etc. - those are venv-state false positives. The actual lint via `coily exec lint` (ruff + mypy) is authoritative. **Open issues, full inventory** - Implementation (above order): #23, #24, #26, #31, #33, #32. - Closed-and-shipped this session: #21 (make watch), #22 (rust build dep), #25 (working_dir), #28 (step 1 split), #29 (config fmt), #30 (step 2 puller), #20 (release infra prior session). - Adjacent and not in this batch: #27 (the parent design issue; closes when #33 + #32 land), upstream coilysiren/repo-recall#220 (the GET /api/sessions endpoint, shipped, what the puller consumes).

coilysiren commented

2026-05-30 05:43:49 +00:00

Author

Owner

Iceboxed in the 2026-05-29 backlog burn-down: Tracking/reading-guide meta-issue, not actionable work itself. Reopen anytime if it becomes real.

coilysiren

2026-05-30 05:43:49 +00:00