Read the source.
Build better Go components.

00 · Read across repositories, starting with design questions

This course began with highly starred GitHub projects and now covers 22 OSS implementations in 27 chapters. The original ten case studies remain. Discovery through awesome-go plus supplementary projects adds HTTP composition, structured logging, CLI boundaries, DI lifecycle, concurrency, retries, circuit breakers, message acknowledgment, and contract testing.

Choose the question before the repository. awesome-go helps discover designs; it is not quality certification. Eight of the twelve added implementations appear in the pinned awesome-go snapshot; four supplement the comparison. Chapter 26 contains the complete directory, maintenance status, and cross-repository decision map. Wire is archived and serves only as a historical code-generation example.

Returning readers can start at 18–26; existing chapter anchors and progress remain. New readers can begin with 01–03, then follow the problems they encounter rather than repository stars.

Evidence boundary. Source entry points pin full commits and line ranges. We closely read selected contracts, call chains, and tests without auditing whole repositories or building upstream projects. Source observations and original teaching sketches are distinct; downloading a file does not imply closely reading all of it. Runnable-lab verification and new design exercises also have separate evidence scopes.

Follow one bounded source route at a time: a contract → a caller → an implementation → a failure test. Predict, read, close the page, restate the invariant, and write a counterexample. Explaining why a pattern should not be copied is more useful than recognizing its name.

01 · Transfer what you already know

Good Go components are usually direct: concrete types hold state, methods perform actions, small interfaces describe the capabilities a call site needs, and ordinary functions assemble them. Abstraction should improve change locality and contracts.

Official Code Review Comments favor consumer-defined interfaces, implementation-side concrete return types, and abstraction after a real need appears. These are defaults: the standard library and plugin systems also offer reasonable exceptions that return interfaces.

Three Go-specific boundary issues

1. Implicit implementation still needs a contract. Matching method signatures proves only that a call is possible. Concurrent safety, mutation of returned slices, return latency after cancellation, and error classification need separate definitions.

2. T and *T have different method sets. An ordinary named type T does not include methods whose receiver is *T; *T includes both sets. Convenient calls on addressable variables do not replace interface assignment rules. Objects with locks or mutable state are generally used through pointers, and must not be copied after use. See Method sets.

3. A typed nil inside an interface is not a nil interface. var p *MyError = nil; var err error = p can make err != nil. Return an explicit nil on success, not an error holding a nil pointer. DI can encounter the same issue. See the Go FAQ.

02 · Standard library: compose capabilities

Requirement: copy bytes from any source

A Java class-hierarchy approach might start with AbstractInputSource, inherited by file, network, and memory objects. Go's io.Reader describes only the reading capability. Copying bytes does not require files and network connections to belong to one inheritance tree.

Source route: Reader contract → copyBuffer dispatch order → MultiReader composition.

io.Copy first asks whether the source has WriterTo, then whether the destination has ReaderFrom. Only otherwise does it use a general read/write loop. This extends a minimal base contract with optional capabilities. Base callers still need only Reader and Writer.

MultiReader holds several Readers and exposes reading itself. Callers need not know whether the source is singular or composite. It also copies the supplied interface slice so callers cannot alter its list; this does not deep-copy each Reader object.

Apply this in your code

This original snippet omits imports and makes export logic depend only on byte capabilities:

func Export(dst io.Writer, header string, body io.Reader) error {
    input := io.MultiReader(strings.NewReader(header), body)
    if _, err := io.Copy(dst, input); err != nil {
        return fmt.Errorf("export document: %w", err)
    }
    return nil
}

Pass a file, bytes.Buffer, or compression writer. The function does not close them on its own: callers created the resources and retain closing responsibility. A function that opens a file itself should arrange closing within that function.

Boundary cases deserve your attention

A Reader may return n > 0 and a non-nil error in the same call. Consume those bytes before handling the error; do not return on err != nil before processing buf[:n]. io.Copy also handles short writes and does not return ordinary EOF as a copy failure. The loop

Useful when: callers need small stable capabilities shared by implementations with matching semantics. Avoid copying blindly: creating an interface for every private helper with one implementation and no independent contract, or accumulating optional type assertions instead of defining clear capability groups.

03 · Gin: middleware is control flow

Requirement: share authorization, tracing, and business handling across a request

Source route: Context.Next and Abort → request object pool → upstream Abort tests.

Gin organizes execution using a handler slice and a cursor. Next executes later handlers from the current middleware; after it returns, the current function continues. Abort moves the cursor into a terminal range, but does not return from your current function. Rejecting a request usually still needs an explicit return.

This resembles around advice, but the order unfolds through ordinary function calls. Do not assume merely omitting Next always blocks later Gin handlers: an outer advancing loop may continue. Use Abort to terminate the remaining chain.

Our standard-library version can be tested directly. http.HandlerFunc is an adapter implemented as a named function type with a method; no class containing only ServeHTTP is necessary. Standard-library adapter

// Package middleware demonstrates composition through http.Handler.
package middleware

import "net/http"

// Trace marks normal execution before and after the next handler.
// mark must be safe for concurrent requests. This is a teaching trace, not a
// panic recovery layer or an HTTP status/latency metrics implementation.
func Trace(name string, mark func(string), next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		mark(name + ":before")
		next.ServeHTTP(w, r)
		mark(name + ":after")
	})
}

// Require stops the handler chain if allowed rejects the request.
// It demonstrates control flow; callers supply the actual access policy.
func Require(allowed func(*http.Request) bool, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if !allowed(r) {
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}
		next.ServeHTTP(w, r)
	})
}

Notice the return in Require and the outer Trace's after step even on rejection. Ordering affects logging, authorization, and recovery, so tests should examine the full trace rather than only the final HTTP status.

Object reuse makes lifetime part of the contract

Gin returns Context to its pool after a request ends. A goroutine retaining the original *gin.Context may see another request's state after reuse. Copy copies some containers, but the Request pointer remains shared, and arbitrary map values are not recursively copied. Context.Copy

Prefer extracted IDs, immutable payloads, and explicit lifetimes for background work. c.Copy() neither extends the HTTP connection's write window nor turns request cancellation into a durable job system.

Avoid: adding sync.Pool to business objects without measurement. Pool entries may be reclaimed; it is not a reliable resource pool. Do not retain mutable references after returning an object. sync.Pool documentation

