v0.2 RESEARCH stage. Synthesizes the 4-phase v0.2 scope (P01-P04) into
updated static docs. No code changes. Decisions are derived from
CLARIFY D-011..D-018 (already on main) and direct investigation of
go.mod, the codebase, and ecosystem docs (Go 1.25+ iter.Seq, govulncheck,
gosec, gitleaks, step-ca).
Key research conclusions logged here:
- ConnectRPC is NOT in go.mod (.ciagent/config.json lists it in
frameworks but the dependency was never added). v0.2 falls back to
stdlib net/http with h2c for the orca.v1.Dispatch service. Zero new
direct deps. (ARCHITECTURE.md AD-014)
- Roll-our-own CA via crypto/x509 (not step-ca/cfssl/vault-pki) keeps
the binary single, dependency-free, and aligned with offline-first
(no external PKI network calls). (ARCHITECTURE.md AD-010)
- govulncheck default mode requires network access to vuln.go.dev. CI
step must use -format json (always exits 0) + a wrapper that gates
on findings via jq/cat, OR pre-mirror the database. Caller to decide
in PLAN. Logged as REQ candidate for IDEATE.
- gosec exit codes: 0 clean, 1 unsuppressed finding. -no-fail always
returns 0. Baseline JSON via -track-suppressions + exclude=. We
adopt -no-fail on initial run, baseline suppressed findings, then
tighten to fail-on-finding once baseline is empty.
- gitleaks default config covers most cases; we extend .gitleaks.toml
with stopwords for our test data paths and CA cert PEM (which would
otherwise trigger the generic-api-key rule).
- iter.Seq: yield func(V) bool, iter.Pull for pull-style, range over
function types since Go 1.25. Cancellation flows through ctx
(consumer-driven backpressure). Single-use vs multi-use semantics
documented in Go spec; we use multi-use for repo.Watch() since
callers can re-iterate.
- mTLS hot-swap via tls.Config.GetCertificate callback enables cert
rotation without daemon restart. tls.Config is read on every
handshake; reload picks up new server.crt/server.key.
ARCHITECTURE.md changes:
- Added Transport Layer (internal/transport) and Dispatcher
(internal/engine/dispatcher.go) components.
- Added Security Manager (internal/security) component with full cert
lifecycle API.
- Added certs table schema (migration 0004) and Cert Go struct.
- Extended Node with NodeCapacity (CPU/memory) for bin-packing.
- Added v0.2 Component Graph ASCII diagram.
- Added 4 named flows: cert issuance, mTLS handshake, job dispatch,
iter.Seq streaming.
- Added 8 new AD-009..AD-016 decisions and AD-014 notes the
ConnectRPC-not-in-go.mod reality.
PERSONAS.md changes:
- Added network-engineer (custom, NEW in v0.2) for transport/dispatcher.
- security-engineer marked phase_specific: [P01, P02] (off after P02).
- network-engineer marked phase_specific: [P02].
- cli-engineer marked phase_specific: [P04] (--watch is a CLI concern).
- data-engineer.territory extended to include
internal/store/migrations/0004_certs.sql.
- security-engineer.territory extended to TLS-config portion of
internal/transport.
- Frontmatter updated: active_personas, phase_specific, reason.
PROJECT.md changes:
- Moved "Multi-node scheduling" out of "Out of Scope" (it ships in P02).
- Added "External PKI / Let's Encrypt / cert transparency logs" to
Out of Scope (per D-011).
- Added "gRPC framework dependency" to Out of Scope (per AD-014).
- Added v0.2 Scope Summary section (4 phases) with cross-refs to
ARCHITECTURE.md flows.
REQ candidates surfaced for IDEATE stage (not added to REQUIREMENTS.md
in this commit — that's the IDEATE stage's job):
- REQ-cand-A: Bounded cert rotation history (retain last N=3 server
certs per node for rollback; documented in ARCHITECTURE.md certs
table as "retention" implication of the schema).
- REQ-cand-B: Trusted-CA fingerprint pinning (D-012 requires operator
to pass --ca-fingerprint at join; the daemon should refuse to start
if the on-disk CA's fingerprint doesn't match a config-pinned value,
to protect against operator typos).
- REQ-cand-C: govulncheck offline mode (CI must not call vuln.go.dev
by default; either pre-mirror the DB or set GOVULNCHECK_DB env to
a local file).
- REQ-cand-D: HCL/YAML schema for NodeCapacity declaration (where
does the operator declare a node's CPU/RAM? Current v0.1 Node model
has no capacity field. P02 will add this — needs a config file
surface, e.g. ~/.orca/node.hcl or flag on `orca node join`).
- REQ-cand-E: gitleaks baseline for pre-existing secrets in history
(the v0.1 .env leak was rotated forward but git history still has
a SHA-1 leak — gitleaks/git filter-repo remediation may need a
baseline file to avoid the same class of false positive recurring).
- REQ-cand-F: --watch output format mode (iter.Seq stream is
table-style by default; users may want --watch --json one-line-per-
event for piping). P04 scope decision; log for IDEATE.
---ci---
project: orca
phase: 0
milestone: v0.2
status: research
---/ci---
Jon Chery
08d321f57f