Skip to content

docs: explain why ilo has no borrow types#401

Merged
danieljohnmorris merged 1 commit into
mainfrom
feature/mem-4-no-borrow-types-doc
May 18, 2026
Merged

docs: explain why ilo has no borrow types#401
danieljohnmorris merged 1 commit into
mainfrom
feature/mem-4-no-borrow-types-doc

Conversation

@danieljohnmorris
Copy link
Copy Markdown
Collaborator

Summary

Brief mem/4: add a defensive doc section to zero-gap-specs/lessons-from-zero.md explaining why ilo deliberately has no user-visible borrow type annotations (ref<T>, mutref<T>, owned<T>). Stops future contributors from re-deriving the rationale every time the question comes up, and gives potential users a clear signal that this is a deliberate design choice with tradeoffs we can articulate, not an oversight.

Note: zero-gap-specs/ was previously kept locally outside the repo. This PR commits the lessons-from-zero doc into the ilo repo so the planning rationale is version-controlled alongside the code it justifies. The expanded section 5a is the substantive change; the rest of the file is the existing planning doc copied as-is so future edits flow through normal PR review.

What's in the diff

  • Expanded ### a) Borrow checker / ownership types in section 5 from a one-line dismissal to a full rationale citing Principles 1 (Token-Conservative) and 4 (Language-Agnostic) by name, plus the "one layer of the stack" framing from section 4h and the manifesto.
  • Added section 10e (escape analysis and linearity inference for RC elision) so the forward-link from section 5a has something to point at. Renumbered the old 10e (multi-agent orchestration) to 10f.
  • Honest about the tradeoff: RC has runtime overhead vs static ownership, and that overhead is the cost agents pay in exchange for source-token simplicity. Generous to Rust and Zero - borrow types are correct for their audiences, wrong answer for ilo's.

Test plan

Docs-only change. No code paths touched.

  • New section references Principles 1 and 4 by name
  • Forward-link to section 10 (escape analysis) resolves to a real entry
  • Tone is generous to Zero and Rust, framed as "different audience, different choice"
  • Under 250 words for the new prose block

Follow-ups

  • Public-facing memory page (separate brief, mem/5).

@danieljohnmorris danieljohnmorris merged commit 4d2a26d into main May 18, 2026
4 checks passed
@danieljohnmorris danieljohnmorris deleted the feature/mem-4-no-borrow-types-doc branch May 18, 2026 19:56
@codecov
Copy link
Copy Markdown

codecov Bot commented May 18, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant