docs: add engine-owned architecture notes

[DysektAI]

User description

Summary

Engine-owned architecture register covering only RatEye concerns — no parent-app content:

• Public config surface: static vs instance state (Config.LogDebug, Path.Debug/LogFile) and the static/instance split visibility
• Lifecycle/disposal contract: RatEyeEngine.Dispose mutates the caller-supplied Config; Dispose vs DisposeStrict semantics
• Rebuild expectations: create-new-then-dispose-old pattern hosts must hand-roll today
• Thread-safety contract: single-flow per instance, IconManager reader/writer lock scope
• Nullability pre-migration baseline: ~78 CS86xx findings measured at 24f8806, with the honest-annotation warning for CS8618
• Cleared leads: disposal idempotency, lock ordering, hash-formatting/cache-key verification (69 RatEyeTest tests)

Each finding carries Status + Last verified so it can be updated rather than rediscovered. No source changes.

---

CodeAnt-AI Description

Document RatEye’s engine-owned architecture, lifecycle rules, and consumer responsibilities

What Changed

• Added an architecture register covering configuration scope, disposal behavior, rebuild procedures, threading expectations, nullability risks, and result boundaries
• Documented that processing must be serialized per engine instance and that rebuilds should create the replacement before disposing the old engine
• Recorded that disposing an engine can mutate its supplied configuration and that lookup results may legitimately be missing
• Captured cleared disposal, locking, resource-lifecycle, and hash-stability findings to prevent repeated investigation

Impact

✅ Clearer engine integration rules
✅ Safer engine rebuilds and disposal
✅ Fewer host-side threading and nullability surprises

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 17dd2b52-f8f3-4846-a863-bdfb2c1987d8

📥 Commits

Reviewing files that changed from the base of the PR and between 24f8806 and c012623.

📒 Files selected for processing (1)

• docs/architecture.md

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added architecture documentation covering system boundaries, lifecycle and disposal behavior, configuration, threading, nullability, result exposure, and consumer responsibilities.
  • Documented open findings, verification details, and resolved engine-side concerns.

Walkthrough

Added docs/architecture.md with RatEye engine boundaries, lifecycle rules, configuration findings, verified concerns, and consumer responsibilities.

Changes

Architecture Documentation

Layer / File(s)	Summary
Engine contracts and findings docs/architecture.md	Documents engine ownership, lifecycle and disposal behavior, configuration scope, rebuild sequencing, threading expectations, nullability risks, result-type exposure, and verified engine-side concerns.
Consumer boundary expectations docs/architecture.md	Documents consumer responsibilities for bitmap ownership, processing flow, engine rebuilds, result access, configuration mutation, and future nullable lookup results.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested labels: size:M

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/engine-architecture

---

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

[codeant-ai]

🏁 CodeAnt Quality Gate Results

Commit: c0126238
Scan Time: 2026-08-08 00:33:20 UTC

✅ Overall Status: PASSED

Quality Gate Details

Quality Gate	Status	Details
Secrets	✅ PASSED	0 secrets found
Duplicate Code	✅ PASSED	0.0% duplicated
SAST	✅ PASSED	No security issues
Bugs	✅ PASSED	Rating S: No bugs
IAC	✅ PASSED	No IAC issues

View Full Results

[kilo-code-bot]

SUGGESTION: Version tag v4.0.0-27 does not exist in the repository

The documentation references v4.0.0-27 as the version for commit 24f8806, but this tag is not present in the repository. Consider either removing the tag reference or confirming the correct version identifier.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

| Severity | Count |
|----------||-------|
| SUGGESTION | 1 |

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
docs/architecture.md	6	Version tag v4.0.0-27 does not exist in the repository

Files Reviewed (1 files)

• docs/architecture.md - 1 issue

Fix these issues in Kilo Cloud

---

_{Reviewed by step-3.7-flash · Input: 35.6K · Output: 4.6K · Cached: 476.2K}