04 · Hugo: configuration, dependencies, and optional capabilities

Requirement: render content with renderers of different capabilities

Source route: small converter interface family → Deps wiring information → filesystem wrapper.

The base Converter requires conversion. Optional ParseRenderer separates parsing from rendering, allowing supported implementations to extract a table of contents first. Provider creates converters for a document context; NewProvider adapts a creation function into a named object with a New method.

These are independent axes: how an object is created and what it can do. Needing a factory does not by itself justify a DI container, a lifecycle framework, and dozens of registries.

Classify component inputs

Hugo's large Deps carries assembly information for a large site build. That source fact does not imply every component should accept *App or *Deps. A formatter needing only a clock and writer should receive those two, exposing its real dependencies in its signature.

When functional options are worthwhile

Gin's constructor does accept OptionFunc. Source Our mini reconciler has only two required dependencies, so New(source, dest) is clearest. Consider functions such as WithTimeout when a public library has many independent, extensible optional settings.

Keep required dependencies explicit. Apply defaults, then overrides, then validation. Do not start goroutines or create partially initialized resources inside options. If 0 is a valid business value, do not also use it for “unspecified”; distinguish them with a pointer, explicit flag, or separate constructor.

Avoid: making every configuration field an option, hiding a dozen dependencies in a giant bag, or treating configuration as a freely mutable shared map without synchronization.

05 · frp: composition, strategies, and plugin registration

Requirement: share behavior across proxy protocols

Source route: Proxy contract and factory → GeneralTCPProxy embedding → Plugin creation and lifecycle.

GeneralTCPProxy embeds *BaseProxy to reuse methods. Plugins map names to constructor functions, then operate through Name, Handle, and Close. Strategy and Factory are familiar labels; registration timing, configuration types, and connection lifetime are the important details.

Embedding is not virtual inheritance

This original semantic snippet omits package and main; comments show results of calls from main:

type Base struct{}
func (Base) Name() string { return "base" }
func (b Base) Describe() string { return b.Name() }

type Child struct{ Base }
func (Child) Name() string { return "child" }

// Child{}.Name()     -> "child"
// Child{}.Describe() -> "base"

Inside promoted Describe, the receiver is still Base. Name is not redispatched through an “actual subclass.” If shared logic needs variable behavior, pass a function or interface explicitly, or delegate through a separate field. Do not expect Go to implement a Template Method that relies on subclass overrides.

A plugin is a replaceable contract

frp's registry is a package-level map; duplicate registration panics, and implementations often register in init. This relies on assumptions such as finishing registration during initialization. These lines do not prove arbitrary concurrent runtime registration and removal are safe.

For two or three fixed strategies, a constructor switch is often enough. Use an explicit registry when plugin composition really varies by build. Validate dynamic configuration, create instances, then enter the running phase. Avoid compensating for unclear type boundaries with reflection on a hot path.

06 · RAGFlow: consistent contracts matter more than method count

Requirement: support different object stores for the same feature

Source route: Storage contract → MemoryStorage defensive copies → Factory selection.

MemoryStorage copies bytes on write and again on read, protecting its map with RWMutex. This isolates ownership of mutable memory: the lock protects internal operations; copies prevent callers from later modifying internal arrays.

It is a useful in-memory adapter to study. The broader Storage interface has many capabilities, while Factory uses a singleton and global configuration. Those decisions do not automatically produce low coupling for all consumers.

Check whether promises match behavior

In the pinned version, Storage.Get's comment allows nil for a missing object, while MemoryStorage.Get returns a wrapped ErrMemoryNotFound. The interface name alone does not establish consistent missing semantics across backends. Contract, implementation

This observation is not a verdict on the whole system; its adapting callers must be read to assess impact. In your own API, remove the ambiguity: distinguish missing, empty content, permission failure, and temporary unavailability, and run the same contract tests against each implementation.

Another concrete example: RetrievalService has one Search method, but takes *gorm.DB. Source It exposes an ORM dependency despite its small method count. One method does not necessarily define a pure domain boundary.

The contract used in this course

type Reader interface {
    Read(ctx context.Context, key string) ([]byte, error)
}

Beyond the signature, specify ErrNotFound recognizable by errors.Is, caller-owned bytes on success, concurrent calls, cancellation checks, and valid empty bytes. Store adds only writing to this contract.

Avoid: passing a general Storage interface everywhere, using (nil, nil) for multiple meanings, or assuming Mutex lets callers freely mutate returned slices.

07 · TypeScript: generics for structure, functions for behavior

Requirement: stable compiler traversal order and AST rewriting

We read the Go implementation under microsoft/TypeScript/tsc/internal. Source route: OrderedMap → public API tests → NodeVisitor → copy only after a change.

OrderedMap uses a map for lookup and a key slice for insertion order. K comparable requires comparable keys; V any leaves values unrestricted. Generics remove container-structure repetition without swallowing business semantics.

Important details: the zero value initializes lazily on Set; updating an existing key does not append it again; iteration uses iter.Seq or Seq2 and stops when yield returns false. Deletion must maintain the key slice, so not all operations can be assumed O(1). noCopy provides a copying-check hint to vet; it is neither a runtime lock nor a concurrency guarantee.

How an Iterator relates to a generator

Think of iter.Seq[T] as handing a yield function to traversal logic; the caller's break feeds back as false. This does not itself start another goroutine. This OrderedMap deliberately checks a dynamic length, allowing iteration to observe items appended during traversal. That is this container's contract, not a universal Go iterator rule.

A Visitor does not need dozens of subclasses

NodeVisitor holds Visit and hook functions. VisitSlice scans first and copies the already visited prefix only when a node is replaced, removed, or otherwise changed; unchanged input returns the original slice. Functions provide variation while the struct holds traversal dependencies, avoiding a hierarchy built only to override behavior.

This suggests clear invariants: unchanged input retains structural sharing; new results must not accidentally alter old views. It is not automatic deep immutability; callbacks mutating Nodes in place still require contractual constraints.

Understand performance techniques; apply them later

The same repository has Arena[T], using bulk allocation to reduce small allocations. Its arrays remain Go-managed; reclamation of old chunks depends on references. This is not equivalent to manually freeing all objects with arena.free. Establish an allocation bottleneck using benchmarks and profiles before assessing lifetimes and aliasing risks.

08 · Syncthing: turn state mutation into a controlled protocol

