Relurpic Internals on Relurpify

Chapter 1 — The Repo Is the Map

Fri, 23 Oct 2026 18:29:44 +0000

# Chapter 1 — The Repo Is the Map

Book 1 put you in the kitchen: you ran doctor, approved a diff, watched a governed turn from the operator’s chair. This book walks you into the building itself. And like any building worth entering, Relurpify comes with a blueprint — one that is unusual in one respect: the blueprint checks itself. The map of this repository is not a diagram in a document that drifts the first time someone renames a package. It is a data structure in the tree, enforced by a gate that reads the real import graph. When the map and the territory disagree, CI fails.

Chapter 2 — The Constitution, Enforced

Fri, 23 Oct 2026 18:30:11 +0000

# Chapter 2 — The Constitution, Enforced

Every sufficiently old codebase has a constitution: the set of rules everyone claims to follow and no tool enforces. It lives in a CONTRIBUTING file, it is enforced by code review and good intentions, and it loses one clause per quarter to “just this once.” Chapter 1 showed you that Relurpify’s map cannot drift silently. This chapter shows the same is true of its law: seven architecture decision records, each with a mechanism that makes it non-optional — and, because the maintainers know fences can rot, a gate that watches the fences themselves.

Chapter 3 — The Surfaces, Graded

Fri, 23 Oct 2026 18:30:27 +0000

# Chapter 3 — The Surfaces, Graded

Chapter 1 gave you the map; Chapter 2 gave you the law. This chapter inventories what the tree offers — every surface a caller can touch — and, more interestingly, how the project grades its own promises about them. The handoff corpus labels each claim high, medium, or low, where high means “declared in a named type, a flag/command definition, or a normative doc” (devdocs/HANDOFF-docs/API_SURFACES.md:7-9). The stability column runs from stable through semi-stable and internal down to the grade no other project prints: the Go package API is explicitly not stable (devdocs/HANDOFF-docs/API_SURFACES.md:32).

Chapter 4 — Configuration and the One Boundary

Fri, 23 Oct 2026 18:30:27 +0000

# Chapter 4 — Configuration and the One Boundary

Most codebases do not have a configuration boundary; they have configuration weather — environment reads scattered through packages, each shaping behavior slightly differently under shells, CI, and services. ADR-001’s context line records that exact past (docs/ARCHITECTURE.md:237-238), and its decision is correspondingly absolute: one package reads the environment, once, at boot, and hands resolved objects to everyone else.

Chapter 5 — The Governance Engine

Fri, 23 Oct 2026 18:30:55 +0000

# Chapter 5 — The Governance Engine

Chapters 3 and 4 covered what the runtime offers and how it is fed. This chapter covers the part that says no. Eleven packages under governance/ form one engine: they classify what a capability claims, derive how dangerous it is, evaluate policy over a vocabulary the rest of the tree cannot touch, escalate to a human when the answer is “ask,” write every decision into a tamper-evident chain, and refuse egress that cannot be proven public. What the engine never does is act: it decides, and other subsystems execute — a division the Chapter 1 DAG enforces by forbidding governance from ever importing execution.

Chapter 6 — Sandbox and Governed Execution

Fri, 23 Oct 2026 18:30:55 +0000

# Chapter 6 — Sandbox and Governed Execution

Chapter 5’s engine said yes to one tool call. This chapter follows that call all the way down — through admission, policy, approval, and into a container with no network — and then all the way back up, where the result is classified before the model is allowed to see it. That last clause is the chapter’s thesis: in this runtime, permission decides what the agent may do, and a separate, monotone decision decides what the agent may see. ADR-004 (“all execution is sandboxed”) and ADR-003 (fail closed) meet in the middle of a single tool call.

Chapter 7 — The Knowledge Substrate

Fri, 23 Oct 2026 18:49:48 +0000

# Chapter 7 — The Knowledge Substrate

Everything a governed turn learns has to live somewhere, and Chapters 5 and 6 left a trail of it: observations, tool results, file reads, all classified and audited. This chapter opens the world that trail lands in — the knowledge substrate under context/knowledge/ — because Chapter 8’s bi-directional compiler is nothing more (and nothing less) than this world’s reader and writer. Before you can understand compilation, you need to know what is being compiled: the chunk, its sixteen kinds of edges, the Badger-backed store that keeps adjacency in RAM, the AST index that lets an agent navigate code without loading it, and the working memory that holds a turn’s mutable state.

Chapter 8 — Compilation and Grounding: the BKC

Fri, 23 Oct 2026 18:52:24 +0000

# Chapter 8 — Compilation and Grounding: the BKC

