Appendix F - Glossary, Bibliography, and Boundary Index
Terminology is useful when it keeps neighboring guarantees separate. Process readiness differs from workload health; requested resources differ from observed use; local durability differs from replicated availability. This glossary gives each term a conceptual meaning and a pinned Orch interpretation. A future-design label is not a promise that the current binary implements the concept.
The complete reference includes stable IDs, related terms, numbered chapter slugs and immutable source provenance. Use the source link to inspect a mechanism, then the chapter to understand its failure window. Definitions avoid circular explanations by naming the actual owner, field or consumer. They describe this edition rather than a changing default branch.
Mechanism glossary
| Term | Meaning and Orch boundary | Chapter |
|---|---|---|
| Trust boundary | A crossing between differently authorized actors or data. User JWT, node credentials, authorized task secrets and Docker authority require separate checks. | 23 |
| Desired state | The requested target of control. Server-owned Task.DesiredStatus constrains which worker reports remain acceptable. | 4 |
| Actual state | The latest accepted observation of execution. Assigned agents report task progress; policy and node-loss logic can transform stored results. | 13 |
| Reconciliation | Repeated comparison and action toward intent. The standalone reconciler exists, while MemoryService also owns integrated bookkeeping paths. | 11 |
| Convergence | An observed approach toward a stated target. Capacity, policy and successful worker actions are prerequisites, not guaranteed eventual outcomes. | 11 |
| Idempotency | Retrying an operation without duplicating its intended effect. Repeated task/container identity checks and duplicate-report rules provide scoped mechanisms. | 12 |
| Optimistic concurrency | Rejecting a write when its expected version is stale. Store operations compare expected UpdatedAt rather than trusting a prior read. | 9 |
| Task claim | A conditional assignment of pending work. One scheduler/store write selects NodeID; it does not fence an isolated old process. | 10 |
| Advisory lock | An application-coordinated database lock. The leadership package uses session-owned PostgreSQL locks; original-connection release matters. | 34 |
| Split brain | Concurrent actors believing they may own the same responsibility. Heartbeat suspicion and package leadership do not establish enforced single-writer runtime authority. | 34 |
| Terminal state | A state that cannot resume ordinary execution. Failed/stopped tasks allow cleanup to removed; terminal deployments remain immutable histories. | 4 |
| Namespace | A named scope for resource selection and access. Context-scoped service lookups do not prove network isolation or every newer workload path. | 27 |
| Admission | Validation and policy before accepting intent. ClusterPolicy can restrict workload fields; acceptance still differs from runtime field propagation. | 26 |
| Quota | A bound on scoped requested resources or objects. MemoryService serializes namespace accounting; zero limits mean unlimited. | 28 |
| Credential enrollment | Exchanging initial authority for an identity credential. Bootstrap registration issues a hashed-record node token for subsequent authenticated calls. | 23 |
| Secret envelope | Authenticated encryption wrapped with key metadata. LocalEnvelope uses AES-GCM; KeyID does not replace the required decrypting key. | 24 |
| SSRF | Server-side requests redirected toward unintended destinations. Probe targets and redirect/dial behavior need policy checks beyond a friendly URL string. | 14 |
| Local volume | Persistent data attached to one runtime locality. Node-pinned volume metadata does not replicate data or establish safe stateful failover. | 32 |
| Rollout surge | Extra active work permitted during a version transition. MaxSurge bounds active task accounting above desired replicas, not physical cleanup completion. | 17 |
| Process readiness | A process-reported ability to accept its expected traffic. The readyz handler does not validate durable orchestration or healthy workload replicas. | 7 |
| Workload health | A workload-specific observation of acceptable behavior. Probe thresholds affect healthy/unhealthy states; gateway reachability remains a separate observation. | 14 |
| Resource request | Declared capacity used to plan or admit work. CPU uses integer millicores and memory uses bytes after parser conversion. | 5 |
| Resource limit | A runtime bound intended to constrain consumption. The Docker adapter supports limits, but the ordinary agent path omits their propagation. | 5 |
| Resource reservation | Accounted requested capacity rather than measured use. Quota and placement arithmetic must not be described as Docker usage or billing. | 28 |
| Memory server | A control plane whose live maps belong to one process. The default server constructs MemoryService and loses intent/credentials on restart. | 1 |
| Durability | Retention of committed state across a defined failure. PostgreSQL store support is not default live-state wiring; identify the actual owner. | 9 |
| Replicated availability | Continued service through failures using multiple coordinated copies. Local persistence and an unwired leader package do not supply this system property. | 34 |
| Leader lease | A bounded authority claim with a loss signal. Lease.Done closing does not alone prove the original database session released its lock. | 34 |
| Fencing | Preventing stale owners from performing side effects. Physical worker/storage fencing is future work, not an effect of marking a node offline. | 34 |
| Autoscaling | Changing replicas in response to a policy and measurement. The package computes recommendations but is not started by the default server. | 22 |
| Stabilization window | A policy interval intended to damp rapid scaling decisions. The field is accepted and validated, but its declared window is not consumed by decisions. | 22 |
| Metrics provider | A component supplying a defined measurement to a policy. Autoscaler CPU input is an interface; a real provider is not wired into the binary. | 22 |
| Cooldown | A delay before another allowed scaling decision. The autoscaler remembers last scale time in a process-local map. | 22 |
| Parser resolver | A resolver that interprets an existing image reference. It accepts supplied digest syntax without fetching a registry’s remote digest. | 25 |
| Digest pinning | Naming content with an immutable digest-form reference. Parser/admission support does not prove remote manifest retrieval or layer verification. | 25 |
| Supply chain | The path from source/artifact origin to executed content. Signing, SBOM and remote provenance designs require separate implementation and evidence. | 29 |
| Registry credential | Authority for access to an image registry. Encrypted stored credentials are resolved for authorized task execution; metadata excludes secrets. | 25 |
| Task identity | A stable ID for one execution attempt. Replacement creates another ID instead of resurrecting a failed attempt. | 4 |
| Deployment version | A service intent generation used during rollout. Tasks are compared against target versions; rollback creates another deployment history record. | 17 |
| Restart policy | A rule determining recovery after workload failure. MemoryService can convert unhealthy to failed when service replacement is permitted. | 14 |
| Probe | A bounded health observation against a configured target. HTTP/TCP policy, timeout and thresholds belong to the actual health implementation. | 14 |
| Public port | A worker-level port forwarding traffic toward a container. Task-assigned public ports can differ from service requests and agent advertise ports. | 20 |
| Node advertise address | The address a worker publishes for reaching its services. Traefik extracts its host and combines the task’s published port. | 21 |
| Discovery | Returning endpoints describing presently eligible work. HTTP discovery filters desired-running tasks; its DNS path has a distinct filter. | 20 |
| DNS answer | A cached name-to-address response. The local DNS implementation returns deduplicated node IPv4 addresses without task ports. | 20 |
| Ingress | A gateway path from client routing to workload endpoints. Traefik uses node host/public-port HTTP backends; it does not create an overlay. | 21 |
| TLS boundary | The hop where encryption terminates or begins. A TLS router flag does not automatically encrypt the generated HTTP worker backend. | 21 |
| Stateful workload | Work whose data/identity constrains relocation. Offline stateful tasks retain assignment for manual recovery rather than assuming local data moved. | 19 |
| Task condition | Additive metadata describing a task circumstance. node_lost remains separate from actual and desired lifecycle states. | 19 |
| Drain | Moving desired work away from a selected worker. Completion counts desired work; actual owned-container removal can finish later. | 19 |
| Node offline | A control-plane status indicating loss of acceptable heartbeat presence. Expiry marks suspicion and recovery intent; it cannot stop a partitioned process. | 19 |
| Heartbeat age | Elapsed server time since a retained heartbeat observation. Zero LastHeartbeat is handled separately; wall-clock assumptions and cutoff strictness matter. | 19 |
| Cache TTL | A time interval for retaining a cached response. DNS uses a configured TTL, creating a freshness boundary after task changes. | 20 |
| Credential rotation | Replacing a credential while retaining an identity relationship. Lost heartbeat responses can leave the worker token behind the stored server hash. | 23 |
| Credential revocation | Rejecting an identity’s previously issued credential. The stored flag participates in validation; new credential storage changes that record. | 23 |
| Bootstrap authority | Initial authority used to admit a worker. Registration and the agent log listener use it differently from issued control-plane credentials. | 23 |
| JWT | A signed token carrying claims validated by the receiver. User validation is conditional on signing-secret configuration; node tokens are a separate scheme. | 23 |
| RBAC | Authorization based on an assigned role. Viewer/operator/admin checks depend on configured user JWT; newer routes can fall through to admin. | 23 |
| Namespace role | Role authority scoped to a selected namespace. Static user maps replace global role and clear namespace-role claims in the current middleware. | 27 |
| Configuration precedence | An ordered selection among configuration inputs. Nonempty flags override environment, YAML and defaults through the corresponding loader. | 24 |
| Redaction | Removing sensitive content from an exposed representation. Config print replaces sensitive fields; it does not sanitize all logs or workload output. | 24 |
| Audit record | An account of an attempted operation and its outcome. Best-effort append behavior must not be mistaken for transactional external audit delivery. | 15 |
| Event | A structured observation of a control-plane occurrence. State-change events and duplicate-report rules differ from a durable event-stream guarantee. | 15 |
| Retention | A rule for pruning older retained history. MemoryServer history pruning is separate from a durable backup and restore strategy. | 35 |
| Usage snapshot | A sampled accounting record over defined resources/time. Requested task resource accounting is not measured consumption or a validated billing engine. | 28 |
| Log stream | A bounded or followed flow of task output. API/agent stream cancellation, authorization and container ownership remain distinct checks. | 16 |
| Cancellation | A signal that dependent work should stop. Context cancellation requires each loop/stream/lease consumer to release its own resources. | 16 |
| Lost response | An operation result that the requester never receives. A heartbeat credential can rotate before its caller observes the new token. | 23 |
| Cleanup | Removing runtime objects after execution intent ends. Label checks protect ownership; service deleted waits for actual removed states. | 18 |
| Duplicate report | A repeated observation of the same accepted state. Identity transitions are accepted without manufacturing another state-change event. | 13 |
| Atomicity | A defined set of effects that succeeds or fails together. Local mutex mutation and store transaction behavior have different process-failure boundaries. | 9 |
| Availability budget | The minimum healthy/available population a controller protects. Old running/healthy and newHealthy predicates differ during rollout. | 17 |
| Rollback | A new operation restoring an earlier service version. It preserves failed/succeeded terminal deployment records instead of rewriting history. | 17 |
| Runtime adapter | The interface boundary translating intent into engine calls. Docker support in isolation does not prove ordinary agent field propagation. | 12 |
| Fake runtime | A controlled test double for runtime side effects. Passing fake-agent tests does not measure Docker startup or registry behavior. | 36 |
| Measurement contract | A definition of cohort, events, clocks and missing data. Fake-load timing and real runtime convergence require separate measurement scopes. | 39 |
| Artifact backup | A retained copy of files or database records. A database dump excludes runtime volumes and the separate envelope key. | 40 |
| Key loss | Loss of the material required to decrypt retained ciphertext. Restored rows and KeyID alone cannot recover LocalEnvelope plaintext. | 24 |
| Recovery point objective | A chosen tolerance for lost committed changes. A future durable deployment must define it; the memory server supplies no durable checkpoint promise. | 40 |
| Recovery time objective | A chosen target duration for restoring a defined service. Measure verified recovery, including schema/key/canary checks, rather than database exit alone. | 40 |
| Teaching extension | Book-owned runnable work with separately stated changes. It must not silently repair or inherit unrun claims from the immutable baseline. | 36 |
| Source pin | An exact revision and byte inventory defining an edition. Full-SHA citations distinguish current baseline code from historical implementation snippets. | 2 |
| Claim classification | A label describing a capability’s actual integration status. Runtime-integrated, package, partial, design, teaching and future labels prevent compositional overclaims. | 1 |
Annotated primary bibliography
Repository citations are evidence about this edition. Vendor documentation supplies the external protocol/runtime contract, and research papers supply comparisons. A paper about consensus cannot establish consensus in Orch. Docker documentation cannot establish that the ordinary agent forwards resource limits. Follow the call path and scoped execution record before making either claim.
The locked module declares Go 1.25.0, Docker SDK v28.5.2, pgx v5.10.0, Prometheus client v1.24.1, Cobra v1.10.2 and yaml.v3 v3.0.1. These are dependency versions, not an inferred Docker daemon negotiation or PostgreSQL server version. All repository bibliography entries use full SHAs; moving external pages retain their access date instead of pretending to be immutable snapshots.
Source code/history
- Orch source edition, Aleksandar Popovic, revision
cbfc94ade5b57e449d6b73bf1485b1c5b1647022. Read executable composition before interpreting feature directories. The companion bibliography indexes every individual cited file and historical commit.
Go/Docker contracts
-
The Go Memory Model, The Go Authors. 2022-06-06 specification revision. Accessed 2026-10-13. Synchronization vocabulary and local memory visibility; does not establish distributed durability.
-
context package, The Go Authors. Go 1.25.0. Accessed 2026-10-13. Cancellation propagation and ownership of cleanup; a canceled context alone does not release every external resource.
Distributed systems
- In Search of an Understandable Consensus Algorithm (Extended Version), Diego Ongaro and John Ousterhout. Extended paper; retrieved PDF edition. Accessed 2026-10-13. Useful contrast for leader election and replicated-log assumptions; Orch does not implement Raft by citing this paper.
HTTP/security
-
Docker Engine security, Docker Inc. Unversioned official documentation. Accessed 2026-10-13. Explains daemon/socket trust and container security boundaries; does not prove Orch passes each runtime field.
-
RFC 9110: HTTP Semantics, R. Fielding, M. Nottingham, J. Reschke (editors). RFC 9110 / STD 97, June 2022. Accessed 2026-10-13. Defines protocol semantics; application idempotency and asynchronous deletion still require their own contracts.
-
Server Side Request Forgery Prevention Cheat Sheet, OWASP Cheat Sheet Series. Unversioned official guidance. Accessed 2026-10-13. Frames destination-policy and request trust boundaries; actual probe behavior remains verified against pinned source/tests.
PostgreSQL/concurrency
- 13.3. Explicit Locking, PostgreSQL Global Development Group. PostgreSQL 16. Accessed 2026-10-13. Distinguishes row, transaction and session-level advisory lock ownership used in the leadership audit.
Observability
- Instrumentation, Prometheus Authors. Unversioned official guidance. Accessed 2026-10-13. Explains instrument selection and scoped metrics; a registered collector does not establish an active controller.
Operating practice
- Backup And Restore, Orch repository edition. Use its key/database artifact distinctions while preserving the default memory-server boundary.
Reading paths through the references
Developers can study six entries in this order: the source composition to locate owners; lifecycle helpers to find valid edges; scheduler tests to identify a race oracle; Go memory model to separate synchronization from distributed persistence; context to follow cancellation; and HTTP semantics to distinguish protocol retries from application effects.
DevOps engineers can follow server composition for active loops; agent runtime construction for engine authority; Docker security for daemon trust; Prometheus instrumentation for observation scope; backup/restore for excluded artifacts and keys; and PostgreSQL locking for the lifetime of database ownership.
Architects can compare architecture intent with actual composition, then the historical graph, leader implementation, Raft’s extended paper, and OWASP’s SSRF guidance. The questions are which owner is real, which failure domain is covered, and which extra mechanism an improvement still requires.
Version and evidence method
A source-inspected claim identifies code and tests but does not claim a run. Executed evidence additionally records commands, prerequisites, versions, UTC timestamps, exit status and logs. Historical snippets use their own commit/object identities; teaching extensions identify changed behavior and independent checks. Expected outcomes remain predictions until the matching experiment runs.
The bibliography checker resolves every manuscript URL to an entry, validates repository files/commits against the locked inventory or separately verified historical objects, and records external access outcomes. A link that opens is not proof that a technical claim is correct. Revisit the enforcing symbol and the integration boundary when a future Orch edition changes, rather than carrying this glossary’s implementation interpretation forward unchanged.
Source-backed boundary statements for this appendix are indexed in the appendix claim record. Detailed command, state, exercise and reference tables retain their own source provenance.