docs: record LARQL phase 1 decisions - #174
Conversation
There was a problem hiding this comment.
Pull request overview
This PR records Phase 1 architectural decisions for the planned LARQL slice-placement roadmap by adding new ADRs and updating existing architecture/developer docs to describe the intended “MLX head + LARQL cold tier + external vindex provenance” model without implying runtime support exists yet.
Changes:
- Added three Phase 1 ADRs covering
LarqlRunner, MLX-head/LARQL-cold-tier execution, and vindex provenance/ownership. - Updated architecture docs (both repo docs and Docusaurus site docs) to describe the planned slice-mode constraints and gating.
- Updated contributor/assistant guidance docs to point to the new ADR location and summarize the roadmap status.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
website/docs/architecture.md |
Adds “planned, not active” LARQL slice-mode notes and constraints to the public architecture narrative. |
website/docs/architecture-reference.md |
Adds a dense reference entry for the planned LarqlRunner and vindex sourcing invariant. |
docs/architecture.md |
Mirrors planned slice-mode + vindex provenance guidance in the repo’s architecture overview. |
docs/adr/README.md |
Introduces ADR format + numbering conventions for future decisions. |
docs/adr/0001-larql-runner-type.md |
ADR for modeling LARQL as a worker-managed runner supervising larql-server. |
docs/adr/0002-head-mlx-cold-larql.md |
ADR for keeping MLX as head runtime and using LARQL peers for cold FFN/expert slices (gated). |
docs/adr/0003-vindex-provenance.md |
ADR defining Skulk as vindex consumer-only, with publishing owned by an external repo. |
CONTRIBUTING.md |
Documents docs/adr/ as the location for architecture decision records. |
CLAUDE.md |
Adds a concise summary of the planned slice-mode ADR decisions for assistant guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9d6f8ac539
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4c0b95deec
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 33ff860eb6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e924ce94b6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0abdd07cd4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6733402fde
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Summary
LarqlRunner, MLX head plus cold LARQL tier, and external vindex provenance.LarqlRunnerSupervisor, vindex directory staging support, readiness event application, and focused tests.Issue Tracking
Validation
uv run basedpyrightuv run ruff checknix --extra-experimental-features "nix-command flakes" fmtuv run pytest— 712 passed, 1 skipped, 167 deselecteduv run python scripts/build_docs.pyscripts/publish-vindex.sh --dry-runfor all smoke and MoE catalogue keysDocs build succeeded with existing TypeDoc/Docusaurus warnings only. Full pytest includes the existing noisy restart-test execv traceback, but the suite exits 0.