Log

[2026-04-24] update | P1.5b/c + P2.2 + P2.5 pre-launch gate complete

Work completed this pass

• P1.5b — Acknowledgements page (src/acknowledgements.typ): two-branch #if demo-mode design. Demo: short CTA + resource links + AI colophon. Paid: warm opener, author bio, AI credits grid (Claude/Codex/Gemini), CACHEalots!! shoutout, resource links grid. Committed and pushed.
• P1.5c — “Where to go from here” page (src/where-to-go.typ): paid tiers only, included before acknowledgements. Sections: Practice, Go Deeper on Systems (Kerrisk, Stevens), Compilers (Crafting Interpreters), Concurrency (McKenney), Kernel Development, Keep Building. Committed and pushed.
• P2.2 — Two new Ch12 intermediate exercises added between Ex 12.2 and Ex 12.3:
  • Ex 12.2b: decode_instruction(uint8_t *rom, uint16_t pc) — returns opcode/operand/length struct, tests 10 sequences including CB-prefixed opcodes
  • Ex 12.2c: parse cartridge header — fread 0x150 bytes, verify Nintendo logo, extract title/type/ROM size, header checksum. Annotated solutions for both included. Committed and pushed.
• P2.5 (pre-launch) — Two diagrams added:
  • Ch01: compilation pipeline (source.c → preprocessor → compiler → assembler → linker) with stop-flag caption
  • Ch03: process virtual address space (x86-64 Linux) — two-column layout, left address column in New Computer Modern Mono, right column with colored segment bands (Stack/gap/Heap/BSS/.data/.text). Committed and pushed.
• P1.8 gate: clear. Both pre-launch gate items (P2.2 + P2.5 diagrams 1+3) are shipped.

Wiki changes this pass

• source-companion-pdf.md: updated status, page counts, new content inventory
• log.md: this entry

[2026-04-21] update | P1.5 complete; workspace meta repo; plan archiving

Work completed since last log entry

