# Source dossier and model boundaries

The lessons, examples, exercises and diagrams are original Ivy material.
Purchased books stay outside the repository and local server. Required
explanations are self-contained; optional reading does not require a purchase.
Full-book ingestion has not been done. A file in a library index is not evidence
that its contents were inspected.

## Objective-to-source map

| Outcome | Source support | Authored model or evidence boundary |
| --- | --- | --- |
| O1: objects, addresses and contiguous space | Kubica chapters 1/3; Stoakes introductory physical/virtual memory passages below | Fixed slots, lowest-fit allocation and release API are teaching choices |
| O2: graph versus layout and line traffic | MIT lecture 23 and notes; Kubica chapter 11 | 64-byte fully associative LRU is specified by the exercise, not inferred from a CPU |
| O3: tracing and reachability | Go GC guide, Tracing Garbage Collection; Green Tea article, Objects and pointers / The mark-sweep algorithm | Stopped-world synthetic heap; valid pointer precondition; independent finite checks |
| O4: page and line distinctions | Stoakes selected passages; Go 1.25.0 size constants; Green Tea graph explanation | Configurable model pages do not implement OS address translation |
| O5: page scheduling, discovery and scanning | Green Tea, Green Tea example; Go 1.25.0 `scanSpan` / `spanSetScans` | Public Go API and trace contract are Ivy designs, not runtime APIs |
| O6: bounded performance claims | Go testing benchmark documentation; Go GC guide, Understanding costs | Original traversal benchmark; no measured benefit is assumed and no runtime-GC effect is established |
| O7: source-reading and counterexample | Dated Green Tea article; pinned Go files below | Runnable fresh capstone with a separate explanation; no independent learner-gain evidence yet |

## Public primary sources inspected for this continuation

Accessed 2026-10-11 unless noted. These links support mechanisms, not a claim
about what Go version is currently the default on a learner's machine.

