CR: Kernel IPC Curriculum — Hierarchical Restructure

1. Change Summary

Field Value

CR ID

CR-2026-04-05-kernel-ipc-curriculum

Date

2026-04-05

Priority

P1 - High

Type

Documentation Architecture / Education

Status

Complete

Requestor

Evan Rosado

Implementor

Evan Rosado

Risk Level

Low (documentation restructure, no infrastructure changes)

Systems Affected

domus-captures education section

Predecessor

CR-2026-04-05-tmux-quantum-oss-refinement

Related CR

CR-2026-04-03-tmux-quantum-creation

2. Objective

Restructure the monolithic kernel IPC deep dive (born from the tmux clipboard bug) into a hierarchical, curriculum-style education module that follows the established domus-captures education standards. Make it adaptable (new IPC topics slot in), scalable (grows without restructuring), and hierarchical (index → individual deep-dive pages).

3. Background

The initial IPC content was written as a single flat file (ipc-environment-variables.adoc) documenting the kernel primitives behind XDG_RUNTIME_DIR, WAYLAND_DISPLAY, and DBUS_SESSION_BUS_ADDRESS. While technically valuable, it did not follow the education standard established by mature sections like Bash Tools Mastery (education/systems/bash/index.adoc).

The established pattern uses:

  • .lead paragraph

  • Philosophy quote

  • "Why X Matters" motivation table

  • Curriculum table with xref’d modules and levels

  • 4-level mastery path (week/month progression)

  • Quick reference with code examples

  • Practice method with real exercises

  • Related resources

4. Architecture

4.1. Model Followed

pages/education/systems/bash/index.adoc (307 lines) — the most mature Tier 2 education module.

4.2. New Directory Structure

pages/education/kernel/
├── index.adoc                          (existing — roadmap, added xref)
├── ipc/
│   ├── index.adoc                      (NEW — curriculum-style overview)
│   ├── tmpfs-runtime-dir.adoc          (NEW — page wrapper)
│   ├── unix-sockets.adoc              (NEW — page wrapper)
│   ├── credential-passing.adoc         (NEW — page wrapper)
│   └── environment-discovery.adoc      (NEW — page wrapper)

partials/education/kernel/ipc/
│   ├── tmpfs-runtime-dir.adoc          (NEW — deep dive content)
│   ├── unix-sockets.adoc              (NEW — deep dive content)
│   ├── credential-passing.adoc         (NEW — deep dive content)
│   └── environment-discovery.adoc      (NEW — deep dive content)

4.3. Why Partials + Pages

Each deep-dive topic is a partial included by its page. This allows tmux-quantum field-notes to reference specific partials, and future kernel pages to include the same content in different contexts. Follows the domus-* single-source-of-truth pattern.

5. Changes

5.1. Files Created (9)

File Purpose

pages/education/kernel/ipc/index.adoc

Curriculum-style overview: lead, Dennis Ritchie quote, "Why IPC Matters" table, curriculum with 4 xref’d modules + 5 future placeholders, 4-level mastery path, syscall quick reference, strace patterns, practice method, related resources

pages/education/kernel/ipc/tmpfs-runtime-dir.adoc

Page wrapper for tmpfs partial

pages/education/kernel/ipc/unix-sockets.adoc

Page wrapper for AF_UNIX/SCM_RIGHTS partial

pages/education/kernel/ipc/credential-passing.adoc

Page wrapper for SO_PEERCRED/D-Bus partial

pages/education/kernel/ipc/environment-discovery.adoc

Page wrapper for environment variable discovery partial

partials/education/kernel/ipc/tmpfs-runtime-dir.adoc

Deep dive: mm/shmem.c, VFS permissions, socket inode creation, memory model

partials/education/kernel/ipc/unix-sockets.adoc

Deep dive: socket types, SCM_RIGHTS fd passing, zero-copy architecture, kernel source map

partials/education/kernel/ipc/credential-passing.adoc

Deep dive: SO_PEERCRED vs SCM_CREDENTIALS, task_struct, struct cred, D-Bus security

partials/education/kernel/ipc/environment-discovery.adoc

Deep dive: fork()/execve() propagation, tmux update-environment filtering, live workaround pattern

5.2. Files Modified (3)

File Change

partials/nav/education.adoc

Replaced flat IPC & Environment Variables entry with hierarchical 5-entry nav under "IPC (Inter-Process Communication)"

partials/projects/tmux-quantum/field-notes.adoc

Updated xref from deleted flat page to new ipc/index.adoc

pages/education/kernel/index.adoc

Added "Hands-On Deep Dives" section with xref to IPC curriculum

5.3. Files Deleted (2)

File Reason

pages/education/kernel/ipc-environment-variables.adoc

Replaced by ipc/index.adoc + 4 module pages

partials/education/kernel/ipc-environment-variables.adoc

Replaced by 4 modular partials under ipc/

6. Scalability

Adding a new IPC topic requires:

  1. Create partials/education/kernel/ipc/<topic>.adoc (deep-dive content)

  2. Create pages/education/kernel/ipc/<topic>.adoc (page wrapper with include)

  3. Add nav entry under IPC in partials/nav/education.adoc

  4. Add row to curriculum table in pages/education/kernel/ipc/index.adoc

No existing files need restructuring. Planned future modules:

  • Pipes & FIFOs — pipe(), mkfifo(), splice()

  • Shared Memory — shmget()/shmat(), mmap(), memfd_create()

  • Message Queues — POSIX vs SysV, priority delivery

  • Netlink Sockets — AF_NETLINK, rtnetlink, genetlink

  • eventfd / signalfd / timerfd — modern fd-based IPC

7. Rollback

# Revert to monolithic structure
git -C ~/atelier/_bibliotheca/domus-captures checkout -- docs/modules/ROOT/pages/education/kernel/ docs/modules/ROOT/partials/education/kernel/ docs/modules/ROOT/partials/nav/education.adoc docs/modules/ROOT/partials/projects/tmux-quantum/field-notes.adoc

8. Related

9. Changelog

Date Author Change

2026-04-05

Evan Rosado

Initial CR — restructured monolithic IPC deep dive into hierarchical curriculum (2 deleted, 9 created, 3 modified)