Requirement: several running components respond to configuration changes

Source route: Modify and Serve → validate, publish, notify → Committer contract.

Callers submit a modification function. The service serializes updates: copy the current configuration, apply the function, prepare and validate, publish, notify subscribers, and wait for this round. Configuration reads still use a mutex. An event loop does not eliminate every need for locks.

This transfers to hot-reloaded routing tables, service-discovery caches, and small control planes: centralize mutation, define read results, and make update order explainable. This is easier to inspect than letting every module lock and mutate a shared map independently.

Three states you must distinguish

1. New configuration validated and stored in memory.
2. All component callbacks completed; some may require a restart.
3. Configuration persisted successfully.

CommitConfiguration returning false marks a restart requirement; it does not magically roll back every component that already reacted. Save has a separate path. A Waiter or completed callback is not a distributed atomic commit.

Constraints when applying the pattern

Keep modification functions short and synchronous. Avoid arbitrary network calls and retaining the configuration pointer externally. Treat subscriber snapshots as read-only; copying a struct does not isolate every nested reference. Define feedback when the queue fills, and define how updates stop being accepted and callbacks finish.

Useful when: components share state requiring ordered updates. Avoid copying blindly: adding a goroutine and message queue to a local two-field object solely for an Actor pattern.

09 · fzf: coalesce interactions, not arbitrary commands

Requirement: rapid typing makes old searches obsolete

Source route: EventBox → Matcher.Loop → partition workers → cancellation and waiting.

EventBox stores events in map[EventType]any; a new Set of the same type replaces the previous value. This suits latest-state UI updates. It is not a FIFO promising delivery of every event or a global chronological order across event types.

Matcher divides searches among a bounded number of workers based on CPU, configuration, and workload. Each worker owns its scratch space. Cancelling an old scan still requires waiting for computations before safely changing data they may be reading.

Derive the mechanism from product semantics

These semantics precede queue selection. You already understand coroutines; next, specify which work can be cancelled, coalesced, retried, or repeated.

A lock boundary to inspect

EventBox.Wait invokes its callback while holding a lock. A callback that calls Set on the same EventBox may try to acquire that lock again. Existing call sites constrain usage. In your own callback API, document whether callbacks run under a lock, or take a copy and unlock before invoking them. Wait and Set

10 · Ollama: separate admission, resource use, and completion

Requirement: expensive model loading with shared, limited resources

Source route: Scheduler fields and initialization → request admission → completion and model expiry → function injection tests.

Scheduler uses a request channel bounded by configuration and returns ErrMaxQueue when full. A loaded reusable runner has a fast path. Loading resources, sharing loaded resources, completing requests, and reclaiming idle models are different actions. State involves both channel events and mutex protection; the whole object is not simply a lock-free actor.

Function fields such as loadFn, newServerFn, and getGpuFn provide substitution boundaries. Tests replace real startup dependencies with functions to induce loading failures. A single call site need not produce an AbstractModelLoaderFactoryProvider.

A buffer is part of an admission policy

A bounded queue must define its full condition: block with cancellation, reject immediately, or overwrite under explicit rules. make(chan Job, 100) is not a complete design. A timeout budget should include queueing, rather than restarting a full timeout at dequeue.

Per-request success and error channels have capacity 1, allowing one result send without the receiver being ready at exactly the same moment. Capacity 1 does not generally solve repeated sends, never-ending producers, or shared-object ownership.

Cancellation, exit, and resource reuse are separate

In this version, Scheduler.Run starts goroutines and returns immediately; that method does not provide a join guarantee. A request object retains its own context to carry that request's lifetime across queues. This is a specifically defined asynchronous work item, not a reason to put Context permanently in an ordinary Service. Run and admission, requests using a runner

Define construction, running, and stopping APIs first. For a simple component, prefer Run(ctx) error blocking until all internal work exits. If startup must be asynchronous, provide Wait or Done separately. Cancellation is cooperative and cannot kill a function that ignores ctx. context documentation

11 · Kubernetes: reconcile current state

Requirement: duplicate events, changing state, and failing writes

Source route: DeploymentController dependencies → processNextWorkItem → syncDeployment → workqueue state machine.

DeploymentController enqueues keys. A worker takes a key and reads the current Deployment through a lister; an already deleted object may be a normal completion. Before modifying an object, it uses DeepCopy to protect the shared informer cache. This is a reconcile loop: compare desired and observed state, then perform necessary actions.

An event means “inspect this object again,” rather than a transaction log entry that must be replayed individually. Caches may lag the server, so handle conflicts, rereads, and retries. Absence of a change in cache does not prove absence of a remote change.

Five lines express two different protocols

Original pseudocode, highlighting responsibilities rather than reproducing upstream code:

key := queue.Get()
defer queue.Done(key)       // End this processing round.
err := reconcile(ctx, key)
if err == nil { queue.Forget(key) } // Clear retry history.
if err != nil { queue.AddRateLimited(key) }

Real code also handles shutdown, error classification, and retry limits. DeploymentController calls Forget on success and specified cases; retryable errors are bounded, and reaching the limit also ends that retry sequence. Upstream worker

Done is not Forget. Done changes who is processing and whether another enqueue is needed. Forget clears rate-limiter history; it neither ends processing nor deletes every pending work item. Rate-limiter wrapper

Why the queue is more than a channel

It manages at least three collections:

During normal operation, every queued key belongs to dirty and not to processing. Get adds a key to processing and clears that round's dirty mark. Add during processing marks it dirty without assigning it to another worker. Done requeues it if it is still dirty. Add, Get, and Done

Coordinating a key inside one queue does not provide distributed exactly-once execution. Processes, restarts, and external writes still require idempotent operations, version checks, or transactions. Do not put a non-idempotent “increment” side effect unchanged into retryable reconciliation.

Lifecycle belongs to the component contract

DeploymentController.Run waits for initial cache synchronization, starts workers, and shuts the queue down and waits for workers on exit. Shutdown and waiting have identifiable code locations. Run This is more complete than giving goroutines a ctx alone.

Tests exercise this protocol: TestAddWhileProcessing explicitly adds an item again while processing. Learn its behavioral scenario, beyond memorizing Controller, Observer, or Factory names.

12 · Turn observations into your own component boundaries

Start with one concrete requirement

“Read source documents and bring the destination to the same content; repeated runs avoid unnecessary writes; cancellation is supported, with at most N distinct keys executing together.”