• P1.5: exercise feedback callouts (#exercise-feedback) inserted into all 36 exercises across 12 chapters — committed and pushed to VHCosta/llc-companion-pdf
• Workspace meta repo: VHCosta/csl created (private). csl/ root is now a git repo. STATUS.md and plans/ added. csl-tools standalone repo retired; scripts folded into tools/bash/ and tools/win/.
• Plan archiving: reviews-and-plans-apr20-2026/ (raw AI reviews) archived under plans/archive/; two completed companion PDF plans archived under reviews/archive/2026-04-plans/

Wiki changes this pass

• source-csl-tools.md: marked retired, updated to reflect folding into meta repo
• meta-workspace-tooling.md: updated workspace shape diagram, csl-tools → tools/ references, design rule
• meta-project-status.md: updated for P0–P1.5 completion; added workspace meta repo; updated remaining work to P1.6–P1.8 and audit
• overview.md: updated Open Work section

Verification

• llc-companion-pdf/tests/run_all.sh: 48/48 pass (unchanged baseline)
• VHCosta/csl initial commit: 21 files, pushed to main

[2026-04-17] ingest + prune | implementation-gap assessment + validation wording fix

Compared the live repos after the 2026-04-17 documentation cleanup pass.

Findings

• the canonical exercise count remains 48; any 47 project-state wording is stale
• the actual nuance lives in llc-course/scripts/validate.sh: it validates the live 48-exercise tree, but intentionally skips ch01/ex1_3 because that exercise is a shell/tooling task with no .c source
• the top-level plan/status surface still pointed at the older 2026-04-16 status snapshot instead of a direct implementation-gap assessment
• llc-companion-pdf/STATUS.md still carried obsolete blocker text that had already been fixed in source

Corrections made

• added llc-course/plans/implementation-gap-assessment-2026-04-17.md
• archived the superseded llc-course status snapshot under plans/archive/2026-04/status-report-2026-04-16.md
• archived the demo implementation report under llc-companion-pdf/reviews/archive/2026-04-demo/
• rewrote llc-companion-pdf/STATUS.md as a current snapshot
• updated source-course-repo, source-exercise-plan, source-exercise-qc, and meta-project-status

Fresh verification

• llc-course: npm run build passed
• llc-course: bash scripts/check-content-sync.sh passed (48 exercises aligned)
• llc-course: bash scripts/validate.sh passed across the live tree with the expected non-C skip for ch01/ex1_3
• llc-companion-pdf: bash tests/run_all.sh passed (48 passed, 0 failed)

[2026-04-16] ingest + archive | status reset to current 48 / 12 / 4 baseline

Compared the live wiki against the current llc-course, llc-companion-pdf, and c-systems-lab-exercises repos after the 2026-04-15 revision closeout and 2026-04-16 doc-pruning pass.

Findings

• the wiki still carried stale 47-exercise state on multiple source/status pages
• several pages still described the PDF as appendices A-C instead of the current 4-appendix baseline
• open-work summaries still stopped at the demo-build stage and did not reflect the current publish-readiness gate
• source pages still pointed at top-level plan/review docs that were now better treated as archived history

Corrections made

• updated overview, meta-project-status, source-companion-pdf, source-course-repo, source-exercise-plan, source-exercise-qc, meta-gb-emulator, meta-terminal-plan, and index
• reset current factual baseline to:
  • 48 exercises
  • 12 chapters
  • 4 appendices
  • 48/48 validation/test status across the canonical and PDF exercise trees
• recorded the new archive locations for:
  • llc-course/plans/archive/2026-04/
  • llc-companion-pdf/reviews/archive/2026-04-revision-pass/
• reframed current frontier as:
  • PDF publish-readiness gate
  • follow-on llc-course truth/consistency review

Source report

• current cross-repo snapshot saved to llc-course/plans/archive/2026-04/status-report-2026-04-16.md

[2026-04-15] ingest | wiki packaging-doc sync

Checked the live wiki against the current llc-course repo after the 2026-04-15 packaging update.

Drift found

• [[source-course-repo]] still showed the older section-type list and did not mention the new python3 zip fallback in scripts/dist.sh
• [[source-exercise-plan]] still documented scripts/dist.sh as using only zip or PowerShell fallback

Corrections made

• refreshed [[source-course-repo]] (updated: 2026-04-15)
• expanded the section-type snapshot to include action, shell, and expect
• updated both source pages to reflect the current dist.sh packaging behavior: zip, python3 zipfile, or PowerShell Compress-Archive

[2026-04-15] audit | wiki drift check and source-page corrections

Compared the live wiki against the current llc-course, llc-companion-pdf, and c-systems-lab-exercises repos after the 2026-04-15 repo updates.

Findings

• high-level status pages were mostly current
• [[source-companion-pdf]] had real structural drift:
  • described a non-existent local content/ tree
  • described non-existent local scripts/validate.sh / scripts/export.sh
  • implied the repo had replaced tests/ with a canonical-content workflow
• [[source-exercise-plan]] still documented scripts/dist.sh as producing only 3 upload folders, but the current script assembles 4 (tier-0-sample through tier-3-complete)
• [[source-product-strategy]] still said the PDF tier covered 11 chapters and treated ch12 as an unresolved strategic question
• [[meta-gb-emulator]] still referred to “all 3 PDF tiers” instead of the current 4-output build

Corrections made

• updated [[source-companion-pdf]] to match the actual repo layout (src/, fonts/, tests/, out/, build.sh) and clarified that canonical exercise authoring lives in llc-course/content/
• updated [[source-exercise-plan]] to document the current 4-folder dist/ packaging output
• updated [[source-product-strategy]] to reflect 12 shipped PDF chapters and mark the ch12 question as resolved
• refreshed audit dates in [[overview]], [[meta-project-status]], and [[meta-gb-emulator]]

Verification target

• run wiki typecheck / formatting check
• run Quartz build after doc updates

[2026-04-14] feature | demo PDF implemented

PDF (VHCosta/llc-companion-pdf)

Implemented the free sample/demo build as a hybrid sample edition.

• build.sh now produces out/companion-demo.pdf
• src/main.typ now supports --input demo=true
• demo edition is a curated sample, not a free slice of the full Complete tier
• demo includes:
  • Chapters 1-3 only
  • selected solutions 1.2, 2.2, 3.2
  • one full extended project: ch03 / Implement the String Library
• demo excludes:
  • Chapters 4-12
  • appendices A-C
  • all other solution blocks
  • all other extended projects
• title page and intro are now sample-aware
• product/docs surfaces updated: README.md, GUMROAD.md, STATUS.md
• implementation report added: llc-companion-pdf/reviews/archive/2026-04-demo/demo-pdf-implementation-report-2026-04-14.md

Verification

• PATH=/tmp/typst-toolchain:$PATH bash build.sh passed
• bash tests/run_all.sh passed: 47/47
• current local page counts:
  • companion.pdf: 143
  • companion-demo.pdf: 37
  • companion-solutions.pdf: 223
  • companion-complete.pdf: 236
• rendered demo checks:
  • sample badge present
  • only solutions 1.2, 2.2, 3.2 present
  • only ch03 extended project present
  • no appendices
  • no ch04 content

Current frontier

• upload companion-demo.pdf to Gumroad as the $0 entry point
• ensure the live Gumroad copy/files match the local demo-aware build

Updated: source-companion-pdf, source-course-repo, overview, meta-project-status, index.

[2026-04-14] ingest + polish | PDF product cleanup + current frontier

PDF (VHCosta/llc-companion-pdf)

Local product polish pass completed and verified.

• Tier presentation cleaned up:
  • base edition now shows one chapter-level solution access note instead of repeating per-exercise upsell boxes
  • lower tiers no longer render empty Extended Project headings
• ch01 extended project is now real content (“Multi-file build system”), not a placeholder shell
• draft prose removed from ch01 solutions
• title-page badges corrected to factual stable claims (47 Exercises, 12 Chapters, 3 Appendices) instead of a false 200+ Pages
• GUMROAD.md corrected from 48 exercises to 47 exercises
• Appendix C bundle layout documentation updated to match the actual paid export structure

Verification

• bash build.sh passed
• bash tests/run_all.sh passed: 47/47
• current locally rebuilt page counts:
  • companion.pdf: 143
  • companion-solutions.pdf: 223
  • companion-complete.pdf: 236
• rendered text sweep clean for: TODO, FIXME, wait, let's verify, 48 exercises, 200+ Pages

Current frontier

• free sample/demo PDF (companion-demo.pdf, ch01-ch03) still planned — see llc-course/plans/DEMO_PDF_PLAN.md
• manual Gumroad asset/copy sync may still be required so the live listing matches the latest local PDF build

Updated: source-companion-pdf, overview, meta-project-status, index, CLAUDE.md.

[2026-04-13] ingest | PDF ch12 complete + new plan documents

PDF (VHCosta/llc-companion-pdf)

ch12 — Game Boy Emulator (capstone) — written and integrated as of 2026-04-12. This is a PDF-exclusive chapter with no web module counterpart.

Structure: intro → key concepts → going deeper (4 sections) → real-world connection (SameBoy) → 4 exercises + solutions → extended project.

Key Concepts: SM83 register file (A/B/C/D/E/H/L/F flags; PC/SP 16-bit), 64 KB memory map with region table, cartridge header layout (0x0147 type, 0x014D checksum), PPU/scanline renderer model.

Going Deeper:

1. Cycle accuracy vs. functional emulation — functional target for a first emulator; Blargg cpu_instrs pass standard
2. Opcode dispatch: switch vs. 256-entry function pointer table (connects to Module 4 / function-pointers)
3. Memory bank controllers — MBC1 and MBC3; rom bank paging at 0x4000–0x7FFF
4. Pixel FIFO vs. scanline renderer — practical model sufficient to boot Tetris

Real-world connection: SameBoy Core/mbc.c — GB_map_mbc_bank + function pointer per MBC type, mirroring the CPU dispatch table pattern.

Exercises: ex12_1 (SM83 register file with flag getters/setters), ex12_2 (memory bus dispatch), ex12_3 (opcode subset with 256-entry function pointer table), ex12_4 (ROM loader with header parse + checksum validation + test_rom.gb).

Extended project: get Tetris booting — full SM83 opcode set, scanline PPU, SDL2 display at 59.7 fps; PPM fallback via -DNO_SDL.

Metadata updated: STATUS.md (47/47 tests, ch12 row, page count rebuild pending), COMPANION.md (ch12 row), GUMROAD.md (48 exercises / 12 chapters), main.typ (ch12 include + “12 chapters” title).

New plan documents (VHCosta/llc-course)

plans/DEMO_PDF_PLAN.md — plan for a free sample PDF covering ch01–ch03. Implementation: demo=true flag in main.typ, new companion-demo.pdf target in build.sh, title-page watermark. Distribution: $0min/$5 suggested tier on Gumroad. No separate content — ch01–ch03 are the sample. Not yet implemented.

plans/GB_EMULATOR_PLAN.md — detailed implementation plan for ch12 (now complete).

plans/TERMINAL_DECISION.md — formal decision to build the companion binary first, defer WASM. Rationale: target audience already has gcc; WASM only covers 4 of 10 modules; TinyCC/Emscripten choice is a genuine blocker; companion has compounding value (Valgrind, ASan, test diffs). Already ingested into meta-terminal-plan.

Updated: source-companion-pdf (ch12 added, exercise count 43→47, status updated), meta-project-status (ch12 row + “complete” status), overview (12 chapters, Open Work updated), source-course-repo (3 new plan files in documents table).

[2026-04-13] feature + infra | Companion setup modal + CI/CD pipeline

Web app (VHCosta/llc-course)

Added CompanionSetup.jsx — a proper guided setup modal replacing the scattered ghost-text companion hint and raw GitHub URL. Two tabs:

• Companion App tab: OS selector (macOS Apple Silicon / Intel / Linux / Windows/WSL2), curl install command, copy button, blinking status dot, live useCompanion() detection bar that turns green with “Done ✓” when companion connects.
• Manual Setup tab: per-OS gcc install command (xcode-select / apt / pacman / WSL2 apt), macOS/Windows contextual notes, gcc --version verify block.

Integrated into App.jsx (showSetup state), LessonView.jsx (replaced span+link with set up C environment → button; auto-triggers once per session on first M5+ visit when companion absent, gated by sessionStorage), and Terminal.jsx (DISCLAIMER_LINES no longer contain raw GitHub URL).

CI/CD pipeline fixed

GitHub Actions deploy workflow (deploy.yml) was failing since creation: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets were never set in repo settings. Added both secrets → workflow now passes. Auto-deploy on push to master is active.

Updated: source-course-repo, meta-project-status, meta-terminal-plan.

[2026-04-11] lint | Wiki health audit

Full wiki lint pass per CLAUDE.md schema.

Orphans: None. All 44 pages have inbound links.
Module lesson tables: All 10 modules complete (IDs, titles, durations).
PDF parity: All 11 chapters verified against /pdf/STATUS.md — all match.

Fixes applied:

• m07 Key Concepts: copy-on-write, signal-mask, pipes were plain-text with no pages. Created concept pages [[pipes]], [[copy-on-write]], [[signal-mask]]; wired wikilinks.
• m08 Key Concepts: select-poll-epoll, tcp-state-machine, non-blocking-io, http-protocol were plain-text. Created [[select-poll-epoll]] and [[tcp-state-machine]]; removed non-blocking-io and http-protocol (content is inline in module page, not yet worth separate pages).
• index.md: Appendix count corrected (A–B → A–C); 5 new concept pages added; updated date bumped.
• log.md line 248: [[plan1]] broken wikilink fixed to plain text (refers to raw/plan1.md, not a wiki page).

Wiki health after lint: 49 pages (10 module, 28 concept, 5 source, 4 meta, 1 overview, 1 index, 1 log). Zero orphans. Zero broken wikilinks.

[2026-04-11] ingest + lint | Post-launch housekeeping

Ingested: current state of llc-course and llc-companion-pdf repos.

Lint findings and fixes:

• meta-wiki-hosting was stale (plan, not yet marked implemented). Updated: status IMPLEMENTED, live URL noted.
• meta-project-status pending items were stale (Gumroad upload was done). Updated current state; added “Next Work to Address” section.
• source-course-repo had stale plan file paths (GB_EMULATOR.md → plans/GB_EMULATOR.md, same for TERMINAL_PLAN.md). Fixed.
• index description for source-course-repo said “terminal rework in progress” — corrected to “planned”.

No orphan pages. All 10 module pages, 23 concept pages, 5 source pages, 4 meta pages accounted for.

Plans surfaced as next work:

1. Terminal rework — see meta-terminal-plan
2. Game Boy emulator ch12 — see meta-gb-emulator

[2026-04-11] plan | Wiki hosting

Created meta-wiki-hosting: plan for serving the wiki as a live, accessible website.

Options evaluated: GitHub Pages, Quartz + Vercel, MkDocs + GitHub Actions, Obsidian Publish, Quartz + Cloudflare Pages.

Recommendation: Quartz + Cloudflare Pages + Cloudflare Access.

• Quartz is the only option with native [[wikilink]] support (no refactoring needed)
• Cloudflare Pages is consistent with existing infrastructure (web app is already there)
• Cloudflare Access provides free SSO-based gating (Google/GitHub login, no password to manage)
• Automatic deploy on git push — fits the existing Claude Code workflow
• Custom domain (wiki.csystemslab.com) available via existing Cloudflare DNS

Implementation steps documented: Quartz scaffold, local verify, Cloudflare Pages deploy, Access policy, custom domain.

[2026-04-11] polish | Web app terminal rework + UI fixes

Work done on the llc-course web app (all committed, pushed, and deployed to Cloudflare Pages):

Bug fixes:

• Browser tab title: removed “Personal Course” suffix → now just “C Systems Lab”
• Sidebar: added 10px gap between the ← collapse arrow and the course title (was 0, visually cramped)
• Terminal collapsed state: output area was bleeding through on initial load and after re-collapsing. Root cause: flex: 1 on the output div doesn’t zero it when the container is exactly header + input height, and padding still rendered. Fixed by setting flex: 0 / overflow: hidden / padding: 0 on the output div when closed.
• Terminal backdrop: clicking the dim overlay above an expanded terminal was removing the dim but not collapsing the terminal. Root cause: Terminal owned its own open state via useState(defaultOpen), so LessonView’s setTerminalExpanded(false) had no effect. Fixed by making Terminal fully controlled — open and onToggle are now props; LessonView is the single source of truth.

Behaviour:

• Terminal remains behind the ”▸ TERMINAL (experimental)” opt-in button (user preference; always-visible drawer was considered but reverted)
• When shown: title bar + input always visible (80px); click header or focus input to expand to full 324px with output
• Clicking the backdrop (semi-transparent overlay above the terminal) collapses it
• Red traffic light closes the terminal entirely, returning to the opt-in button
• ? button in title bar prints a disclaimer explaining why the terminal is simulated

Plan document created:

• TERMINAL_PLAN.md added to the llc-course repo root — see meta-terminal-plan

[2026-04-11] milestone | PRODUCT LIVE

C Systems Lab companion PDF and exercise code pack uploaded to Gumroad and live.

• URL: vhcosta.gumroad.com/l/c-systems-lab
• Tiers: PDF ($18)\cdot PDF+Solutions($28) · Complete ($38)
• Public exercises repo: VHCosta/c-systems-lab-exercises — README updated with Gumroad link, re-pushed
• All publish checklist items complete. See meta-project-status.

[2026-04-11] tooling | dist.sh + cover redesign + publish prep

• PDF cover redesigned: dark #0D0D0F background, Space Grotesk Bold title (72pt → 54pt to fit one line), amber accent bar, pill badges with amber tint. Matches Gumroad cover aesthetic. Static SpaceGrotesk-Bold.ttf added to pdf/fonts/.
• scripts/dist.sh created: single command assembles all Gumroad upload files. Builds PDFs via pdf/build.sh, exports exercises via export.sh, zips via zip or PowerShell fallback, assembles dist/tier-{1,2,3}-*/ with correct files per tier.
• scripts/export.sh fixed: zip step no longer hard-fails when zip not on PATH (Windows-safe).
• dist/ assembled: tier-1-pdf (1.9MB PDF + 76KB starters), tier-2-solutions (3.0MB + 116KB paid), tier-3-complete (3.1MB + 116KB paid). Ready for Gumroad upload.
• Trackers updated: pdf/STATUS.md, obsidian/wiki/meta/meta-project-status.md, obsidian/PROGRESS.md trimmed.

Remaining: upload dist/ files to Gumroad; update exports/public/README.md with Gumroad URL and re-push exercises repo.

[2026-04-10] audit | Exercise Quality Control

Full QC pass across all 43 exercises. Three issues found and resolved:

1. Solutions leaked in public repo — 8 exercises (ch02/ex2_1, ch02/ex2_3, ch03/ex3_3, ch05/ex5_1, ch05/ex5_4, ch06/ex6_2, ch06/ex6_3, ch07/ex7_3) contained full reference solutions. Correct stubs confirmed in content/. Public repo history rewritten as orphan branch (single clean commit) and force-pushed to purge solutions from git history.

2. ch01 numbering gap — ex1_4 renamed to ex1_3 in content/, meta.json, prompt.md, and public repo. Gap was a scar from a previously cut exercise; total count (43) was always correct.

3. Paid export structure — export.sh fixed: solutions now in solutions/ subdir rather than silently overriding stubs. Zip step added to both export modes.

Structural audit: 43/43 exercises have prompt.md, meta.json, starter/, solution/. 42/43 have TODO markers in starter (exception: ch04/ex4_3 is a bug-hunt exercise using /* BUG: */ markers — correct by design).

Compilation validation not re-run (no gcc on Windows host). Re-run validate.sh on Linux to confirm 43/43 PASS after rename.

See source-exercise-qc for full detail.

[2026-04-07] ingest | LLC Course Web App

Initial ingest of llc-course-master repo. Created 10 module pages (m01–m10) with lesson tables, project info, concept links, and PDF status. Created source summary page.

[2026-04-07] ingest | LLC Companion PDF

Initial ingest of llc-companion-pdf-master repo. Documented chapter completion status (ch01 written, ch02–10 stubs). Created source summary page.

[2026-04-07] create | Concept Pages

Created 23 concept pages covering all major C topics in the curriculum: compilation pipeline, types, memory layout, undefined behaviour, pointers, arrays, function pointers, malloc, memory safety, valgrind, arena allocators, structs, unions, preprocessor, file descriptors, fork, signals, sockets, threads, mutexes, atomics, assembly, cache/performance.

[2026-04-07] create | Wiki Scaffold

Created CLAUDE.md (schema), overview.md, index.md, log.md, meta-project-status.md. Wiki is operational.

[2026-04-08] restructure | PDF chapter renumbering — 11-chapter structure

Resolved the web module ↔ PDF chapter mapping mismatch. PDF now has 11 chapters with 1:1 parity to web modules (m1 gets two chapters because it is wide enough to warrant it; all other modules map to exactly one chapter).

Changes to PDF source (pdf/src/chapters/):

• ch03.typ: replaced “Functions and the Stack” stub → “Pointers and the Memory Model” (m2). New stub with 4 exercises (address mapping, bounds-checked string copy, pointer arithmetic, const-correct list) and extended project “Implement the String Library”.
• ch04.typ: replaced merged “Pointers and Memory” stub → “Dynamic Memory” (m3). New stub with 4 exercises (Valgrind-clean list, slab allocator, ASan bug hunt, arena allocator) and extended project “vec_t”.
• ch05.typ: Structs/Unions/Bit Fields (m4) — content unchanged, chapter number stays ch05. ✅
• ch06.typ: replaced “File I/O” stub → “The C Preprocessor” (m5). New stub with 4 exercises (macro pitfall repair, _Generic min/max, platform detection, X-macro state machine) and extended project “Debug Logging System”.
• ch07.typ: File I/O and System Calls (m6) — content from old ch06, renumbered exercises to 7.x.
• ch08.typ: Processes and Signals (m7) — content from old ch07, renumbered to 8.x.
• ch09.typ: Sockets and Networking (m8) — content from old ch08, renumbered to 9.x.
• ch10.typ: Concurrency (m9) — content from old ch09, renumbered to 10.x.
• ch11.typ: Going Below C (m10) — content from old ch10, renumbered to 11.x. New file.
• main.typ: added ch11 include, added web module comments to all includes.

All progress trackers updated: PROGRESS.md (new 11-chapter structure), plan1.md (priority order), plan2-chapter-mapping.md (marked resolved).

All wiki module pages updated: m05–m10 sources fields corrected (ch06–ch11), PDF Status fields rewritten, orphan wikilinks removed (exec, pipes, tcp-ip, select-poll, http, thread-sanitizer, abi, volatile, profiling). source-companion-pdf.md chapter table rewritten. meta-project-status.md chapter table rewritten.

[2026-04-08] fix | Clerical audit pass

Fixed all inconsistencies found in cross-system audit:

• Wiki module frontmatter sources fields corrected for m01–m05 (all had wrong ch references — the PDF chapter numbering does not match web module numbering)
• PDF Status fields in m01–m05 rewritten to reflect actual PDF chapter mapping
• Orphan wikilinks removed from m01, m04, m05, m06 (referenced concept pages that don’t exist: printf, data-structures, oop-in-c, macros, conditional-compilation, makefiles, buffered-io, errno, syscalls)
• Wiki index updated: source-companion-pdf entry corrected to “ch1–2 done”
• Plan1.md: priority order corrected (was using wrong chapter descriptions), done items marked, ch03 real-world connection candidate corrected
• PROGRESS.md: ch03 real-world candidate updated; pre-publish checklist author-name item marked done
• Identified open content gap: Web Module 5 (C Preprocessor) has no PDF chapter

[2026-04-08] infra | PDF Author & Repo

Set author name to “VH Costa” in pdf/src/main.typ. Updated YOUR_USERNAME → VHCosta in pdf/src/appendix/repo.typ. Private development repo identified as VHCosta/llc-companion-pdf; public exercises repo will be VHCosta/llc-companion (not yet created).

[2026-04-08] chapter | PDF ch02 — Types, Operators, and Control Flow

Wrote full PDF chapter 2. Sections completed:

• Key Concepts: integer type width table, <stdint.h> fixed-width types, signed vs unsigned arithmetic, operator precedence traps, short-circuit evaluation, ternary, switch fall-through
• Going Deeper: integer promotion + UAC, signed-overflow UB with optimiser implications, implicit conversions (fgetc, strlen, sizeof traps), preprocessor vs enum vs const
• Real-World Connection: Linux kernel include/linux/types.h, sparse type annotations, CVE-2010-3079 (endianness bug in ath9k driver)
• Exercises 2.1–2.4 with full code (promotion quiz, spot the UB, fixed-width rewrite, safe integer arithmetic)
• Solutions all four, fully annotated
• Test files: tests/ch02/ex2_1, ex2_2, ex2_3, ex2_4
• PROGRESS.md marked ch02 complete

Concept pages deepened: types, undefined-behaviour. Source page updated: source-companion-pdf. Meta status updated: meta-project-status (ch02 Stub → Done, chapter titles corrected to PDF structure).

[2026-04-08] chapter | PDF ch03 — Pointers and the Memory Model

Wrote full PDF chapter 3. Sections completed:

• Key Concepts: pointer syntax map table, arithmetic scaling formula, array decay and its exceptions, NULL, void *, double pointers, function pointer syntax disambiguation
• Going Deeper: pointer provenance & strict aliasing (C11 §6.5, memcpy exception, safe type-punning via memcpy), const-correctness (four combinations, const poison pattern, double-pointer restriction), void * and the type system (C vs C++ assignment rules, sizeof restriction, qsort idiom), function pointers (typedef, signal() canonical painful example, dispatch tables, inlining note)
• Real-World Connection: Linux kernel include/linux/list.h — intrusive linked list and container_of macro (offsetof-based struct recovery, pointer arithmetic within one allocation)
• Exercises 3.1–3.4 with full code (address space map, str_ncopy, void * arithmetic, const-correct linked list)
• Solutions all four, fully annotated with explanations of why the constraints hold
• Test files: tests/ch03/ex3_1, ex3_2, ex3_3, ex3_4
• PROGRESS.md marked ch03 complete

Concept pages deepened: pointers (full treatment: syntax map, arithmetic, decay, NULL, void *, strict aliasing, const, function pointers), memory-layout (regions table, address ranges, stack overflow, debugging tools). Module page deepened: m02-pointers-memory-model (pedagogical notes per lesson, common traps, key code examples, cross-module dependencies, PDF status). Source page updated: source-companion-pdf (ch03 Stub → Written, active frontier updated to ch04). Meta status updated: meta-project-status (ch03 Stub → Done).

[2026-04-08] chapter | PDF ch06 — The C Preprocessor

Wrote full PDF chapter 6. Sections completed:

• Key Concepts: four preprocessor operations table, object vs function-like macros, parenthesisation rule, # (stringisation) and (token paste) with examples, predefined macros table (FILE/LINE/func etc.), include guards vs pragma once, variadic macros with VA_ARGS fix
• Going Deeper: two macro bug classes (missing parens — DOUBLE/SQUARE examples; double evaluation — MAX with i++) with three fix options; conditional compilation (platform branches, feature-test macros, if defined vs ifdef with 0 vs undefined distinction); X-macro pattern (STATE_LIST → enum + string table + transitions, undef X between expansions); _Generic (type_name + safe_max examples, one-argument limitation)
• Real-World Connection: Linux kernel include/linux/kernel.h — container_of (typeof + offsetof + type-checking assignment), BUILD_BUG_ON (zero-length array compile-time assertion, contrast with _Static_assert), likely/unlikely (__builtin_expect, branch layout, when it helps)
• Exercises 6.1–6.4 with full code (5 bugs demonstrated and fixed, _Generic dispatch, platform.h with _Static_assert, X-macro SM with 5 states + 4 events)
• Solutions all four, fully annotated (do-while(0) rationale, _Generic mixed-type limitation, designated initialiser for string table, undef X requirement)
• Extended Project: “Debug Logging System” (compile-time suppression, FILE/LINE/func metadata, runtime toggle, flockfile thread safety)
• Test files: tests/ch06/ex6_1 through ex6_4 (includes platform.h as a separate header)
• PROGRESS.md marked ch06 complete

Module page deepened: m05-c-preprocessor (PDF Status Stub → Complete). Source page updated: source-companion-pdf (ch06 Stub → Written). Meta status updated: meta-project-status (ch06 Stub → Done).

[2026-04-08] chapter | PDF ch11 — Going Below C

Wrote full PDF chapter 11 (capstone). Sections completed:

• Key Concepts: inline assembly (asm volatile, output/input/clobber syntax, rdtsc example), volatile semantics, System V AMD64 ABI table (arg regs, return, caller/callee-saved, stack alignment), cache hierarchy table (L1/L2/L3/DRAM sizes and latencies), reading compiler output (5 diagnostic questions)
• Going Deeper: ABI violation example (callee-saved rbx clobber → deferred corruption in printf, struct hidden-pointer calling convention), volatile vs CPU reordering (x86 TSO works by accident, ARM/POWER breaks; correct uses: MMIO, setjmp, sig_atomic_t), MESI state machine + false sharing step-by-step trace + aligned padding fix, sum_array at -O2 vs -O0 with annotation
• Real-World Connection: Linux kernel arch/x86/include/asm/atomic.h — atomic_add and atomic_cmpxchg inline asm with LOCK_PREFIX SMP/UP conditional, four reasons kernel uses inline asm over C11 stdatomic
• Exercises 11.1–11.4 with full code (dot.s ABI-conforming assembly + C harness, false sharing benchmark with 3 versions, volatile/atomic TSan comparison with preprocessor flags, disassembly archaeology of max(a,b))
• Solutions all four, fully annotated (ABI checklist for dot.s, MESI explanation for false sharing speedup, why volatile is still a race under C11, -O0 vs -O1 assembly delta for max)
• Extended Project: “SIMD-optimized matrix multiply” (ijk/ikj/SSE2/AVX2, N=64/128/256, posix_memalign, cache-vs-SIMD crossover analysis)
• Test files: tests/ch11/ex11_1 (dot.s + ex11_1.c), ex11_2, ex11_3, ex11_4
• PROGRESS.md marked ch11 complete

Module page deepened: m10-going-below-c (PDF Status Stub → Complete). Source page updated: source-companion-pdf (ch11 Stub → Written, frontier updated to ch06–ch09). Meta status updated: meta-project-status (ch11 Stub → Done).

[2026-04-08] chapter | PDF ch10 — Concurrency

Wrote full PDF chapter 10. Sections completed:

• Key Concepts: pthread_create/join/detach lifecycle, mutex with PTHREAD_MUTEX_INITIALIZER, condition variables (wait/signal/broadcast), monitor pattern struct layout, C11 atomics (_Atomic / stdatomic.h with seq-cst and relaxed), deadlock/livelock/priority inversion definitions
• Going Deeper: C11 memory model (happens-before rules, seq-cst vs acquire/release vs relaxed with annotated two-thread example), condition variable pitfalls (spurious wakeups — while mandatory; lost wakeup race — signal must hold mutex; broadcast vs signal guidance), lock-free basics (CAS loop idiom, ABA problem, lock-free ≠ wait-free, atomics vs mutex decision table), TSan shadow memory mechanism, annotated report format, false positives
• Real-World Connection: CPython Python/ceval_gil.c — take_gil/drop_gil with relaxed atomic for drop_request on the hot bytecode path, why the GIL exists (non-atomic refcounts), PEP 703 no-GIL project
• Exercises 10.1–10.4 with full code (bounded queue + producer/consumer checksum, racy/mutex/atomic via preprocessor flags + timing, deadlock demo + consistent-ordering fix, rc_alloc/retain/release with acq_rel explanation)
• Solutions all four, fully annotated (broadcast in queue_close, why mutex is slower than atomic for scalars, consistent lock ordering generalises to N locks, acq_rel vs release-only for rc_release)
• Extended Project: “Work-stealing thread pool” (Chase-Lev deque, lock-free steal path, MESI cache analysis, benchmark spec)
• Test files: tests/ch10/ex10_1 through ex10_4
• PROGRESS.md marked ch10 complete

Module page deepened: m09-concurrency (PDF Status Stub → Complete). Source page updated: source-companion-pdf (ch10 Stub → Written, active frontier updated to ch11). Meta status updated: meta-project-status (ch10 Stub → Done).

[2026-04-08] chapter | PDF ch05 — Structs, Unions, and Bit Fields

Wrote full PDF chapter 5. Sections completed:

• Key Concepts: alignment table (char/short/int/float/double/pointer sizes and alignments), step-by-step padding derivation for struct Bad vs struct Good, sizeof and flexible array members, unions, bit fields with portability callout, designated initialisers and compound literals
• Going Deeper: full two-rule alignment model with worked examples for structs A–D, __attribute__((packed)) mechanics and costs, union type punning via C11 §6.5.2.3 (fast inverse sqrt example) and the memcpy alternative, struct layout across platforms (32/64-bit, ABI differences, portable serialisation with htonl/ntohl), designated initialisers in Linux kernel init_task
• Real-World Connection: Linux kernel include/linux/if_ether.h — ethhdr packed struct maps directly onto Ethernet frame bytes, __be16 sparse annotation, get_unaligned_be16() for ARM unaligned-access safety
• Exercises 5.1–5.4 with full code (layout prediction + _Static_assert, IPv4 header pack/unpack via memcpy, tagged union value_t with ownership, bit field register model with two implementations)
• Solutions all four, fully annotated with explanations of why strict-aliasing rules apply and when bit fields are vs aren’t portable
• Extended Project: “Binary config file serializer” (magic/version/flags bit field/CRC-32 wire format, htonl/ntohl, round-trip test, hex-dump bonus)
• Test files: tests/ch05/ex5_1 through ex5_4
• PROGRESS.md marked ch05 complete

Module page deepened: m04-structs-unions-bitfields (PDF Status Stub → Complete). Source page updated: source-companion-pdf (ch05 Stub → Written, active frontier updated to ch10). Meta status updated: meta-project-status (ch05 Stub → Done).

[2026-04-08] chapter | PDF ch04 — Dynamic Memory

Wrote full PDF chapter 4. Sections completed:

• Key Concepts: allocation function semantics table (malloc/calloc/realloc/free guarantees and traps), sizeof(*ptr) pattern, four bug classes table (leak/overflow/UAF/double-free with production failure modes), detection tools table (ASan/Valgrind/UBSan), arena allocator overview with bump-pointer code
• Going Deeper: heap allocator internals (chunk metadata layout before the returned pointer, free lists and bins, sbrk vs mmap threshold, fragmentation demo, why calloc can skip memset for fresh pages), taxonomy of memory errors (ASan shadow memory mechanism for each class, Valgrind GC scan, definitely/indirectly/possibly/still-reachable categories), ownership conventions (transfer/strdup pattern, borrow/const, arena, cleanup-via-goto idiom fully annotated), realloc invalidation problem (interior pointer danger, store offsets not pointers, realloc(NULL,n), realloc(p,0) implementation-defined)
• Real-World Connection: Redis src/zmalloc.c — PREFIX_SIZE metadata trick (size stored in 8 bytes before the pointer), zmalloc/zfree/zmalloc_size implementation, global used_memory counter driving maxmemory eviction, custom OOM handler as borrowed function pointer
• Exercises 4.1–4.4 with full annotated solutions (Valgrind-clean linked list, slab allocator with embedded free list, ASan bug hunt, arena allocator with benchmark)
• Test files: tests/ch04/ex4_1 through ex4_4
• PROGRESS.md marked ch04 complete

Module page deepened: m03-dynamic-memory (pedagogical notes per lesson, common traps, key code examples, cross-module dependencies, PDF status Stub → Complete). Source page updated: source-companion-pdf (ch04 Stub → Written, active frontier updated to ch05). Meta status updated: meta-project-status (ch04 Stub → Done). Plan updated: plan1.md in raw/ (ch04 marked done, priority order updated, ch05 is next).

[2026-04-08] chapter | PDF ch07 — File I/O and System Calls

Wrote full PDF chapter 7. Sections completed:

• Key Concepts: FILE* vs file descriptor table, stdio functions (fopen/fread/fwrite/fseek/fflush/fclose), POSIX syscall wrappers (open/read/write/close/lseek), O_ flags table, errno model, dup/dup2 and shell redirection pattern
• Going Deeper: three I/O layers table (stdio buffer → page cache → hardware) with fflush/fsync/fdatasync/O_DIRECT/O_SYNC semantics; syscall mechanics (x86-64 syscall instruction, ABI differences from C ABI, context switch cost, vDSO explanation for clock_gettime); three-table file descriptor model (per-process fd table → open file table → inode table) with fork sharing, dup sharing, O_CLOEXEC, close-then-unlink pattern; error handling discipline (EINTR retry loop, EAGAIN, partial write loop, why ignoring write return value is a production bug)
• Real-World Connection: SQLite src/os_unix.c — seekAndWrite with pwrite+EINTR retry, unixWrite partial-write loop, SQLITE_FULL vs SQLITE_IOERR_WRITE distinction, why pwrite over lseek+write for thread safety
• Exercises 7.1–7.4 with full code (buffered vs unbuffered timing with syscall count analysis, minimal cat with POSIX only, fd inheritance with three-table diagram in comments, atomic log writer with O_APPEND race explanation)
• Solutions all four, fully annotated
• Extended Project: “Streaming CSV processor” (fixed-size buffer, partial-record handling, per-column aggregates, O(columns) memory)
• Test files: tests/ch07/ex7_1 through ex7_4
• PROGRESS.md marked ch07 complete

Module page deepened: m06-file-io-syscalls (PDF Status Stub → Complete). Source page updated: source-companion-pdf (ch07 Stub → Written, active frontier updated to ch08–ch09). Meta status updated: meta-project-status (ch07 Stub → Done).

[2026-04-09] chapter | PDF ch08 — Processes and Signals

Wrote full PDF chapter 8. Sections completed:

• Key Concepts: 8-row table (fork/exec/waitpid/pipe/signal/signal-mask/volatile sig_atomic_t/setjmp-longjmp) + process vs. thread callout
• Going Deeper: COW mechanics with ASCII diagram + _exit-vs-exit callout + vfork note; signal delivery model with pending/blocked state diagram, sigaction flags (SA_RESTART/SA_SIGINFO), async-signal-safe function list, self-pipe trick pattern; setjmp/longjmp internals table (saved vs. not: callee registers yes, signal mask no, heap no, open FDs no) + sigsetjmp explanation; exec boundary table (PID/FDs/signal mask preserved; handlers/address space reset) + O_CLOEXEC callout + dynamic linker invocation sequence
• Real-World Connection: Redis src/server.c sigsegvHandler() — SA_RESETHAND/SA_ONSTACK registration, why unsafe stdlib calls are acceptable in crash-only handlers, safe alternative using write() only
• Exercises 8.1–8.4 with full annotated solutions (fork+/proc RSS measurement; sigprocmask critical section with deferred signal demo; mini shell with SIGINT parent-ignores/child-resets pattern; pipe+dup2 run_pipeline)
• Extended Project: job-control shell (process groups, fg/bg/jobs builtins, SIGCHLD reaping, tcsetpgrp terminal handoff)
• Test files: tests/ch08/ex8_1–ex8_4 (all 39 tests pass, 0 failures)
• PROGRESS.md marked ch08 complete

Module page deepened: m07-processes-signals (pedagogical notes per lesson, key code examples, cross-module dependencies, PDF status Stub → Complete). Meta status updated: meta-project-status (ch08 Stub → Done).

2026-04-09 — Ch09 Sockets and Networking written

PDF chapter ch09.typ completed (was a 120-line stub):

• Key Concepts: 8-row table (socket, bind/listen/accept, connect, send/recv, select/poll, TCP state machine, SO_REUSEADDR, non-blocking I/O)
• Going Deeper: socket FD + kernel buffers + Nagle; accept() queue model (SYN/accept queues, thundering herd); select() internals (bitmask, FD_SETSIZE, O(n), poll vs epoll); HTTP framing (CRLF, Content-Length, keep-alive, parsing pitfalls)
• Real-World Connection: Redis acceptTcpHandler() + ae event loop
• Solutions: 9.1 iterative echo, 9.2 select() multi-client, 9.3 HTTP/1.0 GET server, 9.4 Nagle measurement with TCP_NODELAY
• Extended Project: HTTP/1.1 keep-alive + pipelining server
• Test files: tests/ch09/ex9_1–ex9_4 (all compile clean, -Wall -Wextra -Werror -std=c11)
• PROGRESS.md marked ch09 complete

Module page deepened: m08-sockets-networking (pedagogical notes, key code examples, cross-module dependencies, PDF status Stub → Complete). Source page updated: source-companion-pdf (ch08 + ch09 Stub → Written; active frontier updated — all chapters done). Meta status updated: meta-project-status (ch09 Stub → Done).

[2026-04-10] status | Gumroad listing live — publish phase 6 in progress

Confirmed state of the publish pipeline:

• VHCosta/c-systems-lab-exercises is live; /repo redirect active on web app
• Gumroad listing live at vhcosta.gumroad.com/l/c-systems-lab ($18/$28 / $38 tiers); /companion redirect active
• All 3 PDF tiers built: base 142 pp, solutions 207 pp, complete 217 pp
• Appendix C URL confirmed correct in src/appendix/repo.typ

Gumroad listing copy revised: new title (“C Systems Lab — The Complete C Reference (Companion PDF)”), value-first description, fixed Appendix C contradiction, $28tiermarkedMostPopular,improved$38 description, purchase summary box. All copy in pdf/GUMROAD.md.

Remaining: upload tier PDFs to Gumroad; update exercises repo README with Gumroad URL and re-push.

Updated: meta-project-status, source-companion-pdf.

[2026-04-10] ingest | Exercise Distribution Plan

Ingested raw/pdf/plan-public-exercises-and-paid-solutions.md. Key facts:

• Three-distribution model: public exercises repo (free), paid code bundle, private authoring repo
• Canonical exercise tree: content/chNN/exN_M/ — 43 exercises (ch01–ch11), each with starter/, solution/, shared/, prompt.md, meta.json
• scripts/validate.sh: compiles all solution/ trees; 43/43 PASS
• scripts/export.sh: public mode (stubs only) → exports/public/; paid mode (full) → exports/paid/
• Phases 1–4 complete (schema, migration, validation rewiring, export tooling)
• Phases 5–6 pending: publish c-systems-lab-exercises GitHub repo, ship paid bundle on Gumroad

Created: source-exercise-plan. Updated: meta-project-status (exercise distribution section + expanded publish checklist), source-companion-pdf (structure section reflects content/ + scripts/ instead of tests/), index (new source entry).

[2026-04-10] lint | Stale overview + orphan wikilinks

• Fixed overview: PDF section updated from “in progress / only ch1 written” to “complete (pre-publish)”; Open Work updated to reflect actual remaining work (GitHub repo, Gumroad).
• Removed broken wikilinks from m07-processes-signals: copy-on-write, signal-mask, pipes (no concept pages exist).
• Removed broken wikilinks from m08-sockets-networking: select-poll-epoll, tcp-state-machine, non-blocking-io, http-protocol (no concept pages exist).