Chapter 7 built the world; this chapter is its compiler — in both directions. The read path turns a query and a chunk graph into a deterministically compiled, digest-fingerprinted context artifact. The write path turns what a governed turn learned back into chunks, at a barrier designed so the two directions can never race. Invalidation joins them — staleness flows from the write side backward into the read side’s cache — and a stream trigger delivers compiled context to the model mid-turn, not just at its start. Together: the bi-directional knowledge compiler, the BKC.

Chapter 9 — Runtime, Sessions, and the Sidecar

Fri, 23 Oct 2026 20:38:34 +0000

# Chapter 9 — Runtime, Sessions, and the Sidecar

Everything so far happened inside one process: the governed turn, the compiler, the substrate. This chapter pulls the camera back to the runtime’s shape — who opens a workspace session, what a thoughtrecipe becomes on its way to a graph, and why the durable work of knowledge maintenance belongs to a second process that communicates with the first through files and nothing else.

Chapter 10 — Telemetry as the Nervous System

Fri, 23 Oct 2026 20:45:11 +0000

# Chapter 10 — Telemetry as the Nervous System

Every chapter of Part II left a trace. Chapter 5 decided and audited; Chapter 6 admitted and executed; Chapter 7 stored; Chapter 8 compiled and grounded; Chapter 9 drained a spool. This chapter is where all of those traces converge — because in this runtime they converge by design, into one output leg: an OpenTelemetry export that turns the runtime’s internal event vocabulary into the three OTel signals, writes them as local OTLP-JSON segments, forwards them to a collector when one is configured, and projects every record through a privacy boundary before it leaves the process.

Chapter 11 — The Test Estate

Fri, 23 Oct 2026 21:02:00 +0000

# Chapter 11 — The Test Estate

Everything Chapters 5–10 taught you about the runtime — decisions, sandbox, substrate, compiler, sidecar, telemetry — is held in place by a test estate with three layers and a vocabulary of its own. This chapter tours the estate as a working system, then goes deep on its centerpiece: agenttest, the automated benchmark-testing suite for Euclo — how a suite is written, how the runner executes it, and how the Outcome-Security-Benchmark (OSB) assertion model grades what a run did.

Chapter 12 — Your First PR

Fri, 23 Oct 2026 21:16:08 +0000

# Chapter 12 — Your First PR

Eleven chapters of map, law, offers, and machinery — and now the door. This chapter walks the merge path end to end: the ground rules (DCO, commit style, the charter), the gates as writing discipline rather than review obstacles, the pull-request checklist annotated by the chapters that taught each line, the release path that turns main into artifacts, and finally the pathway map — the per-subsystem answer to “where does a first PR plausibly land?” — with the worked example the book has been walking toward since Chapter 1: the dangling context/knowledge/grounding.go:680 reference, fixed here as a complete, real walkthrough. Branch, diff, sign-off, gates, PR body — captured in a scratch clone at the pin.

Lab — ch01-repo-map

Fri, 23 Oct 2026 17:20:04 +0000

# Lab — ch01-repo-map