Write the sequential version first: read source, read destination, compare, write if necessary. Do not begin with empty domain, application, infra, factory, and manager directories. Extract consumer-side Reader and Store dependencies when a second real backend or independent failure-path testing calls for them. Move scheduling into batch when concurrency becomes a separate requirement.

Let reasons for change define packages

ErrNotFound lives near the consumer-defined storage contract. memstore depends on reconcile's contract; reconcile does not import memstore. This is a concrete dependency direction for a small project. Consider a small domain-named package if errors or value types are genuinely shared across independent use cases, rather than creating a general types package in advance.

Four checks more useful than directory names

Change locality. Moving to S3 should mainly add an adapter and alter wiring in main. Reconciliation rules and batch should stay unchanged.

Honest inputs. Do not hide DB, logger, configuration, and dozens of services inside ctx.Value or *Application. Signatures should expose dependencies.

Meaningful encapsulation. Private fields protect invariants. Getters and setters exposing the same mutable map add typing without protecting state.

Short reading paths. An ordinary business call should be understandable across a few nearby functions. Four layers containing only return next.Do(...) suggest layering that explains no variation.

internal is an import boundary enforced by Go tooling. cmd commonly organizes program entry points. pkg is not a compiler-provided “public API” marker, and no universal directory layout is required. See official module layout guidance.

13 · Runnable lab: a small reconciler

Download the complete Go lab and extract go-oss-lab/. It uses only the standard library and requires Go 1.25+. The actual validation environment was Go 1.26.2 on macOS arm64. Upstream default branches may need newer toolchains; this lab does not depend on their build environments.

unzip go-oss-lab.zip
cd go-oss-lab
go run ./cmd/syncdemo
go test ./...
go test -race ./...
go vet ./...

Expected demo output:

pass 1: changed=2
pass 2: changed=0
after source update: changed=1

The first pass writes two documents. The second rereads and compares, making no writes when nothing changed. Changing one source document causes one write in the next round. Duplicate guide inputs are deduplicated within a single batch.

13.1 Reconciliation need not know the memory store

// Package reconcile converges destination bytes toward a source snapshot.
// It owns the use case and its dependency contracts, not storage mechanisms.
package reconcile

import (
	"bytes"
	"context"
	"errors"
	"fmt"
)

// ErrNotFound means the requested key has no value. Empty bytes are a value.
// Adapters must translate their backend's missing-object error to this error.
var ErrNotFound = errors.New("object not found")

// Reader returns caller-owned bytes or an error wrapping ErrNotFound.
// Implementations must honor cancellation and support concurrent calls.
type Reader interface {
	Read(ctx context.Context, key string) ([]byte, error)
}

// Store replaces a whole value. Write must not retain the caller's byte slice.
// Callers must not mutate the input while Write is executing.
type Store interface {
	Reader
	Write(ctx context.Context, key string, value []byte) error
}

// Result describes one completed reconciliation, not a global system state.
type Result struct {
	Changed bool
}

// Reconciler reads current state on each call. It has no background goroutines.
// Different keys may be reconciled concurrently. The caller must serialize
// calls for the same key if it needs to prevent concurrent duplicate writes.
type Reconciler struct {
	source Reader
	dest   Store
}

// New wires dependencies without acquiring resources. Dependencies must be
// non-nil, including the concrete values stored in their interfaces.
func New(source Reader, dest Store) *Reconciler {
	return &Reconciler{source: source, dest: dest}
}

// Reconcile copies the current source value only when the destination differs.
// A missing source is an error; this use case never deletes destination data.
// It provides convergence on repeated calls, not a distributed transaction.
func (r *Reconciler) Reconcile(ctx context.Context, key string) (Result, error) {
	if key == "" {
		return Result{}, errors.New("key is required")
	}
	if err := ctx.Err(); err != nil {
		return Result{}, err
	}
	want, err := r.source.Read(ctx, key)
	if err != nil {
		return Result{}, fmt.Errorf("read source %q: %w", key, err)
	}
	have, err := r.dest.Read(ctx, key)
	if err != nil && !errors.Is(err, ErrNotFound) {
		return Result{}, fmt.Errorf("read destination %q: %w", key, err)
	}
	if err == nil && bytes.Equal(want, have) {
		return Result{}, nil
	}
	if err := r.dest.Write(ctx, key, want); err != nil {
		return Result{}, fmt.Errorf("write destination %q: %w", key, err)
	}
	return Result{Changed: true}, nil
}

Notice three points: destination read failures cannot all mean missing; empty content differs from absence; only equal content produces Changed=false on successful comparison. Each call rereads the source, allowing later calls to converge after source changes.

// Package memstore implements an in-memory adapter for the reconcile contracts.
package memstore

import (
	"bytes"
	"context"
	"fmt"
	"sync"

	"example.com/go-oss-lab/internal/reconcile"
)

// Store is safe for concurrent use. Its zero value is ready to use.
// A Store must not be copied after first use.
type Store struct {
	mu     sync.RWMutex
	values map[string][]byte
}

var _ reconcile.Store = (*Store)(nil)

// Read returns an independent copy. Cancellation is checked after acquiring
// the lock; the mutex acquisition itself cannot be interrupted by ctx.
func (s *Store) Read(ctx context.Context, key string) ([]byte, error) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	if err := ctx.Err(); err != nil {
		return nil, err
	}
	value, ok := s.values[key]
	if !ok {
		return nil, fmt.Errorf("read %q: %w", key, reconcile.ErrNotFound)
	}
	return bytes.Clone(value), nil
}

// Write atomically replaces one value within this process.
// This in-memory store does not persist data across process restarts.
func (s *Store) Write(ctx context.Context, key string, value []byte) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if err := ctx.Err(); err != nil {
		return err
	}
	if s.values == nil {
		s.values = make(map[string][]byte)
	}
	s.values[key] = bytes.Clone(value)
	return nil
}

// Package batch owns bounded, finite concurrent work and its lifetime.
package batch

import (
	"context"
	"errors"
	"fmt"
	"sync"
)