- Michael Knyszek and Austin Clements, [The Green Tea Garbage Collector](https://go.dev/blog/greenteagc),
  published 2025-10-29. Inspected Objects and pointers, The mark-sweep algorithm,
  The problem, Green Tea example, Vector acceleration and Evaluation. The course
  uses the distinction between discovering an object and scanning its pointers,
  and the possibility that delayed page work accumulates useful batches. The
  evaluation is the authors' workload evidence, not a course benchmark result.
  Its release plans are historical statements; this course does not assert a
  current default collector. No screenshots or source diagrams are republished.
- [A Guide to the Go Garbage Collector](https://go.dev/doc/gc-guide), especially
  [Tracing Garbage Collection](https://go.dev/doc/gc-guide#Tracing_Garbage_Collection)
  and [Understanding costs](https://go.dev/doc/gc-guide#Understanding_costs).
  Inspected the definitions of roots/reachability and the distinction between
  work per collection and collection frequency. The guide presents a simplified
  cost model. The course does not derive a hardware time from its toy miss count
  or claim a particular GOGC setting is appropriate for a learner's program.
- Go source, release tag **go1.25.0**:
  [internal/runtime/gc/sizeclasses.go, lines 84–92](https://github.com/golang/go/blob/go1.25.0/src/internal/runtime/gc/sizeclasses.go#L84-L92)
  defines `PageShift = 13`. This supports the version-specific 8 KiB runtime
  unit in lesson 04; it says nothing about the learner's OS page size.
- Go source, release tag **go1.25.0**:
  [runtime/mgcmark_greenteagc.go, lines 5–33](https://github.com/golang/go/blob/go1.25.0/src/runtime/mgcmark_greenteagc.go#L5-L33),
  [scanSpan, lines 587–639](https://github.com/golang/go/blob/go1.25.0/src/runtime/mgcmark_greenteagc.go#L587-L639),
  and [spanSetScans, lines 646–687](https://github.com/golang/go/blob/go1.25.0/src/runtime/mgcmark_greenteagc.go#L646-L687).
  Inspected the sparse-object path and the pending-object bitmap operation.
  Lesson 08 points out that comments around lines 661–663 describe an
  intersection while the expression on line 673 computes a set difference.
  Source interpretation follows the executable operation. The pinned file's
  introduction describes further scan-loop specialization as unfinished;
  the later blog's vector path is not silently attributed to this release.
- Go source, release tag **go1.25.0**:
  [runtime/mgc.go, lines 5–10](https://github.com/golang/go/blob/go1.25.0/src/runtime/mgc.go#L5-L10).
  Inspected the runtime's stated concurrency, parallelism and barrier behavior
  to identify what the course's stopped-world model omits. These properties
  are version-specific source observations, not implemented course features.
- [Go testing package: Benchmarks](https://pkg.go.dev/testing#hdr-Benchmarks).
  Inspected the benchmark entrypoint, operation timing and allocation reporting.
  The course records actual Go traversal timings separately from trace counters.
  This living documentation may describe newer APIs; the course uses the
  conventional benchmark interface compatible with its declared Go baseline.
- MIT 6.046J, Erik Demaine, Spring 2015,
  [lecture 23: Cache-Oblivious Algorithms: Medians & Matrices](https://ocw.mit.edu/courses/6-046j-design-and-analysis-of-algorithms-spring-2015/resources/lecture-23-cache-oblivious-algorithms-medians-matrices/).
  Prior course inspection used bundled transcript lines 59–130. The official
  lecture page and [lecture notes, page 1](https://ocw.mit.edu/courses/6-046j-design-and-analysis-of-algorithms-spring-2015/ed590b1c1f41cdef211fa49dc62dc8f1_MIT6_046JS15_lec23.pdf)
  were revisited for memory hierarchy, blocking, spatial locality and temporal
  locality. No historical latency illustration is presented as current hardware
  measurement.

## Previously inspected owned-book excerpts

These inspection notes are retained from the pilot; the books were not reopened
or fully re-ingested for this continuation. Their role is optional context,
not new evidence about implementation or measurement.

- Jeremy Kubica, *Data Structures the Fun Way*, owned EPUB in
  `books-2026-09-03.zip`. Inspected `OPS/c01.xhtml`, Variables, Composite Data
  Structures and Arrays; `OPS/c03.xhtml`, The Limitations of Arrays and Pointers
  and References; `OPS/c11.xhtml`, Introducing Caches. Chapters 1 and 3 support
  the object/address vocabulary; chapter 11 discusses caches more broadly than
  CPU lines. Exact line sizes and LRU behavior are Ivy's model choices.
- Lorenzo Stoakes, *The Linux Memory Manager*, early access edition 2025-02-07,
  `_EA_Linux_Memory_Manager_21025.pdf`. Inspected printed pages 5–7 (PDF pages
  20–22), physical memory and base pages; printed pages 123–126 (PDF pages
  138–141), virtual memory and page tables. Figure 2-5 was visually inspected for
  its distinction between metadata layout and memory itself. The early-access
  edition may differ from the final book. Linux listings are optional later
  depth and are not prerequisites for the model scheduler.

## What the experiments model

01–03 use a bounded synthetic address space. Objects do not move and the graph
does not change during collection. The retained locality visual performs one
logical load per visited object; it models neither all instructions nor all
pointer slots in a production collector.

06 and 08 use the separate [trace contract](CONTRACT.md): one modeled access
per outgoing pointer slot, eight bytes per pointer, addresses supplied by the
scenario, and separately recorded metadata operations. A leaf scan has no
pointer-slot access. Configurable `page_bytes`, `line_bytes` and `cache_lines`
are declared with each trace. Page visits do not imply OS page faults. Fully
associative LRU omits set conflicts, prefetch, TLBs, writes, coherence, multiple
cache levels, NUMA and memory-level parallelism. The model counts are not
nanoseconds, energy, hardware misses or speedups.

05 measures real execution of the supplied Go traversal and the learner's two
implementations over arrays/indices. It does not run either synthetic collector
inside the Go runtime. Construction, traversal policy, allocation, layout, size,
shape and measurement conditions must be distinguished. Results depend on the
recorded source, configuration, toolchain and machine. Repeated samples improve
inspection; they do not guarantee a particular distribution or generalization.

All public figures use original data. Preserve first submissions, assistance,
repairs, raw timings and configuration. Code-check agreement, visual quality,
source fidelity and learner transfer need different evidence. Human first-time
trials and independent learning-effect evaluation remain unestablished.