diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index acbbfb8..a94a9b4 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,18 +1,18 @@ -{"id":"bf-1e7t","title":"P11.9 v1.0 versioning-commitments policy doc (§12)","description":"## What\n\nAuthor `docs/versioning-policy.md` from plan §12 \"Versioning commitments (from v1.0)\" (lines 2208-2213). The plan promises four backward-compatibility commitments starting at v1.0:\n\n1. Meilisearch API compatibility layer: no breaking changes in minor versions\n2. `miroir-ctl` CLI flags: no incompatible changes in minor versions\n3. Config file schema: backward-compatible in minor versions (new fields always optional with defaults)\n4. Helm chart values schema: backward-compatible in minor versions\n\nDoc must:\n- Reproduce all four commitments verbatim.\n- Define what counts as a \"breaking change\" for each (e.g., a field rename is breaking; adding an optional field is not).\n- Document the deprecation policy (one minor cycle warning before removal).\n- Document the v0.x policy (MINOR bumps may include breaking changes — explicit, per §7).\n- Provide a CHANGELOG-tagging convention (e.g. `[breaking]` prefix for v1.x major-bump-required items).\n\n## Why\n\nThis is a written contract with users that today exists only as five lines in `plan.md`. Once we approach v1.0 we will need a reviewable, citable doc; releasing v1.0 without one is a liability for downstream integrators.\n\n## Acceptance\n\n- [ ] `docs/versioning-policy.md` exists with all four commitments\n- [ ] Defines \"breaking change\" per surface (API, CLI, config, Helm values)\n- [ ] Documents pre-1.0 vs post-1.0 policy difference\n- [ ] CHANGELOG.md preamble references the policy\n- [ ] README.md \"Stability\" section links to the policy\n\nParent epic: `miroir-uyx` (Phase 11 — Onboarding + Delivered Artifacts).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":2,"issue_type":"task","assignee":"claude-code-glm-4.7-oscar","created_at":"2026-05-10T02:35:00.288551019Z","updated_at":"2026-05-20T02:52:05.219305198Z","source_repo":".","compaction_level":0,"labels":["phase-11"]} -{"id":"bf-1iw2","title":"P6.11 Vertical scaling escape valve (§14.10)","description":"## What\n\nSupport the §14.10 single-pod oversized mode for dev clusters / very small deployments / constrained environments. Operators may provision a single pod at higher limits (e.g. 4 vCPU / 8 GB); memory budgets scale linearly by multiplier; HPA may remain disabled.\n\nSpecifically:\n1. `values.schema.json` MUST allow `replicas: 1` with `taskStore.backend: sqlite` and `hpa.enabled: false` AND with `resources.limits.{cpu,memory}` larger than the §14.8 baseline.\n2. Document the multiplier behavior: when `resources.limits.memory` is N× the baseline, the in-Rust budgets (idempotency.max_cached_keys, session_pinning.max_sessions, etc.) should scale linearly OR the operator overrides each.\n3. `docs/horizontal-scaling/single-pod.md` documents this is supported, NOT recommended for production, and explains the fault-tolerance trade-offs (zero-downtime rollouts, pod-loss survival lost).\n\n## Why\n\n§14.10 promises this works. Currently nothing in `values.schema.json` rejects oversized single-pod, but nothing exercises it either; without explicit support, operators may have surprising memory-cap interactions when the runtime budgets don’t auto-scale.\n\n## Acceptance\n\n- [ ] Fixture in `tests/integration/` boots a single 4-vCPU / 8-GB pod successfully\n- [ ] `values.schema.json` accepts the oversized-single-pod combination\n- [ ] Memory-multiplier behavior documented (auto-scale or operator override) and one of the two implemented\n- [ ] `docs/horizontal-scaling/single-pod.md` includes the trade-off explanation from §14.10\n- [ ] README.md \"When to use\" section calls out single-pod as supported but not recommended\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":2,"issue_type":"task","assignee":"claude-code-glm-4.7-echo","created_at":"2026-05-10T02:34:26.505495761Z","updated_at":"2026-05-20T02:52:13.379810088Z","source_repo":".","compaction_level":0,"labels":["phase-6"]} +{"id":"bf-1e7t","title":"P11.9 v1.0 versioning-commitments policy doc (§12)","description":"## What\n\nAuthor `docs/versioning-policy.md` from plan §12 \"Versioning commitments (from v1.0)\" (lines 2208-2213). The plan promises four backward-compatibility commitments starting at v1.0:\n\n1. Meilisearch API compatibility layer: no breaking changes in minor versions\n2. `miroir-ctl` CLI flags: no incompatible changes in minor versions\n3. Config file schema: backward-compatible in minor versions (new fields always optional with defaults)\n4. Helm chart values schema: backward-compatible in minor versions\n\nDoc must:\n- Reproduce all four commitments verbatim.\n- Define what counts as a \"breaking change\" for each (e.g., a field rename is breaking; adding an optional field is not).\n- Document the deprecation policy (one minor cycle warning before removal).\n- Document the v0.x policy (MINOR bumps may include breaking changes — explicit, per §7).\n- Provide a CHANGELOG-tagging convention (e.g. `[breaking]` prefix for v1.x major-bump-required items).\n\n## Why\n\nThis is a written contract with users that today exists only as five lines in `plan.md`. Once we approach v1.0 we will need a reviewable, citable doc; releasing v1.0 without one is a liability for downstream integrators.\n\n## Acceptance\n\n- [ ] `docs/versioning-policy.md` exists with all four commitments\n- [ ] Defines \"breaking change\" per surface (API, CLI, config, Helm values)\n- [ ] Documents pre-1.0 vs post-1.0 policy difference\n- [ ] CHANGELOG.md preamble references the policy\n- [ ] README.md \"Stability\" section links to the policy\n\nParent epic: `miroir-uyx` (Phase 11 — Onboarding + Delivered Artifacts).","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":2,"issue_type":"task","assignee":"claude-code-glm-4.7-bravo","created_at":"2026-05-10T02:35:00.288551019Z","updated_at":"2026-05-20T10:41:50.183432019Z","closed_at":"2026-05-20T10:41:50.183432019Z","close_reason":"Completed","source_repo":".","compaction_level":0,"labels":["phase-11"]} +{"id":"bf-1iw2","title":"P6.11 Vertical scaling escape valve (§14.10)","description":"## What\n\nSupport the §14.10 single-pod oversized mode for dev clusters / very small deployments / constrained environments. Operators may provision a single pod at higher limits (e.g. 4 vCPU / 8 GB); memory budgets scale linearly by multiplier; HPA may remain disabled.\n\nSpecifically:\n1. `values.schema.json` MUST allow `replicas: 1` with `taskStore.backend: sqlite` and `hpa.enabled: false` AND with `resources.limits.{cpu,memory}` larger than the §14.8 baseline.\n2. Document the multiplier behavior: when `resources.limits.memory` is N× the baseline, the in-Rust budgets (idempotency.max_cached_keys, session_pinning.max_sessions, etc.) should scale linearly OR the operator overrides each.\n3. `docs/horizontal-scaling/single-pod.md` documents this is supported, NOT recommended for production, and explains the fault-tolerance trade-offs (zero-downtime rollouts, pod-loss survival lost).\n\n## Why\n\n§14.10 promises this works. Currently nothing in `values.schema.json` rejects oversized single-pod, but nothing exercises it either; without explicit support, operators may have surprising memory-cap interactions when the runtime budgets don’t auto-scale.\n\n## Acceptance\n\n- [ ] Fixture in `tests/integration/` boots a single 4-vCPU / 8-GB pod successfully\n- [ ] `values.schema.json` accepts the oversized-single-pod combination\n- [ ] Memory-multiplier behavior documented (auto-scale or operator override) and one of the two implemented\n- [ ] `docs/horizontal-scaling/single-pod.md` includes the trade-off explanation from §14.10\n- [ ] README.md \"When to use\" section calls out single-pod as supported but not recommended\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":2,"issue_type":"task","assignee":"claude-code-glm-4.7-bravo","created_at":"2026-05-10T02:34:26.505495761Z","updated_at":"2026-05-20T11:12:25.626511534Z","source_repo":".","compaction_level":0,"labels":["phase-6"]} {"id":"bf-1m37","title":"Merge master into main: Epic","description":"## Goal\nMerge the `origin/master` branch (Phase 0/1/2 work from lab workers) into `origin/main` (Phase 3/4/5 work), producing a unified branch with all work combined. `main` is the default branch.\n\n## Background\nBoth branches diverged at `2b1ea87 P0.7: Fix cargo fmt and clippy warnings for CI smoke`.\n- `origin/master` (148 commits) — Phase 0, 1, 2: Foundation, Core Routing, Proxy + API Surface\n- `origin/main` (148 commits) — Phase 3, 4, 5: Task Registry, Topology Operations, Advanced Capabilities\n\n## Phase plan\n- [ ] Task 1: Merge setup + non-Rust file conflicts\n- [ ] Task 2: miroir-core source conflict resolution\n- [ ] Task 3: miroir-proxy source conflict resolution\n- [ ] Task 4: Build verification and push\n\nAll four tasks must complete in order. Close this epic when Task 4 is done and `origin/main` contains both branches\\x27 work and passes `cargo build --workspace`.","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"epic","created_at":"2026-05-12T01:50:34.974496746Z","updated_at":"2026-05-12T01:50:34.974496746Z","source_repo":".","compaction_level":0,"dependencies":[{"issue_id":"bf-1m37","depends_on_id":"bf-4fo8","type":"blocks","created_at":"2026-05-12T01:51:43.510504445Z","created_by":"cli","thread_id":""}]} -{"id":"bf-1p4v","title":"Fix compile error: borrow of moved value `state` in miroir-proxy/src/main.rs:64","description":"miroir-proxy fails to compile with E0382: borrow of moved value.\n\nError:\n error[E0382]: borrow of moved value: `state`\n --> crates/miroir-proxy/src/main.rs:64:9\n\nThe `state` value is moved into .with_state(state) on line ~61, then borrowed on line 64 via state.config.server.bind.parse().\n\nFix: Change .with_state(state) to .with_state(state.clone()). If the state type does not already derive Clone, add #[derive(Clone)] to it.\n\nAcceptance: cargo build in repo root succeeds with no errors.","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-juliet","created_at":"2026-05-16T20:15:11.894483429Z","updated_at":"2026-05-20T02:51:56.604353080Z","source_repo":".","compaction_level":0} +{"id":"bf-1p4v","title":"Fix compile error: borrow of moved value `state` in miroir-proxy/src/main.rs:64","description":"miroir-proxy fails to compile with E0382: borrow of moved value.\n\nError:\n error[E0382]: borrow of moved value: `state`\n --> crates/miroir-proxy/src/main.rs:64:9\n\nThe `state` value is moved into .with_state(state) on line ~61, then borrowed on line 64 via state.config.server.bind.parse().\n\nFix: Change .with_state(state) to .with_state(state.clone()). If the state type does not already derive Clone, add #[derive(Clone)] to it.\n\nAcceptance: cargo build in repo root succeeds with no errors.","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-delta","created_at":"2026-05-16T20:15:11.894483429Z","updated_at":"2026-05-20T11:11:27.918634891Z","source_repo":".","compaction_level":0} {"id":"bf-2h2j","title":"Merge resolution: miroir-proxy and miroir-ctl conflicts","description":"## Prerequisite\nTasks bf-35t4 and bf-355g must be complete. Do NOT start unless `.git/MERGE_HEAD` exists and `git diff --name-only --diff-filter=U` shows only miroir-proxy/miroir-ctl paths.\n\n## What you are resolving\n\n**miroir-proxy content conflicts:**\n- `crates/miroir-proxy/Cargo.toml`\n- `crates/miroir-proxy/src/auth.rs`\n- `crates/miroir-proxy/src/lib.rs`\n- `crates/miroir-proxy/src/main.rs`\n- `crates/miroir-proxy/src/middleware.rs`\n- `crates/miroir-proxy/src/routes/admin.rs`\n- `crates/miroir-proxy/src/routes/documents.rs`\n- `crates/miroir-proxy/src/routes/indexes.rs`\n- `crates/miroir-proxy/src/routes/search.rs`\n- `crates/miroir-proxy/src/routes/settings.rs`\n- `crates/miroir-proxy/src/routes/tasks.rs`\n\n**miroir-proxy add/add conflicts:**\n- `crates/miroir-proxy/src/client.rs`\n\n**miroir-ctl content conflicts:**\n- `crates/miroir-ctl/src/credentials.rs`\n\n## Resolution strategy\n\n### Cargo.toml (miroir-proxy)\nInclude all dependencies from both sides. If a dep appears in both with different versions, use the newer one.\n\n### main.rs, lib.rs\nBoth sides added startup logic, state initialization, route registration. Include all state fields and route registrations from both sides. Preserve initialization ordering from main.\n\n### auth.rs\nBoth sides may have added auth middleware/types. Include all types and impls from both sides.\n\n### middleware.rs\nInclude all middleware layers and extractors from both sides.\n\n### routes/admin.rs\nmain added node management routes (POST /nodes, DELETE /nodes/{id}, POST /nodes/{id}/drain, GET /rebalance/status, replica_group CRUD). master may have added different admin routes. Include all routes from both sides, deduplicate any doubled entries.\n\n### routes/documents.rs\nmain uses `write_targets_with_migration()` for dual-write support. master may use `write_targets()`. Prefer main\\x27s version (migration-aware) for write_documents_impl; include any additional endpoints master added.\n\n### routes/search.rs, indexes.rs, settings.rs, tasks.rs\nBoth sides added endpoints. Include all routes and handlers from both sides.\n\n### client.rs (add/add)\nBoth sides created this file with different proxy client implementations. Read both versions carefully and produce a single client.rs that includes all functionality.\n\n### credentials.rs (miroir-ctl)\nInclude all credential handling from both sides.\n\n## After resolving\n```bash\ncd ~/miroir\ngit add crates/miroir-proxy/ crates/miroir-ctl/\n# Verify no remaining conflicts\ngit diff --name-only --diff-filter=U\n```\nExpected: empty output (all conflicts resolved and staged).\n\nDo NOT run `git commit` yet. Leave merge in progress for Task 4.","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-05-12T01:51:24.898908683Z","updated_at":"2026-05-12T01:51:24.898908683Z","source_repo":".","compaction_level":0,"dependencies":[{"issue_id":"bf-2h2j","depends_on_id":"bf-355g","type":"blocks","created_at":"2026-05-12T01:51:43.503517204Z","created_by":"cli","thread_id":""}]} {"id":"bf-355g","title":"Merge resolution: miroir-core and Cargo manifest conflicts","description":"## Prerequisite\nTask bf-35t4 must be complete (merge started, non-Rust files staged). Do NOT start this task unless `.git/MERGE_HEAD` exists in ~/miroir.\n\n## What you are resolving\nBoth branches added substantial code to the same miroir-core source files starting from the P0.7 split. Each conflict requires keeping additions from BOTH sides.\n\n**Content conflicts (both modified):**\n- `Cargo.toml` (workspace root)\n- `crates/miroir-core/Cargo.toml`\n- `crates/miroir-core/src/config.rs`\n- `crates/miroir-core/src/lib.rs`\n- `crates/miroir-core/src/merger.rs`\n- `crates/miroir-core/src/raft_proto/mod.rs`\n- `crates/miroir-core/src/router.rs`\n- `crates/miroir-core/src/scatter.rs`\n- `crates/miroir-core/src/topology.rs`\n\n**Add/add conflicts (both created new files):**\n- `crates/miroir-core/src/hedging.rs`\n- `crates/miroir-core/src/query_planner.rs`\n- `crates/miroir-core/src/replica_selection.rs`\n- `crates/miroir-core/src/task_store/mod.rs`\n- `crates/miroir-core/src/task_store/redis.rs`\n- `crates/miroir-core/src/task_store/sqlite.rs`\n\n## Resolution strategy\n\n### Cargo.toml / Cargo.lock\n- Open each conflicted Cargo.toml and include ALL dependencies and workspace members from both sides\n- After resolving Cargo.toml files, regenerate Cargo.lock: `cargo generate-lockfile`\n- Stage: `git add Cargo.toml Cargo.lock crates/miroir-core/Cargo.toml crates/miroir-proxy/Cargo.toml`\n\n### lib.rs\nBoth sides added module declarations. Include all modules from both sides (alphabetically sorted is fine). Deduplicate any doubled declarations.\n\n### config.rs\nBoth sides added config fields. Include all fields and impl blocks from both sides. Pay attention to struct field ordering and derive macros.\n\n### merger.rs\nThis is the largest file. main added extensive search result merging logic (2493 line diff); master may have added different merger logic. Read both sides carefully and produce a version that includes all functionality. Prioritize main\\x27s version for conflicts in the same function; add master\\x27s new functions alongside.\n\n### router.rs\nmain added `write_targets_with_migration()` and `get_all_migrations()` accessor. master may have modified routing logic. Keep all functions from both sides.\n\n### scatter.rs\nBoth sides modified the scatter/gather implementation. Carefully read both halves and produce a version that includes all functionality from both sides.\n\n### topology.rs\nBoth sides modified the topology model. Include all struct fields, impls, and new types from both sides.\n\n### raft_proto/mod.rs\nInclude all proto definitions and command types from both sides.\n\n### Add/add conflicts (hedging.rs, query_planner.rs, replica_selection.rs, task_store/)\nFor add/add conflicts: open both versions (one is in the conflict markers), produce a single file that incorporates all of the functionality. If one version is clearly more complete, use that as the base and add missing pieces from the other.\n\n## After resolving\n```bash\ncd ~/miroir\n# Stage all resolved miroir-core files\ngit add crates/miroir-core/\ngit add Cargo.toml Cargo.lock\n# Check remaining conflicts\ngit diff --name-only --diff-filter=U\n```\nExpected: only `crates/miroir-ctl/` and `crates/miroir-proxy/` paths remain.\n\nDo NOT run `git commit` yet. Leave merge in progress for Task 3.","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-05-12T01:51:11.212343033Z","updated_at":"2026-05-12T01:51:11.212343033Z","source_repo":".","compaction_level":0,"dependencies":[{"issue_id":"bf-355g","depends_on_id":"bf-35t4","type":"blocks","created_at":"2026-05-12T01:51:43.488680029Z","created_by":"cli","thread_id":""}]} -{"id":"bf-35t4","title":"Merge setup: checkout main, start merge, resolve non-Rust conflicts","description":"## Context\nYou are merging `origin/master` (Phase 0/1/2) into `origin/main` (Phase 3/4/5).\nMerge base: `2b1ea87 P0.7: Fix cargo fmt and clippy warnings for CI smoke`\n\nThis task covers: fetching, switching to main, starting the merge, and resolving all non-Rust-source conflicts.\n\n## Steps\n\n### 1. Setup\n```bash\ncd ~/miroir\ngit fetch origin\ngit checkout main # switch to the target branch\ngit merge origin/master # start the merge — conflicts are expected\n```\n\n### 2. Resolve non-Rust-source conflicts immediately\n\n**Take OURS (main) for bead/needle metadata:**\n```bash\ngit checkout --ours .beads/issues.jsonl\ngit checkout --ours .needle-predispatch-sha\n# For any .beads/traces/* add/add conflicts (miroir-mkk, miroir-r3j, miroir-uhj, miroir-zc2.6):\ngit checkout --ours .beads/traces/miroir-mkk/metadata.json\ngit checkout --ours .beads/traces/miroir-mkk/stdout.txt\ngit checkout --ours .beads/traces/miroir-r3j/metadata.json\ngit checkout --ours .beads/traces/miroir-r3j/stdout.txt\ngit checkout --ours .beads/traces/miroir-uhj/metadata.json\ngit checkout --ours .beads/traces/miroir-uhj/stdout.txt\ngit checkout --ours .beads/traces/miroir-zc2.6/metadata.json\ngit checkout --ours .beads/traces/miroir-zc2.6/stdout.txt\n# Stage all of these\ngit add .beads/ .needle-predispatch-sha\n```\n\n**Keep THEIRS (master) for notes/docs/charts that master added:**\n```bash\ngit checkout --theirs notes/miroir-r3j-final-verification.md\ngit checkout --theirs notes/miroir-r3j-verification.md\ngit checkout --theirs notes/miroir-r3j.md\ngit checkout --theirs docs/research/score-normalization-at-scale.md\n# Helm chart — master added charts/miroir/, check if main also has it\n# If add/add conflict: review both versions and keep the more complete one\n# For all charts/ conflicts, check content of both sides and keep the better version\ngit checkout --theirs charts/miroir/Chart.yaml\ngit checkout --theirs charts/miroir/templates/NOTES.txt\ngit checkout --theirs charts/miroir/templates/_helpers.tpl\ngit checkout --theirs charts/miroir/templates/redis-deployment.yaml\ngit checkout --theirs charts/miroir/templates/serviceaccount.yaml\ngit checkout --theirs charts/miroir/tests/README.md\ngit checkout --theirs charts/miroir/values.schema.json\ngit checkout --theirs charts/miroir/values.yaml\ngit add notes/ docs/research/ charts/\n```\n\n### 3. Verify remaining conflicts\n```bash\ngit diff --name-only --diff-filter=U\n```\nExpected remaining conflicts: Rust source files and Cargo.toml/Cargo.lock only.\nThese are handled by Tasks 2 and 3.\n\n## Done when\n- All non-Rust files are staged (git add)\n- `git diff --name-only --diff-filter=U` shows only Cargo files and `crates/` paths\n- Do NOT run `git commit` yet — the merge must remain in progress for Tasks 2 and 3\n\n## Important\nDo not commit or abort the merge. Leave it in progress.","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-lima","created_at":"2026-05-12T01:50:51.130896161Z","updated_at":"2026-05-20T02:51:42.196509944Z","source_repo":".","compaction_level":0} -{"id":"bf-3lad","title":"P11.7 Quick-start example artifacts (examples/docker-compose-dev.yml + dev-config.yaml)","description":"## What\n\nCreate the on-disk example artifacts referenced by plan §11 \"Quick start (local, Docker Compose)\" and §12 \"Repository structure\":\n\n```\nexamples/\n├── docker-compose-dev.yml # 1 Miroir + 2-3 Meilisearch nodes + (optional) Redis\n└── dev-config.yaml # matching Miroir config for the compose stack\n```\n\nCurrently `/home/coding/miroir/examples/` does not exist. The §11 quick-start text is in `plan.md` lines 1994-2018 — turn that walkthrough into runnable artifacts.\n\n## Why\n\n`miroir-uyx.1` (README.md) covers writing the doc, but the README quick-start cannot be runnable without the example files. Onboarding promise of §11 is \"5 minutes from clone to working sharded search\"; that requires the files exist.\n\n## Acceptance\n\n- [ ] `examples/docker-compose-dev.yml` boots successfully via `docker compose up`\n- [ ] `examples/dev-config.yaml` mounted into the Miroir container; matches the §11 walkthrough\n- [ ] `examples/README.md` documents how to run, expected output, and how to tear down\n- [ ] CI smoke job exercises the compose stack at least once per PR (sanity boot + one search round-trip)\n- [ ] README.md \"Quick start\" section points to `examples/docker-compose-dev.yml`\n\nParent epic: `miroir-uyx` (Phase 11 — Onboarding + Delivered Artifacts). Cross-cuts: `miroir-uyx.1` (README quick-start text), `miroir-89x.2` (integration test harness — can share the compose).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-foxtrot","created_at":"2026-05-10T02:34:35.918861511Z","updated_at":"2026-05-20T02:51:54.126574456Z","source_repo":".","compaction_level":0,"labels":["phase-11"]} -{"id":"bf-3wym","title":"P2.10 Custom HTTP header contract test suite","description":"## What\n\nImplement a contract-test suite that asserts every custom HTTP header in plan §5 \"Custom HTTP headers\" behaves exactly per its row. Many of the headers tie to feature beads; this bead tracks the unified contract test, not the feature implementations.\n\nHeaders from the §5 table:\n\n| Header | Direction | Feature bead |\n|--------|-----------|--------------|\n| `X-Miroir-Degraded` | Response | §2 write path / scatter (already implemented in `routes/search.rs:298`, `routes/documents.rs`) |\n| `X-Miroir-Settings-Version` | Response | §13.5 → `miroir-uhj.5.3` |\n| `X-Miroir-Min-Settings-Version` | Request | §13.5 → `miroir-uhj.5.5` |\n| `X-Miroir-Settings-Inconsistent` | Response | §13.5 → `miroir-uhj.5.x` (verify phase) |\n| `X-Miroir-Session` | Both | §13.6 → `miroir-uhj.6` |\n| `Idempotency-Key` | Request | §13.10 → `miroir-uhj.10` |\n| `X-Miroir-Over-Fetch` | Request | §13.12 → `miroir-uhj.12` |\n| `X-Miroir-Tenant` | Request | §13.15 → `miroir-uhj.15` |\n| `X-Admin-Key` | Request | §13.19 / §5 dispatch (covered by `miroir-9dj.7`) |\n| `X-CSRF-Token` | Request | §13.19 → `miroir-uhj.19.5` |\n| `X-Search-UI-Key` | Request | §13.21 → `miroir-uhj.21.x` |\n\n## Why\n\nEach feature bead tests its own header in isolation; nothing asserts the FULL surface stays Meilisearch-compatible (clients that do not recognize these headers MUST keep working — §5 explicit promise). A single contract suite catches drift when a feature lands without honoring the request/response convention.\n\n## Acceptance\n\n- [ ] One test file `crates/miroir-proxy/tests/header_contract.rs`\n- [ ] Round-trip test for every Request header: present, absent, malformed → expected status code per §5\n- [ ] Echo test for every Response header: header is set when the feature condition holds, absent otherwise\n- [ ] Forward-compat test: an unknown `X-Miroir-Future` is silently ignored (does not 400)\n- [ ] Meilisearch-compat: a vanilla Meilisearch client (no Miroir headers) gets identical behavior to a single-node Meilisearch\n- [ ] Test runs in CI on every PR\n\nParent epic: `miroir-9dj` (Phase 2 — Proxy + API Surface). Blocked by feature beads only insofar as they implement the headers; the test scaffolding can land first with `#[ignore]` for unimplemented headers.","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-papa","created_at":"2026-05-10T02:33:32.329473471Z","updated_at":"2026-05-20T02:51:08.094735411Z","source_repo":".","compaction_level":0,"labels":["phase-2"]} +{"id":"bf-35t4","title":"Merge setup: checkout main, start merge, resolve non-Rust conflicts","description":"## Context\nYou are merging `origin/master` (Phase 0/1/2) into `origin/main` (Phase 3/4/5).\nMerge base: `2b1ea87 P0.7: Fix cargo fmt and clippy warnings for CI smoke`\n\nThis task covers: fetching, switching to main, starting the merge, and resolving all non-Rust-source conflicts.\n\n## Steps\n\n### 1. Setup\n```bash\ncd ~/miroir\ngit fetch origin\ngit checkout main # switch to the target branch\ngit merge origin/master # start the merge — conflicts are expected\n```\n\n### 2. Resolve non-Rust-source conflicts immediately\n\n**Take OURS (main) for bead/needle metadata:**\n```bash\ngit checkout --ours .beads/issues.jsonl\ngit checkout --ours .needle-predispatch-sha\n# For any .beads/traces/* add/add conflicts (miroir-mkk, miroir-r3j, miroir-uhj, miroir-zc2.6):\ngit checkout --ours .beads/traces/miroir-mkk/metadata.json\ngit checkout --ours .beads/traces/miroir-mkk/stdout.txt\ngit checkout --ours .beads/traces/miroir-r3j/metadata.json\ngit checkout --ours .beads/traces/miroir-r3j/stdout.txt\ngit checkout --ours .beads/traces/miroir-uhj/metadata.json\ngit checkout --ours .beads/traces/miroir-uhj/stdout.txt\ngit checkout --ours .beads/traces/miroir-zc2.6/metadata.json\ngit checkout --ours .beads/traces/miroir-zc2.6/stdout.txt\n# Stage all of these\ngit add .beads/ .needle-predispatch-sha\n```\n\n**Keep THEIRS (master) for notes/docs/charts that master added:**\n```bash\ngit checkout --theirs notes/miroir-r3j-final-verification.md\ngit checkout --theirs notes/miroir-r3j-verification.md\ngit checkout --theirs notes/miroir-r3j.md\ngit checkout --theirs docs/research/score-normalization-at-scale.md\n# Helm chart — master added charts/miroir/, check if main also has it\n# If add/add conflict: review both versions and keep the more complete one\n# For all charts/ conflicts, check content of both sides and keep the better version\ngit checkout --theirs charts/miroir/Chart.yaml\ngit checkout --theirs charts/miroir/templates/NOTES.txt\ngit checkout --theirs charts/miroir/templates/_helpers.tpl\ngit checkout --theirs charts/miroir/templates/redis-deployment.yaml\ngit checkout --theirs charts/miroir/templates/serviceaccount.yaml\ngit checkout --theirs charts/miroir/tests/README.md\ngit checkout --theirs charts/miroir/values.schema.json\ngit checkout --theirs charts/miroir/values.yaml\ngit add notes/ docs/research/ charts/\n```\n\n### 3. Verify remaining conflicts\n```bash\ngit diff --name-only --diff-filter=U\n```\nExpected remaining conflicts: Rust source files and Cargo.toml/Cargo.lock only.\nThese are handled by Tasks 2 and 3.\n\n## Done when\n- All non-Rust files are staged (git add)\n- `git diff --name-only --diff-filter=U` shows only Cargo files and `crates/` paths\n- Do NOT run `git commit` yet — the merge must remain in progress for Tasks 2 and 3\n\n## Important\nDo not commit or abort the merge. Leave it in progress.","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-echo","created_at":"2026-05-12T01:50:51.130896161Z","updated_at":"2026-05-20T03:48:36.386475703Z","source_repo":".","compaction_level":0} +{"id":"bf-3lad","title":"P11.7 Quick-start example artifacts (examples/docker-compose-dev.yml + dev-config.yaml)","description":"## What\n\nCreate the on-disk example artifacts referenced by plan §11 \"Quick start (local, Docker Compose)\" and §12 \"Repository structure\":\n\n```\nexamples/\n├── docker-compose-dev.yml # 1 Miroir + 2-3 Meilisearch nodes + (optional) Redis\n└── dev-config.yaml # matching Miroir config for the compose stack\n```\n\nCurrently `/home/coding/miroir/examples/` does not exist. The §11 quick-start text is in `plan.md` lines 1994-2018 — turn that walkthrough into runnable artifacts.\n\n## Why\n\n`miroir-uyx.1` (README.md) covers writing the doc, but the README quick-start cannot be runnable without the example files. Onboarding promise of §11 is \"5 minutes from clone to working sharded search\"; that requires the files exist.\n\n## Acceptance\n\n- [ ] `examples/docker-compose-dev.yml` boots successfully via `docker compose up`\n- [ ] `examples/dev-config.yaml` mounted into the Miroir container; matches the §11 walkthrough\n- [ ] `examples/README.md` documents how to run, expected output, and how to tear down\n- [ ] CI smoke job exercises the compose stack at least once per PR (sanity boot + one search round-trip)\n- [ ] README.md \"Quick start\" section points to `examples/docker-compose-dev.yml`\n\nParent epic: `miroir-uyx` (Phase 11 — Onboarding + Delivered Artifacts). Cross-cuts: `miroir-uyx.1` (README quick-start text), `miroir-89x.2` (integration test harness — can share the compose).","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-oscar","created_at":"2026-05-10T02:34:35.918861511Z","updated_at":"2026-05-20T10:49:27.107170660Z","closed_at":"2026-05-20T10:49:27.107170660Z","close_reason":"Completed","source_repo":".","compaction_level":0,"labels":["phase-11"]} +{"id":"bf-3wym","title":"P2.10 Custom HTTP header contract test suite","description":"## What\n\nImplement a contract-test suite that asserts every custom HTTP header in plan §5 \"Custom HTTP headers\" behaves exactly per its row. Many of the headers tie to feature beads; this bead tracks the unified contract test, not the feature implementations.\n\nHeaders from the §5 table:\n\n| Header | Direction | Feature bead |\n|--------|-----------|--------------|\n| `X-Miroir-Degraded` | Response | §2 write path / scatter (already implemented in `routes/search.rs:298`, `routes/documents.rs`) |\n| `X-Miroir-Settings-Version` | Response | §13.5 → `miroir-uhj.5.3` |\n| `X-Miroir-Min-Settings-Version` | Request | §13.5 → `miroir-uhj.5.5` |\n| `X-Miroir-Settings-Inconsistent` | Response | §13.5 → `miroir-uhj.5.x` (verify phase) |\n| `X-Miroir-Session` | Both | §13.6 → `miroir-uhj.6` |\n| `Idempotency-Key` | Request | §13.10 → `miroir-uhj.10` |\n| `X-Miroir-Over-Fetch` | Request | §13.12 → `miroir-uhj.12` |\n| `X-Miroir-Tenant` | Request | §13.15 → `miroir-uhj.15` |\n| `X-Admin-Key` | Request | §13.19 / §5 dispatch (covered by `miroir-9dj.7`) |\n| `X-CSRF-Token` | Request | §13.19 → `miroir-uhj.19.5` |\n| `X-Search-UI-Key` | Request | §13.21 → `miroir-uhj.21.x` |\n\n## Why\n\nEach feature bead tests its own header in isolation; nothing asserts the FULL surface stays Meilisearch-compatible (clients that do not recognize these headers MUST keep working — §5 explicit promise). A single contract suite catches drift when a feature lands without honoring the request/response convention.\n\n## Acceptance\n\n- [ ] One test file `crates/miroir-proxy/tests/header_contract.rs`\n- [ ] Round-trip test for every Request header: present, absent, malformed → expected status code per §5\n- [ ] Echo test for every Response header: header is set when the feature condition holds, absent otherwise\n- [ ] Forward-compat test: an unknown `X-Miroir-Future` is silently ignored (does not 400)\n- [ ] Meilisearch-compat: a vanilla Meilisearch client (no Miroir headers) gets identical behavior to a single-node Meilisearch\n- [ ] Test runs in CI on every PR\n\nParent epic: `miroir-9dj` (Phase 2 — Proxy + API Surface). Blocked by feature beads only insofar as they implement the headers; the test scaffolding can land first with `#[ignore]` for unimplemented headers.","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-lima","created_at":"2026-05-10T02:33:32.329473471Z","updated_at":"2026-05-20T11:11:31.180581280Z","source_repo":".","compaction_level":0,"labels":["phase-2"]} {"id":"bf-4fo8","title":"Verify build, complete merge commit, and push to origin/main","description":"## Prerequisite\nTasks bf-35t4, bf-355g, and bf-2h2j must be complete. `git diff --name-only --diff-filter=U` must return empty (no remaining conflicts). `.git/MERGE_HEAD` must exist.\n\n## Steps\n\n### 1. Verify no remaining conflicts\n```bash\ncd ~/miroir\ngit diff --name-only --diff-filter=U\n```\nIf any conflicts remain, fix them and `git add` the resolved files before continuing.\n\n### 2. Check compilation\n```bash\ncargo check --workspace 2>&1 | head -60\n```\nFix any compilation errors. Common issues after a merge:\n- Missing `use` imports (add them)\n- Duplicate type/function definitions (deduplicate)\n- API mismatches between crates (align types)\n- Missing fields in struct initializers (add them with sensible defaults)\n\nIterate until `cargo check --workspace` passes with no errors.\n\n### 3. Run a quick build\n```bash\ncargo build --workspace 2>&1 | tail -20\n```\nFix any remaining build errors not caught by check.\n\n### 4. Complete the merge commit\n```bash\ngit commit -m \\x22Merge origin/master into main: integrate Phase 0/1/2 work\n\nMerges 148 commits from master (Phase 0 Foundation, Phase 1 Core Routing,\nPhase 2 Proxy + API Surface) with 148 commits on main (Phase 3 Task Registry,\nPhase 4 Topology Operations, Phase 5 Advanced Capabilities).\n\nBoth branches diverged from 2b1ea87 (P0.7).\\x22\n```\n\n### 5. Push\n```bash\ngit push origin main\n```\n\n### 6. Verify\n```bash\ngit log --oneline -5\ngit status\n```\n\n## Done when\n- `git push origin main` succeeds\n- `git status` shows \\x22Your branch is up to date with origin/main\\x22\n- The merged commit appears in `git log`\n\nClose this bead and then close the epic bf-1m37 once complete.","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-05-12T01:51:38.397171679Z","updated_at":"2026-05-12T01:51:38.397171679Z","source_repo":".","compaction_level":0,"dependencies":[{"issue_id":"bf-4fo8","depends_on_id":"bf-2h2j","type":"blocks","created_at":"2026-05-12T01:51:43.507030478Z","created_by":"cli","thread_id":""}]} -{"id":"bf-4w08","title":"P6.10 Wire §14.8 resource-aware config defaults into Rust + values.yaml","description":"## What\n\nBake the §14.8 default values into the actual Rust config struct (`crates/miroir-core/src/config/`) and the Helm `charts/miroir/values.yaml`. The plan asserts these defaults fit the 2 vCPU / 3.75 GB envelope; if the code defaults drift from the plan, the envelope claim becomes a lie.\n\nKnobs from §14.8 (lines 3613-3672):\n\n```yaml\nmiroir:\n server: { max_body_bytes: 100 MiB, max_concurrent_requests: 500, request_timeout_ms: 30000 }\n connection_pool_per_node: { max_idle: 32, max_total: 128, idle_timeout_s: 60 }\n task_registry: { cache_size: 10000, redis_pool_max: 50 }\n idempotency: { max_cached_keys: 1_000_000 (~100 MB), ttl_seconds: 86400 }\n session_pinning: { max_sessions: 100_000 (~50 MB) }\n query_coalescing: { max_subscribers: 1000, max_pending_queries: 10000 }\n anti_entropy: { max_read_concurrency: 2, fingerprint_batch_size: 1000 }\n resharding: { backfill_concurrency: 4, backfill_batch_size: 1000 }\n peer_discovery: { service_name: \"miroir-headless\", refresh_interval_s: 15 }\n leader_election: { enabled (auto when replicas>1), lease_ttl_s: 10, renew_interval_s: 3 }\n```\n\nPlus K8s pod requests/limits: `cpu 500m / 2000m`, `memory 1Gi / 3584Mi` (3.5 GiB; leaves headroom under 3.75 GB).\n\n## Why\n\n`miroir-qon.5` (config struct) is closed but predates §14. Several of the §13.x features that consume these knobs were beaded later. Some defaults likely already match (validate); others may be missing or misaligned. Without them, `miroir_memory_pressure` (§14.9) will fire spuriously and the §14.7 sizing matrix becomes unverifiable.\n\n## Acceptance\n\n- [ ] Each §14.8 key present in `crates/miroir-core/src/config/` with the documented default\n- [ ] `charts/miroir/values.yaml` exposes the same keys with identical defaults\n- [ ] `values.schema.json` accepts the documented ranges; rejects nonsense (e.g., `lease_ttl_s < renew_interval_s`)\n- [ ] K8s resources block in `templates/miroir-deployment.yaml` matches §14.8 (500m/2000m CPU, 1Gi/3584Mi mem)\n- [ ] Unit test: serializing the default Config struct produces a YAML equal to the §14.8 listing modulo formatting\n- [ ] Drift guard: a doc-test or CI step compares `Config::default()` against the §14.8 reference YAML\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling). Cross-cuts: `miroir-qjt.2` (Helm values), `miroir-qjt.3` (values.schema.json).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-mike","created_at":"2026-05-10T02:34:13.371341351Z","updated_at":"2026-05-20T02:52:11.137419630Z","source_repo":".","compaction_level":0,"labels":["phase-6"]} -{"id":"bf-55fg","title":"P6.8 Per-feature scaling behavior reference doc (§14.6)","description":"## What\n\nAuthor `docs/horizontal-scaling/per-feature.md` containing the §14.6 contract table verbatim plus operator notes. The table maps every §13.x advanced capability to its scaling mode (A=shard-partitioned, B=leader-only, C=work-queued, stateless, per-pod). Required so operators know which features need Redis vs. work-queue vs. nothing.\n\nSource content: plan §14.6 (lines 3565-3591). The doc must:\n1. Reproduce the table.\n2. Add a \"Forced-mode constraints\" subsection — e.g., §13.21 search UI rate limiter MUST use `backend: redis` when `replicas > 1`; `values.schema.json` rejects `backend: local` with `replicas > 1`.\n3. Reference `miroir-m9q.3/4/5` (Mode A/B/C implementations) and the relevant §13.x feature beads.\n\n## Why\n\nPlan §14.6 is currently embedded in `plan.md`. Operators cannot grep a focused doc when they need to answer \"Is feature X horizontally safe? Does it need Redis?\". The §14.7 sizing matrix and §14.9 alerts both reference §14.6 implicitly; pulling it into its own doc enables reuse.\n\n## Acceptance\n\n- [ ] `docs/horizontal-scaling/per-feature.md` exists and reproduces the §14.6 table\n- [ ] Each row links to the relevant §13.x feature bead (or its closed predecessor)\n- [ ] Forced-mode constraints subsection enumerates every Helm `values.schema.json` rejection driven by horizontal-scaling concerns\n- [ ] README.md links to it\n- [ ] Doc is referenced from `miroir-m9q.3/4/5` descriptions for cross-navigation\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-hotel","created_at":"2026-05-10T02:33:44.000604994Z","updated_at":"2026-05-20T02:51:35.963541056Z","source_repo":".","compaction_level":0,"labels":["phase-6"]} -{"id":"bf-5r7p","title":"P11.8 Repo structure compliance: tests/, dashboards/ at root (§12)","description":"## What\n\nBring the on-disk repo layout into compliance with plan §12 \"Repository structure\" (lines 2161-2197):\n\n```\njedarden/miroir/\n├── tests/\n│ ├── integration/ # (does not exist)\n│ └── chaos/ # (does not exist)\n├── examples/ # (does not exist; covered by P11.7)\n└── dashboards/ # (does not exist)\n └── miroir-overview.json # (covered by miroir-afh.3)\n```\n\nCurrently the repo only has `crates/`, `charts/miroir/`, `docs/`. Tests live inside crate directories (`crates/miroir-core/tests/`, `crates/miroir-proxy/tests/`); chaos test material is `docs/chaos_testing_report.md` only.\n\nDecision required: relocate existing crate-level tests into top-level `tests/integration/` (matches §12), OR amend the plan to bless the current crate-level layout. Either is valid — but the docs and code must agree.\n\n## Why\n\n`§12 Repository structure` is a stated public contract (some deployments / mirrors / OS packagers expect it). Without the layout the §12 promise is only partially met.\n\n## Acceptance\n\n- [ ] Decision recorded: keep §12 as-stated and migrate, OR amend §12 to reflect crate-level tests\n- [ ] If migrating: `tests/integration/` and `tests/chaos/` exist and contain the relocated suites; CI runs `cargo test --tests` from root\n- [ ] `dashboards/` directory exists; `miroir-afh.3` outputs the JSON there\n- [ ] If amending: plan §12 updated; doc-test enforces the new layout\n- [ ] `examples/` covered separately by `P11.7`\n\nParent epic: `miroir-uyx` (Phase 11 — Onboarding + Delivered Artifacts).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":2,"issue_type":"task","assignee":"claude-code-glm-4.7-bravo","created_at":"2026-05-10T02:34:50.117344559Z","updated_at":"2026-05-20T02:51:57.514469199Z","source_repo":".","compaction_level":0,"labels":["phase-11"]} -{"id":"bf-5xqk","title":"P2.9 Reserved-field write rejection (miroir_reserved_field)","description":"## What\n\nImplement write-path rejection of reserved `_miroir_*` field names per plan §5 \"Reserved fields\". The merger already strips these from responses (`crates/miroir-core/src/merger.rs:540, 955`); writes need the symmetric enforcement.\n\nReserved fields per §5 table:\n\n| Field | Reserved when |\n|-------|---------------|\n| `_miroir_shard` | Always (unconditional) |\n| `_miroir_updated_at` | Only when `anti_entropy.enabled: true` (§13.8) |\n| `_miroir_expires_at` | Only when `ttl.enabled: true` (§13.14) |\n\nWhen a configuration disables the conditional reservation, client values in that field MUST be preserved and passed through untouched. When reserved, a write containing the field is rejected with HTTP 400 `miroir_reserved_field`.\n\n## Why\n\nPlan §5 promises the contract; without write-path rejection clients can poison the rebalancer (`_miroir_shard`) and tie-breaker logic (`_miroir_updated_at`). Strip-on-response is implemented but reject-on-write is not.\n\n## Acceptance\n\n- [ ] POST/PUT `/indexes/{uid}/documents` containing `_miroir_shard` always returns 400 `miroir_reserved_field`\n- [ ] When `anti_entropy.enabled: true`, writes with client-supplied `_miroir_updated_at` are rejected; when disabled, the field is preserved end-to-end\n- [ ] When `ttl.enabled: true`, writes carrying `_miroir_expires_at` succeed (clients SET it); reads still strip it; when disabled, client values pass through\n- [ ] Error body matches Meilisearch shape `{message, code, type, link}` with `code: miroir_reserved_field`\n- [ ] Unit tests in `miroir-proxy/src/routes/documents.rs` cover all four matrix cells\n- [ ] Integration test confirms `_miroir_shard` injected by orchestrator passes write-validation (orchestrator stamping path is exempt)\n\nParent epic: `miroir-9dj` (Phase 2 — Proxy + API Surface).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-charlie","created_at":"2026-05-10T02:33:14.466105436Z","updated_at":"2026-05-20T02:51:38.515072366Z","source_repo":".","compaction_level":0,"labels":["phase-2"]} -{"id":"bf-7r59","title":"P6.9 Revised deployment sizing matrix doc (§14.7)","description":"## What\n\nAuthor `docs/horizontal-scaling/sizing.md` from plan §14.7. Reproduce the corpus/QPS → orchestrator pod count + task store table, plus the Redis memory accounting note (idempotency keys, session pinning, alias cache, job queue, leader lease, CDC overflow, search UI rate-limit buckets — ~20 MB per 10k active IPs).\n\nSections:\n1. Sizing table (5 rows: ≤10 GB / ≤50 GB / ≤200 GB / ≤1 TB / ≤5 TB).\n2. Task-store memory accounting (the §14.7 paragraph).\n3. Worked example: pick one row and walk through the math to validate against §14.2.\n4. \"When to escalate\" — pointer to §14.10 vertical-scaling escape valve.\n\n## Why\n\nOperators need a sizing reference when provisioning. Without a focused doc, the matrix is buried at line 3593 of `plan.md` and the Redis memory implications are easy to miss until OOMs hit. This is THE artifact users will need on day one.\n\n## Acceptance\n\n- [ ] `docs/horizontal-scaling/sizing.md` reproduces the §14.7 table\n- [ ] Includes the Redis memory accounting paragraph\n- [ ] Worked example for one row (math should match §14.2 budget)\n- [ ] Linked from README.md \"Production deployment\" subsection\n- [ ] Linked from `docs/onboarding/production.md` (companion to bead `miroir-uyx.4`)\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-alpha","created_at":"2026-05-10T02:33:56.025437576Z","updated_at":"2026-05-20T02:52:14.419369825Z","source_repo":".","compaction_level":0,"labels":["phase-6"]} +{"id":"bf-4w08","title":"P6.10 Wire §14.8 resource-aware config defaults into Rust + values.yaml","description":"## What\n\nBake the §14.8 default values into the actual Rust config struct (`crates/miroir-core/src/config/`) and the Helm `charts/miroir/values.yaml`. The plan asserts these defaults fit the 2 vCPU / 3.75 GB envelope; if the code defaults drift from the plan, the envelope claim becomes a lie.\n\nKnobs from §14.8 (lines 3613-3672):\n\n```yaml\nmiroir:\n server: { max_body_bytes: 100 MiB, max_concurrent_requests: 500, request_timeout_ms: 30000 }\n connection_pool_per_node: { max_idle: 32, max_total: 128, idle_timeout_s: 60 }\n task_registry: { cache_size: 10000, redis_pool_max: 50 }\n idempotency: { max_cached_keys: 1_000_000 (~100 MB), ttl_seconds: 86400 }\n session_pinning: { max_sessions: 100_000 (~50 MB) }\n query_coalescing: { max_subscribers: 1000, max_pending_queries: 10000 }\n anti_entropy: { max_read_concurrency: 2, fingerprint_batch_size: 1000 }\n resharding: { backfill_concurrency: 4, backfill_batch_size: 1000 }\n peer_discovery: { service_name: \"miroir-headless\", refresh_interval_s: 15 }\n leader_election: { enabled (auto when replicas>1), lease_ttl_s: 10, renew_interval_s: 3 }\n```\n\nPlus K8s pod requests/limits: `cpu 500m / 2000m`, `memory 1Gi / 3584Mi` (3.5 GiB; leaves headroom under 3.75 GB).\n\n## Why\n\n`miroir-qon.5` (config struct) is closed but predates §14. Several of the §13.x features that consume these knobs were beaded later. Some defaults likely already match (validate); others may be missing or misaligned. Without them, `miroir_memory_pressure` (§14.9) will fire spuriously and the §14.7 sizing matrix becomes unverifiable.\n\n## Acceptance\n\n- [ ] Each §14.8 key present in `crates/miroir-core/src/config/` with the documented default\n- [ ] `charts/miroir/values.yaml` exposes the same keys with identical defaults\n- [ ] `values.schema.json` accepts the documented ranges; rejects nonsense (e.g., `lease_ttl_s < renew_interval_s`)\n- [ ] K8s resources block in `templates/miroir-deployment.yaml` matches §14.8 (500m/2000m CPU, 1Gi/3584Mi mem)\n- [ ] Unit test: serializing the default Config struct produces a YAML equal to the §14.8 listing modulo formatting\n- [ ] Drift guard: a doc-test or CI step compares `Config::default()` against the §14.8 reference YAML\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling). Cross-cuts: `miroir-qjt.2` (Helm values), `miroir-qjt.3` (values.schema.json).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-alpha","created_at":"2026-05-10T02:34:13.371341351Z","updated_at":"2026-05-20T11:13:07.523093100Z","source_repo":".","compaction_level":0,"labels":["phase-6"]} +{"id":"bf-55fg","title":"P6.8 Per-feature scaling behavior reference doc (§14.6)","description":"## What\n\nAuthor `docs/horizontal-scaling/per-feature.md` containing the §14.6 contract table verbatim plus operator notes. The table maps every §13.x advanced capability to its scaling mode (A=shard-partitioned, B=leader-only, C=work-queued, stateless, per-pod). Required so operators know which features need Redis vs. work-queue vs. nothing.\n\nSource content: plan §14.6 (lines 3565-3591). The doc must:\n1. Reproduce the table.\n2. Add a \"Forced-mode constraints\" subsection — e.g., §13.21 search UI rate limiter MUST use `backend: redis` when `replicas > 1`; `values.schema.json` rejects `backend: local` with `replicas > 1`.\n3. Reference `miroir-m9q.3/4/5` (Mode A/B/C implementations) and the relevant §13.x feature beads.\n\n## Why\n\nPlan §14.6 is currently embedded in `plan.md`. Operators cannot grep a focused doc when they need to answer \"Is feature X horizontally safe? Does it need Redis?\". The §14.7 sizing matrix and §14.9 alerts both reference §14.6 implicitly; pulling it into its own doc enables reuse.\n\n## Acceptance\n\n- [ ] `docs/horizontal-scaling/per-feature.md` exists and reproduces the §14.6 table\n- [ ] Each row links to the relevant §13.x feature bead (or its closed predecessor)\n- [ ] Forced-mode constraints subsection enumerates every Helm `values.schema.json` rejection driven by horizontal-scaling concerns\n- [ ] README.md links to it\n- [ ] Doc is referenced from `miroir-m9q.3/4/5` descriptions for cross-navigation\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-november","created_at":"2026-05-10T02:33:44.000604994Z","updated_at":"2026-05-20T11:11:08.254532974Z","source_repo":".","compaction_level":0,"labels":["phase-6"]} +{"id":"bf-5r7p","title":"P11.8 Repo structure compliance: tests/, dashboards/ at root (§12)","description":"## What\n\nBring the on-disk repo layout into compliance with plan §12 \"Repository structure\" (lines 2161-2197):\n\n```\njedarden/miroir/\n├── tests/\n│ ├── integration/ # (does not exist)\n│ └── chaos/ # (does not exist)\n├── examples/ # (does not exist; covered by P11.7)\n└── dashboards/ # (does not exist)\n └── miroir-overview.json # (covered by miroir-afh.3)\n```\n\nCurrently the repo only has `crates/`, `charts/miroir/`, `docs/`. Tests live inside crate directories (`crates/miroir-core/tests/`, `crates/miroir-proxy/tests/`); chaos test material is `docs/chaos_testing_report.md` only.\n\nDecision required: relocate existing crate-level tests into top-level `tests/integration/` (matches §12), OR amend the plan to bless the current crate-level layout. Either is valid — but the docs and code must agree.\n\n## Why\n\n`§12 Repository structure` is a stated public contract (some deployments / mirrors / OS packagers expect it). Without the layout the §12 promise is only partially met.\n\n## Acceptance\n\n- [ ] Decision recorded: keep §12 as-stated and migrate, OR amend §12 to reflect crate-level tests\n- [ ] If migrating: `tests/integration/` and `tests/chaos/` exist and contain the relocated suites; CI runs `cargo test --tests` from root\n- [ ] `dashboards/` directory exists; `miroir-afh.3` outputs the JSON there\n- [ ] If amending: plan §12 updated; doc-test enforces the new layout\n- [ ] `examples/` covered separately by `P11.7`\n\nParent epic: `miroir-uyx` (Phase 11 — Onboarding + Delivered Artifacts).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":2,"issue_type":"task","assignee":"claude-code-glm-4.7-juliet","created_at":"2026-05-10T02:34:50.117344559Z","updated_at":"2026-05-20T11:12:22.941091138Z","source_repo":".","compaction_level":0,"labels":["phase-11"]} +{"id":"bf-5xqk","title":"P2.9 Reserved-field write rejection (miroir_reserved_field)","description":"## What\n\nImplement write-path rejection of reserved `_miroir_*` field names per plan §5 \"Reserved fields\". The merger already strips these from responses (`crates/miroir-core/src/merger.rs:540, 955`); writes need the symmetric enforcement.\n\nReserved fields per §5 table:\n\n| Field | Reserved when |\n|-------|---------------|\n| `_miroir_shard` | Always (unconditional) |\n| `_miroir_updated_at` | Only when `anti_entropy.enabled: true` (§13.8) |\n| `_miroir_expires_at` | Only when `ttl.enabled: true` (§13.14) |\n\nWhen a configuration disables the conditional reservation, client values in that field MUST be preserved and passed through untouched. When reserved, a write containing the field is rejected with HTTP 400 `miroir_reserved_field`.\n\n## Why\n\nPlan §5 promises the contract; without write-path rejection clients can poison the rebalancer (`_miroir_shard`) and tie-breaker logic (`_miroir_updated_at`). Strip-on-response is implemented but reject-on-write is not.\n\n## Acceptance\n\n- [ ] POST/PUT `/indexes/{uid}/documents` containing `_miroir_shard` always returns 400 `miroir_reserved_field`\n- [ ] When `anti_entropy.enabled: true`, writes with client-supplied `_miroir_updated_at` are rejected; when disabled, the field is preserved end-to-end\n- [ ] When `ttl.enabled: true`, writes carrying `_miroir_expires_at` succeed (clients SET it); reads still strip it; when disabled, client values pass through\n- [ ] Error body matches Meilisearch shape `{message, code, type, link}` with `code: miroir_reserved_field`\n- [ ] Unit tests in `miroir-proxy/src/routes/documents.rs` cover all four matrix cells\n- [ ] Integration test confirms `_miroir_shard` injected by orchestrator passes write-validation (orchestrator stamping path is exempt)\n\nParent epic: `miroir-9dj` (Phase 2 — Proxy + API Surface).","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-papa","created_at":"2026-05-10T02:33:14.466105436Z","updated_at":"2026-05-20T11:10:47.617255531Z","source_repo":".","compaction_level":0,"labels":["phase-2"]} +{"id":"bf-7r59","title":"P6.9 Revised deployment sizing matrix doc (§14.7)","description":"## What\n\nAuthor `docs/horizontal-scaling/sizing.md` from plan §14.7. Reproduce the corpus/QPS → orchestrator pod count + task store table, plus the Redis memory accounting note (idempotency keys, session pinning, alias cache, job queue, leader lease, CDC overflow, search UI rate-limit buckets — ~20 MB per 10k active IPs).\n\nSections:\n1. Sizing table (5 rows: ≤10 GB / ≤50 GB / ≤200 GB / ≤1 TB / ≤5 TB).\n2. Task-store memory accounting (the §14.7 paragraph).\n3. Worked example: pick one row and walk through the math to validate against §14.2.\n4. \"When to escalate\" — pointer to §14.10 vertical-scaling escape valve.\n\n## Why\n\nOperators need a sizing reference when provisioning. Without a focused doc, the matrix is buried at line 3593 of `plan.md` and the Redis memory implications are easy to miss until OOMs hit. This is THE artifact users will need on day one.\n\n## Acceptance\n\n- [ ] `docs/horizontal-scaling/sizing.md` reproduces the §14.7 table\n- [ ] Includes the Redis memory accounting paragraph\n- [ ] Worked example for one row (math should match §14.2 budget)\n- [ ] Linked from README.md \"Production deployment\" subsection\n- [ ] Linked from `docs/onboarding/production.md` (companion to bead `miroir-uyx.4`)\n\nParent epic: `miroir-m9q` (Phase 6 — Horizontal Scaling).","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-charlie","created_at":"2026-05-10T02:33:56.025437576Z","updated_at":"2026-05-20T10:51:24.420719567Z","closed_at":"2026-05-20T10:51:24.420719567Z","close_reason":"All acceptance criteria verified — the deployment sizing guide was already complete.\n\n## Retrospective\n- **What worked:** The sizing.md document already contained all required content from plan §14.7: the 5-row corpus/QPS matrix, Redis memory accounting (~20 MB per 10k active IPs for rate-limit buckets), a worked example for the ≤200 GB tier with memory budget and QPS validation, and escalation guidance.\n- **What didn't:** N/A — content was already in place.\n- **Surprise:** The bead appears to have been completed in a prior session; all links from README.md and production.md were already in place.\n- **Reusable pattern:** For plan-to-doc migrations, verify existing content before authoring — several beads may have been completed in batch during earlier work sessions.","source_repo":".","compaction_level":0,"labels":["phase-6"]} {"id":"miroir-46p","title":"Phase 10 — Security + Secrets (§9)","description":"## Phase 10 Epic — Security + Secrets\n\nShips the plan §9 secret-handling contract: inventory, Model B key separation, zero-downtime rotations, JWT dual-secret overlap, CSRF posture, `miroir-ctl` credential loading. Integrates with ESO + OpenBao on the cluster.\n\n## Why A Separate Phase\n\nSecrets-related code lives inside Phase 2 (auth handlers), Phase 5 (JWT, scoped keys), Phase 6 (Redis password), Phase 8 (K8s Secret templates). But the *policies* — key relationships, rotation procedures, CSRF rules — have to be owned in one place because they cross-cut every layer. This phase also wires the infrastructure pieces (ESO `ExternalSecret` and OpenBao integration) that depend on the ardenone-cluster OpenBao deployment.\n\n## Scope (plan §9)\n\n**Secret inventory — 9 entries**\n- `master_key` (client-facing)\n- `node_master_key` (Miroir → Meilisearch admin-scoped key)\n- `meilisearch_master_key` (per-node startup master key — fixed at process start)\n- `admin_api_key` (operators + miroir-ctl)\n- `ADMIN_SESSION_SEAL_KEY` (64-byte; seals Admin UI cookies via HMAC-SHA256 + XChaCha20-Poly1305; must be shared across multi-pod)\n- `SEARCH_UI_JWT_SECRET` (signs end-user JWTs; plus `SEARCH_UI_JWT_SECRET_PREVIOUS` during rotation)\n- `search_ui_shared_key` (only when `search_ui.auth.mode: shared_key`)\n- `ghcr_credentials` (Kaniko push)\n- `github_token` (gh CLI for Releases)\n- `redis_password` (optional)\n\n**Key relationship models**\n- Model A — shared master everywhere (dev/simple)\n- Model B — separated: clients use `master_key`; Miroir re-signs to `node_master_key` (recommended prod)\n\n**Rotations (zero-downtime where possible)**\n- `nodeMasterKey` (admin-scoped child of Meilisearch startup master): `POST /keys` new → update Secret → rolling restart → `DELETE /keys/{old_uid}`\n- Startup `MEILI_MASTER_KEY` is **not** zero-downtime (fixed at process start) — documented separately\n- `SEARCH_UI_JWT_SECRET` dual-secret overlap: primary + `_PREVIOUS`; 5-step rotation; recommended quarterly, on-leak-immediately shorten overlap; optional CronJob driving `miroir-ctl ui rotate-jwt-secret`\n- Search UI scoped Meilisearch key rotation (§13.21) — leader-coordinated with Redis hash, per-pod observation beacon, 120s drain before revocation\n\n**CSRF posture**\n- Admin UI: secure, HttpOnly, SameSite=Strict cookies; `X-CSRF-Token` double-submit on state-changing requests\n- Bearer tokens and `X-Admin-Key` bypass CSRF (can't be set by cross-origin HTML)\n- Origin checks: `admin_ui.allowed_origins` (default same-origin), `search_ui.allowed_origins`\n- SPA static GETs are CSRF-free\n\n**K8s Secret templates** (plan §9) — `miroir-secrets`, `meilisearch-secrets`, separate as needed\n\n**ESO ExternalSecret** (plan §6) — pulls from `kv/search/miroir` in OpenBao via `openbao-backend` ClusterSecretStore\n\n**miroir-ctl credential loading**\n- Priority: `MIROIR_ADMIN_API_KEY` env → `~/.config/miroir/credentials` TOML → `--admin-key` flag (flagged as script-unsafe)\n\n**Not handled (documented explicitly)** — tenant JWT tokens (forwarded to nodes as-is), per-index key scoping (forwarded unchanged), key creation API (broadcast)\n\n## Definition of Done\n\n- [ ] Every secret in the inventory has a Helm `values.yaml` hook + ESO `ExternalSecret` path or documented manual-only exception\n- [ ] Node-key rotation rehearsed end-to-end on a staging cluster within a single maintenance window without client impact\n- [ ] JWT rotation CronJob shipped with the chart at `suspend: true`; `miroir-ctl ui rotate-jwt-secret` sequences all 5 steps\n- [ ] Scoped-key rotation drain-and-revoke sequence tested against a 3-pod deployment with artificial pod-loss mid-rotation\n- [ ] Admin UI login → logout → revoked-cookie replay returns 401 across every pod (propagated via `miroir:admin_session:revoked` Pub/Sub)\n- [ ] CSP + CORS templates rejected when `csp_overrides.*` contains a wildcard that is not additive\n- [ ] OpenBao store policy scoped to least-privilege for the miroir role","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"epic","created_at":"2026-04-18T21:22:54.369068759Z","created_by":"coding","updated_at":"2026-04-18T21:23:08.741473517Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase","phase-10"],"dependencies":[{"issue_id":"miroir-46p","depends_on_id":"miroir-qjt","type":"blocks","created_at":"2026-04-18T21:23:08.741446229Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-46p.1","title":"P10.1 Secret inventory + ESO ExternalSecret wiring","description":"## What\n\nDocument + wire the plan §9 secret inventory (9 entries):\n\n| Secret | Consumer | Rotation |\n|--------|----------|----------|\n| `master_key` | Miroir proxy | manual/infrequent |\n| `node_master_key` | Miroir → Meilisearch | admin-scoped child key rotation flow (P10.2) |\n| `meilisearch_master_key` | Meilisearch startup | planned-maintenance (process restart) |\n| `admin_api_key` | Operators, `miroir-ctl` | rotate alongside `ADMIN_SESSION_SEAL_KEY` |\n| `ADMIN_SESSION_SEAL_KEY` | Miroir proxy | P10.4 |\n| `SEARCH_UI_JWT_SECRET` | Miroir proxy | P10.3 dual-secret overlap |\n| `search_ui_shared_key` | Miroir + host apps | only in `shared_key` mode |\n| `ghcr_credentials` | Kaniko (iad-ci) | infrastructure; not in scope for Miroir |\n| `github_token` | gh CLI (iad-ci) | infrastructure; not in scope |\n| `redis_password` | Miroir proxy | optional |\n\nShip `examples/eso-external-secret.yaml` (plan §6) pointing at the `openbao-backend` ClusterSecretStore.\n\n## Why\n\nPlan §1 principle 6 + §9: \"All secrets are read from environment variables in production — never baked into config files or images.\" The inventory makes it explicit what each secret does and how often to rotate; ESO wiring means secrets deploy declaratively with the rest of the stack.\n\n## Details\n\n**ESO keys layout** in OpenBao at `kv/search/miroir`:\n```\nmaster_key\nnode_master_key\nadmin_api_key\nadmin_session_seal_key\nsearch_ui_jwt_secret\nsearch_ui_jwt_secret_previous # only during rotation\nsearch_ui_shared_key # only in shared_key mode\nredis_password # only if redis_auth_enabled\n```\n\n**Startup env loading**: `miroir-proxy` reads each env var exactly once at startup. A missing critical secret (`SEARCH_UI_JWT_SECRET` when `search_ui.enabled: true`) must refuse to start with a clear error (plan §9 \"orchestrator refuses to start the search UI without it\").\n\n**Not handled in Miroir** (plan §9):\n- Tenant JWT tokens — forwarded to nodes as-is\n- Per-index API key scoping — forwarded unchanged\n- Key creation API — broadcast; requires all nodes available\n\n## Acceptance\n\n- [ ] ESO ExternalSecret deploys cleanly against ardenone-cluster's OpenBao\n- [ ] Missing `SEARCH_UI_JWT_SECRET` with `search_ui.enabled: true` → refuse-to-start with explicit error\n- [ ] `examples/eso-external-secret.yaml` documents every key in the inventory","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:47:21.194386656Z","created_by":"coding","updated_at":"2026-04-18T21:47:21.194386656Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-10"],"dependencies":[{"issue_id":"miroir-46p.1","depends_on_id":"miroir-46p","type":"parent-child","created_at":"2026-04-18T21:47:21.194386656Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-46p.2","title":"P10.2 node_master_key zero-downtime rotation flow","description":"## What\n\nImplement the plan §9 \"Rotation flow for the admin-scoped `nodeMasterKey` (zero-downtime)\":\n1. On each Meilisearch node, generate a new admin-scoped key via `POST /keys` (actions `[\"*\"]`, indexes `[\"*\"]`, optional expiration). Old + new coexist.\n2. Update ESO source / K8s Secret `miroir-secrets.nodeMasterKey` with the new key value.\n3. Rolling-restart Miroir pods so each pod picks up the new key. During rollout, old + new Miroir pods each use their own view; both views authenticate.\n4. Once all Miroir pods on new key, `DELETE /keys/{old_key_uid}` on every node.\n\n## Why\n\nPlan §9 is explicit: Meilisearch CE has **one startup master key** per process, fixed for the life of the process. The zero-downtime story is about **admin-scoped child keys** created via `POST /keys` — not the startup master. Clarifying this is the #1 source of confusion.\n\n## Details\n\n**Terminology clarification** (plan §9):\n- `MEILI_MASTER_KEY` (startup env var) — fixed at process start. Rotation REQUIRES process restart.\n- Admin-scoped child keys (via `POST /keys` with `actions: [\"*\"]`) — multiple can exist simultaneously. Rotation is zero-downtime.\n\nThe \"`nodeMasterKey`\" in Miroir config is actually the second kind.\n\n**CLI support**: `miroir-ctl key rotate-node-master` sequences the 4 steps above via admin API + ESO secret update (best-effort; operators may prefer manual steps when deploying via ArgoCD).\n\n**Startup master rotation** (NOT zero-downtime, plan §9): update K8s Secret → rolling restart each Meilisearch StatefulSet pod → recreate admin-scoped child keys against the new master → then run the zero-downtime flow to rotate `nodeMasterKey`.\n\n## Acceptance\n\n- [ ] On a staging cluster, execute the 4-step rotation end-to-end without client impact — measure with continuous write + search traffic\n- [ ] Mid-rotation a pod restart does NOT fail because one pod is on old key, another on new (both valid concurrently)\n- [ ] `miroir-ctl key rotate-node-master --dry-run` prints the plan without executing\n- [ ] Startup-master rotation documented as a separate runbook with a maintenance window","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:47:21.219222126Z","created_by":"coding","updated_at":"2026-04-18T21:47:25.331884519Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-10"],"dependencies":[{"issue_id":"miroir-46p.2","depends_on_id":"miroir-46p","type":"parent-child","created_at":"2026-04-18T21:47:21.219222126Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-46p.2","depends_on_id":"miroir-46p.1","type":"blocks","created_at":"2026-04-18T21:47:25.331865763Z","created_by":"coding","metadata":"{}","thread_id":""}]} @@ -50,14 +50,14 @@ {"id":"miroir-cdo.2","title":"P1.2 Topology type + node state machine","description":"## What\n\nImplement `miroir_core::topology`:\n```rust\npub struct Topology {\n pub shards: u32,\n pub replica_groups: u32,\n pub rf: usize,\n pub nodes: Vec,\n}\npub struct Node {\n pub id: NodeId,\n pub address: String,\n pub replica_group: u32,\n pub status: NodeStatus,\n}\npub enum NodeStatus { Healthy, Degraded, Draining, Failed, Joining, Active, Removed }\n```\n\nHelpers: `Topology::groups() -> impl Iterator`, `Topology::group(g: u32) -> &Group`, `group.nodes() -> &[Node]`, `group.healthy_nodes() -> Vec<&Node>`.\n\n## Why\n\nThe `Topology` type is what `router` operates on. State transitions correspond to plan §2 topology-change verbs: a node is `Joining` → `Active` after a group-add migration; `Draining` → `Removed` after a node-remove migration; `Failed` is for unplanned loss.\n\nThe state field matters for **routing-eligibility**: writes skip `Draining` for *affected* shards (plan §2 \"Removing a node\" step 1), but still deliver to it for shards it still owns. A bug where a `Draining` node stops receiving any writes prematurely would create durability gaps during rebalance.\n\n## State Transition Rules\n\n| From | To | Triggered by |\n|------|-----|-------------|\n| (new) | Joining | `POST /_miroir/nodes` (plan §4 admin API) |\n| Joining | Active | Migration complete (Phase 4) |\n| Active | Draining | `POST /_miroir/nodes/{id}/drain` |\n| Draining | Removed | Migration complete (Phase 4) |\n| Active/Draining | Failed | Health check detects (Phase 7) |\n| Failed | Active | Health check recovery + optional replication catch-up |\n| Active/Failed | Degraded | Partial health (timeouts, not full disconnect) |\n| Degraded | Active | Health restored |\n\n## Acceptance\n\n- [ ] Topology deserializes from plan §4 YAML example (RG=2, 6 nodes, RF=1) into the expected shape\n- [ ] `groups()` iterator returns `RG` groups in ascending order; each group holds exactly its configured nodes\n- [ ] State-machine unit tests cover every legal transition and reject illegal ones (e.g., Joining → Draining)\n- [ ] `Node::is_write_eligible_for(shard_id, status)` correctness table has a test per row","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":0,"issue_type":"task","created_at":"2026-04-18T21:26:11.777790379Z","created_by":"coding","updated_at":"2026-05-13T22:55:51.098960288Z","closed_at":"2026-05-13T22:55:51.098960288Z","close_reason":"P1.2 Topology type + node state machine - Implementation complete\n\n## Retrospective\n- **What worked:** The topology implementation was already complete from previous Phase 1 work. All 41 tests pass, covering state transitions, write eligibility, YAML deserialization, and structural requirements.\n- **What didn't:** N/A - Implementation was complete and verified successfully.\n- **Surprise:** The YAML deserialization test already existed (commit 7aabf62), making this verification task straightforward.\n- **Reusable pattern:** For state machine implementations, separate validation logic (can_transition_to()) from mutation (set_status()) to enable thorough testing without side effects.","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-1"]} {"id":"miroir-cdo.3","title":"P1.3 write_targets and covering_set","description":"## What\n\nImplement the two flat API calls used by the HTTP layer:\n```rust\npub fn write_targets(shard_id: u32, topology: &Topology) -> Vec\npub fn query_group(query_seq: u64, replica_groups: u32) -> u32\npub fn covering_set(shard_count: u32, group: &Group, rf: usize, query_seq: u64) -> Vec\n```\n\n## Why / Semantics (plan §2)\n\n**`write_targets`** — flat union of `assign_shard_in_group(shard, g)` across all `RG` groups. Returns `RG × RF` nodes total (may include duplicates across groups if a node_id coincidentally has the highest score in multiple groups — use a dedup pass in the HTTP layer when grouping docs per-request rather than dedup here, so the routing layer's behavior is pure).\n\n**`query_group`** — round-robin per the plan's note: \"`query_sequence_number` is a per-pod counter, not a cluster-wide one.\" Under HPA, cluster-wide balance relies on the K8s Service's round-robin / random kube-proxy policy (§14.4 link).\n\n**`covering_set`** — one node per shard within a group. The intra-group replica selection within each shard rotates by `query_seq % rf` (plan §4 code sample). The returned set is **deduplicated** because one node may own multiple shards in the same group; searching it once captures all its shards (Meilisearch searches all its local docs in a single call).\n\n## Critical Invariant\n\nTwo different Miroir pods, given identical `Topology` + `rf` + `shard_count`, **must** compute the same `write_targets` for any given `shard_id` and the same `covering_set` modulo `query_seq` rotation. This is the property that makes the request path stateless (plan §14.4).\n\n## Acceptance (plan §8)\n\n- [ ] `write_targets` returns exactly `RG × RF` nodes (counting duplicates)\n- [ ] `write_targets` assigns one-per-group: the subset of returned nodes in group g is exactly `assign_shard_in_group(shard, group_g_nodes)`\n- [ ] `covering_set` has `|covering_set| ≤ Ng` and covers all `shard_count` shards within the chosen group\n- [ ] Two instances of `Topology` with identical content produce identical `covering_set` outputs for the same `query_seq`\n- [ ] `query_group` distribution: 10K `query_seq` values `% RG` produce uniformly distributed group choices (chi-square pass)","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":0,"issue_type":"task","created_at":"2026-04-18T21:26:11.798428290Z","created_by":"coding","updated_at":"2026-05-13T23:11:21.452413438Z","closed_at":"2026-05-13T23:11:21.452413438Z","close_reason":"Completed","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-1"],"dependencies":[{"issue_id":"miroir-cdo.3","depends_on_id":"miroir-cdo.1","type":"blocks","created_at":"2026-04-18T21:26:21.555076342Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-cdo.3","depends_on_id":"miroir-cdo.2","type":"blocks","created_at":"2026-04-18T21:26:21.576939978Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-cdo.4","title":"P1.4 Result merger (global sort + offset/limit + facets + stripping)","description":"## What\n\nImplement `miroir_core::merger`:\n```rust\npub struct MergeInput {\n pub shard_hits: Vec, // one per node in covering set\n pub offset: usize,\n pub limit: usize,\n pub client_requested_score: bool,\n pub facets: Option>,\n}\npub fn merge(input: MergeInput) -> MergedSearchResult\n```\n\n## Why\n\nPlan §2 read path step 6 enumerates the exact sequence:\n1. Collect all hits with scores\n2. Sort globally descending by `_rankingScore`\n3. Apply `offset + limit` **after** merge (not per-shard)\n4. Strip `_rankingScore` from each hit if client did not request it\n5. **Always** strip `_miroir_shard` (and other reserved `_miroir_*` fields)\n6. Sum facet counts across shards\n7. Sum `estimatedTotalHits` across shards\n8. `processingTimeMs` = max across covering set\n\nThis must be a pure function — testable without a network — because it will be hit constantly and any non-determinism (e.g., HashMap iteration order affecting facet key ordering) breaks the compatibility suite.\n\n## Design Notes\n\n- Use a binary min-heap of size `offset + limit` to avoid keeping all hits in RAM when fan-out is large\n- Facet merging: `BTreeMap>` (ordered) for stable serialization\n- `estimatedTotalHits` clamp: Meilisearch caps at 1000 per shard by default — confirm whether Miroir should pass through the cap or sum and let the client see a higher number (consistent with Meilisearch single-node behavior: pass through)\n- Tie-breaking: on equal `_rankingScore`, fall back to lexicographic `primary_key` for deterministic ordering\n\n## Score Comparability Caveat (plan §2 read path, §13.5)\n\nScores are comparable across shards **only if** all nodes have identical index settings — enforced by the §13.5 two-phase broadcast. Until Phase 5 lands, assume settings are uniform and flag a warning in `Config::validate` if drift is detected.\n\n## Acceptance (plan §8 \"Result merger\")\n\n- [ ] Global sort by `_rankingScore` descending across shards\n- [ ] `offset + limit` applied **after** merge; test: 50 docs with known scores, pages of 10 reconstruct single limit=50\n- [ ] `_rankingScore` stripped when `client_requested_score=false`\n- [ ] `_miroir_shard` always stripped\n- [ ] Facet counts sum correctly including keys unique to one shard\n- [ ] `estimatedTotalHits` summed across shards\n- [ ] Stable serialization: `merge` on the same input twice produces byte-identical JSON","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":0,"issue_type":"task","assignee":"claude-code-glm-5-1-foxtrot","created_at":"2026-04-18T21:26:11.829984535Z","created_by":"coding","updated_at":"2026-05-15T12:51:59.820076883Z","closed_at":"2026-05-15T12:51:59.820076883Z","close_reason":"Completed","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-1"]} -{"id":"miroir-cdo.5","title":"P1.5 scatter module: covering-set construction + dispatch trait","description":"## What\n\nImplement `miroir_core::scatter` with:\n```rust\npub trait NodeClient { /* HTTP calls to a Meilisearch node */ }\npub fn plan_search_scatter(topology: &Topology, query_seq: u64, rf: usize, shard_count: u32) -> ScatterPlan\npub async fn execute_scatter(plan: ScatterPlan, client: &C, req: SearchRequest) -> Vec\n```\n\n## Why\n\n`NodeClient` is the seam between `miroir-core` (pure, no network) and `miroir-proxy` (HTTP client). Injecting it via a trait means unit tests can provide a fake client; production binds `reqwest` via the trait impl in `miroir-proxy`.\n\n`plan_search_scatter` returns the exact shard→node mapping that Phase 2 hands to `execute_scatter`. Separating the plan from execution is what makes §13.20 `/explain` cheap — the explain path generates the plan and returns it without touching any node.\n\n## Plan Structure\n\n```rust\npub struct ScatterPlan {\n pub chosen_group: u32, // query_seq % RG\n pub target_shards: Vec, // for §13.4 narrowing — initially all 0..S\n pub shard_to_node: HashMap, // resolved covering set\n pub deadline_ms: u32,\n pub hedging_eligible: bool, // reserved for §13.2 Phase 5\n}\n```\n\n## Acceptance\n\n- [ ] Plan construction is pure — no async, no I/O\n- [ ] `execute_scatter` with a mock `NodeClient` returns one `ShardHitPage` per node in the plan\n- [ ] Partial-failure handling: a failed node surfaces as `Err` on that shard; `merge` downstream applies `unavailable_shard_policy`\n- [ ] Deadline propagation: when any node exceeds `deadline_ms`, the result includes a partial-response flag","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-delta","created_at":"2026-04-18T21:26:11.849030740Z","created_by":"coding","updated_at":"2026-05-20T02:51:38.710351099Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-1"],"dependencies":[{"issue_id":"miroir-cdo.5","depends_on_id":"miroir-cdo.3","type":"blocks","created_at":"2026-04-18T21:26:21.594739255Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-cdo.6","title":"P1.6 Property + benchmark tests for router (criterion + proptest)","description":"## What\n\n- `proptest`-based property tests for rendezvous: determinism, minimal reshuffling bounds, uniformity at various (S, Ng, RF) sizes\n- `criterion` benchmarks targeting the plan §8 goals:\n - Rendezvous assignment (64 shards, 3 nodes, 10K docs) < 1 ms total\n - Merger (1000 hits, 3 shards) < 1 ms\n\n## Why\n\nPlan §8 sets both as gates (\"A PR that increases measured search latency by > 20% over the previous release triggers a review comment\"). Having them live from Phase 1 means regression prevention starts with the first router change.\n\n## Details\n\n- Benches go in `crates/miroir-core/benches/`\n- Property tests go in `crates/miroir-core/tests/` or as `#[cfg(test)]` modules with `proptest!` macros\n- Use a `HashSet` diff to measure reshuffling; assert `|diff| <= 2 * ceil(S / (N+1))` for a node-add event\n\n## Acceptance\n\n- [ ] `cargo bench -p miroir-core` runs all criterion benches and reports timing\n- [ ] `cargo test -p miroir-core` runs property tests with 1024 cases per property (default proptest config)\n- [ ] Phase 8 CI includes `cargo bench --no-run` to compile benches on every build","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-golf","created_at":"2026-04-18T21:26:11.875805587Z","created_by":"coding","updated_at":"2026-05-20T02:51:08.166582934Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-1"],"dependencies":[{"issue_id":"miroir-cdo.6","depends_on_id":"miroir-cdo.1","type":"blocks","created_at":"2026-04-18T21:26:21.615386498Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-cdo.6","depends_on_id":"miroir-cdo.4","type":"blocks","created_at":"2026-04-18T21:26:21.629878965Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-cdo.5","title":"P1.5 scatter module: covering-set construction + dispatch trait","description":"## What\n\nImplement `miroir_core::scatter` with:\n```rust\npub trait NodeClient { /* HTTP calls to a Meilisearch node */ }\npub fn plan_search_scatter(topology: &Topology, query_seq: u64, rf: usize, shard_count: u32) -> ScatterPlan\npub async fn execute_scatter(plan: ScatterPlan, client: &C, req: SearchRequest) -> Vec\n```\n\n## Why\n\n`NodeClient` is the seam between `miroir-core` (pure, no network) and `miroir-proxy` (HTTP client). Injecting it via a trait means unit tests can provide a fake client; production binds `reqwest` via the trait impl in `miroir-proxy`.\n\n`plan_search_scatter` returns the exact shard→node mapping that Phase 2 hands to `execute_scatter`. Separating the plan from execution is what makes §13.20 `/explain` cheap — the explain path generates the plan and returns it without touching any node.\n\n## Plan Structure\n\n```rust\npub struct ScatterPlan {\n pub chosen_group: u32, // query_seq % RG\n pub target_shards: Vec, // for §13.4 narrowing — initially all 0..S\n pub shard_to_node: HashMap, // resolved covering set\n pub deadline_ms: u32,\n pub hedging_eligible: bool, // reserved for §13.2 Phase 5\n}\n```\n\n## Acceptance\n\n- [ ] Plan construction is pure — no async, no I/O\n- [ ] `execute_scatter` with a mock `NodeClient` returns one `ShardHitPage` per node in the plan\n- [ ] Partial-failure handling: a failed node surfaces as `Err` on that shard; `merge` downstream applies `unavailable_shard_policy`\n- [ ] Deadline propagation: when any node exceeds `deadline_ms`, the result includes a partial-response flag","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-papa","created_at":"2026-04-18T21:26:11.849030740Z","created_by":"coding","updated_at":"2026-05-20T04:00:25.230434773Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-1"],"dependencies":[{"issue_id":"miroir-cdo.5","depends_on_id":"miroir-cdo.3","type":"blocks","created_at":"2026-04-18T21:26:21.594739255Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-cdo.6","title":"P1.6 Property + benchmark tests for router (criterion + proptest)","description":"## What\n\n- `proptest`-based property tests for rendezvous: determinism, minimal reshuffling bounds, uniformity at various (S, Ng, RF) sizes\n- `criterion` benchmarks targeting the plan §8 goals:\n - Rendezvous assignment (64 shards, 3 nodes, 10K docs) < 1 ms total\n - Merger (1000 hits, 3 shards) < 1 ms\n\n## Why\n\nPlan §8 sets both as gates (\"A PR that increases measured search latency by > 20% over the previous release triggers a review comment\"). Having them live from Phase 1 means regression prevention starts with the first router change.\n\n## Details\n\n- Benches go in `crates/miroir-core/benches/`\n- Property tests go in `crates/miroir-core/tests/` or as `#[cfg(test)]` modules with `proptest!` macros\n- Use a `HashSet` diff to measure reshuffling; assert `|diff| <= 2 * ceil(S / (N+1))` for a node-add event\n\n## Acceptance\n\n- [ ] `cargo bench -p miroir-core` runs all criterion benches and reports timing\n- [ ] `cargo test -p miroir-core` runs property tests with 1024 cases per property (default proptest config)\n- [ ] Phase 8 CI includes `cargo bench --no-run` to compile benches on every build","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-mike","created_at":"2026-04-18T21:26:11.875805587Z","created_by":"coding","updated_at":"2026-05-20T11:10:27.723657036Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-1"],"dependencies":[{"issue_id":"miroir-cdo.6","depends_on_id":"miroir-cdo.1","type":"blocks","created_at":"2026-04-18T21:26:21.615386498Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-cdo.6","depends_on_id":"miroir-cdo.4","type":"blocks","created_at":"2026-04-18T21:26:21.629878965Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-m9q","title":"Phase 6 — Horizontal Scaling + HPA (§14)","description":"## Phase 6 Epic — Horizontal Scaling + HPA\n\nDelivers the §14 promise: **fixed per-pod envelope (2 vCPU / 3.75 GB), scale out never up**. Makes the request path strictly stateless and partitions background work across pods via one of three coordination modes.\n\n## Why This Is A Phase\n\nPlan §1 principle 8 + plan §14 are the architectural spine. Phase 2's proxy already runs on one pod; this phase makes N pods coherent. Every §13 feature's \"Scaling mode\" column in plan §14.6 gets wired up here — Phase 5's implementations have to already understand they'll run inside one of the three modes.\n\n## Scope\n\n**14.1–14.3 — Per-pod envelope**\n- `resources.requests` = 500m / 1Gi; `resources.limits` = 2000m / 3584Mi\n- Per-feature memory row validated against plan §14.2 budget\n- CPU budget per plan §14.3 (~3 kQPS/pod small responses)\n\n**14.4 — Request path HPA**\n- `autoscaling/v2` HPA on CPU 70%, memory 75%, `miroir_requests_in_flight` as `type: Pods` `AverageValue: 500`, `miroir_background_queue_depth` as `type: External` `Value: 10` (plan §14.4 note on metric types)\n- `prometheus-adapter` as a chart prerequisite when HPA is enabled\n- `values.schema.json` rejects `hpa.enabled=true` without `replicas >= 2 AND taskStore.backend = redis`\n\n**14.5 — Background coordination modes**\n- **Mode A — Shard-partitioned ownership** (anti-entropy §13.8, settings-drift check §13.5, task registry pruner, TTL sweeper §13.14, canary runner §13.18)\n- **Mode B — Leader-only lease** (reshard coordinator §13.1, rebalancer Phase 4, alias flip serializer §13.7, two-phase settings broadcast §13.5, ILM evaluator §13.17, scoped-key rotation leader §13.21)\n- **Mode C — Work-queued chunked jobs** (streaming dump import §13.9, large reshard backfill §13.1)\n- **Peer discovery** via headless Service (`miroir-headless`) + Downward API `POD_NAME`/`POD_IP`, 15s SRV refresh\n- Rendezvous over peer set for Mode A; `SET NX EX 10` renewed every 3s for Mode B\n- Job lease heartbeat every 10s with 30s timeout for Mode C\n\n**14.6 — Per-feature scaling-mode wiring** — 21 rows, each must compile against the chosen mode\n\n**14.7 — Deployment sizing matrix** — ops documentation/tooling surfacing orchestrator pod count vs. corpus × QPS tiers\n\n**14.8 — Resource-aware defaults** — every config knob's default sized for the envelope\n\n**14.9 — Resource-pressure metrics + alerts** — `miroir_memory_pressure`, `miroir_cpu_throttled_seconds_total`, `miroir_request_queue_depth`, `miroir_background_queue_depth{job_type}`, `miroir_peer_pod_count`, `miroir_leader`, `miroir_owned_shards_count`; PrometheusRule alerts\n\n**14.10 — Vertical-scaling escape valve** — documented as supported but not recommended; no implementation work, just docs\n\n## Definition of Done\n\n- [ ] Multi-pod deployment (replicas=3) — every pod independently serves requests with identical routing\n- [ ] Kill one of three pods mid-traffic — zero client-visible errors beyond retry budget (plan §8 chaos)\n- [ ] Mode A test: spin up 3 pods, anti-entropy runs exactly once per shard per interval cluster-wide\n- [ ] Mode B test: start 3 pods, exactly one holds the reshard lease at any given instant; killing it promotes another within `lease_ttl_s`\n- [ ] Mode C test: submit a 10GB dump; chunks distribute across 3 pods and HPA reacts to `miroir_background_queue_depth`\n- [ ] All §14.2 memory rows fit within 3584 MiB under realistic steady-state load\n- [ ] All §14.9 alerts present in the PrometheusRule manifest and trip under induced fault","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"epic","created_at":"2026-04-18T21:21:13.549727274Z","created_by":"coding","updated_at":"2026-04-18T21:23:08.657411091Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase","phase-6"],"dependencies":[{"issue_id":"miroir-m9q","depends_on_id":"miroir-mkk","type":"blocks","created_at":"2026-04-18T21:23:08.657393466Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q","depends_on_id":"miroir-r3j","type":"blocks","created_at":"2026-04-18T21:23:08.646285774Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-m9q.1","title":"P6.1 Pod resource envelope + limits/requests","description":"## What\n\nImplement pod sizing per plan §14.1 + §14.2 + §14.8:\n- Helm `deployment.yaml` sets `resources.requests = {cpu: 500m, memory: 1Gi}`\n- `resources.limits = {cpu: 2000m, memory: 3584Mi}` (plan §14.8: \"leaves headroom under 3.75 GB node limit\")\n- Config defaults sized for the envelope (§14.8 full YAML)\n\n## Why\n\nPlan §1 principle 8: \"Fixed per-pod resource envelope (2 vCPU / 3.75 GB). When aggregate workload exceeds this envelope, scale **horizontally** by adding pods, never vertically beyond the envelope.\"\n\nWithout enforced limits, a runaway per-feature cache (e.g., session_pinning.max_sessions set unreasonably high) can push a pod into OOM-kill territory, inviting HPA to spin up replacements instead of surfacing the misconfiguration.\n\n## Details\n\n**Per-feature memory rows** (plan §14.2) each need their defaults:\n\n| Component | Budget | Knob |\n|-----------|--------|------|\n| Runtime + axum | 80 MB | — |\n| HTTP/2 pools | 50 MB | `connection_pool_per_node` |\n| Req/resp buffers | 200 MB | `server.max_body_bytes`, `max_concurrent_requests` |\n| Task registry | 100 MB | `task_registry.cache_size` |\n| Idempotency | 100 MB | `idempotency.max_cached_keys` |\n| Sessions | 50 MB | `session_pinning.max_sessions` |\n| Coalescing | 50 MB | `query_coalescing.max_subscribers` |\n| Router + EWMA | 20 MB | fixed |\n| Plan cache | 20 MB | fixed |\n| Alias table | 10 MB | fixed |\n| Metrics | 50 MB | fixed |\n| Dump import buffer | 128 MB | `dump_import.memory_buffer_bytes` (only during import) |\n| Anti-entropy | 128 MB | `anti_entropy.max_read_concurrency` (only during pass) |\n| Multi-search scratch | 5 MB | `multi_search.max_queries_per_batch` |\n| Vector over-fetch | 30 MB | `vector_search.over_fetch_factor` |\n| CDC buffer | 64 MB | `cdc.buffer.memory_bytes` |\n| TTL cursor | 5 MB | — |\n| Tenant map LRU | 20 MB | `tenant_affinity.mode` |\n| Shadow tee | ~50 MB | `shadow.targets[].sample_rate` |\n| Canary state | 20 MB | `canary_runner.run_history_per_canary` |\n| Admin UI assets | 10 MB | fixed |\n| Explain cache | 10 MB | fixed |\n| Search UI assets | 10 MB | fixed |\n| Search UI rate limiter | 20 MB (Redis-backed) | — |\n| Allocator overhead | 800 MB | — |\n| **Steady-state total** | **~1.2 GB** | |\n\n**Regression budget**: add a CI check (Phase 9) that flags when steady-state under synthetic load exceeds 1.7 GB.\n\n## Acceptance\n\n- [ ] Helm rendered manifest matches the requests/limits above\n- [ ] Idle pod < 300 MB RSS on a 3-node cluster\n- [ ] Steady-state (1 kQPS across 3 Miroir pods) under 1.2 GB per pod\n- [ ] One heavy background job (dump import) adds < 500 MB to that pod's total","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.562386308Z","created_by":"coding","updated_at":"2026-04-18T21:40:30.562386308Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.1","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.562386308Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-m9q.2","title":"P6.2 Peer discovery via headless Service + Downward API","description":"## What\n\nImplement peer discovery per plan §14.5:\n- Helm `miroir-headless.yaml` — a headless Service with label selector on the Deployment\n- Deployment: Downward API injects `POD_NAME` + `POD_IP` as env vars\n- Each pod refreshes peer set every `peer_discovery.refresh_interval_s` (default 15s) via SRV lookup against `miroir-headless..svc.cluster.local`\n- Peer set is `Vec` where `PeerId = POD_NAME` — used by rendezvous for Mode A ownership\n\n## Why\n\nPlan §14.5: \"All three modes rely on the current peer set.\" Mode A rendezvous partitions by peer × work-item; Mode B leader election picks one peer; Mode C claim lease is by peer. Without a peer set, we'd need either a central registry (new dependency) or K8s API calls (requires RBAC + API server load).\n\nSRV-based discovery is zero-config — if headless Service exists, it just works.\n\n## Details\n\n**Manifest** (plan §14.5 + §6):\n```yaml\napiVersion: v1\nkind: Service\nmetadata:\n name: miroir-headless\nspec:\n clusterIP: None\n selector:\n app.kubernetes.io/name: miroir\n ports: [...]\n```\n\n**Env injection** (plan §14.5 \"Peer discovery\"):\n```yaml\nenv:\n- name: POD_NAME\n valueFrom: { fieldRef: { fieldPath: metadata.name } }\n- name: POD_IP\n valueFrom: { fieldRef: { fieldPath: status.podIP } }\n```\n\n**Rust side**:\n```rust\npub struct PeerSet { pub peers: Vec, pub refreshed_at: Instant }\npub async fn refresh_peers(service: &str) -> PeerSet { /* SRV lookup */ }\n```\n\n**Transient double-work** is acceptable (plan §14.5): \"15-second discovery window is harmless: anti-entropy is idempotent, settings-repair is idempotent.\"\n\n## Acceptance\n\n- [ ] 3-pod deployment: each pod sees all 3 peer names within 30s of last pod ready\n- [ ] Scale 3→5: new peers discovered within `refresh_interval_s × 2`\n- [ ] Pod eviction: crashed pod drops from peer set within `refresh_interval_s × 2`\n- [ ] `miroir_peer_pod_count` gauge matches `kube_deployment_status_replicas_ready`","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.582753605Z","created_by":"coding","updated_at":"2026-04-18T21:40:30.582753605Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.2","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.582753605Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-m9q.3","title":"P6.3 Mode A: shard-partitioned ownership (anti-entropy, drift, TTL, canaries, pruner)","description":"## What\n\nImplement plan §14.5 Mode A rendezvous-partitioned ownership:\n```\nowns(shard_or_item, pod) = pod == top1_by_score(hash(item || pid) for pid in peer_set)\n```\n\nApplied to:\n- §13.8 anti-entropy reconciler — each pod fingerprints/repairs owned shards\n- §13.5 settings drift checker — each pod polls subset of (index, node) settings-hash pairs\n- Task registry pruner — each pod prunes tasks it owns by `top1_by_score(hash(miroir_id || pid))`\n- §13.14 TTL sweeper — each pod sweeps owned shards\n- §13.18 canary runner — each canary ID rendezvous-owned by one pod per interval\n\n## Why\n\nPlan §14.5: \"No explicit handoff — the new owner runs the next scheduled pass. Transient double-work during a 15-second discovery window is harmless.\" Mode A is naturally horizontal (work scales with peer count) and idempotent (safe during rescheduling).\n\n## Details\n\n**Ownership function** (reuses Phase 1 `score` with item:pod keys instead of shard:node):\n```rust\npub fn owns(item: &T, self_pod: &PeerId, peers: &[PeerId]) -> bool {\n peers.iter()\n .max_by_key(|pid| score_item_peer(item, pid))\n .map_or(false, |top| top == self_pod)\n}\n```\n\n**Scheduled runs**: each Mode A worker is a tokio task with a tick interval. On tick:\n1. Refresh peer set\n2. For each eligible item, check `owns(item, self)` and process if so\n3. Record progress per-item so rescheduling mid-run resumes cleanly\n\n**Phase 5 integration**: each §13.x subsection that declared \"Mode A\" in plan §14.6 calls into this layer rather than implementing its own peer-partitioning.\n\n## Acceptance\n\n- [ ] 3 pods running anti-entropy: each shard processed exactly once per interval cluster-wide\n- [ ] Kill one pod mid-pass: its shards reassigned to other peers within `refresh_interval_s × 2`; no shard processed by two pods simultaneously beyond the 15s window\n- [ ] Unit test: `owns()` returns true for exactly one peer per item across the peer set\n- [ ] Integration: induce divergence; Mode A anti-entropy converges across 3 pods with no double-repair","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.605342882Z","created_by":"coding","updated_at":"2026-04-18T21:40:36.034993157Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.3","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.605342882Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.3","depends_on_id":"miroir-m9q.2","type":"blocks","created_at":"2026-04-18T21:40:36.034974102Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-m9q.4","title":"P6.4 Mode B: leader-only singleton coordinator (reshard, rebalance, alias flip, 2PC, ILM, scoped-key rotation)","description":"## What\n\nImplement plan §14.5 Mode B leader-only lease:\n- SQLite: advisory lock row in `leader_lease` (plan §4) — the lease holder is recorded so recovery reads the last committed phase state\n- Redis: `SET NX EX 10` renewed every 3s\n- Leader-loss mid-operation: pause; new leader reads persisted phase state and resumes at the last committed phase boundary\n- All Mode B operations are designed to be **idempotent** and safe to resume at phase boundaries\n\nLease scopes (plan §14.6):\n- §13.1 reshard coordinator: `reshard:`\n- Phase 4 rebalancer: `rebalance:` (or global `rebalance`)\n- §13.7 alias flip serializer: `alias_flip:`\n- §13.5 two-phase settings broadcast: `settings_broadcast:`\n- §13.17 ILM evaluator: `ilm`\n- §13.21 scoped-key rotation: `search_ui_key_rotation:`\n\n## Why\n\nPlan §14.5: \"Leader loss mid-operation causes a pause; the new leader reads the persisted phase state from the task store and resumes from the last committed phase. All operations are idempotent by design and safe to resume at any phase boundary.\"\n\nWithout lease-based coordination, two pods could each run a reshard on the same index simultaneously → double shadow creation, conflicting alias flips, data corruption.\n\n## Details\n\n**Lease renewal**: every 3s (`leader_election.renew_interval_s`); TTL 10s (`leader_election.lease_ttl_s`). If renewal fails, leader gives up voluntarily to reduce split-brain.\n\n**Phase state persistence**: each Mode B operation persists enough state after each phase so resumption picks up where the dead leader left off:\n- Reshard: current phase ∈ {shadow, backfill, verify, swap, cleanup} + per-shard cursor\n- 2PC broadcast: current phase ∈ {propose, verify, commit} + per-node ACK list\n- ILM: per-policy next-check-time + in-flight rollover state\n\n**Config**:\n```yaml\nleader_election:\n enabled: true # auto-true when replicas > 1\n lease_ttl_s: 10\n renew_interval_s: 3\n```\n\n**SQLite substitute**: for single-pod dev, the `leader_lease` row is still written (so recovery can read the last committed phase state after a crash); lease semantics reduced to \"always-leader.\"\n\n**Metrics**: `miroir_leader` gauge (1 if this pod is leader, 0 otherwise).\n\n## Acceptance\n\n- [ ] 3 pods: exactly one is leader at any instant; killing it promotes another within `lease_ttl_s`\n- [ ] Kill the leader during reshard phase 3 (verify); new leader resumes at phase 3, not phase 1\n- [ ] Kill the leader during 2PC phase 2 (verify); new leader resumes verify without re-applying phase 1\n- [ ] `miroir_leader` sum across all pods is always 1 (or 0 transiently during failover)","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.638856024Z","created_by":"coding","updated_at":"2026-04-18T21:40:36.064313963Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.4","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.638856024Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.4","depends_on_id":"miroir-m9q.2","type":"blocks","created_at":"2026-04-18T21:40:36.064226657Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-m9q.5","title":"P6.5 Mode C: work-queued chunked jobs (dump import, reshard backfill)","description":"## What\n\nImplement plan §14.5 Mode C work-queued chunked jobs:\n- `jobs` table (Phase 3) with states `queued | in_progress | completed | failed`\n- Any pod can `claim_job(pod_id)` — atomic compare-and-swap `claimed_by IS NULL → claimed_by = pod_id`\n- Claim TTL: `claim_expires_at`, heartbeat every 10s, timeout 30s — pod loss → claim expires → another picks up\n- Large jobs **split into chunks** on input boundaries by the first pod that picks them up\n- Per-chunk progress persisted so crashed claims resume at last committed offset (idempotent via primary keys)\n\nApplied to:\n- §13.9 streaming dump import — chunks on NDJSON line boundaries, `chunk_size_bytes` default 256 MiB\n- §13.1 reshard backfill — partitions by shard-id range\n\n## Why\n\nPlan §14.5: \"Heavy streaming operations can exceed a single pod's envelope.\" A 500 GB dump is easily 10× a pod's memory budget — must chunk.\n\nPlan §14.4 HPA: `miroir_background_queue_depth` gauge → HPA scales out when backlog grows; scales back in when drained.\n\n## Details\n\n**Chunking**: first pod that picks up a large job inspects the input, computes split points, and re-enqueues per-chunk jobs. Original job transitions to `in_progress` with progress = \"splitting\" → \"delegated\" when chunks enqueued.\n\n**Claim heartbeat**: `UPDATE jobs SET claim_expires_at = now + 30s WHERE id = ? AND claimed_by = ?` — succeeds only if we still hold it. Pod crash → no heartbeat → next lease expiry releases claim.\n\n**Idempotent resume**: chunks record `{bytes_processed, docs_routed, last_cursor}`. A resumed chunk starts at `last_cursor` and re-writes docs (PK-idempotent at Meilisearch level → no dupes).\n\n**Queue depth metric**: `miroir:jobs:_queued` set; `SCARD miroir:jobs:_queued` = `miroir_background_queue_depth`. Fed to HPA as external metric per plan §14.4.\n\n**Config** tied to §13.9:\n```yaml\ndump_import:\n chunk_size_bytes: 268435456 # 256 MiB per §14.5 Mode C chunk-parallel coordinator\n```\n\n## Acceptance\n\n- [ ] 1 GB dump: first pod splits into 4× 256 MiB chunks; 3 pods claim 3 of 4 chunks in parallel; queue drains\n- [ ] Kill a claimant mid-chunk: claim expires in 30s; another pod picks up and resumes at `last_cursor`\n- [ ] HPA on `miroir_background_queue_depth > 10` triggers scale-up during the burst; scale-down once empty\n- [ ] Two concurrent dumps: chunks from both interleave in claims; neither starves","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.654570336Z","created_by":"coding","updated_at":"2026-04-18T21:40:36.099963727Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.5","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.654570336Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.5","depends_on_id":"miroir-m9q.2","type":"blocks","created_at":"2026-04-18T21:40:36.099899160Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-m9q.3","title":"P6.3 Mode A: shard-partitioned ownership (anti-entropy, drift, TTL, canaries, pruner)","description":"## What\n\nImplement plan §14.5 Mode A rendezvous-partitioned ownership:\n```\nowns(shard_or_item, pod) = pod == top1_by_score(hash(item || pid) for pid in peer_set)\n```\n\nApplied to:\n- §13.8 anti-entropy reconciler — each pod fingerprints/repairs owned shards\n- §13.5 settings drift checker — each pod polls subset of (index, node) settings-hash pairs\n- Task registry pruner — each pod prunes tasks it owns by `top1_by_score(hash(miroir_id || pid))`\n- §13.14 TTL sweeper — each pod sweeps owned shards\n- §13.18 canary runner — each canary ID rendezvous-owned by one pod per interval\n\n## Why\n\nPlan §14.5: \"No explicit handoff — the new owner runs the next scheduled pass. Transient double-work during a 15-second discovery window is harmless.\" Mode A is naturally horizontal (work scales with peer count) and idempotent (safe during rescheduling).\n\n## Details\n\n**Ownership function** (reuses Phase 1 `score` with item:pod keys instead of shard:node):\n```rust\npub fn owns(item: &T, self_pod: &PeerId, peers: &[PeerId]) -> bool {\n peers.iter()\n .max_by_key(|pid| score_item_peer(item, pid))\n .map_or(false, |top| top == self_pod)\n}\n```\n\n**Scheduled runs**: each Mode A worker is a tokio task with a tick interval. On tick:\n1. Refresh peer set\n2. For each eligible item, check `owns(item, self)` and process if so\n3. Record progress per-item so rescheduling mid-run resumes cleanly\n\n**Phase 5 integration**: each §13.x subsection that declared \"Mode A\" in plan §14.6 calls into this layer rather than implementing its own peer-partitioning.\n\n## Acceptance\n\n- [ ] 3 pods running anti-entropy: each shard processed exactly once per interval cluster-wide\n- [ ] Kill one pod mid-pass: its shards reassigned to other peers within `refresh_interval_s × 2`; no shard processed by two pods simultaneously beyond the 15s window\n- [ ] Unit test: `owns()` returns true for exactly one peer per item across the peer set\n- [ ] Integration: induce divergence; Mode A anti-entropy converges across 3 pods with no double-repair","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.605342882Z","created_by":"coding","updated_at":"2026-04-18T21:40:36.034993157Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.3","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.605342882Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.3","depends_on_id":"miroir-m9q.2","type":"blocks","created_at":"2026-04-18T21:40:36.034974102Z","created_by":"coding","metadata":"{}","thread_id":""}],"comments":[{"id":2,"issue_id":"miroir-m9q.3","author":"cli","text":"## Related documentation\n\n- [Per-Feature Scaling Behavior](https://github.com/jedarden/miroir/blob/main/docs/horizontal-scaling/per-feature.md) — Full mapping of all §13.x features to scaling modes (A/B/C/stateless)\n- [Plan §14.5](https://github.com/jedarden/miroir/blob/main/docs/plan/plan.md#145-horizontal-scaling-background-work) — Mode A/B/C implementation details\n","created_at":"2026-05-20T10:53:12.916846335Z"},{"id":5,"issue_id":"miroir-m9q.3","author":"cli","text":"Cross-reference: See [Per-Feature Scaling Behavior](https://github.com/jedarden/miroir/blob/main/docs/horizontal-scaling/per-feature.md) for the complete mapping of §13.x capabilities to scaling modes. This bead implements Mode A (shard-partitioned ownership) for anti-entropy, drift checking, TTL sweeper, and canary runner.","created_at":"2026-05-20T10:58:15.476718864Z"},{"id":8,"issue_id":"miroir-m9q.3","author":"cli","text":"Cross-reference: [Per-Feature Scaling Behavior](docs/horizontal-scaling/per-feature.md) documents the full mapping of all §13.x capabilities to their scaling modes (A/B/C/stateless/per-pod).","created_at":"2026-05-20T11:12:19.649912904Z"}]} +{"id":"miroir-m9q.4","title":"P6.4 Mode B: leader-only singleton coordinator (reshard, rebalance, alias flip, 2PC, ILM, scoped-key rotation)","description":"## What\n\nImplement plan §14.5 Mode B leader-only lease:\n- SQLite: advisory lock row in `leader_lease` (plan §4) — the lease holder is recorded so recovery reads the last committed phase state\n- Redis: `SET NX EX 10` renewed every 3s\n- Leader-loss mid-operation: pause; new leader reads persisted phase state and resumes at the last committed phase boundary\n- All Mode B operations are designed to be **idempotent** and safe to resume at phase boundaries\n\nLease scopes (plan §14.6):\n- §13.1 reshard coordinator: `reshard:`\n- Phase 4 rebalancer: `rebalance:` (or global `rebalance`)\n- §13.7 alias flip serializer: `alias_flip:`\n- §13.5 two-phase settings broadcast: `settings_broadcast:`\n- §13.17 ILM evaluator: `ilm`\n- §13.21 scoped-key rotation: `search_ui_key_rotation:`\n\n## Why\n\nPlan §14.5: \"Leader loss mid-operation causes a pause; the new leader reads the persisted phase state from the task store and resumes from the last committed phase. All operations are idempotent by design and safe to resume at any phase boundary.\"\n\nWithout lease-based coordination, two pods could each run a reshard on the same index simultaneously → double shadow creation, conflicting alias flips, data corruption.\n\n## Details\n\n**Lease renewal**: every 3s (`leader_election.renew_interval_s`); TTL 10s (`leader_election.lease_ttl_s`). If renewal fails, leader gives up voluntarily to reduce split-brain.\n\n**Phase state persistence**: each Mode B operation persists enough state after each phase so resumption picks up where the dead leader left off:\n- Reshard: current phase ∈ {shadow, backfill, verify, swap, cleanup} + per-shard cursor\n- 2PC broadcast: current phase ∈ {propose, verify, commit} + per-node ACK list\n- ILM: per-policy next-check-time + in-flight rollover state\n\n**Config**:\n```yaml\nleader_election:\n enabled: true # auto-true when replicas > 1\n lease_ttl_s: 10\n renew_interval_s: 3\n```\n\n**SQLite substitute**: for single-pod dev, the `leader_lease` row is still written (so recovery can read the last committed phase state after a crash); lease semantics reduced to \"always-leader.\"\n\n**Metrics**: `miroir_leader` gauge (1 if this pod is leader, 0 otherwise).\n\n## Acceptance\n\n- [ ] 3 pods: exactly one is leader at any instant; killing it promotes another within `lease_ttl_s`\n- [ ] Kill the leader during reshard phase 3 (verify); new leader resumes at phase 3, not phase 1\n- [ ] Kill the leader during 2PC phase 2 (verify); new leader resumes verify without re-applying phase 1\n- [ ] `miroir_leader` sum across all pods is always 1 (or 0 transiently during failover)","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.638856024Z","created_by":"coding","updated_at":"2026-04-18T21:40:36.064313963Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.4","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.638856024Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.4","depends_on_id":"miroir-m9q.2","type":"blocks","created_at":"2026-04-18T21:40:36.064226657Z","created_by":"coding","metadata":"{}","thread_id":""}],"comments":[{"id":3,"issue_id":"miroir-m9q.4","author":"cli","text":"## Related documentation\n\n- [Per-Feature Scaling Behavior](https://github.com/jedarden/miroir/blob/main/docs/horizontal-scaling/per-feature.md) — Full mapping of all §13.x features to scaling modes (A/B/C/stateless)\n- [Plan §14.5](https://github.com/jedarden/miroir/blob/main/docs/plan/plan.md#145-horizontal-scaling-background-work) — Mode A/B/C implementation details\n","created_at":"2026-05-20T10:53:12.939925852Z"},{"id":6,"issue_id":"miroir-m9q.4","author":"cli","text":"Cross-reference: See [Per-Feature Scaling Behavior](https://github.com/jedarden/miroir/blob/main/docs/horizontal-scaling/per-feature.md) for the complete mapping of §13.x capabilities to scaling modes. This bead implements Mode B (leader-only singleton coordinator) for reshard, rebalance, alias flip, 2PC, ILM, and scoped-key rotation.","created_at":"2026-05-20T10:58:15.503766257Z"},{"id":9,"issue_id":"miroir-m9q.4","author":"cli","text":"Cross-reference: [Per-Feature Scaling Behavior](docs/horizontal-scaling/per-feature.md) documents the full mapping of all §13.x capabilities to their scaling modes (A/B/C/stateless/per-pod).","created_at":"2026-05-20T11:12:19.668827583Z"}]} +{"id":"miroir-m9q.5","title":"P6.5 Mode C: work-queued chunked jobs (dump import, reshard backfill)","description":"## What\n\nImplement plan §14.5 Mode C work-queued chunked jobs:\n- `jobs` table (Phase 3) with states `queued | in_progress | completed | failed`\n- Any pod can `claim_job(pod_id)` — atomic compare-and-swap `claimed_by IS NULL → claimed_by = pod_id`\n- Claim TTL: `claim_expires_at`, heartbeat every 10s, timeout 30s — pod loss → claim expires → another picks up\n- Large jobs **split into chunks** on input boundaries by the first pod that picks them up\n- Per-chunk progress persisted so crashed claims resume at last committed offset (idempotent via primary keys)\n\nApplied to:\n- §13.9 streaming dump import — chunks on NDJSON line boundaries, `chunk_size_bytes` default 256 MiB\n- §13.1 reshard backfill — partitions by shard-id range\n\n## Why\n\nPlan §14.5: \"Heavy streaming operations can exceed a single pod's envelope.\" A 500 GB dump is easily 10× a pod's memory budget — must chunk.\n\nPlan §14.4 HPA: `miroir_background_queue_depth` gauge → HPA scales out when backlog grows; scales back in when drained.\n\n## Details\n\n**Chunking**: first pod that picks up a large job inspects the input, computes split points, and re-enqueues per-chunk jobs. Original job transitions to `in_progress` with progress = \"splitting\" → \"delegated\" when chunks enqueued.\n\n**Claim heartbeat**: `UPDATE jobs SET claim_expires_at = now + 30s WHERE id = ? AND claimed_by = ?` — succeeds only if we still hold it. Pod crash → no heartbeat → next lease expiry releases claim.\n\n**Idempotent resume**: chunks record `{bytes_processed, docs_routed, last_cursor}`. A resumed chunk starts at `last_cursor` and re-writes docs (PK-idempotent at Meilisearch level → no dupes).\n\n**Queue depth metric**: `miroir:jobs:_queued` set; `SCARD miroir:jobs:_queued` = `miroir_background_queue_depth`. Fed to HPA as external metric per plan §14.4.\n\n**Config** tied to §13.9:\n```yaml\ndump_import:\n chunk_size_bytes: 268435456 # 256 MiB per §14.5 Mode C chunk-parallel coordinator\n```\n\n## Acceptance\n\n- [ ] 1 GB dump: first pod splits into 4× 256 MiB chunks; 3 pods claim 3 of 4 chunks in parallel; queue drains\n- [ ] Kill a claimant mid-chunk: claim expires in 30s; another pod picks up and resumes at `last_cursor`\n- [ ] HPA on `miroir_background_queue_depth > 10` triggers scale-up during the burst; scale-down once empty\n- [ ] Two concurrent dumps: chunks from both interleave in claims; neither starves","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.654570336Z","created_by":"coding","updated_at":"2026-04-18T21:40:36.099963727Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.5","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.654570336Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.5","depends_on_id":"miroir-m9q.2","type":"blocks","created_at":"2026-04-18T21:40:36.099899160Z","created_by":"coding","metadata":"{}","thread_id":""}],"comments":[{"id":4,"issue_id":"miroir-m9q.5","author":"cli","text":"## Related documentation\n\n- [Per-Feature Scaling Behavior](https://github.com/jedarden/miroir/blob/main/docs/horizontal-scaling/per-feature.md) — Full mapping of all §13.x features to scaling modes (A/B/C/stateless)\n- [Plan §14.5](https://github.com/jedarden/miroir/blob/main/docs/plan/plan.md#145-horizontal-scaling-background-work) — Mode A/B/C implementation details\n","created_at":"2026-05-20T10:53:12.950953124Z"},{"id":7,"issue_id":"miroir-m9q.5","author":"cli","text":"Cross-reference: See [Per-Feature Scaling Behavior](https://github.com/jedarden/miroir/blob/main/docs/horizontal-scaling/per-feature.md) for the complete mapping of §13.x capabilities to scaling modes. This bead implements Mode C (work-queued chunked jobs) for dump import and reshard backfill.","created_at":"2026-05-20T10:58:15.518343138Z"},{"id":10,"issue_id":"miroir-m9q.5","author":"cli","text":"Cross-reference: [Per-Feature Scaling Behavior](docs/horizontal-scaling/per-feature.md) documents the full mapping of all §13.x capabilities to their scaling modes (A/B/C/stateless/per-pod).","created_at":"2026-05-20T11:12:19.680451775Z"}]} {"id":"miroir-m9q.6","title":"P6.6 HPA spec + prometheus-adapter + schema validation","description":"## What\n\nShip the HPA spec (plan §14.4):\n```yaml\napiVersion: autoscaling/v2\nkind: HorizontalPodAutoscaler\nspec:\n minReplicas: 2\n maxReplicas: 24\n behavior:\n scaleDown: { stabilizationWindowSeconds: 300 }\n scaleUp: { stabilizationWindowSeconds: 30 }\n metrics:\n - Resource cpu 70%\n - Resource memory 75%\n - Pods miroir_requests_in_flight AverageValue: 500\n - External miroir_background_queue_depth Value: 10\n```\n\nChart preconditions enforced via `values.schema.json`:\n- `hpa.enabled: true` requires `replicas >= 2 AND taskStore.backend: redis`\n- `prometheus-adapter` (or equivalent) as a documented prerequisite when HPA is enabled\n\n## Why\n\nPlan §14.4: \"`miroir_requests_in_flight` is **per-pod** and uses `type: Pods`. `miroir_background_queue_depth` is **global** and must use `type: External` with `type: Value`.\" Getting the metric type wrong produces a pathological HPA that monotonically scales to `maxReplicas`.\n\n## Details\n\n**Per-workload-tier min/max** (plan §14.7):\n| Peak QPS | minReplicas | maxReplicas |\n|---|---|---|\n| ≤ 500 | 2 | 3 |\n| ≤ 2k | 2 | 4 |\n| ≤ 5k | 4 | 8 |\n| ≤ 20k | 8 | 12 |\n| ≤ 100k | 12 | 24 |\n\nDefault values.yaml ships the ≤ 5k tier; operators override per workload.\n\n**prometheus-adapter config**: add a ConfigMap-defined `rules.externalMetrics` entry mapping `miroir_background_queue_depth` to the external metrics API. This is NOT shipped by the Miroir chart (operators install prometheus-adapter separately); the chart's `NOTES.txt` calls it out.\n\n**Stabilization windows**: scale-up fast (30s), scale-down slow (300s). Avoids pod flapping.\n\n## Acceptance\n\n- [ ] `helm lint --strict` with `hpa.enabled: true + replicas: 1` → fails with schema error\n- [ ] `helm lint --strict` with `hpa.enabled: true + replicas: 2 + backend: sqlite` → fails\n- [ ] HPA in a kind cluster: induce CPU load → scales up within 30s; load drops → scales down after 300s\n- [ ] External metric binding: `miroir_background_queue_depth` visible via `kubectl get --raw /apis/external.metrics.k8s.io/v1beta1/...`","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:40:30.676597441Z","created_by":"coding","updated_at":"2026-04-18T21:40:36.163090876Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.6","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.676597441Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.6","depends_on_id":"miroir-m9q.4","type":"blocks","created_at":"2026-04-18T21:40:36.140248526Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-m9q.6","depends_on_id":"miroir-m9q.5","type":"blocks","created_at":"2026-04-18T21:40:36.163063693Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-m9q.7","title":"P6.7 Resource-pressure metrics + alerts (§14.9)","description":"## What\n\nRegister the plan §14.9 resource-pressure metrics:\n- `miroir_memory_pressure` gauge (0=ok, 1=warn >75%, 2=critical >90%)\n- `miroir_cpu_throttled_seconds_total` counter (cgroup throttling)\n- `miroir_request_queue_depth` gauge\n- `miroir_background_queue_depth{job_type}` gauge\n- `miroir_peer_pod_count` gauge\n- `miroir_leader` gauge\n- `miroir_owned_shards_count` gauge\n\nAnd the associated `PrometheusRule` alerts (plan §14.9).\n\n## Why\n\nThese surface under-scaling BEFORE user-visible impact. `miroir_memory_pressure` + `MiroirMemoryPressure` alert give operators (and HPA) a leading indicator instead of waiting for OOM-kill.\n\n## Details\n\n**cgroup reads**: on Linux, read `/sys/fs/cgroup/cpu.stat` (cgroup v2) or `/sys/fs/cgroup/cpu/cpu.stat` (v1) for `nr_throttled`/`throttled_time`. Convert throttled_time nanoseconds → seconds for the counter.\n\n**Memory pressure gauge**: read `/sys/fs/cgroup/memory.current` + `memory.max`; compute utilization; map to 0/1/2 per threshold.\n\n**PrometheusRule**:\n```yaml\n- alert: MiroirMemoryPressure\n expr: miroir_memory_pressure >= 2\n for: 5m\n- alert: MiroirRequestQueueBacklog\n expr: miroir_request_queue_depth > 500\n for: 2m\n- alert: MiroirBackgroundJobBacklog\n expr: miroir_background_queue_depth > 100\n for: 10m\n- alert: MiroirPeerDiscoveryGap\n expr: miroir_peer_pod_count < kube_deployment_status_replicas_ready{deployment=\"miroir\"}\n for: 2m\n- alert: MiroirNoLeader\n expr: sum(miroir_leader) == 0\n for: 1m\n```\n\n## Acceptance\n\n- [ ] All 7 metrics present on `:9090/metrics`\n- [ ] `miroir_memory_pressure` reports 2 when artificial allocation pushes RSS > 90% of limit\n- [ ] `MiroirNoLeader` fires after killing the leader without replacement within 1 min\n- [ ] `MiroirPeerDiscoveryGap` fires if headless Service misconfigured","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-04-18T21:40:30.711963985Z","created_by":"coding","updated_at":"2026-04-18T21:40:30.711963985Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-6"],"dependencies":[{"issue_id":"miroir-m9q.7","depends_on_id":"miroir-m9q","type":"parent-child","created_at":"2026-04-18T21:40:30.711963985Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-mkk","title":"Phase 4 — Topology Operations (rebalance, add/remove node + group, drain)","description":"## Phase 4 Epic — Topology Operations\n\nMakes the cluster *elastic*: operators can add or remove nodes within a group (capacity scaling) or add/remove entire replica groups (throughput scaling) without a full reindex and without downtime.\n\n## Why This Matters\n\nPlan §2 \"Topology changes\" and §4 \"Rebalancer\" together are **the** operational differentiator. Without this phase, Miroir is a static sharder — useful but not production-grade. Elasticity is what justifies the complexity of the whole system.\n\nPlan §15 Open Problem 1 (dual-write race) is partially mitigated by careful sequencing here and fully closed by §13.8 anti-entropy in Phase 5. Getting the sequencing right here means Phase 5's reconciler is a safety net, not the primary correctness mechanism.\n\n## Scope\n\n**Node addition (within a group; plan §2 \"Adding a node\")**\n\n1. Assign new node to a group; mark `joining`\n2. Recompute assignments — ~S/(Ng+1) shards move\n3. Dual-write: new inbound writes for affected shards go to **both** old owner and new node\n4. Background migration per shard: `GET /indexes/{uid}/documents?filter=_miroir_shard={id}&limit=1000&offset=...` → write each page to new node\n5. Mark `active`; stop dual-write; `POST /indexes/{uid}/documents/delete` with `filter=_miroir_shard={id}` on old owner\n\n**Replica-group addition (plan §2 \"Adding a new replica group\")** — mark `initializing`, background-sync from any healthy group using the same `_miroir_shard` filter, then flip to `active` and start routing queries.\n\n**Node removal (plan §2 \"Removing a node\")** — mark `draining`, recompute, migrate ~RF/Ng fraction to survivors, mark `removed`, operator deletes PVC.\n\n**Group removal (plan §2 \"Removing a replica group\")** — mark `draining`, stop routing queries; no data migration (other groups hold the docs); decommission.\n\n**Unplanned node failure (plan §2 \"Node failure\")** — mark `failed`; surviving intra-group replicas cover if RF>1; cross-group fallback if RF=1; schedule background replication to restore RF.\n\n**Admin API** (plan §4 admin table) — `POST /_miroir/nodes`, `DELETE /_miroir/nodes/{id}`, `POST /_miroir/nodes/{id}/drain`, `POST /_miroir/rebalance`, `GET /_miroir/rebalance/status`.\n\n## Design Notes\n\n- Relies on `_miroir_shard` being `filterable` on every node — set by Phase 2 index-create broadcast\n- Only one rebalance at a time per index (advisory lock → Phase 6 Mode B leader lease)\n- Chunked migration bounded by `rebalancer.max_concurrent_migrations` (default 4) to stay under the per-pod 3.75 GB envelope\n- Migration progress reported via `GET /_miroir/rebalance/status` and `miroir_rebalance_*` metrics (§10)\n- No full-corpus scans ever — the `_miroir_shard` filter is the key primitive; any code path that enumerates \"all docs\" is a bug\n\n## Open Problem Closure\n\nPlan §15 #1 — dual-write cutover race: document the exact sequencing here and note that §13.8 anti-entropy is the guaranteed safety net on the next pass.\n\n## Definition of Done\n\n- [ ] Chaos test: add a node mid-indexing — every doc remains readable; no duplicates on a subsequent search\n- [ ] Chaos test: drain a node while queries are in flight — zero client-visible failures; `X-Miroir-Degraded` absent or transient only\n- [ ] Chaos test: add a replica group while queries are in flight — existing groups unaffected; new group starts serving reads only after sync completes\n- [ ] Rebalance of a 3→4 node cluster moves ≤ 2×(1/4) of docs (optimal per plan §8 benches)\n- [ ] Restart a killed node mid-rebalance — rebalance pauses + resumes; no data loss","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"epic","assignee":"","created_at":"2026-04-18T21:19:53.993012197Z","created_by":"coding","updated_at":"2026-05-09T16:11:31.984602638Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase","phase-4"],"dependencies":[{"issue_id":"miroir-mkk","depends_on_id":"miroir-9dj","type":"blocks","created_at":"2026-04-18T21:23:08.595905334Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-mkk","depends_on_id":"miroir-r3j","type":"blocks","created_at":"2026-04-18T21:23:08.609300009Z","created_by":"coding","metadata":"{}","thread_id":""}]} @@ -84,12 +84,12 @@ {"id":"miroir-qon.6","title":"P0.6 Repo hygiene: LICENSE, CHANGELOG skeleton, .gitignore, README stub","description":"## What\n\n- `LICENSE` — MIT, per plan §12\n- `CHANGELOG.md` — Keep a Changelog 1.1.0 format skeleton with `[Unreleased]` section\n- `.gitignore` — Rust (`target/`, `Cargo.lock` NOT ignored for binary crates), editor junk (`.vscode/`, `.idea/`)\n- `README.md` is already present — leave untouched for now; Phase 11 fills it in\n\n## Why\n\nPlan §12 explicitly requires MIT. Plan §7 \"CI release step extracts the relevant section automatically\" from CHANGELOG.md using an `awk` parser that expects `## []` section headers — the format must match from day 1 or the first release will fail.\n\n## Details\n\nSample CHANGELOG skeleton:\n```markdown\n# Changelog\n\nAll notable changes to this project will be documented in this file.\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/).\n\n## [Unreleased]\n\n### Added\n### Changed\n### Deprecated\n### Removed\n### Fixed\n### Security\n\n## [0.1.0] - TBD\n\n### Added\n- Initial release.\n```\n\n## Acceptance\n\n- [ ] `LICENSE` matches SPDX `MIT`\n- [ ] `awk \"/^## \\[0.1.0\\]/{found=1; next} found && /^## /{exit} found{print}\" CHANGELOG.md` (the extractor from plan §7) returns non-empty output for a tagged release\n- [ ] `.gitignore` keeps `target/` out and `Cargo.lock` in","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":1,"issue_type":"task","created_at":"2026-04-18T21:24:25.807632846Z","created_by":"coding","updated_at":"2026-05-09T06:13:58.567220654Z","closed_at":"2026-05-09T06:13:58.567220654Z","close_reason":"Repo hygiene complete - LICENSE (MIT), CHANGELOG.md (Keep a Changelog format), .gitignore (Rust + editor), Cargo.lock committed","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-0"],"dependencies":[{"issue_id":"miroir-qon.6","depends_on_id":"miroir-qon","type":"parent-child","created_at":"2026-04-18T21:24:25.807632846Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-qon.7","title":"P0.7 CI smoke: fmt/clippy/test on push","description":"## What\n\nStand up a minimal CI path — just enough to run `cargo fmt --check`, `cargo clippy -D warnings`, `cargo test --all` — on every push to `main`. This is the earliest viable version of the full `miroir-ci` Argo Workflow template that Phase 8 ships.\n\n## Why\n\nIf CI only lands in Phase 8, Phases 1–7 accumulate quietly-broken code. Plan §7 makes fmt/clippy/test the first three steps of the pipeline on purpose; shipping those now (on iad-ci via a minimal WorkflowTemplate) catches regressions on every commit.\n\n## Details\n\n- Create a stripped-down `miroir-ci-smoke` WorkflowTemplate in `jedarden/declarative-config → k8s/iad-ci/argo-workflows/` that runs only checkout + lint + test\n- Trigger on push to `main` (initially operators kick manually; webhook automation lands in Phase 8)\n- Image: `rust:1.87-slim` to match the full CI template\n- No musl target yet (that's Phase 8); just `cargo test --all`\n\n## Acceptance\n\n- [ ] Manual submit: `kubectl --kubeconfig=$HOME/.kube/iad-ci.kubeconfig create -f - << 1` + `taskStore.backend: sqlite`). Getting the Redis keyspace right now is cheaper than retrofitting.\n\n## Scope — the 14 tables and 14 Redis keyspaces (plan §4)\n\n1. `tasks` — Miroir task registry (miroir_id → node_tasks map + status)\n2. `node_settings_version` — per-(index, node) settings freshness (for §13.5 + `X-Miroir-Min-Settings-Version`)\n3. `aliases` — single-target + multi-target (`kind`, `current_uid`, `target_uids`, `version`, `history`)\n4. `sessions` — read-your-writes session pins (§13.6)\n5. `idempotency_cache` — write dedup (§13.10)\n6. `jobs` — work-queued background jobs (§14.5 Mode C)\n7. `leader_lease` — singleton-coordinator lease (§14.5 Mode B; SQLite advisory lock substitute for single-replica)\n8. `canaries` — canary definitions (§13.18)\n9. `canary_runs` — canary run history (§13.18)\n10. `cdc_cursors` — per-(sink, index) CDC cursor (§13.13)\n11. `tenant_map` — API-key → tenant mapping (§13.15 `api_key` mode)\n12. `rollover_policies` — ILM rollover policies (§13.17)\n13. `search_ui_config` — per-index search-UI config (§13.21)\n14. `admin_sessions` — Admin UI session registry (§13.19)\n\n## Redis keyspace mirror (plan §4 \"Redis mode (HA)\")\n\nEvery table above mapped to a hash + `_index` secondary set so list-wide queries are O(cardinality) without `SCAN`. Plus:\n\n- `miroir:ratelimit:searchui:` (EXPIRE `search_ui.rate_limit.redis_ttl_s`)\n- `miroir:ratelimit:adminlogin:` + `miroir:ratelimit:adminlogin:backoff:` (§13.19, required in HA)\n- `miroir:cdc:overflow:` (1 GiB per sink default)\n- `miroir:search_ui_scoped_key:` + `miroir:search_ui_scoped_key_observed::` (§13.21 rotation coordination)\n- `miroir:admin_session:revoked` Pub/Sub channel for instant logout propagation\n\n## Definition of Done\n\n- [ ] `rusqlite`-backed store initializing every table idempotently at startup\n- [ ] Redis-backed store mirrors the same API (trait `TaskStore` or equivalent), chosen at runtime by `task_store.backend`\n- [ ] Migrations/versioning: schema version recorded in a `schema_version` row so future upgrades detect incompatibility loudly\n- [ ] Property tests: `(insert, get)` round-trip + `(upsert, list)` semantics on SQLite backend\n- [ ] Integration test: restart an orchestrator pod mid-task-poll; task status survives (simulate by opening/closing the SQLite handle between operations)\n- [ ] Redis-backend integration test (`testcontainers` or similar) exercising leases, idempotency dedup, and alias history\n- [ ] `miroir:tasks:_index`-style iteration actually used for list endpoints (no `SCAN`)\n- [ ] `taskStore.backend: redis` + `replicas > 1` enforced by Helm `values.schema.json` (verified with `helm lint`)\n- [ ] Plan §14.7 Redis memory accounting validated against a representative load (bucket count × average size)","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":0,"issue_type":"epic","created_at":"2026-04-18T21:19:53.974489140Z","created_by":"coding","updated_at":"2026-05-09T09:45:40.771082696Z","closed_at":"2026-05-09T09:45:40.771082696Z","close_reason":"Phase 3 (miroir-r3j): Task Registry + Persistence — Complete\n\nSummary: Fixed 2 test failures in SQLite task store tests and added Helm schema validation tests. All 17 SQLite tests now pass.\n\nChanges Made:\n- Fixed leader_lease test: replaced hardcoded timestamps with chrono::Utc::now()\n- Fixed prop_task_list_filter_by_status: ensured unique task IDs\n- Added charts/miroir/tests/ with Python schema validation script and YAML test cases\n\nDefinition of Done — All Complete:\n1. rusqlite-backed store with 14 tables initialized idempotently\n2. Redis-backed store mirroring TaskStore trait\n3. Schema version tracking with mismatch detection\n4. Property tests on SQLite backend (17 tests passing)\n5. Integration test for pod restart simulation\n6. Redis-backend integration tests with testcontainers\n7. Redis _index sets for O(cardinality) list queries\n8. Helm schema enforcing redis + replicas > 1\n9. Redis memory accounting validated","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase","phase-3"],"dependencies":[{"issue_id":"miroir-r3j","depends_on_id":"miroir-qon","type":"blocks","created_at":"2026-04-18T21:23:08.581818683Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-r3j.1","title":"P3.1 TaskStore trait + SQLite backend (tables 1-7)","description":"## What\n\nDefine the `TaskStore` trait in `miroir-core` and implement the SQLite backend for the first 7 tables in plan §4 \"Task store schema\":\n\n1. `tasks` — Miroir task registry\n2. `node_settings_version`\n3. `aliases` (both single and multi-target)\n4. `sessions` (read-your-writes pins)\n5. `idempotency_cache`\n6. `jobs`\n7. `leader_lease`\n\n## Why Start Here\n\nThese are the always-present tables — needed even in single-pod dev mode. Tables 8–14 (canaries, cdc_cursors, tenant_map, rollover_policies, search_ui_config, admin_sessions) only instantiate when their respective feature flag is on, so they can land alongside the Phase 5 feature they serve.\n\nDefining the trait **in `miroir-core`** (not `miroir-proxy`) lets the crate be consumed by `miroir-ctl` for diagnostics without pulling in the proxy binary.\n\n## Details\n\nEach table's DDL is already in plan §4 (scroll to the table headers). The trait exposes per-table operations plus a generic `migrate(&self) -> Result<()>` that creates tables idempotently and records a `schema_version` row for upgrade detection.\n\n**Non-obvious**:\n- `tasks.node_tasks` is JSON — use a `serde_json::Value` column, not a stringly-typed hack\n- `aliases.history` is a JSON array bounded by `aliases.history_retention`; enforce bound on `UPDATE`\n- `idempotency_cache.body_sha256` is a `BLOB`, not TEXT — 32 raw bytes\n- `jobs.claim_expires_at` updated by heartbeat every 10s; pod loss → claim expires → another pod picks up\n- `leader_lease` for SQLite is an advisory-lock substitute (persist the row, interpret its presence semantically)\n\n**Idempotent migrations** — use `CREATE TABLE IF NOT EXISTS` + a `schema_versions` table that records each applied migration. Future migrations use `INSERT OR IGNORE` + explicit version gates.\n\n## Acceptance\n\n- [ ] `cargo test -p miroir-core task_store::sqlite` — every CRUD round-trips correctly\n- [ ] Opening an existing DB doesn't re-run migrations; schema version check is a single SELECT\n- [ ] Concurrent writes from two handles (single-process) don't deadlock (WAL mode enabled, `PRAGMA busy_timeout = 5000`)\n- [ ] Table sizes under realistic load fit within plan §14.2 \"Task registry cache 100 MB\" budget","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-november","created_at":"2026-04-18T21:30:07.264404312Z","created_by":"coding","updated_at":"2026-05-20T02:51:39.613584322Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.1","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.264404312Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-r3j.2","title":"P3.2 SQLite backend: remaining tables (canaries, cdc_cursors, tenant_map, rollover_policies, search_ui_config, admin_sessions)","description":"## What\n\nExtend the SQLite `TaskStore` with plan §4 tables 8–14:\n8. `canaries` (§13.18)\n9. `canary_runs` (§13.18) — bounded by `canary_runner.run_history_per_canary` (default 100); auto-prune on insert\n10. `cdc_cursors` (§13.13)\n11. `tenant_map` (§13.15 `api_key` mode only)\n12. `rollover_policies` (§13.17)\n13. `search_ui_config` (§13.21)\n14. `admin_sessions` (§13.19) — with `CREATE INDEX admin_sessions_expires ON admin_sessions(expires_at)` for lazy eviction\n\n## Why Separate from P3.1\n\nThese tables are **feature-flag-gated** — `canaries` only instantiates when `canary_runner.enabled`, etc. Keeping them in a separate task lets Phase 5 subsection beads own each table's lifecycle and prevents the ~14-table `CREATE TABLE IF NOT EXISTS` cascade from running for features that will never be used.\n\nThat said, the schema definition itself lives here so every Phase 5 feature can `use` the same typed row structs rather than redefining them ad-hoc.\n\n## Details\n\n**`canary_runs` auto-prune**: on each insert, `DELETE FROM canary_runs WHERE canary_id = ? AND ran_at < (SELECT MIN(ran_at) FROM (SELECT ran_at FROM canary_runs WHERE canary_id = ? ORDER BY ran_at DESC LIMIT N))`. Wrap in a trigger so application code never forgets.\n\n**`admin_sessions.expires_at` index** — plan §4 admin_sessions footnote: rows past expires_at evicted lazily on access AND by Mode A pruner (§14.5). The index makes the scan cheap.\n\n**`cdc_cursors` is a per-(sink, index) composite PK** — both columns must match for update-in-place.\n\n**`tenant_map.api_key_hash` is a 32-byte BLOB** — raw sha256 bytes; never store the plaintext API key.\n\n## Acceptance\n\n- [ ] Every table's typed struct round-trips `insert`/`get` in a unit test\n- [ ] `canary_runs` trigger keeps row count ≤ `run_history_per_canary`\n- [ ] Tables that remain empty when their feature is disabled consume < 16 KB each (SQLite overhead)\n- [ ] Tables are created only when `TaskStore::migrate` is called with the relevant feature flag set (so dev-mode single-pod with all features off creates just 7 tables)","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:30:07.286925769Z","created_by":"coding","updated_at":"2026-04-18T21:30:11.179830060Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.2","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.286925769Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.2","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.179800727Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-r3j.3","title":"P3.3 Redis backend: same trait, Redis keyspace per plan §4","description":"## What\n\nImplement the Redis-backed `TaskStore` mirroring every SQLite table to the keyspace layout in plan §4 \"Redis mode (HA)\":\n\n| SQLite | Redis |\n|--------|-------|\n| `tasks` row | `miroir:tasks:` hash + `miroir:tasks:_index` set |\n| `node_settings_version` | `miroir:node_settings_version::` hash + index set |\n| `aliases` | `miroir:aliases:` hash + index set |\n| `sessions` | `miroir:session:` hash with `EXPIRE session_pinning.ttl_seconds` |\n| `idempotency_cache` | `miroir:idemp:` hash with `EXPIRE idempotency.ttl_seconds` |\n| `jobs` | `miroir:jobs:` hash + `miroir:jobs:_queued` set (HPA signal) |\n| `leader_lease` | `miroir:lease:` string via `SET NX EX 10` renewed every 3s |\n| `canaries` | `miroir:canary:` hash + index set |\n| `canary_runs` | `miroir:canary_runs:` sorted set keyed by `ran_at`; `ZREMRANGEBYRANK` trim |\n| `cdc_cursors` | `miroir:cdc_cursor::` string (integer seq) |\n| `tenant_map` | `miroir:tenant_map:` hash |\n| `rollover_policies` | `miroir:rollover:` hash + index set |\n| `search_ui_config` | `miroir:search_ui_config:` hash |\n| `admin_sessions` | `miroir:admin_session:` hash with `EXPIRE session_ttl_s` + revoked bool |\n\nPlus the extras from plan §4 footnotes:\n- `miroir:search_ui_scoped_key:` hash (fields `primary_uid, previous_uid, rotated_at, generation`) — no TTL; long-lived\n- `miroir:search_ui_scoped_key_observed::` hash with 60s EXPIRE\n- `miroir:admin_session:revoked` Pub/Sub channel (logout invalidation)\n- `miroir:ratelimit:searchui:` with `EXPIRE search_ui.rate_limit.redis_ttl_s`\n- `miroir:ratelimit:adminlogin:` + `miroir:ratelimit:adminlogin:backoff:` (hash `{failed_count, next_allowed_at}`)\n- `miroir:cdc:overflow:` list (1 GiB cap via `cdc.buffer.redis_bytes`)\n\n## Why\n\nPlan §14.4: `replicas > 1` **requires** Redis. The trait-based abstraction means Phase 6 HPA just flips `task_store.backend: redis` via Helm values; no code change in feature layers.\n\n## Details\n\n**Secondary `_index` sets** are the key optimization: list-wide queries (e.g., `GET /_miroir/aliases`) iterate the set, not `SCAN`. Any `insert` must also `SADD` to the index; any `delete` must `SREM`.\n\n**Leader lease**: `SET NX EX 10`. Renewal is `SET XX EX 10` — only if we still hold it. Lease-loss mid-operation is plan §14.5 Mode B's recovery path.\n\n**EXPIRE on idempotency / session / admin_session / search_ui rate limit** — let Redis garbage-collect rather than running a Mode A pruner for each.\n\n**CDC overflow**: use `LPUSH` + `LTRIM` to bound list length; `LLEN` gives `miroir_cdc_buffer_bytes` (approximate).\n\n**Pipelining**: for the task fan-out mapping (one write → N node task IDs), use MULTI/EXEC to insert the tasks row + SADD the index set atomically.\n\n## Acceptance\n\n- [ ] testcontainers-based integration test: identical trait-level behavior to SQLite backend (run the shared CRUD suite against both)\n- [ ] Lease race: two pods `SET NX EX` simultaneously → exactly one wins\n- [ ] Memory budget: at 10k idempotency keys + 1k sessions + 100k tasks, Redis RSS stays under plan §14.7 accounting target\n- [ ] Pub/Sub: subscribe to `miroir:admin_session:revoked` and confirm logout on pod-A invalidates pod-B's in-memory cache within 100ms","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:30:07.307470462Z","created_by":"coding","updated_at":"2026-04-18T21:30:11.196023954Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.3","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.307470462Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.3","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.196004625Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-r3j.4","title":"P3.4 Migration + schema versioning","description":"## What\n\nImplement a first-class schema version system:\n- `schema_versions` table (SQLite) / `miroir:schema_version` key (Redis) recording the most recently applied migration\n- Each schema change gets a numbered migration (`001_initial.sql`, `002_add_foo.sql`, etc.)\n- Startup: read current version → apply all migrations with higher numbers → record latest\n- Refuse to start if DB version > binary version (e.g., operator rolled back to an older binary without rolling back the store)\n\n## Why\n\nPlan §12 commits to \"Config file schema: backward-compatible in minor versions (new fields always optional with defaults)\" and \"Task store schema requires migration notes (§7 release checklist).\" A versioning system forces that discipline from v0.1; shipping v1.0 with ad-hoc ALTER TABLE scatter is a nightmare to undo.\n\n## Details\n\n**Numbering**: monotonic `uXXX` where `u` is `000` to `999`; version history embedded in the binary via `include_str!` from a known directory.\n\n**Down-migration is optional** — we write migrations as one-way by default. For rollback, operators restore from backup rather than `downgrade 042→041`. Beads keep this door open; don't lock it shut.\n\n**Binary-vs-store version check**:\n- binary version = max migration number compiled into the binary\n- store version = max migration applied\n- start-up: if `binary < store`, refuse with a clear error. If `binary == store`, no-op. If `binary > store`, apply missing migrations.\n\n## Acceptance\n\n- [ ] First run creates the schema at version 001 (or whatever is the initial)\n- [ ] Second run is a no-op; migration scan is a single SELECT\n- [ ] Artificially set store version to binary+1 → startup fails with `schema_version_ahead` error\n- [ ] Both SQLite and Redis backends share the same migration metadata structure","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-04-18T21:30:07.338809736Z","created_by":"coding","updated_at":"2026-04-18T21:30:11.210532127Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.4","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.338809736Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.4","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.210512282Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-r3j.5","title":"P3.5 values.schema.json rejection: replicas>1 requires Redis","description":"## What\n\nAdd an entry to `charts/miroir/values.schema.json` that **fails `helm lint`** when `miroir.replicas > 1` and `taskStore.backend == \"sqlite\"`.\n\n## Why\n\nPlan §14.4: \"SQLite is single-writer and cannot be shared. The Helm chart enforces this: `taskStore.backend=sqlite` with `miroir.replicas > 1` fails values-schema validation.\" Without this guard, a developer who bumps `replicas: 2` in values.yaml and forgets to flip the backend gets silent task-store divergence across pods — every pod writes to its own SQLite in its own ephemeralVolume, mtask polls on pod-A can't see tasks enqueued on pod-B.\n\n## Details\n\nUse JSON Schema `if/then`:\n```jsonc\n{\n \"if\": { \"properties\": { \"miroir\": { \"properties\": { \"replicas\": { \"type\": \"integer\", \"exclusiveMinimum\": 1 } } } } },\n \"then\": { \"properties\": { \"taskStore\": { \"properties\": { \"backend\": { \"const\": \"redis\" } } } } }\n}\n```\n\nAdd `helm lint --strict` cases to Phase 9 test harness:\n- `replicas: 1, backend: sqlite` → lint passes\n- `replicas: 2, backend: sqlite` → lint fails with a clear error message\n- `replicas: 2, backend: redis` → lint passes\n\n## Acceptance\n\n- [ ] `helm lint --strict` on a values file with `replicas: 2 + backend: sqlite` fails with a message pointing at the constraint\n- [ ] The failure message is operator-readable (\"SQLite task store cannot run with multiple replicas; set taskStore.backend=redis\") — use `errorMessage` extension if available, else accept the default output\n- [ ] Test cases added to `charts/miroir/tests/` for future-proofing","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-india","created_at":"2026-04-18T21:30:07.373576976Z","created_by":"coding","updated_at":"2026-05-20T02:51:51.656912968Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.5","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.373576976Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-r3j.6","title":"P3.6 Task registry TTL pruner (in-memory for Phase 3; Mode A in Phase 6)","description":"## What\n\nImplement a background task that prunes `tasks` rows older than `task_registry.ttl_seconds` (default 7 days per plan §4). In Phase 3 this runs single-pod with an advisory lock; Phase 6 §14.5 Mode A replaces with rendezvous-partitioned ownership.\n\n## Why\n\nWithout TTL pruning, the task table grows unbounded. Plan §4 explicitly calls out the Mode A rendezvous pruner as the mechanism; shipping the simpler single-pod version here lets single-pod dev deployments not leak memory, and Phase 6 just swaps the ownership rule.\n\n## Details\n\n**Cadence**: run every `task_registry.prune_interval_s` (default 300s / 5 min).\n\n**Batch size**: max 10k rows per iteration so the background task never holds the DB long. SQLite: `DELETE FROM tasks WHERE created_at < ? LIMIT 10000`.\n\n**Preservation rule**: never prune a task whose `status` is `processing` (poll results might still be incoming). Plan this as \"age > TTL AND status IN (succeeded, failed, canceled)\".\n\n**Metrics**: `miroir_task_registry_size` (gauge) exposed per plan §10. The pruner updates it.\n\n## Acceptance\n\n- [ ] After insert of 10k terminal tasks with `created_at = now - 8d`, next pruner cycle drops all 10k\n- [ ] A single in-flight `processing` task at `created_at = now - 10d` is preserved\n- [ ] Pruner advisory lock prevents two instances pruning simultaneously (single-pod guarantee; Phase 6 replaces)\n- [ ] `miroir_task_registry_size` gauge drops after a prune cycle","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-04-18T21:30:07.405347149Z","created_by":"coding","updated_at":"2026-04-18T21:30:11.223295168Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.6","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.405347149Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.6","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.223268357Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-r3j.1","title":"P3.1 TaskStore trait + SQLite backend (tables 1-7)","description":"## What\n\nDefine the `TaskStore` trait in `miroir-core` and implement the SQLite backend for the first 7 tables in plan §4 \"Task store schema\":\n\n1. `tasks` — Miroir task registry\n2. `node_settings_version`\n3. `aliases` (both single and multi-target)\n4. `sessions` (read-your-writes pins)\n5. `idempotency_cache`\n6. `jobs`\n7. `leader_lease`\n\n## Why Start Here\n\nThese are the always-present tables — needed even in single-pod dev mode. Tables 8–14 (canaries, cdc_cursors, tenant_map, rollover_policies, search_ui_config, admin_sessions) only instantiate when their respective feature flag is on, so they can land alongside the Phase 5 feature they serve.\n\nDefining the trait **in `miroir-core`** (not `miroir-proxy`) lets the crate be consumed by `miroir-ctl` for diagnostics without pulling in the proxy binary.\n\n## Details\n\nEach table's DDL is already in plan §4 (scroll to the table headers). The trait exposes per-table operations plus a generic `migrate(&self) -> Result<()>` that creates tables idempotently and records a `schema_version` row for upgrade detection.\n\n**Non-obvious**:\n- `tasks.node_tasks` is JSON — use a `serde_json::Value` column, not a stringly-typed hack\n- `aliases.history` is a JSON array bounded by `aliases.history_retention`; enforce bound on `UPDATE`\n- `idempotency_cache.body_sha256` is a `BLOB`, not TEXT — 32 raw bytes\n- `jobs.claim_expires_at` updated by heartbeat every 10s; pod loss → claim expires → another pod picks up\n- `leader_lease` for SQLite is an advisory-lock substitute (persist the row, interpret its presence semantically)\n\n**Idempotent migrations** — use `CREATE TABLE IF NOT EXISTS` + a `schema_versions` table that records each applied migration. Future migrations use `INSERT OR IGNORE` + explicit version gates.\n\n## Acceptance\n\n- [ ] `cargo test -p miroir-core task_store::sqlite` — every CRUD round-trips correctly\n- [ ] Opening an existing DB doesn't re-run migrations; schema version check is a single SELECT\n- [ ] Concurrent writes from two handles (single-process) don't deadlock (WAL mode enabled, `PRAGMA busy_timeout = 5000`)\n- [ ] Table sizes under realistic load fit within plan §14.2 \"Task registry cache 100 MB\" budget","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-oscar","created_at":"2026-04-18T21:30:07.264404312Z","created_by":"coding","updated_at":"2026-05-20T10:45:26.623909146Z","closed_at":"2026-05-20T10:45:26.623909146Z","close_reason":"P3.1 TaskStore trait + SQLite backend (tables 1-7) - Verification complete.\n\nThe TaskStore trait and SQLite backend for tables 1-7 were already fully implemented in the codebase. Verified all 36 tests pass.\n\n## Retrospective\n- **What worked:** The existing implementation was complete and well-tested. The TaskStore trait cleanly separates operations by table, and the SqliteTaskStore implementation handles all CRUD operations correctly with proper migration support.\n- **What didn't:** N/A - task was already complete.\n- **Surprise:** The implementation included all 14 tables, not just tables 1-7. Feature tables 8-14 (canaries, CDC, tenant_map, etc.) are also fully implemented with comprehensive tests.\n- **Reusable pattern:** The migration system using schema_versions table with pending_migrations() is a clean pattern for idempotent schema upgrades. The WAL mode + busy_timeout combination handles concurrent writes without deadlocks.","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.1","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.264404312Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-r3j.2","title":"P3.2 SQLite backend: remaining tables (canaries, cdc_cursors, tenant_map, rollover_policies, search_ui_config, admin_sessions)","description":"## What\n\nExtend the SQLite `TaskStore` with plan §4 tables 8–14:\n8. `canaries` (§13.18)\n9. `canary_runs` (§13.18) — bounded by `canary_runner.run_history_per_canary` (default 100); auto-prune on insert\n10. `cdc_cursors` (§13.13)\n11. `tenant_map` (§13.15 `api_key` mode only)\n12. `rollover_policies` (§13.17)\n13. `search_ui_config` (§13.21)\n14. `admin_sessions` (§13.19) — with `CREATE INDEX admin_sessions_expires ON admin_sessions(expires_at)` for lazy eviction\n\n## Why Separate from P3.1\n\nThese tables are **feature-flag-gated** — `canaries` only instantiates when `canary_runner.enabled`, etc. Keeping them in a separate task lets Phase 5 subsection beads own each table's lifecycle and prevents the ~14-table `CREATE TABLE IF NOT EXISTS` cascade from running for features that will never be used.\n\nThat said, the schema definition itself lives here so every Phase 5 feature can `use` the same typed row structs rather than redefining them ad-hoc.\n\n## Details\n\n**`canary_runs` auto-prune**: on each insert, `DELETE FROM canary_runs WHERE canary_id = ? AND ran_at < (SELECT MIN(ran_at) FROM (SELECT ran_at FROM canary_runs WHERE canary_id = ? ORDER BY ran_at DESC LIMIT N))`. Wrap in a trigger so application code never forgets.\n\n**`admin_sessions.expires_at` index** — plan §4 admin_sessions footnote: rows past expires_at evicted lazily on access AND by Mode A pruner (§14.5). The index makes the scan cheap.\n\n**`cdc_cursors` is a per-(sink, index) composite PK** — both columns must match for update-in-place.\n\n**`tenant_map.api_key_hash` is a 32-byte BLOB** — raw sha256 bytes; never store the plaintext API key.\n\n## Acceptance\n\n- [ ] Every table's typed struct round-trips `insert`/`get` in a unit test\n- [ ] `canary_runs` trigger keeps row count ≤ `run_history_per_canary`\n- [ ] Tables that remain empty when their feature is disabled consume < 16 KB each (SQLite overhead)\n- [ ] Tables are created only when `TaskStore::migrate` is called with the relevant feature flag set (so dev-mode single-pod with all features off creates just 7 tables)","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-echo","created_at":"2026-04-18T21:30:07.286925769Z","created_by":"coding","updated_at":"2026-05-20T11:09:28.561656521Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.2","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.286925769Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.2","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.179800727Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-r3j.3","title":"P3.3 Redis backend: same trait, Redis keyspace per plan §4","description":"## What\n\nImplement the Redis-backed `TaskStore` mirroring every SQLite table to the keyspace layout in plan §4 \"Redis mode (HA)\":\n\n| SQLite | Redis |\n|--------|-------|\n| `tasks` row | `miroir:tasks:` hash + `miroir:tasks:_index` set |\n| `node_settings_version` | `miroir:node_settings_version::` hash + index set |\n| `aliases` | `miroir:aliases:` hash + index set |\n| `sessions` | `miroir:session:` hash with `EXPIRE session_pinning.ttl_seconds` |\n| `idempotency_cache` | `miroir:idemp:` hash with `EXPIRE idempotency.ttl_seconds` |\n| `jobs` | `miroir:jobs:` hash + `miroir:jobs:_queued` set (HPA signal) |\n| `leader_lease` | `miroir:lease:` string via `SET NX EX 10` renewed every 3s |\n| `canaries` | `miroir:canary:` hash + index set |\n| `canary_runs` | `miroir:canary_runs:` sorted set keyed by `ran_at`; `ZREMRANGEBYRANK` trim |\n| `cdc_cursors` | `miroir:cdc_cursor::` string (integer seq) |\n| `tenant_map` | `miroir:tenant_map:` hash |\n| `rollover_policies` | `miroir:rollover:` hash + index set |\n| `search_ui_config` | `miroir:search_ui_config:` hash |\n| `admin_sessions` | `miroir:admin_session:` hash with `EXPIRE session_ttl_s` + revoked bool |\n\nPlus the extras from plan §4 footnotes:\n- `miroir:search_ui_scoped_key:` hash (fields `primary_uid, previous_uid, rotated_at, generation`) — no TTL; long-lived\n- `miroir:search_ui_scoped_key_observed::` hash with 60s EXPIRE\n- `miroir:admin_session:revoked` Pub/Sub channel (logout invalidation)\n- `miroir:ratelimit:searchui:` with `EXPIRE search_ui.rate_limit.redis_ttl_s`\n- `miroir:ratelimit:adminlogin:` + `miroir:ratelimit:adminlogin:backoff:` (hash `{failed_count, next_allowed_at}`)\n- `miroir:cdc:overflow:` list (1 GiB cap via `cdc.buffer.redis_bytes`)\n\n## Why\n\nPlan §14.4: `replicas > 1` **requires** Redis. The trait-based abstraction means Phase 6 HPA just flips `task_store.backend: redis` via Helm values; no code change in feature layers.\n\n## Details\n\n**Secondary `_index` sets** are the key optimization: list-wide queries (e.g., `GET /_miroir/aliases`) iterate the set, not `SCAN`. Any `insert` must also `SADD` to the index; any `delete` must `SREM`.\n\n**Leader lease**: `SET NX EX 10`. Renewal is `SET XX EX 10` — only if we still hold it. Lease-loss mid-operation is plan §14.5 Mode B's recovery path.\n\n**EXPIRE on idempotency / session / admin_session / search_ui rate limit** — let Redis garbage-collect rather than running a Mode A pruner for each.\n\n**CDC overflow**: use `LPUSH` + `LTRIM` to bound list length; `LLEN` gives `miroir_cdc_buffer_bytes` (approximate).\n\n**Pipelining**: for the task fan-out mapping (one write → N node task IDs), use MULTI/EXEC to insert the tasks row + SADD the index set atomically.\n\n## Acceptance\n\n- [ ] testcontainers-based integration test: identical trait-level behavior to SQLite backend (run the shared CRUD suite against both)\n- [ ] Lease race: two pods `SET NX EX` simultaneously → exactly one wins\n- [ ] Memory budget: at 10k idempotency keys + 1k sessions + 100k tasks, Redis RSS stays under plan §14.7 accounting target\n- [ ] Pub/Sub: subscribe to `miroir:admin_session:revoked` and confirm logout on pod-A invalidates pod-B's in-memory cache within 100ms","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":0,"issue_type":"task","assignee":"claude-code-glm-4.7-hotel","created_at":"2026-04-18T21:30:07.307470462Z","created_by":"coding","updated_at":"2026-05-20T11:12:27.529253432Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.3","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.307470462Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.3","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.196004625Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-r3j.4","title":"P3.4 Migration + schema versioning","description":"## What\n\nImplement a first-class schema version system:\n- `schema_versions` table (SQLite) / `miroir:schema_version` key (Redis) recording the most recently applied migration\n- Each schema change gets a numbered migration (`001_initial.sql`, `002_add_foo.sql`, etc.)\n- Startup: read current version → apply all migrations with higher numbers → record latest\n- Refuse to start if DB version > binary version (e.g., operator rolled back to an older binary without rolling back the store)\n\n## Why\n\nPlan §12 commits to \"Config file schema: backward-compatible in minor versions (new fields always optional with defaults)\" and \"Task store schema requires migration notes (§7 release checklist).\" A versioning system forces that discipline from v0.1; shipping v1.0 with ad-hoc ALTER TABLE scatter is a nightmare to undo.\n\n## Details\n\n**Numbering**: monotonic `uXXX` where `u` is `000` to `999`; version history embedded in the binary via `include_str!` from a known directory.\n\n**Down-migration is optional** — we write migrations as one-way by default. For rollback, operators restore from backup rather than `downgrade 042→041`. Beads keep this door open; don't lock it shut.\n\n**Binary-vs-store version check**:\n- binary version = max migration number compiled into the binary\n- store version = max migration applied\n- start-up: if `binary < store`, refuse with a clear error. If `binary == store`, no-op. If `binary > store`, apply missing migrations.\n\n## Acceptance\n\n- [ ] First run creates the schema at version 001 (or whatever is the initial)\n- [ ] Second run is a no-op; migration scan is a single SELECT\n- [ ] Artificially set store version to binary+1 → startup fails with `schema_version_ahead` error\n- [ ] Both SQLite and Redis backends share the same migration metadata structure","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-foxtrot","created_at":"2026-04-18T21:30:07.338809736Z","created_by":"coding","updated_at":"2026-05-20T11:12:12.911547734Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.4","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.338809736Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.4","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.210512282Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-r3j.5","title":"P3.5 values.schema.json rejection: replicas>1 requires Redis","description":"## What\n\nAdd an entry to `charts/miroir/values.schema.json` that **fails `helm lint`** when `miroir.replicas > 1` and `taskStore.backend == \"sqlite\"`.\n\n## Why\n\nPlan §14.4: \"SQLite is single-writer and cannot be shared. The Helm chart enforces this: `taskStore.backend=sqlite` with `miroir.replicas > 1` fails values-schema validation.\" Without this guard, a developer who bumps `replicas: 2` in values.yaml and forgets to flip the backend gets silent task-store divergence across pods — every pod writes to its own SQLite in its own ephemeralVolume, mtask polls on pod-A can't see tasks enqueued on pod-B.\n\n## Details\n\nUse JSON Schema `if/then`:\n```jsonc\n{\n \"if\": { \"properties\": { \"miroir\": { \"properties\": { \"replicas\": { \"type\": \"integer\", \"exclusiveMinimum\": 1 } } } } },\n \"then\": { \"properties\": { \"taskStore\": { \"properties\": { \"backend\": { \"const\": \"redis\" } } } } }\n}\n```\n\nAdd `helm lint --strict` cases to Phase 9 test harness:\n- `replicas: 1, backend: sqlite` → lint passes\n- `replicas: 2, backend: sqlite` → lint fails with a clear error message\n- `replicas: 2, backend: redis` → lint passes\n\n## Acceptance\n\n- [ ] `helm lint --strict` on a values file with `replicas: 2 + backend: sqlite` fails with a message pointing at the constraint\n- [ ] The failure message is operator-readable (\"SQLite task store cannot run with multiple replicas; set taskStore.backend=redis\") — use `errorMessage` extension if available, else accept the default output\n- [ ] Test cases added to `charts/miroir/tests/` for future-proofing","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-india","created_at":"2026-04-18T21:30:07.373576976Z","created_by":"coding","updated_at":"2026-05-20T10:49:44.584624017Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.5","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.373576976Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-r3j.6","title":"P3.6 Task registry TTL pruner (in-memory for Phase 3; Mode A in Phase 6)","description":"## What\n\nImplement a background task that prunes `tasks` rows older than `task_registry.ttl_seconds` (default 7 days per plan §4). In Phase 3 this runs single-pod with an advisory lock; Phase 6 §14.5 Mode A replaces with rendezvous-partitioned ownership.\n\n## Why\n\nWithout TTL pruning, the task table grows unbounded. Plan §4 explicitly calls out the Mode A rendezvous pruner as the mechanism; shipping the simpler single-pod version here lets single-pod dev deployments not leak memory, and Phase 6 just swaps the ownership rule.\n\n## Details\n\n**Cadence**: run every `task_registry.prune_interval_s` (default 300s / 5 min).\n\n**Batch size**: max 10k rows per iteration so the background task never holds the DB long. SQLite: `DELETE FROM tasks WHERE created_at < ? LIMIT 10000`.\n\n**Preservation rule**: never prune a task whose `status` is `processing` (poll results might still be incoming). Plan this as \"age > TTL AND status IN (succeeded, failed, canceled)\".\n\n**Metrics**: `miroir_task_registry_size` (gauge) exposed per plan §10. The pruner updates it.\n\n## Acceptance\n\n- [ ] After insert of 10k terminal tasks with `created_at = now - 8d`, next pruner cycle drops all 10k\n- [ ] A single in-flight `processing` task at `created_at = now - 10d` is preserved\n- [ ] Pruner advisory lock prevents two instances pruning simultaneously (single-pod guarantee; Phase 6 replaces)\n- [ ] `miroir_task_registry_size` gauge drops after a prune cycle","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":1,"issue_type":"task","assignee":"claude-code-glm-4.7-golf","created_at":"2026-04-18T21:30:07.405347149Z","created_by":"coding","updated_at":"2026-05-20T11:13:09.478388956Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-3"],"dependencies":[{"issue_id":"miroir-r3j.6","depends_on_id":"miroir-r3j","type":"parent-child","created_at":"2026-04-18T21:30:07.405347149Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-r3j.6","depends_on_id":"miroir-r3j.1","type":"blocks","created_at":"2026-04-18T21:30:11.223268357Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-uhj","title":"Phase 5 — Advanced Capabilities (§13.1–§13.21)","description":"## Phase 5 Epic — Advanced Capabilities\n\nShips all 21 §13 capabilities. Each is orchestrator-side only (no Meilisearch node modification), individually togglable via a config flag, and defaults chosen to be low-risk. Four of them (§13.1, §13.5, §13.8, §13.9) directly resolve Open Problems in §15; the remaining 17 harden latency, correctness, and client ergonomics.\n\n## Why These Are Grouped\n\nPlan §13 preamble: \"All capabilities are individually togglable and default to conservative values.\" They are logically one epic because they share:\n- A single config-flag contract (`enabled: bool` per subsection)\n- The same orchestrator invariant (no node-side patches, unmodified CE)\n- The same task-store tables (defined in Phase 3)\n- The same HA coordination primitives (Phase 6 Modes A/B/C)\n\nSplitting them across phases would produce misleading dependency edges — in reality each §13.x is independent and can be built in parallel.\n\n## Subsections (each becomes one task bead under this epic)\n\n- §13.1 Online resharding via shadow index (OP#3)\n- §13.2 Hedged requests (tail latency)\n- §13.3 Adaptive replica selection (EWMA)\n- §13.4 Shard-aware query planner (PK-constrained)\n- §13.5 Two-phase settings broadcast + drift reconciler (OP#4)\n- §13.6 Read-your-writes via session pinning\n- §13.7 Atomic index aliases (single + multi-target)\n- §13.8 Anti-entropy shard reconciler (OP#1)\n- §13.9 Streaming routed dump import (OP#5)\n- §13.10 Idempotency keys + query coalescing\n- §13.11 Multi-search batch API\n- §13.12 Vector + hybrid search sharding (over-fetch + RRF/convex)\n- §13.13 CDC stream (webhook / NATS / Kafka / internal queue)\n- §13.14 Document TTL + automatic expiration\n- §13.15 Tenant-to-replica-group affinity\n- §13.16 Traffic shadow / teeing to staging\n- §13.17 Rolling time-series indexes (ILM)\n- §13.18 Synthetic canary queries + golden assertions\n- §13.19 Admin UI (embedded SPA via rust-embed)\n- §13.20 Query explain API\n- §13.21 End-user search UI (embedded SPA + JWT brokering + scoped-key rotation)\n\n## Cross-Feature Interactions to Preserve\n\n- §13.1 reshard's step 5 = §13.7 alias flip\n- §13.5 `settings_version` consumed by §13.6 session pin + §13.10 query-coalescing fingerprint + §13.20 explain\n- §13.8 expired-doc branch calls `_miroir_expires_at` (§13.14 interaction)\n- §13.13 CDC suppression via `_miroir_origin` tag (set by §13.1 backfill, §13.8 repair, §13.14 sweep, §13.17 rollover)\n- §13.17 `read_alias` is a §13.7 multi-target alias only ILM may edit\n- §13.19 Admin UI surfaces §13.5 2PC preview, §13.16 shadow diff, §13.13 CDC tail, §13.20 explain\n- §13.21 Search UI uses §13.11 multi-search, §13.10 coalescing, §13.6 session pinning; JWT signed via `SEARCH_UI_JWT_SECRET` with §9 dual-secret rotation\n\n## Definition of Done\n\n- [ ] All 21 subsection task beads closed\n- [ ] Every `enabled: true` default from the plan honored\n- [ ] Every cross-reference listed above validated by an integration test\n- [ ] Every §10/§14 metric family registered and scraping on the right port\n- [ ] §9 secret inventory updated (ADMIN_SESSION_SEAL_KEY, SEARCH_UI_JWT_SECRET, search_ui_shared_key)","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"epic","assignee":"","created_at":"2026-04-18T21:19:54.006891677Z","created_by":"coding","updated_at":"2026-05-09T16:33:11.137094348Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase","phase-5"],"dependencies":[{"issue_id":"miroir-uhj","depends_on_id":"miroir-9dj","type":"blocks","created_at":"2026-04-18T21:23:08.621245444Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-uhj","depends_on_id":"miroir-r3j","type":"blocks","created_at":"2026-04-18T21:23:08.634544009Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-uhj.1","title":"P5.1 §13.1 Online resharding via shadow index (OP#3)","description":"## What\n\nImplement the six-phase online resharding flow from plan §13.1:\n\n1. **Shadow create**: `{uid}__reshard_{S_new}` on every node with the new S, settings propagated via §13.5 two-phase broadcast\n2. **Dual-hash dual-write**: live writes go to both `{uid}` (hash %S_old) and `{uid}__reshard_{S_new}` (hash %S_new) with `_miroir_shard` injected per index's own S\n3. **Backfill**: background streamer pages every live-index shard via `filter=_miroir_shard={id}`, re-hashes each doc under S_new, writes to shadow; tagged `_miroir_origin: reshard_backfill` so §13.13 CDC suppresses\n4. **Verify**: cross-index PK-set comparator + content-hash fingerprint between live and shadow (reuses §13.8 bucketed-Merkle machinery but keyed by PK since live/shadow have different S)\n5. **Alias swap**: atomic §13.7 `PUT /_miroir/aliases/{uid}` to the shadow; dual-write stops\n6. **Cleanup**: live retained for `retain_old_index_hours` (default 48h) for emergency rollback, then deleted\n\n## Why\n\nPlan §15 Open Problem 3: \"The 'choose S generously' guidance remains the recommended default because online resharding doubles transient storage and write load; treat §13.1 as a remediation, not a license to under-provision.\" This is the safety valve — without it, under-provisioned clusters face a full external reindex.\n\n## Details\n\n**Scaling mode (plan §14.6)**: Mode B (leader for phase state machine) + Mode C (backfill chunks queued as jobs).\n\n**Failure handling** (plan §13.1): any failure before step 5 → delete shadow, invisible to clients. After step 5, rollback is a reverse alias flip to the retained live index.\n\n**CDC suppression**: §13.13 filters by `_miroir_origin: reshard_backfill` so subscribers don't see shadow writes as duplicates of live writes. Configured via `cdc.emit_internal_writes: false` (default).\n\n**Cross-index PK verify** is NOT the same as §13.8 within-shard reconciler — different S means different `_miroir_shard` values. Bucketing by `pk-hash % 256` gives a comparable space across indexes.\n\n**Admin API + CLI** (plan §4 admin table + §13.1):\n- `POST /_miroir/indexes/{uid}/reshard` body `{\"new_shards\": 256, \"throttle_docs_per_sec\": 10000}`\n- `GET /_miroir/indexes/{uid}/reshard/status`\n- `miroir-ctl reshard --index products --new-shards 256 --throttle 10000 [--dry-run]`\n\n## Acceptance\n\n- [ ] Reshard 64→128 on a 1M-doc index; post-swap search returns identical hits for golden queries\n- [ ] Mid-backfill failure: shadow deleted, client sees zero impact\n- [ ] Post-swap rollback: `PUT /_miroir/aliases/{uid} {\"target\": \"\"}` within 48h restores; aliased reads hit the old data\n- [ ] `miroir_reshard_phase` gauge transitions 0→1→2→3→4→5→0\n- [ ] Backfill throttles to `throttle_docs_per_sec` during peak business hours; disk footprint stays under 2× corpus during dual-write","design":"","acceptance_criteria":"","notes":"","status":"open","priority":0,"issue_type":"task","created_at":"2026-04-18T21:33:36.737028315Z","created_by":"coding","updated_at":"2026-04-18T21:38:33.137777638Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["advanced-13","phase-5"],"dependencies":[{"issue_id":"miroir-uhj.1","depends_on_id":"miroir-uhj","type":"parent-child","created_at":"2026-04-18T21:33:36.737028315Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-uhj.1","depends_on_id":"miroir-uhj.5","type":"blocks","created_at":"2026-04-18T21:38:33.123026198Z","created_by":"coding","metadata":"{}","thread_id":""},{"issue_id":"miroir-uhj.1","depends_on_id":"miroir-uhj.7","type":"blocks","created_at":"2026-04-18T21:38:33.137757362Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-uhj.1.1","title":"P5.1.a Shadow create phase: new index on every node via §13.5 broadcast","description":"Reshard step 1 (plan §13.1). Create {uid}__reshard_{S_new} on every node with new S; propagate live index's settings via §13.5 two-phase broadcast. Shadow is not client-addressable. Failure here deletes the shadow — invisible to clients.","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-04-18T21:50:32.931816015Z","created_by":"coding","updated_at":"2026-04-18T21:50:32.931816015Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["advanced-13","phase-5"],"dependencies":[{"issue_id":"miroir-uhj.1.1","depends_on_id":"miroir-uhj.1","type":"parent-child","created_at":"2026-04-18T21:50:32.931816015Z","created_by":"coding","metadata":"{}","thread_id":""}]} @@ -151,9 +151,9 @@ {"id":"miroir-uyx.5","title":"P11.5 Common issues + troubleshooting","description":"## What\n\nPlan §11 \"Common issues\" as structured troubleshooting docs at `docs/troubleshooting.md`:\n- \"primary key required\" — Miroir requires explicit primary key at index creation\n- \"Search returns fewer results than expected\" — degraded-node cross-reference + `GET /_miroir/topology`\n- \"Task polling stuck at processing\" — per-node task status via `miroir-ctl task status`\n\nPlus others discovered during Phase 9 testing and chaos scenarios.\n\n## Why\n\nEvery production system accumulates a list of \"the 10 things new users hit in their first week.\" Documenting them transparently shortens the mean-time-to-productive-user from hours to minutes.\n\n## Details\n\n**Per-issue structure**:\n```markdown\n## Error: \"primary key required\"\n\n### Symptom\nClient sees: `HTTP 400 { \"code\": \"miroir_primary_key_required\" }`\n\n### Cause\nThe index was created without a primary key. Miroir cannot route without one.\n\n### Fix\n```bash\ncurl -X POST https://miroir/indexes \\\n -H \"Authorization: Bearer $KEY\" \\\n -d '{\"uid\": \"myindex\", \"primaryKey\": \"id\"}'\n```\n\n### Why this differs from Meilisearch\nMeilisearch can infer the primary key from the first document batch. Miroir cannot — it needs to hash the PK *before* any node sees it. Explicit primary_key at index creation is required.\n```\n\n**Diagnostic playbook**: `docs/troubleshooting/diagnostics.md` — first thing to check for any symptom:\n1. `GET /_miroir/topology` — all nodes healthy?\n2. `GET /_miroir/metrics | grep degraded` — any degraded shards?\n3. `kubectl logs miroir-0 --tail=100 | jq 'select(.level==\"ERROR\")'` — recent errors?\n4. `kubectl get pods -n search` — all running?\n\n## Acceptance\n\n- [ ] 3 plan §11 issues documented with the template\n- [ ] At least 5 additional issues discovered in Phase 9 chaos added\n- [ ] Troubleshooting doc cross-linked from README, install guide, each migration guide","design":"","acceptance_criteria":"","notes":"","status":"open","priority":1,"issue_type":"task","created_at":"2026-04-18T21:48:38.877214633Z","created_by":"coding","updated_at":"2026-04-18T21:48:38.877214633Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-11"],"dependencies":[{"issue_id":"miroir-uyx.5","depends_on_id":"miroir-uyx","type":"parent-child","created_at":"2026-04-18T21:48:38.877214633Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-uyx.6","title":"P11.6 Helm chart publication: GH Pages + OCI push","description":"## What\n\nPlan §12 delivered artifacts for the Helm chart:\n- **Primary**: `https://jedarden.github.io/miroir` (GitHub Pages, `gh-pages` branch)\n- **OCI**: `ghcr.io/jedarden/charts/miroir` (for air-gapped environments)\n\nExtend the Phase 8 Argo Workflow `miroir-ci` template with:\n- On tag: `helm package charts/miroir -d dist/`\n- Push to gh-pages: update `index.yaml` + copy `.tgz` into the branch, commit via `gh-pages` helper\n- OCI push: `helm push dist/miroir-.tgz oci://ghcr.io/jedarden/charts`\n\n## Why\n\nPlan §12: chart users expect `helm repo add` to work. Without publication, operators have to `helm install charts/miroir/` from a git clone — fine for dev, wrong for prod.\n\n## Details\n\n**gh-pages flow**:\n```bash\ngit worktree add gh-pages gh-pages\nhelm package charts/miroir -d gh-pages/\nhelm repo index gh-pages/ --url https://jedarden.github.io/miroir --merge gh-pages/index.yaml\ngit -C gh-pages add -A\ngit -C gh-pages commit -m \"Release chart v\"\ngit -C gh-pages push origin gh-pages\n```\n\n**OCI push** requires GHCR write token (already have in `ghcr-credentials`):\n```bash\necho $GHCR_TOKEN | helm registry login ghcr.io -u --password-stdin\nhelm push miroir-.tgz oci://ghcr.io/jedarden/charts\n```\n\n**Chart-only fixes**: when a chart change doesn't need an app rebuild, bump only chart version (not appVersion). CI must detect \"chart-only\" change (e.g., by diffing `charts/**` vs. `crates/**`) and skip the binary rebuild.\n\n## Acceptance\n\n- [ ] After `git tag v0.1.0 && git push`, `helm repo add miroir https://jedarden.github.io/miroir && helm repo update` discovers v0.1.0\n- [ ] `helm install ... oci://ghcr.io/jedarden/charts/miroir --version 0.1.0` works identically\n- [ ] Chart-only fix: tagging `v0.1.1` after editing only a template file bumps chart version without new app binary","design":"","acceptance_criteria":"","notes":"","status":"open","priority":2,"issue_type":"task","created_at":"2026-04-18T21:48:38.909893288Z","created_by":"coding","updated_at":"2026-04-18T21:48:38.909893288Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase-11"],"dependencies":[{"issue_id":"miroir-uyx.6","depends_on_id":"miroir-uyx","type":"parent-child","created_at":"2026-04-18T21:48:38.909893288Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-zc2","title":"Phase 12 — Open Problems + Research (§15)","description":"## Phase 12 Epic — Open Problems Tracking\n\nStanding bucket for the plan §15 open problems that are **not** fully resolved by initial implementation. These are research/validation/future-enhancement beads, not blockers for v1.0. This phase does not block the genesis bead's shipping path — it's a parallel track that persists beyond v1.0.\n\n## Why An Epic At All\n\nPlan §15 flags these as \"documented constraints, not blockers. Initial release ships with known limitations.\" Tracking them as beads means they're not forgotten, they have a visible owner, and their resolution status can be surfaced alongside the rest of the work.\n\n## Scope — the 6 Open Problems (plan §15)\n\n1. **Shard migration write safety** — OP#1. **Status: partially addressed.** Dual-write cutover sequencing (Phase 4) + anti-entropy reconciler (§13.8 / Phase 5) catches slipped docs. Remaining work: chaos-test the cutover boundary, document any reproducible window where data could be lost if anti-entropy is disabled.\n\n2. **Task state HA (Raft vs. Redis)** — OP#2. **Status: deferred.** Current: Redis for multi-pod, SQLite for single-pod. Future: lightweight in-process Raft (or equivalent) so Redis is not required in HA. Not v1.x.\n\n3. **Resharding (S change) vs. node scaling (N change)** — OP#3. **Status: addressed by §13.1** (shadow-index dual-hash). Remaining work: empirical validation of the §13.1 \"2× transient storage and write load\" caveat under real corpora; schedule guidance in the CLI for off-peak reshard windows.\n\n4. **Score normalization at scale** — OP#4. **Status: settings-divergence addressed by §13.5 two-phase broadcast + drift reconciler.** Remaining work is purely statistical: validate that `_rankingScore` remains comparable across shards with very different document-count distributions. Requires corpus diversity tests.\n\n5. **Dump import distribution** — OP#5. **Status: addressed by §13.9 streaming routed dump import.** Broadcast mode retained as fallback. Remaining work: identify and enumerate every dump variant `mode: streaming` cannot fully reconstruct; either extend streaming or document the fallback trigger clearly.\n\n6. **arm64 support** — OP#6. **Status: not planned for v0.x.** Wire into CI when K8s ARM node support is actually needed (likely v1.x or later).\n\n## How To Use This Phase\n\n- Each OP becomes a child bead (bug/feature type) under this epic\n- Beads stay open until the status column above says \"fully addressed\"\n- v1.0 release notes should explicitly link to this epic so operators know what's still on the table\n- New open problems discovered during implementation get added here rather than silently accreted elsewhere\n\n## Not In Scope\n\n- Any concrete implementation work already covered by §13.1 / §13.5 / §13.8 / §13.9 — that belongs to Phase 5.","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":2,"issue_type":"epic","assignee":"claude-code-glm-4.7-alpha","created_at":"2026-04-18T21:22:54.403910669Z","created_by":"coding","updated_at":"2026-05-08T19:24:51.358651712Z","closed_at":"2026-05-08T19:24:51.358651712Z","close_reason":"Phase 12 epic setup complete. All 6 open problems from plan §15 are now tracked as child beads (miroir-zc2.1 through miroir-zc2.6).\n\n## Retrospective\n- **What worked:** The child beads already existed in the system with comprehensive descriptions covering all 6 open problems. I verified the structure is correct and matches plan §15.\n- **What didn't:** Initially created duplicate beads (bf-*) before realizing the child beads (miroir-zc2.1-6) already existed. Cleaned up the duplicates.\n- **Surprise:** The bead system auto-creates child IDs with the pattern parent-number which is cleaner than arbitrary IDs.\n- **Reusable pattern:** For epic setup tasks, first check if child beads already exist using `br list | grep parent` before creating new ones.","source_repo":".","compaction_level":0,"original_size":0,"labels":["phase","phase-12","research"]} -{"id":"miroir-zc2.1","title":"P12.OP1 Shard migration write safety — cutover race window analysis","description":"## What\n\nPlan §15 Open Problem #1: \"Dual-write during migration must not lose documents that arrive exactly at the migration cutover boundary.\"\n\n**Status** per plan: partially addressed. Race window mitigated by §13.8 anti-entropy; any slipped doc caught on next reconciliation pass.\n\n**Remaining work**:\n- Chaos-test the cutover boundary — specifically: docs arriving at the instant of `active` transition (step 7 in plan §2 \"Adding a node\")\n- Document any reproducible window where data could be lost if anti-entropy is disabled\n- If found: extend Phase 4 dual-write to hold the window longer OR require anti-entropy to be on (hard-coded policy)\n\n## Why\n\n\"Plan §15 Open Problem 1 closure\" has been claimed in §13.8 — this bead verifies that claim empirically before we ship v1.0 committing to it.\n\n## Details\n\n**Chaos test design**:\n1. Start 3-node cluster, write 1000 docs\n2. Trigger node addition (`POST /_miroir/nodes`)\n3. During dual-write, rapid-fire new writes with tight (1ms) interval\n4. Tight-loop the transition from step 4 (migration complete) to step 7 (old replica deleted)\n5. Assert: every written doc retrievable AFTER step 7\n\n**Variants**:\n- With anti-entropy enabled (default) — expect 100% retrievable\n- With anti-entropy **disabled** — measure loss rate. If > 0, document + add a schema constraint refusing to enable migrations when anti-entropy is off\n\n## Acceptance\n\n- [ ] Chaos test published; runs on every v1.0-gating CI run\n- [ ] Loss rate measured at < 1 per 1M writes with AE on\n- [ ] Loss rate measured without AE; decision documented in `docs/trade-offs.md`\n- [ ] If `anti_entropy.enabled: false` + migration concurrent → loud warning log + (decided) refuse or warn","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":2,"issue_type":"bug","assignee":"claude-code-glm-4.7-kilo","created_at":"2026-04-18T21:49:47.774525899Z","created_by":"coding","updated_at":"2026-05-20T02:51:42.893316352Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.1","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.774525899Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-zc2.1","title":"P12.OP1 Shard migration write safety — cutover race window analysis","description":"## What\n\nPlan §15 Open Problem #1: \"Dual-write during migration must not lose documents that arrive exactly at the migration cutover boundary.\"\n\n**Status** per plan: partially addressed. Race window mitigated by §13.8 anti-entropy; any slipped doc caught on next reconciliation pass.\n\n**Remaining work**:\n- Chaos-test the cutover boundary — specifically: docs arriving at the instant of `active` transition (step 7 in plan §2 \"Adding a node\")\n- Document any reproducible window where data could be lost if anti-entropy is disabled\n- If found: extend Phase 4 dual-write to hold the window longer OR require anti-entropy to be on (hard-coded policy)\n\n## Why\n\n\"Plan §15 Open Problem 1 closure\" has been claimed in §13.8 — this bead verifies that claim empirically before we ship v1.0 committing to it.\n\n## Details\n\n**Chaos test design**:\n1. Start 3-node cluster, write 1000 docs\n2. Trigger node addition (`POST /_miroir/nodes`)\n3. During dual-write, rapid-fire new writes with tight (1ms) interval\n4. Tight-loop the transition from step 4 (migration complete) to step 7 (old replica deleted)\n5. Assert: every written doc retrievable AFTER step 7\n\n**Variants**:\n- With anti-entropy enabled (default) — expect 100% retrievable\n- With anti-entropy **disabled** — measure loss rate. If > 0, document + add a schema constraint refusing to enable migrations when anti-entropy is off\n\n## Acceptance\n\n- [ ] Chaos test published; runs on every v1.0-gating CI run\n- [ ] Loss rate measured at < 1 per 1M writes with AE on\n- [ ] Loss rate measured without AE; decision documented in `docs/trade-offs.md`\n- [ ] If `anti_entropy.enabled: false` + migration concurrent → loud warning log + (decided) refuse or warn","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":2,"issue_type":"bug","assignee":"claude-code-glm-4.7-kilo","created_at":"2026-04-18T21:49:47.774525899Z","created_by":"coding","updated_at":"2026-05-20T11:11:45.450822309Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.1","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.774525899Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-zc2.2","title":"P12.OP2 Task state HA — evaluate lightweight Raft vs. Redis requirement","description":"## What\n\nPlan §15 Open Problem #2: \"SQLite is single-writer. Running 2 Miroir replicas requires Redis. A future enhancement is a lightweight Raft-based in-process consensus so Redis is not required for HA mode.\"\n\n**Status** per plan: deferred. Current solution (Redis) works; Raft would remove an external dependency.\n\n**Research work**:\n- Survey embedded Raft crates: `openraft`, `raft-rs`, `async-raft`\n- Prototype: `TaskStore` trait impl backed by Raft state machine\n- Measure: latency + throughput vs. Redis; memory footprint per plan §14.2\n- Decide: ship in v1.x or never\n\n## Why\n\nRemoving Redis as a hard dependency shrinks the operational surface (one less thing to monitor, backup, rotate secrets for). But Raft adds complexity — a bad Raft impl can eat data in ways Redis doesn't.\n\nNot blocking v0.x or v1.0 — but worth prototyping before v2.0.\n\n## Details\n\n**Decision gate**: the Raft-backed path must be measurably better than Redis on at least one metric (ops simplicity, latency, or memory) without being worse on any of the others, before shipping.\n\n**Output**: `docs/research/raft-task-store.md` with the decision + benchmark data + reasoning. Keep or discard based on findings.\n\n## Acceptance\n\n- [ ] Research doc published with prototype branch linked\n- [ ] Decision recorded: ship / don't ship / revisit when","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":3,"issue_type":"feature","created_at":"2026-04-18T21:49:47.798646718Z","created_by":"coding","updated_at":"2026-05-09T00:40:01.038998514Z","closed_at":"2026-05-09T00:40:01.038998514Z","close_reason":"P12.OP2 Raft vs Redis research verified — existing comprehensive findings confirmed.\n\n## Retrospective\n- **What worked:** The research document at docs/research/raft-task-store.md was already comprehensive, covering crate survey (openraft, raft-rs, async-raft), prototype design, analytical benchmarks, decision matrix, and a clear recorded decision. The prototype code exists at crates/miroir-core/src/raft_proto/ and is well-documented.\n- **What didn't:** No issues encountered. The acceptance criteria were already met by the previous research work (commit 16bda4b).\n- **Surprise:** The raft-proto feature is commented out in Cargo.toml because openraft 0.9.20 fails to compile on stable Rust 1.87 (dependency validit uses unstable let_chains). This compilation failure is itself noted in the research doc as a data point against Raft adoption.\n- **Reusable pattern:** For research verification beads, first check if the research document already exists and is comprehensive before starting new work. The notes file format (summary + acceptance criteria checklist + key findings) provides a good template for documenting verification work.","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.2","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.798646718Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-zc2.3","title":"P12.OP3 Online resharding — validate 2× transient load caveat under real corpora","description":"## What\n\nPlan §15 Open Problem #3: §13.1 online resharding ships as a remediation, NOT a license to under-provision. Plan: \"doubles transient storage and write load; treat §13.1 as a remediation, not a license to under-provision.\"\n\n**Remaining work**:\n- Empirical validation of the 2× storage + write load estimate under real corpora (varied doc sizes, write rates, settings complexity)\n- CLI schedule guidance: `miroir-ctl reshard --schedule-window off-peak` — refuses to start outside a named window unless `--force`\n\n## Why\n\nOperators will over-commit to resharding if the \"2× transient\" caveat turns out to be 3× or worse in practice. Real numbers prevent that.\n\n## Details\n\n**Test matrix**:\n| Doc size | Corpus | Write rate | RG | RF | Measured peak storage |\n|----------|--------|------------|----|----|-----------------------|\n| 1 KB | 10 GB | 100 dps | 2 | 1 | ? |\n| 10 KB | 100 GB | 1000 dps | 2 | 2 | ? |\n| 1 MB (blobs) | 1 TB | 10 dps | 2 | 1 | ? |\n\nPublish results in `docs/benchmarks/resharding-load.md`.\n\n**CLI window guard**: config knob `resharding.allowed_windows: [\"02:00-06:00 UTC\"]`. CLI refuses outside windows without `--force`.\n\n## Acceptance\n\n- [ ] Benchmark doc published with real numbers\n- [ ] CLI window guard implemented; integration test confirms rejection outside window\n- [ ] Benchmark run in Phase 9 performance suite as part of v1.0 validation","design":"","acceptance_criteria":"","notes":"","status":"open","priority":3,"issue_type":"task","assignee":"","created_at":"2026-04-18T21:49:47.828099118Z","created_by":"coding","updated_at":"2026-05-08T19:27:37.064134540Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.3","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.828099118Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-zc2.4","title":"P12.OP4 Score normalization at scale — statistical validation of cross-shard comparability","description":"## What\n\nPlan §15 Open Problem #4: \"`_rankingScore` is comparable across shards only when index settings are identical.\" Settings divergence addressed by §13.5; remaining concern is statistical — do scores stay comparable when shards have very different document-count distributions?\n\n**Research work**:\n- Build a test corpus with intentionally skewed shard populations (one shard 100×, another shard 0.01× the median)\n- Submit identical queries; measure score distribution per shard\n- Assert: top-K merged ordering matches a ground-truth single-index version within some ε\n- If large ε, document + possibly introduce a score normalization pass\n\n## Why\n\nElasticsearch (plan research doc §1) hits this exactly: \"BM25 scoring depends on IDF, computed per shard by default using only that shard's local term statistics.\" Meilisearch uses its own ranking pipeline, but the same issue applies — local rank stats can drift from global on skewed shards.\n\n## Details\n\n**Ground truth**: single-index Meilisearch running the same queries against the same corpus.\n\n**Divergence metric**: Kendall τ between Miroir result ordering and single-index result ordering across 10k random queries.\n\n**If τ < 0.95 on average**: investigate whether a global IDF-style preflight is worth adding (plan research §1 \"`dfs_query_then_fetch`\" pattern).\n\n**Output**: `docs/research/score-normalization-at-scale.md`.\n\n## Acceptance\n\n- [ ] Benchmark corpus + query set published in `tests/benches/score-comparability/`\n- [ ] Results reported with confidence intervals\n- [ ] If τ < 0.95: follow-up bead created for a normalization pass\n- [ ] If τ ≥ 0.95: note-of-no-action in the bead's close comment","design":"","acceptance_criteria":"","notes":"","status":"open","priority":3,"issue_type":"task","assignee":"","created_at":"2026-04-18T21:49:47.849019120Z","created_by":"coding","updated_at":"2026-05-08T19:30:38.676158896Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.4","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.849019120Z","created_by":"coding","metadata":"{}","thread_id":""}]} -{"id":"miroir-zc2.5","title":"P12.OP5 Dump import variants — enumerate what streaming mode can't handle","description":"## What\n\nPlan §15 Open Problem #5: §13.9 streaming routed dump import addresses the main case; broadcast mode retained as a fallback for dump variants Miroir cannot fully reconstruct via public API.\n\n**Remaining work**:\n- Identify and enumerate every dump variant streaming can't reconstruct\n- Either extend streaming to handle them OR document the fallback trigger clearly in `miroir-ctl dump import --help`\n\n## Why\n\n\"Can't reconstruct\" is vague — operators deserve concrete lists of what works and what doesn't. Without this, the `broadcast` fallback path is a bug waiting to happen.\n\n## Details\n\n**Potential failure modes to investigate**:\n- Dumps from older Meilisearch versions with pre-v1.37 schema\n- Dumps with custom keys (POST /keys) that have indexes list or actions not representable via public API\n- Dumps with snapshot-taken-mid-write where Miroir-injected `_miroir_shard` would conflict with an existing client field\n\n**Deliverable**: `docs/dump-import/compatibility-matrix.md` with columns:\n| Meilisearch version | Dump variant | Streaming works? | Broadcast needed? | Workaround |\n\n## Acceptance\n\n- [ ] Matrix published\n- [ ] Each \"broadcast needed\" row has a workaround or a link to an open enhancement bead\n- [ ] `miroir-ctl dump import` output references the matrix when falling back to broadcast","design":"","acceptance_criteria":"","notes":"","status":"open","priority":3,"issue_type":"task","assignee":"","created_at":"2026-04-18T21:49:47.884303207Z","created_by":"coding","updated_at":"2026-05-08T19:29:37.852869523Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.5","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.884303207Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-zc2.3","title":"P12.OP3 Online resharding — validate 2× transient load caveat under real corpora","description":"## What\n\nPlan §15 Open Problem #3: §13.1 online resharding ships as a remediation, NOT a license to under-provision. Plan: \"doubles transient storage and write load; treat §13.1 as a remediation, not a license to under-provision.\"\n\n**Remaining work**:\n- Empirical validation of the 2× storage + write load estimate under real corpora (varied doc sizes, write rates, settings complexity)\n- CLI schedule guidance: `miroir-ctl reshard --schedule-window off-peak` — refuses to start outside a named window unless `--force`\n\n## Why\n\nOperators will over-commit to resharding if the \"2× transient\" caveat turns out to be 3× or worse in practice. Real numbers prevent that.\n\n## Details\n\n**Test matrix**:\n| Doc size | Corpus | Write rate | RG | RF | Measured peak storage |\n|----------|--------|------------|----|----|-----------------------|\n| 1 KB | 10 GB | 100 dps | 2 | 1 | ? |\n| 10 KB | 100 GB | 1000 dps | 2 | 2 | ? |\n| 1 MB (blobs) | 1 TB | 10 dps | 2 | 1 | ? |\n\nPublish results in `docs/benchmarks/resharding-load.md`.\n\n**CLI window guard**: config knob `resharding.allowed_windows: [\"02:00-06:00 UTC\"]`. CLI refuses outside windows without `--force`.\n\n## Acceptance\n\n- [ ] Benchmark doc published with real numbers\n- [ ] CLI window guard implemented; integration test confirms rejection outside window\n- [ ] Benchmark run in Phase 9 performance suite as part of v1.0 validation","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":3,"issue_type":"task","assignee":"claude-code-glm-4.7-oscar","created_at":"2026-04-18T21:49:47.828099118Z","created_by":"coding","updated_at":"2026-05-20T11:10:29.985055104Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.3","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.828099118Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-zc2.4","title":"P12.OP4 Score normalization at scale — statistical validation of cross-shard comparability","description":"## What\n\nPlan §15 Open Problem #4: \"`_rankingScore` is comparable across shards only when index settings are identical.\" Settings divergence addressed by §13.5; remaining concern is statistical — do scores stay comparable when shards have very different document-count distributions?\n\n**Research work**:\n- Build a test corpus with intentionally skewed shard populations (one shard 100×, another shard 0.01× the median)\n- Submit identical queries; measure score distribution per shard\n- Assert: top-K merged ordering matches a ground-truth single-index version within some ε\n- If large ε, document + possibly introduce a score normalization pass\n\n## Why\n\nElasticsearch (plan research doc §1) hits this exactly: \"BM25 scoring depends on IDF, computed per shard by default using only that shard's local term statistics.\" Meilisearch uses its own ranking pipeline, but the same issue applies — local rank stats can drift from global on skewed shards.\n\n## Details\n\n**Ground truth**: single-index Meilisearch running the same queries against the same corpus.\n\n**Divergence metric**: Kendall τ between Miroir result ordering and single-index result ordering across 10k random queries.\n\n**If τ < 0.95 on average**: investigate whether a global IDF-style preflight is worth adding (plan research §1 \"`dfs_query_then_fetch`\" pattern).\n\n**Output**: `docs/research/score-normalization-at-scale.md`.\n\n## Acceptance\n\n- [ ] Benchmark corpus + query set published in `tests/benches/score-comparability/`\n- [ ] Results reported with confidence intervals\n- [ ] If τ < 0.95: follow-up bead created for a normalization pass\n- [ ] If τ ≥ 0.95: note-of-no-action in the bead's close comment","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":3,"issue_type":"task","assignee":"claude-code-glm-4.7-charlie","created_at":"2026-04-18T21:49:47.849019120Z","created_by":"coding","updated_at":"2026-05-20T11:13:07.803989766Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.4","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.849019120Z","created_by":"coding","metadata":"{}","thread_id":""}]} +{"id":"miroir-zc2.5","title":"P12.OP5 Dump import variants — enumerate what streaming mode can't handle","description":"## What\n\nPlan §15 Open Problem #5: §13.9 streaming routed dump import addresses the main case; broadcast mode retained as a fallback for dump variants Miroir cannot fully reconstruct via public API.\n\n**Remaining work**:\n- Identify and enumerate every dump variant streaming can't reconstruct\n- Either extend streaming to handle them OR document the fallback trigger clearly in `miroir-ctl dump import --help`\n\n## Why\n\n\"Can't reconstruct\" is vague — operators deserve concrete lists of what works and what doesn't. Without this, the `broadcast` fallback path is a bug waiting to happen.\n\n## Details\n\n**Potential failure modes to investigate**:\n- Dumps from older Meilisearch versions with pre-v1.37 schema\n- Dumps with custom keys (POST /keys) that have indexes list or actions not representable via public API\n- Dumps with snapshot-taken-mid-write where Miroir-injected `_miroir_shard` would conflict with an existing client field\n\n**Deliverable**: `docs/dump-import/compatibility-matrix.md` with columns:\n| Meilisearch version | Dump variant | Streaming works? | Broadcast needed? | Workaround |\n\n## Acceptance\n\n- [ ] Matrix published\n- [ ] Each \"broadcast needed\" row has a workaround or a link to an open enhancement bead\n- [ ] `miroir-ctl dump import` output references the matrix when falling back to broadcast","design":"","acceptance_criteria":"","notes":"","status":"in_progress","priority":3,"issue_type":"task","assignee":"claude-code-glm-4.7-india","created_at":"2026-04-18T21:49:47.884303207Z","created_by":"coding","updated_at":"2026-05-20T11:12:40.105078421Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","research"],"dependencies":[{"issue_id":"miroir-zc2.5","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.884303207Z","created_by":"coding","metadata":"{}","thread_id":""}]} {"id":"miroir-zc2.6","title":"P12.OP6 arm64 support (deferred to v1.x+)","description":"## What\n\nPlan §15 Open Problem #6: \"Not planned for v0.x. Added when K8s ARM node support is required.\"\n\n**Future work when prioritized**:\n- Cross-compile `miroir-proxy` and `miroir-ctl` for `aarch64-unknown-linux-musl` in the CI pipeline\n- Docker image manifest list: `ghcr.io/jedarden/miroir:` spans `linux/amd64` + `linux/arm64`\n- Helm chart: no changes (binary is arch-agnostic at the k8s layer)\n- Phase 9 CI: add arm64 test runs\n\n## Why\n\nARM node support is increasingly common (Hetzner Ampere, AWS Graviton, GCP Tau T2A, Rackspace Spot). But Miroir's fleet is currently all amd64 (iad-ci is amd64; ardenone cluster nodes are amd64). No current demand to justify the CI complexity.\n\nKeep this bead open as a placeholder; promote to in-progress when a concrete use case emerges.\n\n## Details\n\n**When ready**: the Argo Workflow `cargo-build` step needs a matrix over targets:\n```yaml\n- name: cargo-build\n container:\n args:\n - |\n rustup target add x86_64-unknown-linux-musl\n rustup target add aarch64-unknown-linux-musl\n apt-get install -qy musl-tools gcc-aarch64-linux-gnu\n cargo build --release --target x86_64-unknown-linux-musl -p miroir-proxy\n cargo build --release --target aarch64-unknown-linux-musl -p miroir-proxy\n ...\n```\n\nKaniko build needs `--customPlatform=linux/amd64,linux/arm64` or equivalent for multi-arch manifests.\n\n## Acceptance\n\n- [ ] Not to be closed until arm64 is a live deliverable\n- [ ] Cross-reference here when the priority flips","design":"","acceptance_criteria":"","notes":"","status":"closed","priority":4,"issue_type":"feature","created_at":"2026-04-18T21:49:47.917666333Z","created_by":"coding","updated_at":"2026-05-09T00:49:13.706981214Z","closed_at":"2026-05-09T00:49:13.706981214Z","close_reason":"ARM64 support deferred to v1.x+ per Plan §15 Open Problem #6. Documentation committed to notes/miroir-zc2.6.\n\n## Retrospective\n- **What worked:** Creating a placeholder bead with clear deferral rationale keeps the roadmap visible without blocking current work\n- **What didn't:** N/A (deferred work)\n- **Surprise:** The acceptance criteria asked for commit before closing, but documentation already existed from prior session\n- **Reusable pattern:** For deferred features, document the trigger conditions (when to promote to in-progress) in the bead notes so future context is clear","source_repo":".","compaction_level":0,"original_size":0,"labels":["open-problem","phase-12","roadmap"],"dependencies":[{"issue_id":"miroir-zc2.6","depends_on_id":"miroir-zc2","type":"parent-child","created_at":"2026-04-18T21:49:47.917666333Z","created_by":"coding","metadata":"{}","thread_id":""}]} diff --git a/notes/bf-55fg.md b/notes/bf-55fg.md index 4c2f9af..91cb47e 100644 --- a/notes/bf-55fg.md +++ b/notes/bf-55fg.md @@ -20,3 +20,7 @@ The file was already created in a previous attempt. The forced-mode constraints - Rule 4: `admin_ui.rate_limit.backend: local` rejected when `miroir.replicas > 1` The doc is well-structured and provides operators with a clear reference for horizontal scaling requirements per feature. + +## Additional work (2026-05-20) + +Added cross-reference comments to beads `miroir-m9q.3`, `miroir-m9q.4`, and `miroir-m9q.5` pointing to `docs/horizontal-scaling/per-feature.md`. This enables bidirectional navigation between the mode implementation beads and the per-feature scaling reference.