// Run processes each distinct key at most once in this invocation.
// The first cancellation cause stops dispatch and is returned after all
// workers exit. Work already started may complete. Results are not rolled back.
// fn must honor ctx, be safe for concurrent calls, and must not panic.
// Run does not retry, serialize keys across invocations, or persist a queue.
func Run(ctx context.Context, keys []string, workers int, fn func(context.Context, string) error) error {
	if workers < 1 {
		return errors.New("workers must be positive")
	}
	if fn == nil {
		return errors.New("work function is required")
	}
	ctx, cancel := context.WithCancelCause(ctx)
	defer cancel(nil)
	jobs := make(chan string)
	var wg sync.WaitGroup
	for range min(workers, len(keys)) {
		wg.Go(func() {
			for {
				select {
				case <-ctx.Done():
					return
				case key, ok := <-jobs:
					if !ok || ctx.Err() != nil {
						return
					}
					if err := fn(ctx, key); err != nil {
						cancel(fmt.Errorf("process %q: %w", key, err))
						return
					}
				}
			}
		})
	}
	seen := make(map[string]struct{}, len(keys))
dispatch:
	for _, key := range keys {
		if _, exists := seen[key]; exists {
			continue
		}
		seen[key] = struct{}{}
		select {
		case <-ctx.Done():
			break dispatch
		case jobs <- key:
		}
	}
	close(jobs) // This function is the only sender and therefore owns closure.
	wg.Wait()   // Cancellation requests exit; Wait observes that exit completed.
	return context.Cause(ctx)
}

What this lab promises

Read–compare–write in Reconcile is not a cross-backend transaction. Concurrent calls on one key may both decide to write; a source change within a call may briefly leave the destination behind. Add key serialization, version/CAS checks, or transactions as requirements demand, and ensure another reconciliation can be triggered.

Cancelling sibling workers after the first failure does not undo successful writes. Rerunning is useful here because writes replace content with its desired value. Sending email, charging money, or incrementing counters would require a new side-effect protocol.

A remote Write may commit while its success acknowledgment is lost. Returning an error or Changed=false then does not prove absence of side effects. Reread, retry idempotently, or reconcile by operation identity. Changed describes this call's confirmed result, not a transactional proof about the external world.

14 · Clean code: contracts you can review

Errors provide diagnostics and form part of the API

Intermediate layers add action and key, for example fmt.Errorf("read source %q: %w", key, err). Callers decide with errors.Is and errors.As, not string comparisons. %w exposes the underlying error's identity; decide at the boundary whether a driver error should be public. Official error-design discussion

Usually log at the boundary that understands the operation's outcome, while intermediate layers return contextual errors. Avoid logging the same stack at every layer. A retry loop may record retry events, but distinguish these from final failure. Return errors for user input, I/O failure, and resource exhaustion; panic should not replace ordinary business branches.

Add sentinel or typed errors when callers can make different decisions. Partial success needs enough result information; an arbitrary bool rarely explains what already happened.

Useful zero values and constructors coexist

memstore has a useful zero value because the first Write initializes its map. The reconciler requires external dependencies, so its constructor requires valid implementations. Do not demand every zero value be runnable, or prohibit a naturally usable one merely to add NewX.

Prefer constructors that assemble. If construction opens files, listeners, or connections, failure must clean up and successful ownership must define closing. Keep “created,” “running,” and “ready to serve” distinguishable.

References and lifetimes: quick checks

Defer arguments are evaluated when the defer statement executes; release order is last-in, first-out. Flush and Close can themselves produce reportable write errors. Defer alone does not guarantee successful output. Effective Go: Defer

Concurrency and performance checks

Channels convey work, signals, or ownership; mutexes protect shared-state invariants. Choose based on ownership and operation granularity. Replacing every lock with a channel does not eliminate races. GC manages reachable memory, but cannot terminate a blocked goroutine. Visibility and happens-before still depend on synchronization operations. Go Memory Model

Make behavior clear, then measure. Generic containers, handwritten loops, caches, pools, and arenas may help, but identify the allocation or CPU time worth optimizing. The lab provides a 4 KiB copying-read benchmark to explore ownership isolation costs:

go test ./internal/memstore -run '^$' -bench BenchmarkReadCopy -benchmem

One result does not establish performance on other machines or production workloads. The race detector only finds races on exercised execution paths; it is not a proof of concurrent correctness.

Do not mechanically copy old Go tutorials

Starting with Go 1.22, under the applicable language version, iteration variables newly declared in a loop have per-iteration semantics. Adding v := v is no longer a universally necessary fix. Reused external variables, shared pointer targets, and concurrent map writes can still race. Inspect go.mod and actual sharing rather than memorizing an old counterexample. Official explanation

15 · Tests should describe components

Tests should survive internal implementation changes. The lab uses external test packages for observable behavior and small handwritten fakes for failures, rather than generating dozens of mocks just to verify one function called another.

Use controllable events in concurrent tests

Do not sleep for 100 ms and hope a worker has started. Gate channels decide when work can proceed. Go 1.25+ testing/synctest waits until other goroutines in a test bubble are blocked before assertions. It suits controlled concurrent logic; real networks, system calls, and external dependencies impose limitations. synctest documentation

func TestCancelWaitsForAllWorkers(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		ctx, cancel := context.WithCancel(t.Context())
		defer cancel()
		var started, exited atomic.Int64
		done := make(chan error, 1)
		go func() {
			done <- batch.Run(ctx, []string{"a", "b", "c", "d"}, 3, func(ctx context.Context, _ string) error {
				started.Add(1)
				defer exited.Add(1)
				<-ctx.Done()
				return ctx.Err()
			})
		}()
		synctest.Wait()
		if started.Load() != 3 {
			t.Errorf("started=%d", started.Load())
		}
		cancel()
		if err := <-done; !errors.Is(err, context.Canceled) {
			t.Fatal(err)
		}
		if exited.Load() != started.Load() {
			t.Fatalf("returned with active workers: started=%d exited=%d", started.Load(), exited.Load())
		}
	})
}

Upstream tests teach scenario selection: Gin checks execution order, TypeScript external container behavior, and K8s requeueing during processing. We read selected upstream tests; the tests executed here belong to the lab. This is not a claim that all upstream suites passed.

Ten code-review questions

1. What change does this component own? Does its name explain the responsibility?
2. Do imports make business rules depend on concrete infrastructure?
3. Does the interface follow a real caller's needs? Do parameters smuggle in large dependencies?
4. Who creates and closes resources? Who may mutate returned references?
5. Do errors distinguish absence, rejection, cancellation, and temporary failure?
6. When does each goroutine exit, and who waits for it?
7. Are queue size and concurrency bounded? Does timeout include queueing?
8. Is repeated execution safe? Does idempotency include external side effects?
9. Do tests cover cancellation, partial success, aliasing, and failure beyond the happy path?
10. Does measurement support the optimization and justify added complexity?

