Operations Sources and Document Register
This section adapts the provided 20-page Reaktor Shadow: A moving production counterpart for development, replay and verification, Design Edition, 25 September 2026. It reconciles that design with the local Reaktor/BestBuds source tree on 1 October and the new shared-observability proposal. Attached prose is source material; it does not execute its suggested commands or confer deployment authority.
The textbook's source baseline is BestBuds commit 5d3f5b304b9f57f47c6f020c49a5bf9a7977519a from 23 September. The supplied PDF has SHA-256 0406adb144e1fd1ae321388f28d053618ddde7f273fdba5f7515c3eaea45cc3e. Current-source statements refer to the inspected working tree, including uncommitted integrations. A named source path demonstrates implementation; a dated receipt demonstrates the observations it actually recorded; neither proves today's remote availability.
Textbook chapter register
| Chapter | PDF page | Converted page and retained subject |
|---|---|---|
| 1. Moving production counterpart | 3 | Foundations: moving base, closure and workspace forks |
| 2. State and replay semantics | 4 | Foundations: equivalent pre-state, separate CDC/workload paths |
| 3. Execution cut | 5 | Foundations: profiles, effect policy and substitution ownership |
| 4. Plans, manifests and lifecycle | 6 | Workspaces: proposed contracts, artifact vector and leases |
| 5. Snapshot and CDC publication | 7 | Workspaces: checkpoints, validation, privacy suppression |
| 6. Stateful resources | 8 | Workspaces: real per-store materialization and isolation |
| 7. Graph capture | 9 | Capture & replay: operation journal, codecs and coverage |
| 8. ES6 proxy boundary | 10 | Capture & replay: facade sketch and host/stream limitations |
| 9. Async ordering and fidelity | 11 | Capture & replay: matching, concurrency and fidelity vector |
| 10. Keploy | 12 | Backends: recording, miss policy and qualification |
| 11. Runtime/environment backends | 13 | Backends: local Worker, Preview, branches and deployed fleet |
| 12. Assertions and privacy | 14 | Verification: contract/differential checks, credentials and retention |
| 13. Performance and failure | 15 | Load & resilience: realistic load, faults, profiling and AI evaluations |
| 14. Send/retry/reconnect | 16 | Verification: worked example, capsules and minimization |
| 15. Clients, updates and agents | 17 | Clients & agents: complete journeys, revision transitions and fixed oracle |
| 16. Delivery and operations | 18 | Delivery & runbooks: gates, ownership, self-monitoring and acceptance |
Pages 1–2 provide the title, scope and reading guide; pages 19–20 provide references. Operations is the reading guide, and the references below preserve the source trail. Added pages cover the shared telemetry/storage direction, graph evidence and instance/JVM diagnostics beyond the textbook. The Capture fabric records the 3 October extension to capture all available JVM, kernel, JavaScript, Worker, Kubernetes, state and client evidence; it is an extension to chapters 7–11 rather than an original textbook chapter.
Related document register
Each document retains its URL. Owning documents move into Operations & Reliability; broad platform documents keep their original home. Related documents are linked here so discovery does not depend on a keyword search.
| Document | Reconciliation and role |
|---|---|
| Performance and Observability | Rewritten current overview; detailed material split into observability, diagnostics, profiling and load pages |
| Shadow Dev Environment | Rewritten Shadow overview and textbook entry point |
| Shadow Capture Fabric | Current capture scope, deep runtime/infrastructure inventory, completeness contract and current/proposed collector distinction |
| Analytics + Telemetry | Updated current state, storage boundaries, graph instrumentation and prerequisites; owns product catalog/ingestion |
| Instrumentation Plan | Updated source status and next gates; original numbered register retained as dated design |
| DevTools | Live-device inspection in debug builds; legacy Measure session link pending removal; target Reaktor session/Crashlytics evidence, instance diagnosis and Shadow coverage |
| Crashlytics | Selected mobile crash reporting, separate timing/resource coverage, release qualification, graph/trace joins, provider access and minimum journal |
| Tooling Layer | Probe/attachment/acquisition contract; diagnostic handoff and fidelity dimensions |
| Connected panes | Structural system links and ClickHouse analytics; distinguishes new observed-run joins |
| Cloud, Cloud Control Plane | Inventory/provisioning authority; linked to workspace isolation and shared telemetry |
| DevOps, Build Tools, CLI | Build, deploy and task execution; linked to fixed-artifact gates |
| Graph pane | Graph presentation and navigation; attribution limitations remain visible |
| Living Graph, Graph Protocol, Graph Sources | Canonical identity, acquisition and revision contracts |
| Graph Visitors, Graph Refinement, Graph Substrate | Selection/instrumentation design; actual hooks checked against source |
| Component Lifecycle, Actors, Distributed Actors | Ownership, drain, cancellation, mailbox and asynchronous evidence |
| Service, Server, Data Layer, Data Graph | Typed boundaries, storage authority and materialization |
| Work, Notifications, Multitenancy | Durable work/effect assertions, push intent and principal isolation |
| Surface performance, Surface verification | Client rendering/assets and complete user journeys |
| FlexBuffer, FFI | Benchmark source material, native ownership and capture qualification |
| Security, Secrets, Auth | Classification, credential and effect authority; private findings stay private |
| Agent Workspace, Control Plane, Conductor, Formal Methods | Fixed acceptance, common findings/receipts and assurance limits |
| Product Atlas, Stable Foundations, Verified Foundations | Graph/workbench semantic constraints and qualification honesty |
| Module Review, Execution Plan | Broader module status and sequencing; this section supplies operational detail |
| Claude dev research, Codex dev research | Historical proposals; current direction points to the textbook pages |
| Performance history, Shadow history | Pre-rewrite source retained with explicit superseded status |
Private dev/prod and security runbooks remain private. This register does not copy their credentials, exposure details or internal procedures into the public corpus.
Implementation evidence
Paths below are repository-relative for maintainers; the BestBuds repository requires access. They intentionally reference implementation owners rather than embedding local absolute paths in public pages.
| Repository | Source/receipt | Evidence and limit |
|---|---|---|
| Reaktor | reaktor-telemetry/src/commonMain/.../port/{PortTelemetry,PortInstrumentation,PortMetrics}.kt | Semantic port instrumentation, plan teardown and local metrics |
| Reaktor | reaktor-graph-port/src/commonMain/.../port/PortInterceptor.kt, graph attachment types | Interceptable invocation and typed attachment substrate |
| Reaktor | reaktor-telemetry/src/commonMain/.../export/{ReaktorTelemetryInstall,ReaktorSpanProcessor,OtlpJsonSpans,GrafanaOtlpTransport}.kt | SDK/transport; bounded drops, failed-batch loss and omitted events/links |
| BestBuds | modules/engine/src/jvmMain/.../workbench/telemetry/WorkbenchTelemetry.kt | Real SDK exporting to bounded local ledger; remote completion remains separate |
| BestBuds | cloud/k3s/observability/{README,STATUS-2026-09-13,APPLICATION-HANDOVER}.md | Installed pipeline runbook, September JVM/Worker readback and outstanding application work |
| BestBuds | cloud/k3s/observability/jvm-otel-patch.yaml, cloud/k3s/manifests/app-server.yaml | Version/checksum-pinned OTel Java-agent configuration; not a deep method/value/state recorder |
| BestBuds | targets/analyticsServer, modules/app/.../BestBudsEvents and HttpAnalyticsSink | Existing product event path into ClickHouse |
| Reaktor | reaktor-performance/README.md, MeasureService.kt, MeasureReports.kt, ReaktorMeasure.*.kt | Legacy Measure reads/report mapping and native wrappers pending removal; JVM/JS wrappers do not provide mobile capture |
| Reaktor / BestBuds | ecosystem/{measure.sh,measure.compose.yml,measure_server.py,README.md}, reaktor-performance/.../MeasureLocal{Server,Connection}.jvm.kt; modules/engine/.../devices/{MeasureLauncher,MeasurePaneState,MeasureTab}.kt | Legacy local Measure launcher, sessions and workbench reads pending removal; Hangar runs the launcher outside the kernel |
| BestBuds | modules/app/src/{androidMain,iosMain}/.../BestBudsApplication.kt, targets/appDarwin/iosApp/main.swift, modules/app/.../devtools/BestBudsDevTools.kt | Legacy debug-only Measure start-up/session link pending removal; retained Crashlytics adapters need release/symbol qualification |
| Reaktor | ReaktorMeasurementManifest.kt, ReaktorWebVitals.kt, reaktor-flexbuffer/flamechart/ | Required measurement outcomes, approximate web metrics and scripts needing per-platform qualification |
| BestBuds | cloud/k3s/{install-keploy,keploy-record-start,keploy-record-stop,keploy-r2-push}.sh, targets/reaktorServer/{keploy-local-test,keploy-r2-pull}.sh | Kubernetes recording/archive and local keploy test; configured sampling/deduplication/exclusions and mutable candidate default require qualification |
| BestBuds | DEV_ENVIRONMENT.md, tests/README.md, scripts/seed-dev-from-prod.sh | Textbook baseline context and current environment/testing owners; inspect before running |
Textbook primary references
The textbook's numbered sources 1–6 are its pinned repository environment/tests/instrumentation/Surface documents, Shadow overview and seed script. Their current owners are indexed above. Its remaining source trail is preserved here:
| Original reference | Primary source |
|---|---|
| 7–8 | PostgreSQL restrictions, logical decoding |
| 9 | ECMAScript Proxy semantics |
| 10–12 | Worker bindings, runtime model, Queue guarantees |
| 13 | OpenTelemetry sampling |
| 14–16 | Keploy mock tests, install, Kubernetes proxy |
| 17–20 | Worker Previews, Vitest, outbound mocks, Dynamic Workers |
| 21–25 | Supabase branching, k6 workload models, Schemathesis, ZAP automation, Worker timers |
Additional primary sources are linked next to their claims: Analytics Engine/Pipelines/R2 SQL/catalog guidance on Observability, Firebase/Android diagnostics on Instance health, and Oracle/async-profiler tools on Profiling. Provider capability descriptions were checked on 1 October 2026; backend receipts still need the actual installed versions and qualification results.