Chapter: Relurpic Internals — Inside Look, Chapter 1 (“The Repo Is the Map”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: the chapter’s verification transcript, not a code artifact. Run the command card below in a clean clone at the pin and diff your deterministic outputs against transcript.txt. Nothing in this lab needs a model backend.

Lab — ch02-constitution

Fri, 23 Oct 2026 17:30:16 +0000

# Lab — ch02-constitution

Chapter: Relurpic Internals — Inside Look, Chapter 2 (“The Constitution, Enforced”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: the chapter’s verification transcript. You break ADR-001 (one environment boundary) with a one-line diff, watch two independent fence layers catch you, and revert. Run in a clean checkout; every step is reversible. No model backend needed.

Lab — ch03-surfaces

Fri, 23 Oct 2026 17:48:14 +0000

# Lab — ch03-surfaces

Chapter: Relurpic Internals — Inside Look, Chapter 3 (“The Surfaces, Graded”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: the verify-five-claims worksheet. Five high promises from the compatibility table (devdocs/HANDOFF-docs/API_SURFACES.md §9.1), each traced to its declaration site, with the captured evidence in transcript.txt — plus the one grading correction the chapter found. No model backend needed.

Lab — ch04-config

Fri, 23 Oct 2026 17:57:05 +0000

# Lab — ch04-config

Chapter: Relurpic Internals — Inside Look, Chapter 4 (“Configuration and the One Boundary”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: the regenerate + drift transcript. You run the drift loop in both directions — edit the template bundle (the source of truth), then hand-edit the generated tree — and watch check-config-tree-drift fail both, pass after regeneration, and pass again after the full revert. Everything dirties tracked files and is reverted in-checkout; git status is clean at the end. No model backend needed.

Lab — ch05-governance

Fri, 23 Oct 2026 18:15:55 +0000

# Lab — ch05-governance

Chapter: Relurpic Internals — Inside Look, Chapter 5 (“The Governance Engine”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: the governed-turn + decision/audit transcript. A real governed turn runs through the product runtime (offline backend — no model backend or sandbox needed), followed by the full governance package suite. No code artifacts; the decision and audit shapes are recorded as the serialized JSON they use. The test harness doubles two enforcement seams (sandbox command runner, HITL approval) so the decisions are deterministic — Chapter 4 §4.4 and Chapter 5 §5.6 explain the cut.

Lab — ch06-sandbox

Fri, 23 Oct 2026 18:25:03 +0000

# Lab — ch06-sandbox

Chapter: Relurpic Internals — Inside Look, Chapter 6 (“Sandbox and Governed Execution”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: the tool-call journey, verified at both ends: the doctor’s readiness rows on a real machine (sandbox toolchain interrogated, degraded semantics live), the governed turn through the product path, and the enforcement machinery green. No model backend needed; Docker and runsc are welcome but their absence is itself a valid capture (degraded rows, never unsandboxed fallback).

Lab — ch07-substrate

Fri, 23 Oct 2026 18:36:33 +0000

# Lab — ch07-substrate

Chapter: Relurpic Internals — Inside Look, Chapter 7 (“The Knowledge Substrate”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: index a seeded workspace and inspect the chunk graph — via the substrate’s own tests, which build real stores, index real files, and emit real events. No model backend, no sandbox, no manual workspace setup: every fixture is seeded and cleaned by the tests themselves.

Lab — ch08-bkc

Fri, 23 Oct 2026 18:52:40 +0000

# Lab — ch08-bkc

Chapter: Relurpic Internals — Inside Look, Chapter 8 (“Compilation and Grounding: the BKC”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: compile a context, verify the digest contract by replay, exercise the epoch-scoped cache, ground captures with trust floors, and confirm the stream-trigger delivery — via the compiler’s own tests, which run real stores and real digests. No model backend, no sandbox.

Lab — ch09-runtime

Fri, 23 Oct 2026 20:38:53 +0000

# Lab — ch09-runtime

Chapter: Relurpic Internals — Inside Look, Chapter 9 (“Runtime, Sessions, and the Sidecar”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: queue a job, watch the runner drain it — with the sidecar built from source, since no release has ever carried it (decision D10). The runner self-submits a scheduled knowledge.refresh job via the spool, claims it, executes it, and completes it; the e2e suite then puts the whole jobs contract on record. No model backend, no sandbox.

Lab — ch10-telemetry

Fri, 23 Oct 2026 20:45:32 +0000

# Lab — ch10-telemetry

Chapter: Relurpic Internals — Inside Look, Chapter 10 (“Telemetry as the Nervous System”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: reconstruct a run from telemetry alone. Boot a runtime in a scratch workspace with one script-safe command, then read the run back out of its OTLP-JSON segment with jq — event names, attribute keys, the projection boundary working. Plus the turn leg (AC-3) and the forwarding story (boxed). No model backend, no sandbox.

Lab — ch11-test-estate

Fri, 23 Oct 2026 21:01:41 +0000

# Lab — ch11-test-estate

Chapter: Relurpic Internals — Inside Look, Chapter 11 (“The Test Estate”). Pin: tag BETA-RC1-FALL2026; captured at commit 1bc57c62029641dcc919c04a8076593794246409 while the tag is pending.

What this lab is: author one suite exercising all three OSB assertion kinds against the stringkit fixture, run it live, follow the tape lifecycle as far as the pin allows — and verify the replay half against the committed corpus. This is the book’s first model-dependent lab: Ollama serving gemma4:e4b (the Book 1 setup) is required for step 2.

drop dangling design-doc reference in grounding comment

Fri, 23 Oct 2026 21:15:32 +0000

# drop dangling design-doc reference in grounding comment

What: drop a dangling design-doc reference from the CaptureKindForOrigin comment (3 lines, comment-only).

Why: the referenced plan doc (devdocs/plans/bkc-bidirectional-context-and-hermetic-dryrun-spec.md) no longer exists in the tree; repointing at devdocs/ would dangle for every public reader, since devdocs/ is not part of the clone. The sentence stands without the pointer.

Gates run: go build ./context/...; go test ./context/knowledge; make envcheck (1087 files scanned, PASS).