16 · Six practice sessions

Allow 60–90 minutes per session. Try first, then read the answers. Work in the separate lab directory.

Final assignment: add a file-storage adapter

Evolve the memory-only demo without building a complete file-sync product in one step. Require internally generated keys and initially reject path separators and traversal. Implement Read/Write, translate missing errors, and define whole-value replacement. Handle write, close, and replacement failures plus temporary-file cleanup.

This introduces real persistence. A temporary file followed by rename can offer certain same-filesystem replacement properties, but does not automatically provide a portable, crash-durable transaction. For crash durability, investigate platform-specific fsync, directory synchronization, and recovery. This course does not implement the adapter or present the exercise as a verified durability guarantee.

At minimum show: changing storage leaves reconciliation rules untouched; missing and empty files differ; failure is not reported as Changed=true; a missing source does not silently delete the destination; concurrency and cancellation follow the contract.

Afterwards, explain a component's responsibilities, dependencies, ownership, errors, and exit protocol in two minutes, pointing to the corresponding code.

17 · Source index and reproducible evidence

These fixed-version entry points follow the learning path. Follow function line links in each chapter to continue reading. research/ranking.json records the original query; repositories.json records rank, commit, license identifiers, and selection reasons; reading-map.json records reading ranges; source-index.json records SHA-256 fingerprints of downloaded files.

The source index for the twelve added repositories is in Chapter 26. ecosystem-repositories.json records discovery and status, ecosystem-reading-map.json records close-reading ranges, and ecosystem-source-index.json records downloaded-file SHA-256 hashes. python3 research/fetch_ecosystem.py refetches pinned commits; discover_ecosystem.py creates a new discovery snapshot and is not a replacement for reproducing an old version.

In the full local course source checkout, python3 research/fetch_sources.py downloads source and licenses at pinned commits without running upstream code. Source caches and large raw directory trees remain local and are not included in the course commit. Permanent links do not depend on those caches. The website's lab download is the smaller runnable experiment, not the full research checkout.

Lab verification record: test commands, environment, and the verified source commit. Upstream projects were neither built nor audited in full.

18 · Chi × Gin: keep HTTP composition at the boundary

Requirement: call the same use case from HTTP and a CLI

Gin introduced framework Context, handler chains, and object pooling. Now read Chi with a narrower question: how much business code should your routing-library choice affect?

Source route: reverse wrapping in chain → With and Group → what Timeout actually does.

A Chi middleware accepts an http.Handler and returns an http.Handler. Composition preserves the contract: another wrapper can consume the result. chain wraps from the last middleware backward, so A, B produces A(B(handler)). Entry order is A then B; return order reverses it. No business-service hierarchy is required.

With creates an inline Mux with a middleware slice while sharing the routing tree. A new wrapper is not an independent deep copy. Group uses With to add behavior to a set of routes; do not interpret it as a freely mutable, inherently thread-safe configuration snapshot.

Two APIs protecting the same boundary

Original sketch with imports omitted. The point is dependency direction, not a routing-library recommendation:

type Importer interface {
    Import(context.Context, string) error
}

func ImportHandler(importer Importer) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Method != http.MethodPost {
            w.WriteHeader(http.StatusMethodNotAllowed)
            return
        }
        key := r.URL.Query().Get("key")
        if key == "" {
            http.Error(w, "missing key", http.StatusBadRequest)
            return
        }
        if err := importer.Import(r.Context(), key); err != nil {
            http.Error(w, "import failed", http.StatusInternalServerError)
            return
        }
        w.WriteHeader(http.StatusNoContent)
    })
}

The HTTP error mapping is simplified. A real adapter should distinguish validation, not found, conflict, and cancellation. Do not expose internal error strings directly to clients. Nor do you need Chi merely to use a Handler: the standard library already provides that contract.

Counterexample: Timeout does not forcibly terminate a handler

The pinned Chi Timeout uses context.WithTimeout, calls next.ServeHTTP, and only after it returns checks the deadline in a deferred function and attempts to write 504. A handler that ignores Context may keep running. If a response is already committed, the later 504 cannot replace its status. This mechanism does not preempt a handler at the deadline. Implementation and comments

Transfer rule: keep the framework at the edge. For each middleware, specify whether it calls next, mutates the request, owns the response, and runs its after behavior on rejection or error.

19 · Zap × Zerolog: allocation and ownership behind API ergonomics

Requirement: searchable structured logs with controlled hot-path cost

Source route: Zap Core contract → Check and child loggers → multiple-sink composition; compare the Zerolog Event lifetime.

Zap organizes encoding, output, and level policy around zapcore.Core. With clones the encoder for child context; Check decides whether an Entry should be written, and Write consumes an Entry already selected for writing. NewTee combines Cores, but writes to multiple sinks are not an atomic transaction: one can fail after another has written.

Zerolog accumulates fields in a fluent Event and finishes it with Msg / Send. The Event is mutable and returns to a pool; the source explicitly prohibits calling Msg twice on one Event. It is not a Scala immutable builder, and you should not store it for reuse by multiple goroutines. Event lifecycle

Fluent syntax does not imply lazy evaluation

Go evaluates arguments before invoking a function. These two forms have different costs:

// Original sketch: expensiveSnapshot runs even when Debug is disabled.
log.Debug("state", zap.String("snapshot", expensiveSnapshot()))

// Gate expensive field construction with the level decision.
if ce := log.Check(zap.DebugLevel, "state"); ce != nil {
    ce.Write(zap.String("snapshot", expensiveSnapshot()))
}

Zerolog's MsgFunc does not call its callback for a nil Event, allowing deferred message construction. Other field arguments do not become lazy automatically. Zap's WithLazy is not an immutable snapshot either: it may retain object references and observe their state at logging time. Decide whether you intend to record the current value or a later state. Zap, Zerolog

Clean code does not require unifying every logging library

Recommendation: choose stable fields such as operation, key, attempt, duration, and outcome; avoid logging the same event at every layer. Usually the boundary that decides the action's outcome logs an error once, while lower layers return contextual errors. The resource owner decides when to Sync/flush and how to handle sink failures; ordinary business functions must not close a shared logger.

