Skip to content
Orbit Orbit Orbit

Auditability — Vision

Mirrored from docs/design/auditability/3_vision.md. Edit the source document in the repository, not this generated page.

This document captures the questions that remain before Orbit’s auditability story matches its product promise end to end. 2_design.md is the current implementation; this file names the pressure points that should drive future tasks and ADRs.

1. Open Questions

Section titled “1. Open Questions”
  1. Canonical query surface. Should orbit audit stay command-row-only, or grow a run-centric view that joins command rows, job-run state, v2 envelopes, loop JSONL, blobs, and invocation metrics?
  2. Local tamper evidence. Should Orbit use per-file hash chains, SQLite append proofs, signed manifests, git-backed checkpoints, or export-time attestations while staying self-hosted by default?
  3. Auditing audit reads. Should orbit audit reads, exports, and prunes remain outside the guard to avoid recursion, or be recorded through a separate path?
  4. Stable identity key. What joins human CLI usage, model-first tool inputs, task attribution fields, v2 agent_identity, invocation metrics, commits, and PR metadata?
  5. Stdout/stderr retention. The command schema has truncated stdout/stderr fields, but most paths leave them empty. What retention policy should exist before broad capture?
  6. JSONL migration. [T20260426-0519] moved run traces to .orbit/state/audit/; should old .orbit/audit/ files be migrated, ignored, or read through a legacy fallback?
  7. Replay payload depth. When are redacted verbatim prompts/responses required, and when are summaries enough?
  8. Uniform denials. Can filesystem denials, tool allowlist denials, task-lock conflicts, and gate starvation share one audit shape?
  9. Coverage enforcement. What lint or tests should fail review when a new mutation path lacks audit coverage?
  10. Metrics derivation. Should invocation metrics stay primary records, or eventually derive from loop traces at the cost of tighter coupling?

2. Prior Work

Section titled “2. Prior Work”

2.1 Orbit-Internal

Section titled “2.1 Orbit-Internal”

Activity / Job’s audit-envelope section and ADRs in ../activity-job/2_design.md and ../activity-job/4_decisions.md document the v2 envelope, backend differences, CLI allowlist delegation, file-backed audit placement, and invocation trace persistence.

The product contract lives in ../../../README.md and ../../POSITIONING.md: auditability should answer what, why, and who; audit rows should be structured and queryable; provider interactions should be reproducible after redaction; retention should become tamper-evident; and identity should attach to every write.

The redaction and blob-store implementation is the existing write-side safety boundary. Future query tools should preserve it even if they read blobs more directly.

2.2 Workflow and Observability Systems

Section titled “2.2 Workflow and Observability Systems”

Temporal and Airflow show the value of explicit run, step, retry, and state-transition history. OpenTelemetry shows the value of trace/span identifiers and exportable schemas. Orbit should borrow the join model while keeping accountability and replay obligations distinct from generic telemetry.

2.3 Supply-Chain Attestation

Section titled “2.3 Supply-Chain Attestation”

SLSA, in-toto, Sigstore, and Rekor point toward signed or transparency-backed provenance. Orbit can learn from those systems, but local/self-hosted operation must remain the default.

2.4 Security Event Logging

Section titled “2.4 Security Event Logging”

Security audit systems treat reads, writes, privilege decisions, and retention as one accountability surface. Orbit’s domain is narrower, but a policy denial, task update, provider request, and PR operation should all be explainable from the audit trail.

3. What May Be Distinctive

Section titled “3. What May Be Distinctive”
  1. Code-aware audit joins. Orbit can join records by run id, task id, context selector, lock reservation, worktree, graph node, and commit attribution.
  2. Agent identity as a first-class actor. The trail can name humans, model families, provider backends, and task roles without treating agents as generic service accounts.
  3. Transcript plus structure. V2 envelopes describe the workflow tree while loop blobs preserve redacted provider/tool payloads.
  4. Local tamper evidence. A self-hosted team-scale runtime can produce verifiable local audit bundles without a hosted control plane.
  5. Coverage as a design gate. New mutation paths should name their audit event family before they ship.

4. References

Section titled “4. References”

Orbit-internal:

External reference categories:

  • Workflow run history: Temporal, Airflow.
  • Structured traces and logs: OpenTelemetry.
  • Supply-chain provenance and tamper evidence: SLSA, in-toto, Sigstore, Rekor.
  • Security audit logging: append-only security event logs and retention policies.

Task References

Section titled “Task References”
  • [T20260419-0002] — Add workspace provenance and v2 audit envelope events for activity/job execution.
  • [T20260426-0519] — Move file-backed activity/job audit traces under workspace state.
  • [T20260426-0526] — Persist v2 invocation traces for metrics beside audit.
  • [T20260426-0605] — Add this auditability design folder and name future auditability questions.
  • [T20260430-20] — Shorten the auditability docs while preserving required guarantees.

Resolve any task above with orbit task show <ID> or git log --grep=<ID>.