docs: restructure policies into layered invariant model + bump filter-chain

[K1ngst0m]

PR Summary by Qodo

Docs: layered policy invariants + roadmap refresh; bump filter-chain submodule
📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

Walkthroughs

User Description

Splits the documentation/policy work out of the P5 fix PR (#146) into its own PR, as requested.

Contents

• docs/project_policies.md restructured into a layered invariant model.
• New per-layer policy docs: docs/policies/{process,boundary,resource,sync,liveness}.md.
• ROADMAP.md updated to match.
• filter-chain submodule bumped.
• pixi.lock synced with the manifest (see below).

CI note (pre-existing main breakage)

CI's Setup Pixi runs pixi install --locked on a clean checkout and currently fails on main with "lock-file not up-to-date with the workspace" — the committed lock pinned libxkbcommon 1.13.1, which no longer matches the manifest resolution. This is pre-existing on main and independent of this PR's content (a clean origin/main checkout reproduces it under both pixi v0.65.0 and v0.67.2; the green checks on main are stale, predating the drift).

The pixi.lock sync commit here regenerates it with the CI-pinned pixi v0.65.0 — a single transitive patch bump (libxkbcommon 1.13.1 → 1.13.2), no manifest/dependency-intent change. The identical sync rides on #146; whichever merges first lands it, the other becomes a no-op.

🤖 Generated with Claude Code

AI Description

• Reframe project policies into a layered invariant model with a consistent rule schema.
• Split policy invariants into per-layer documents for easier navigation and review.
• Update the roadmap to reflect current progress and known latency issues; bump filter-chain
  submodule.

Diagram

graph TD
  A["docs/project_policies.md"] --> B["docs/policies/process.md"] --> C["docs/policies/boundary.md"] --> D["docs/policies/resource.md"] --> E["docs/policies/sync.md"] --> F["docs/policies/liveness.md"]
  A --> G["ROADMAP.md"]
  H["filter-chain (submodule)"] --> G

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep a single policies document with per-layer sections

• ➕ Single file to search and review; fewer links and less navigation overhead
• ➕ Avoids risk of duplicated/overlapping rules drifting between files
• ➖ Becomes long and hard to scan; reviewers must context-switch within a large file
• ➖ Harder to treat layer docs as focused checklists for specific change types

2. Generate docs from a structured rule source (YAML/JSON) + renderer

• ➕ Enforces schema consistency (IDs, required fields like Escapes)
• ➕ Enables tooling (linting, cross-link validation, rule index pages)
• ➖ Adds build/tooling complexity and a new source-of-truth format to maintain
• ➖ Higher upfront cost than a pure-Markdown approach

Recommendation: The PR’s approach (Markdown per-layer files plus a canonical overview and rule schema) is the best near-term tradeoff: it improves navigability and makes the invariant model explicit without introducing extra tooling. Consider adding lightweight link-checking (or a small script) later if cross-file references/IDs start to drift.

File Changes

Documentation (7)

ROADMAP.md Refresh roadmap progress, known latency issues, and CI test enablement steps +17/-35

Refresh roadmap progress, known latency issues, and CI test enablement steps

• Updates shader preset compatibility language and points the “fix filter chain, not shaders” rule at the submodule path. Replaces speculative latency bullets with instrumented status plus concrete known issues, and marks multiple visual-regression milestones complete while adding a specific CI-enablement checklist.

ROADMAP.md

---

boundary.md Add boundary-layer invariants for module interfaces and ownership contracts +119/-0

Add boundary-layer invariants for module interfaces and ownership contracts

• Introduces boundary rules covering accessors/encapsulation, typed events over callbacks, and preventing cross-module type leakage. Adds render-facing boundary invariants (DMA-BUF ownership transfer, Vulkan result checking, destruction ordering) plus code/comment and header guard conventions.

docs/policies/boundary.md

---

liveness.md Add liveness-layer invariants for hot-reload, frame progress, and shutdown +53/-0

Add liveness-layer invariants for hot-reload, frame progress, and shutdown

• Defines progress guarantees for shader hot-reload (non-blocking recordability), per-frame pipeline advancement without deadlock, and compositor event-loop termination/shutdown boundedness. Includes explicit guard predicates and “Escapes” rationales for why static tools can’t enforce these properties.

docs/policies/liveness.md

---

process.md Add process-layer invariants for lifecycle, threads, globals, and mediators +63/-0

Add process-layer invariants for lifecycle, threads, globals, and mediators

• Documents process-lifetime rules: ownership-driven lifecycle ordering, structural thread ownership boundaries, restrictions on global mutable state, and a prohibition on runtime mediator “god objects.” Each rule is expressed in the shared Guard/Safety/Locked/Free schema.

docs/policies/process.md

---

resource.md Add resource-layer invariants for swapchain, DMA-BUF import, and wlroots listeners +65/-0

Add resource-layer invariants for swapchain, DMA-BUF import, and wlroots listeners

• Specifies lifecycle and rollback expectations for swapchain recreation and DMA-BUF import (including fd dup/release semantics). Adds a compositor rule ensuring wlroots listeners are attached/detached in a way that prevents use-after-free on signal callbacks.

docs/policies/resource.md

---

sync.md Add sync-layer invariants for Vulkan fences/semaphores and cross-thread channels +63/-0

Add sync-layer invariants for Vulkan fences/semaphores and cross-thread channels

• Documents semaphore import/retire rules for DMA-BUF sync fds, the fence-before-acquire requirement for per-frame resource reuse, and invariants for compositor↔main thread handoff. Emphasizes copy-under-lock/dup semantics and encourages typed channels over ad-hoc shared mutable state.

docs/policies/sync.md

---

project_policies.md Restructure project policies into layered invariants with a formal rule schema +321/-270

Restructure project policies into layered invariants with a formal rule schema

• Rewrites the document into a v2.0 layered invariant model (Process/Boundary/Resource/Sync/Liveness) and defines a consistent rule schema (Guard/Safety plus required Escapes and Locked/Free). Adds an agent self-check protocol, a layer selection guide, and a gate-migration log, while moving many concrete invariants into the appropriate layers and scopes.

docs/project_policies.md

---

Other (1)

filter-chain Bump filter-chain submodule to a newer pinned commit +1/-1

Bump filter-chain submodule to a newer pinned commit

• Updates the submodule pointer from d053e43… to e9ce587…. This effectively changes the pinned external filter-chain implementation used by the project without modifying in-repo source.

filter-chain

---

[coderabbitai]

Warning

Review limit reached

@K1ngst0m, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 34 minutes and 59 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 50aeaf85-f302-4afa-b155-a73c107682a8

📥 Commits

Reviewing files that changed from the base of the PR and between 9532e82 and 7a578af.

⛔ Files ignored due to path filters (1)

• pixi.lock is excluded by !**/*.lock

📒 Files selected for processing (8)

• ROADMAP.md
• docs/policies/boundary.md
• docs/policies/liveness.md
• docs/policies/process.md
• docs/policies/resource.md
• docs/policies/sync.md
• docs/project_policies.md
• filter-chain

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/policy-invariant-model

---

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

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0)

1. Headless init policy mismatch 🐞 Bug ≡ Correctness

Description

PROC.app.001’s Safety defines a single init sequence that includes SDL/ImGui/shader system even in
headless mode, but Application::create_headless() does not initialize those subsystems. This makes
the new policy rule incorrect for headless execution and can lead to wrong enforcement or refactors
of the startup/shutdown path.

Code

docs/project_policies.md[R61-64]

+### PROC.app.001 — Subsystem init/destroy ordering

----
+**Guard:** Modifying `Application::create()`, `Application::shutdown()`, the `run_app()` function in `main.cpp`, or the initialization/destruction sequence of any top-level subsystem.
+**Safety:** Init: logger → signal FD (headless only) → SDL → VulkanBackend → ImGuiLayer → shader system → CompositorServer. Destroy: ImGuiLayer → CompositorServer (thread joins) → VulkanBackend → SDL. Compositor thread must join before VulkanBackend destruction.

Evidence

The policy text states headless init includes SDL/ImGui/shader system, but the actual headless
factory only creates the headless Vulkan backend and compositor server (no SDL/ImGui/shader system).

docs/project_policies.md[59-65]
src/app/application.cpp[222-258]
src/app/main.cpp[540-558]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`docs/project_policies.md` introduces `PROC.app.001` with a Safety init/destroy ordering that doesn’t match the actual headless code path. In headless mode the app skips SDL/ImGui/shader-system init, so the documented sequence is false and can cause incorrect review/agent enforcement.

### Issue Context
- Windowed path constructs SDL → VulkanBackend → ImGuiLayer → shader system → CompositorServer.
- Headless path constructs VulkanBackend(headless) → CompositorServer(headless) (no SDL/ImGui/shader system).

### Fix Focus Areas
- Update `PROC.app.001` Safety to explicitly define **two** sequences (windowed vs headless), or make the SDL/ImGui/shader-system steps explicitly conditional.
- Ensure the destroy ordering section likewise reflects headless vs windowed teardown.

- docs/project_policies.md[61-72]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---