20 · Cobra: a command is an adapter; PostRunE is not finally

Requirement: flags, validation, and a testable business action

Source route: the execute hook sequence → happy-path hook test.

Cobra centralizes command trees, arguments, and flag protocols. Business rules need not accept *cobra.Command. Reading execute reveals ValidateArgs, pre-run hooks, required-flag validation, RunE, and post-run hooks. When RunE returns an error, execution returns immediately without the later public PostRunE / PersistentPostRunE hooks. The source's deferred c.postRun() invokes internal finalizers; it is distinct from public PostRunE.

Original adapter sketch, imports omitted. Its closure owns this command's flag state; an ordinary function performs the work:

func NewImportCommand(run func(context.Context, string) error) *cobra.Command {
    var key string
    cmd := &cobra.Command{
        Use: "import",
        Args: cobra.NoArgs,
        RunE: func(cmd *cobra.Command, _ []string) error {
            if key == "" {
                return errors.New("key is required")
            }
            return run(cmd.Context(), key)
        },
    }
    cmd.Flags().StringVar(&key, "key", "", "Document key")
    return cmd
}

At the process boundary, use ExecuteContext to pass cancellation and map the final error to an exit status. Business functions should not call os.Exit: it bypasses process deferred cleanup and makes reuse and testing harder. Inject an io.Writer, or use the command's output writer in the adapter, when output is needed.

Arrange release where you acquire the resource

An unsafe design opens a file or connection in PersistentPreRunE and assumes PersistentPostRunE always closes it. Validation or RunE failures can skip the public post hook you expected.

A smaller design acquires the resource inside the function RunE calls, immediately defers Close, and merges close errors into the return value where needed. If several commands truly share a longer-lived resource, give an outer owner responsibility. Do not infer exception semantics from hook names.

Transfer rule: the CLI adapter converts input/output, the use case performs the action, and the composition root decides dependencies and process lifetime. This resembles Java controller/service separation without adding an interface to every layer.

21 · Manual DI × Fx × Wire: construction is not lifecycle

Requirement: start and stop dependent components, including partial startup failure

Source route: Fx Hook contract → Start / Stop counting and order → App rollback. Compare Wire-generated code and its provider contract.

Start with ordinary Go functions: create storage, then the service, then the HTTP server. For a small component set, explicit constructors and cleanup order are usually sufficient. DI means passing dependencies explicitly; it does not inherently require a container.

Fx makes lifecycle composable through Hooks. The pinned implementation starts them in registration order and stops started Hooks in reverse; App.Start attempts rollback on failure. A failing OnStart is not counted as successfully started, so it must clean up its own partially acquired resources before returning an error. Stop collects errors, and an expired Context budget can prevent later cleanup. Context does not forcibly interrupt an uncooperative hook.

Study Wire's generated Go without recommending an archived dependency

Wire turns provider declarations into ordinary constructor calls. Its tutorial output is short enough to trace dependencies and error returns directly. A provider may return a cleanup function; the generator orders cleanup according to dependencies. Provider markers

Maintenance status: the 2026-09-05 snapshot marks google/wire archived, and its README explicitly says it is no longer maintained. Project statement We use it as a historical code-generation example. Appearance in this course is not a reason to add it to a new system.

Transfer rule: explain the wiring in handwritten Go before automating it. Every DI approach still needs separate ownership, readiness, rollback, and shutdown contracts.

22 · x/sync: errgroup scope, admission, and cancellation

Requirement: run a finite batch concurrently, signal other work on first failure, then join everything

Source route: Group / WithContext / Wait → Go / TryGo / SetLimit → Context after Wait test → cancelable semaphore Acquire.

errgroup.WithContext combines error propagation, cancellation signaling, and joining. It does not automatically give arbitrary goroutines complete structured concurrency: register related work through the Group, make it honor Context, and call Wait.

A commonly missed rule: Wait cancels the derived Context when it returns, even if all work succeeded. Do not use that Context for a next-stage request after a successful Wait.

// Original sketch; fetch must honor the supplied Context.
func FetchAll(ctx context.Context, keys []string,
    fetch func(context.Context, string) error) error {
    g, workCtx := errgroup.WithContext(ctx)
    g.SetLimit(4)
    for _, key := range keys {
        key := key
        g.Go(func() error { return fetch(workCtx, key) })
    }
    return g.Wait()
}

This is a finite-batch sketch, not a full admission policy. When the limit is full, Go waits for a semaphore slot without selecting on Context. TryGo returns false immediately when no slot is available. For cancellation-aware admission, examine weighted semaphore Acquire(ctx, n), or the earlier lab's fixed workers and explicit queue protocol.

Similarities to and differences from Futures / task groups

Exercise acceptance: cover success, first failure, parent cancellation, and blocked admission. Coordinate with gates rather than guessed sleeps. Assert all registered workers exit before return, and that successful Wait closes workCtx.Done. The next operation must use a deliberately chosen Context. Do not change SetLimit while workers are active.

23 · Backoff × Gobreaker: separate retry, deadline, and circuit breaker

Requirement: call an unreliable remote without letting failure traffic overwhelm the service

Source route: Backoff option contracts → retry loop → cancellation test; compare Gobreaker settings, Execute admission, and generation accounting.

This chapter pins a v7 branch snapshot of cenkalti/backoff; it does not combine APIs from other major versions found online. After studying the control flow, check the release you actually depend on.

Backoff's WithMaxTries(3) means at most three total attempts. WithMaxElapsedTime constrains retry scheduling budget; it does not interrupt an operation already running. Operation[T] takes no Context argument, so a closure must pass Context into underlying I/O. This Retry version runs the operation once before checking Context on the failure path. An already-canceled caller Context therefore does not imply zero invocations: the operation must observe it itself.

The backoff policy contains mutable state. Do not casually share one instance among concurrent Retry calls. Treat it as the state of one logical call rather than a package-level singleton.

Gobreaker's MaxRequests limits probes in half-open state, not global concurrency in normal closed state. Its Timeout controls time spent open, not operation timeout. Actual requests run without holding the breaker mutex; completion checks the generation so an old request does not pollute a newer state cycle. Execution, state handling

Composition order changes the meaning of statistics

retry(breaker(oneAttempt))  → breaker observes each attempt
breaker(retry(oneAttempt))  → breaker observes the final logical-operation result

