Specify scope arenas, dynamic reuse, and global anchors

[TheLazyCat00]

What changed

• Split each scope arena into two lazy, non-overlapping chunk chains: fixed-size storage and dynamic backing stores.
• Move anchors into one runtime-global pool of equal-sized cells with a single free-address stack.
• Preserve one anchor identity across overwrite, movement, and cross-scope rehosting; no forwarding cells or guest repointing are needed.
• Return an anchor to the global free stack when its hosting lineage ends. Immediate reuse is safe because lexical scope rules make a surviving stale guest unrepresentable.
• Distinguish explicitly declared guest-only &T storage from a full-size T slot that remains host-capable while in guest state after rehosting.
• Define byte-based power-of-two dynamic blocks beginning at 128 bytes, with exact-size stack lookup before frontier allocation.
• Define blocks larger than 1 MiB as dedicated contiguous oversized spans addressed by one base segmented offset and size class.
• Align the memory-model story with the normative specification.

Why

Fixed-size values and hosts should remain densely inline, while only variable-sized backing stores need relocation and intra-scope reuse. Anchors have a different lifetime shape again: they must keep one stable identity across scopes, but every cell has the same size and can be recycled when the hosting lineage ends.

A global fixed-slot pool directly preserves source- and destination-scope guests across later moves. It avoids moving anchor cells, repointing guests, creating forwarding chains, or re-anchoring promoted values.

Validation

• The PR changes only spec/memory.md and stories/memory.md.
• Dynamic allocation checks the exact-size stack before the frontier.
• Ordinary blocks never cross a 1 MiB boundary; larger blocks use dedicated contiguous spans.
• Global anchor allocation checks one free-address stack before its frontier.
• Rehosting keeps one anchor identity.
• Anchor reuse requires no generation counter because the language forbids guests from outliving the hosting lineage.

Summary by CodeRabbit

• Documentation
  • Updated the memory model documentation to describe scope-based arenas for fixed-size and dynamic storage.
  • Clarified segmented addressing, untethered sentinels, allocation sizing, and oversized dynamic blocks.
  • Documented stable anchor identity across moves, promotions, and rehosting.
  • Revised lifecycle, ownership, safety, concurrency, and source/runtime terminology guidance.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: zane-lang/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4afb8840-3219-4f94-9e75-96a0bfb6f612

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The memory model now defines separate fixed-size and dynamic regions per scope, a runtime-global anchor pool, unified segmented offsets, scoped allocation reuse, and stable anchor identity across moves and rehosting.

Changes

Memory model

Layer / File(s)	Summary
Region and offset model spec/memory.md, stories/memory.md	Defines scope-owned fixed-size and dynamic regions, exclusive chunk mapping, segmented offsets, sentinel handling, and host-capable storage.
Allocation and backing-store layout spec/memory.md, stories/memory.md	Specifies bump allocation, power-of-two dynamic blocks with exact-size LIFO reuse, oversized spans, and aligned dynamic buffers.
Promotion and anchor-cell behavior spec/memory.md, stories/memory.md	Describes lazy global anchor allocation, stable anchor identity, payload-offset updates during moves and rehosting, and revised host/guest terminology.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main changes: scope arenas, dynamic reuse, and a global anchor pool.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/fix-host-overwrite-reuse

---

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

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

spec/memory.md (1)

413-418: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Do not lose source-scope anchor paths during promotion.

Promotion can leave source tethers using the old cell while destination tethers use a newly minted cell. With only one backpointer, later moves update one cell and stale the other. Define forwarding/multi-anchor semantics or prohibit re-anchoring/movement while the old cell remains live.

• spec/memory.md#L413-L418: correct the normative promotion algorithm.
• stories/memory.md#L106-L110: align the explanation with that algorithm.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@spec/memory.md` around lines 413 - 418, The promotion semantics in
spec/memory.md lines 413-418 and stories/memory.md lines 106-110 must preserve
all live source-scope anchor paths. Define forwarding or multi-anchor behavior
so subsequent moves update both the old source cell and any newly minted
destination cell, or explicitly prohibit re-anchoring and movement while the old
cell remains live; make both sections describe the same normative algorithm.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@spec/memory.md`:
- Around line 304-316: Define the representation and allocation rules for
dynamic blocks exceeding one chunk in the normative allocator section around the
dynamic block growth rules in spec/memory.md:304-316, including contiguous
multi-chunk spans and how their handles address them, or explicitly cap blocks
at one chunk. Apply the same oversized-block behavior in the corresponding
narrative at stories/memory.md:80-82 so both documents remain consistent.

---

Outside diff comments:
In `@spec/memory.md`:
- Around line 413-418: The promotion semantics in spec/memory.md lines 413-418
and stories/memory.md lines 106-110 must preserve all live source-scope anchor
paths. Define forwarding or multi-anchor behavior so subsequent moves update
both the old source cell and any newly minted destination cell, or explicitly
prohibit re-anchoring and movement while the old cell remains live; make both
sections describe the same normative algorithm.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: zane-lang/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 38120942-bcee-4ab5-9075-0622b78dc8c5

📥 Commits

Reviewing files that changed from the base of the PR and between 89083ff and 905cc5b.

📒 Files selected for processing (2)

• spec/memory.md
• stories/memory.md

[TheLazyCat00]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@spec/memory.md`:
- Line 230: Update the headings in spec/memory.md, including “3.1 Scope arenas,
the global anchor pool, and segmented offsets” and the additionally identified
headings, by inserting one blank line between each heading and its following
content to satisfy markdownlint MD022.
- Around line 403-407: Clarify the move/rehosting rules in section 4.5 for
destinations with existing anchored guests. Define how the source and
destination anchor identities and both guest sets are preserved, or explicitly
forbid this move; align the result with section 2.2 and ensure no anchor
identity can be recycled while referenced.
- Around line 274-276: Clarify the anchor-page reclamation contract in the
free-address stack description: either require wholly free anchor pages to
remain mapped while their offsets are retained, or specify that unmapping
removes all offsets for the page and updates the chunk directory and any reused
chunk IDs before reclamation. Ensure later allocations cannot pop an offset
referring to an unmapped or repurposed page.
- Around line 261-263: Align anchor-cell representation with segmented-offset
encoding by choosing and documenting either 8-byte physical cell stride/padding
or a 4-byte offset unit. Update spec/memory.md lines 261-263 to define
anchor-page addressability and alignment, reconcile the anchor-cell width and
12-byte logical cost in spec/memory.md lines 338-351, and mirror the normative
representation in stories/memory.md lines 63-69; revise all affected memory-cost
and capacity claims consistently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: zane-lang/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ff6870d4-96b8-4599-87ee-389081f9015e

📥 Commits

Reviewing files that changed from the base of the PR and between 905cc5b and 4eeedb4.

📒 Files selected for processing (2)

• spec/memory.md
• stories/memory.md