coreci/orca
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 91 Wiki Activity
Files
f503404ddada676cf4a5da9225e30ae4d1bb8669
orca/.ciagent/PROJECT.md
T
ciagent f503404dda docs(audit): fix .ciagent/ file discipline findings from v0.2 P01 audit 
CIAgent audit (.ciagent/AUDIT_v0.2_P01.md) surfaced 3 .ciagent/ file
discipline issues. This commit addresses all 3:

1. config.json: re-add the 'workflow' top-level block. It was added in
   d10f89d (v0.1 milestone) and lost from main during the parallel-
   history resolution that produced origin/main's be9afa2 PR-#1 merge.
   The 4 standing rules (no_hitl, release_flow_per_phase, merge_strategy,
   branching) are restored.

2. PROJECT.md: add literal '## What This Is' and '## Key Decisions'
   section headers. The v0.1 audit-fix (f1c55ca) added the content
   inline but without the explicit headers, so the audit check missed
   them. The Key Decisions section summarizes D-011..D-018.

3. REQUIREMENTS.md: consolidate two overlapping REQ tables (the v0.1
   status table and the v0.2 traceability table) into a single
   canonical table covering all 40 REQs (REQ-001..REQ-040). Each row
   has REQ-ID, summary, priority, phase, status. v0.1 REQs show
   'Complete'; v0.2 REQs show 'Complete' (P01 shipped) or 'Pending
   (P##)'. The v0.1 Milestone Summary and v0.2 Milestone Summary
   sections are preserved below the table.

4. AUDIT_v0.2_P01.md: the audit report itself, with reconstruction
   state, file discipline table, branch hygiene, commit discipline,
   and the 3 findings above (plus non-blocking observations). The
   report's verdict: 'v0.2 P01 ship is healthy; 3 issues are
   paper-cleanup items addressed in this commit. None block P02
   EXECUTE.'

---ci---
project: orca
phase: 0
milestone: v0.2
status: fix
---/ci---
2026-06-03 22:19:45 +00:00

7.9 KiB
Raw Blame History

Project: Orca

What This Is

A minimalist, offline-first, CLI-first orchestration engine inspired by HashiCorp Nomad, prioritizing stability, security, and simplicity over feature richness. Single-binary distribution, no container runtime, no cloud dependencies, no K8s-level complexity.

Vision

A minimalist, offline-first, CLI-first orchestration engine inspired by HashiCorp Nomad, prioritizing stability, security, and simplicity over feature richness.

Objective

Build a lightweight system to manage and execute workloads across a set of nodes, keeping complexity far below that of Kubernetes.

Requirements

  • CLI First: Primary interaction through a CLI tool.
  • Offline First: Functional without constant internet connectivity.
  • AI First: Designed to be easily discoverable and manageable by AI agents.
  • Stability & Security: Prioritize security fixes and bug fixes over new features.
  • Language: Written in Go 1.25+.
  • Simplicity: Minimalist implementation, avoiding the "K8s complexity trap".

Constraints

  • No web UI as a primary requirement.
  • Must not implement K8s-level complexity.
  • Feature development must move slowly to ensure stability.
  • Only CI system allowed: CoreCI (git.cloudinit.dev/coreci/coreci).
  • Gitea remote: git.cloudinit.dev/coreci/orca.

Clarified Decisions (D-series, full autonomy)

ID Question Decision Rationale Confidence
D-001 Single binary or multi-binary distribution? Single binary Simpler distribution; subcommands baked into one orca binary. Aligns with simplicity pillar. 0.95
D-002 Local state store technology? modernc/sqlite (pure Go, CGO-free) Cross-compile friendly, no CGO dependency, single file on disk, mature. 0.92
D-003 Inter-node communication? Embedded HTTP (net/http) over loopback, mTLS for cross-node No external RPC framework needed for v0.1. HTTP suffices. 0.85
D-004 Scheduling algorithm for v0.1? Single-node only (no scheduling) Multi-node scheduling is out of scope for v0.1. Tasks run on the node they're submitted to. 0.90
D-005 CLI output format? Human-readable by default, --json flag for machine consumption Serves both humans and AI agents. 0.95
D-006 Job/task definition format? HCL or YAML in .hcl/.yaml files Familiar to Nomad/HashiCorp users; simpler than JSON for humans. 0.88
D-007 Authentication? mTLS for v0.1, token-based deferred mTLS is the most secure default. Tokens can be added later if needed. 0.80
D-008 Container runtime? Direct process execution (no container runtime) for v0.1 Avoids the Docker/container dependency. Pure process management. 0.85
D-009 Configuration file location? ~/.orca/config.hcl and /etc/orca/orca.hcl Standard XDG-style paths. 0.90
D-010 Logging format? Structured JSON via log/slog Native Go 1.21+ slog, no external dependency. 0.95
D-011 v0.2 mTLS cert authority model? Internal CA with CSR join One node bootstraps a local CA; peers generate CSRs and submit them to the CA for signing. CA cert is the trust anchor. More secure than self-signed per-node (single trust root) without the operational complexity of an external PKI. 0.92
D-012 v0.2 CA bootstrap & cert distribution? Operator-mediated, fingerprint-verified Bootstrap node writes ~/.orca/ca.crt and ~/.orca/ca.key (mode 0600). Operator copies ca.crt to peers; peers verify by SHA-256 fingerprint at orca node join --ca-fingerprint <sha256>. No automated secret distribution. 0.85
D-013 v0.2 cert validity & rotation? Server certs 90 days, CA cert 10 years, rotate 30 days before expiry Server certs are short-lived (compromise window small); CA is long-lived (manual rotation is expensive). orca cert renew reissues server certs automatically. 0.90
D-014 v0.2 mTLS handshake timing? Eager — at orca node join time Fail fast on bad certs, misconfigurations, or CA mismatches. Lazy handshake would let stale configs run until first request, complicating debugging. 0.88
D-015 v0.2 minimum TLS version & cipher suites? TLS 1.3 only; AEAD cipher allowlist MinVersion=tls.VersionTLS13, CipherSuites limited to TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_GCM_SHA256. No TLS 1.2 fallback. 0.92
D-016 v0.2 security-scanning placement? validate pipeline of .coreci.yml, gates merges to main gosec baseline JSON checked into repo; new findings fail the build. govulncheck ./... exit-on-known. Pre-commit hook with gitleaks is opt-in (developer machine). 0.85
D-017 v0.2 iter.Seq API surface? orca job list --watch and orca node list --watch Pull-based iter.Seq[Job] / iter.Seq[Node]; cancellation via context.Context; signal.NotifyContext on ctrl-c. Backpressure is implicit (consumer-driven). 0.90
D-018 v0.2 multi-node scheduling algorithm? Bin-packing by available CPU/memory, FIFO within a node Simple, deterministic, matches D-004 minimalism. Cross-node dispatch via ConnectRPC orca.v1.Dispatch service. Retry on transient failures with exponential backoff. 0.85

Out of Scope

  • Full-blown Kubernetes-compatible API.
  • Complex cloud-provider integrations.
  • GUI-based management consoles.
  • Container runtime integration.
  • Service mesh / sidecar injection.
  • Auto-scaling / horizontal pod autoscaler.
  • External PKI / Let's Encrypt / cert transparency logs.
  • gRPC framework dependency (ConnectRPC in config.json frameworks but not in go.mod; v0.2 uses stdlib net/http with h2c for orca.v1.Dispatch — see ARCHITECTURE.md AD-014).

v0.2 Scope Summary

v0.2 is a focused 4-phase milestone that turns Orca from a single-node process executor into a small cluster engine with strong transport security and richer I/O. The 4 phases are:

  • P01 — mTLS handshake + internal CA with CSR join. Internal CA, CSR join, eager handshake at node join, TLS 1.3 + AEAD allowlist. See ARCHITECTURE.md Flow 1 + Flow 2.
  • P02 — Multi-node scheduling & job dispatch. Best-fit bin-packing by CPU/memory, FIFO within a node, orca.v1.Dispatch over mTLS. See ARCHITECTURE.md Flow 3.
  • P03 — gosec + govulncheck + gitleaks in CI. gosec baseline JSON in repo, govulncheck ./... in validate pipeline, gitleaks in pre-commit (opt-in).
  • P04 — iter.Seq streaming for --watch flags. Go 1.25+ range-over-func semantics, context.Context cancellation, signal.NotifyContext on ctrl-c. See ARCHITECTURE.md Flow 4.

The vision ("minimalist, offline-first, CLI-first orchestration engine") is unchanged. v0.2 is a hardening + small-cluster extension, not a direction change.

Key Decisions

The 18 D-series decisions (D-001..D-018) are recorded in the "Clarified Decisions" table above. The 10 v0.1 decisions (D-001..D-010) are stable and unchanged in v0.2. The 8 v0.2 decisions (D-011..D-018) were auto-resolved under full autonomy and are summarized here:

  • D-011: Internal CA with CSR join (vs. self-signed per-node or SPIFFE). Single trust root, no external PKI, CSR workflow.
  • D-012: Operator-mediated CA cert distribution with fingerprint verify (no automated secret distribution — matches offline-first principle).
  • D-013: 90d server certs, 10y CA cert, 30d pre-expiry rotation.
  • D-014: Eager mTLS handshake at orca node join time (fail fast).
  • D-015: TLS 1.3 only, AEAD cipher allowlist (no TLS 1.2 fallback).
  • D-016: gosec+govulncheck in validate pipeline of .coreci.yml (gates merges to main). gitleaks in pre-commit (opt-in).
  • D-017: iter.Seq for orca job list --watch and orca node list --watch (pull-based, ctx cancellation, ctrl-c via signal.NotifyContext).
  • D-018: Bin-packing by CPU/memory with FIFO within node; JSON-over-HTTP orca.v1.Dispatch for cross-node (no ConnectRPC dep).
Reference in New Issue View Git Blame Copy Permalink