This is a control-flow deduction, not a library recommendation for every backend. The first form exposes consecutive failures quickly but can pointlessly retry ErrOpenState. The second can hide several failed attempts behind a final success. Decide the units of metrics and failure budget before choosing the wrapping order.

Three layers making at most three total attempts each can amplify to 3 × 3 × 3 = 27 bottom-level attempts. Avoid uncoordinated retries in the client, service, and job layers; assign one owner to the overall budget. For payment, create, publish, and other side effects, design idempotency keys and outcome lookup before adding retries.

24 · Watermill: Ack is a protocol, not a business transaction

Requirement: receive a message, change state, publish follow-up events, and recover after failure

Source route: Message Ack / Nack → Router processing order → Publisher / Subscriber contracts → Ack/Nack tests.

Watermill's Message records Ack/Nack through state and channels. Repeating the same terminal action can succeed; the opposite action fails. This is a local “first terminal state wins” protocol. It neither establishes a broker durable commit nor includes a database modification.

The normal Router path runs the handler, publishes produced messages, and then Acks the original message. Handler or publish errors cause Nack. But the Publisher interface explicitly allows synchronous or asynchronous implementation behavior, and batch publishing is usually not atomic. Check the concrete adapter to understand what a nil Publish error means.

Reason about crash windows

Acknowledgment alone does not imply exactly-once business effects. A design recommendation is a stable business operation ID, recording state changes and deduplication within a transaction that satisfies the required contract. For reliable event handoff, study a transactional outbox and the relay's duplicate-publish handling. This is an architecture exercise, not a claim that Watermill's generic Router implements that transaction for you.

Compare K8s reconciliation: both require reasoning about repetition, but workqueue key coalescing and broker delivery/acknowledgment are different protocols. State convergence can reread the latest state; commands or events that must not be lost cannot merely retain the last key.

Ownership reminder: NewMessage accepts a payload slice without automatically deep-copying it. Define when publisher/handler goroutines may still access it and when callers may reuse the buffer. GC does not prevent aliasing or data races.

25 · Afero × go-cmp: testability depends on contracts, not mock count

Requirement: substitute an in-memory store without hiding important production differences

Source route: Afero Fs → ReadOnlyFs → io/fs adapter → optional capability forwarding; compare cmp.Equal rules and EquateEmpty.

Afero's Fs interface covers create, open, remove, rename, permissions, and other filesystem operations. It suits infrastructure that needs these capabilities. A configuration reader receiving the whole Fs also sees unnecessary write capabilities; io/fs.FS or a consumer-defined contract may be more precise.

ReadOnlyFs keeps the Fs method set but rejects writes with runtime permission errors. That differs from omitting write methods in the type system. IOFS adapts Afero to io/fs, handling path validation, file adaptation, and directory entries. Do not assume a read-only or base-path wrapper is a security sandbox.

Wrapper substitution includes optional capabilities

Earlier, io.Copy queried WriterTo / ReaderFrom. Afero's BasePathFile forwards those capabilities when available and falls back to ordinary copy otherwise. Code A wrapper can change a performance path even while implementing the basic methods. Measure the real workload before adding forwarding; preserving every optional interface can create an oversized proxy layer.

Your comparator is part of the specification

By default, go-cmp distinguishes nil slices/maps from non-nil empty values, may call a type's Equal method, and panics on unhandled unexported fields. cmpopts.EquateEmpty explicitly changes the nil/empty equivalence relation. That is a domain decision, not an option to add because the diff looks inconvenient. Contract, option

// Original test sketch: use only when the API defines nil and empty equally.
if diff := cmp.Diff(want, got, cmpopts.EquateEmpty()); diff != "" {
    t.Fatalf("result mismatch (-want +got):\n%s", diff)
}

Transfer rule: derive test seams from caller needs and verify observable behavior. A fake is a model with a defined scope, not proof about production.

26 · From catalog to your components: an executable design workshop

Ask a design question before opening awesome-go

awesome-go is a discovery catalog. Inclusion, stars, and attractive APIs do not replace contract review. Of the 12 added implementations below, eight appear in the pinned awesome-go README; four are upstream supplements for a fuller comparison. We do not claim all are currently recommended by awesome-go, and we have not ranked their performance.

Source snapshot: 2026-09-05. ecosystem.json publishes full commits, license identifiers, archived status, and awesome-go membership line numbers for the added repositories. Not archived does not imply active maintenance; this check did not fully audit release cadence, security history, or maintainers. Recheck these factors for the version you actually adopt.

Cross-repository decision map

Workshop: a document import service

Requirements: CLI and HTTP can submit a document key; read a source and update a target; emit an event for each successful change; support cancellation, bounded work, and repeated delivery. Do not introduce every library at once. Start with the existing lab and add one requirement at a time.

cmd/importer       chooses dependencies, owns process lifetime
  ├─ adapters/http → Import(ctx, key)
  ├─ adapters/cli  → Import(ctx, key)
  └─ application/importer
       ├─ Source.Read(ctx, key)
       ├─ Target.Apply(ctx, operationID, value)
       └─ outcome / error
adapters/storage   implements the application contract
adapters/events    implements a separately specified delivery protocol

This is a suggested dependency sketch, not a mandatory directory template. Start with the application in one package; split only when responsibilities and reasons for change truly differ. Avoid common, utils, and universal Manager packages that obscure dependency direction.

Write a contract card first: is input a key or a complete command? Who generates the operation ID? Is the same ID with a different payload a conflict or an overwrite? Which errors are retryable? Who owns returned slices? Does timeout include admission wait? Does shutdown reject work before closing the store? Does a log represent an attempt or a logical operation? Every answer needs an owner and observable acceptance.

Keep expanding without chasing another leaderboard

Choose a current design problem and find two different APIs in the relevant awesome-go category. Pin each version. Read one contract, implementation, caller, and failure test from each; compare the same requirement under both designs. Transfer one idea to a small experiment, then try to disprove it with a counterexample. The learning comes from comparison, not from the number of installed dependencies.

Inline code in the new chapters is original teaching material with imports omitted; it is outside the existing lab verification's execution scope. Source facts come from pinned reading ranges. The downloadable lab remains a runnable standard-library-only foundation. The expanded workshop is a follow-up assignment, not a claim that a complete service has already been implemented and tested.