Documentation
¶
Overview ¶
Package orchestrator is L9 of the SigComply CLI: wires L3 through L8 for the `sigcomply check` command — config load, registry init, plan, collect, evaluate, persist, aggregate, submit, render. The only layer that talks to the human, owns the exit codes, and performs CI environment detection.
See docs/architecture/02-layers.md for the full layer contract.
Package orchestrator is L9 of the SigComply CLI: wires L3 through L8 for the `sigcomply check` command — config load, registry init, plan, collect, evaluate, persist, aggregate, submit, render. The only layer that talks to the human, owns the exit codes, and performs CI environment detection.
See docs/architecture/02-layers.md §L9.
Index ¶
- Constants
- Variables
- func AdvancePolicyState(...) *core.PolicyState
- func Bootstrap(configPath string) (*spec.ProjectConfig, *registry.Set, error)
- func BulkReadPolicyStates(ctx context.Context, vault core.Vault, framework string, policyIDs []string) (map[string]*core.PolicyState, []error)
- func ListPolicyStates(ctx context.Context, vault core.Vault, framework string) (map[string]*core.PolicyState, error)
- func PolicyStatePath(framework, policyID string) string
- func PolicyStatePrefix(framework string) string
- func ReadPolicyState(ctx context.Context, vault core.Vault, framework, policyID string) (*core.PolicyState, error)
- func WritePolicyState(ctx context.Context, vault core.Vault, ps *core.PolicyState) error
- type Mode
- type Options
- type Result
Constants ¶
const ( ExitOK = 0 ExitViolation = 1 ExitExecution = 2 ExitConfig = 3 )
Exit codes match docs/architecture/02-layers.md §Layered errors.
const ManifestSchemaVersion = "run.v1"
ManifestSchemaVersion is the run-manifest schema stamped at write time.
Variables ¶
var ErrBootstrapAlreadyInitialized = errors.New("orchestrator: already initialized")
ErrBootstrapAlreadyInitialized is reserved for future use.
Functions ¶
func AdvancePolicyState ¶ added in v0.21.0
func AdvancePolicyState( framework, policyID, runID, periodID, configuredCadence, policyHash, envelopeRef string, status core.PolicyStatus, startedAt time.Time, cadenceInterval time.Duration, ) *core.PolicyState
AdvancePolicyState updates the per-policy state at the end of a run that actually evaluated the policy. The caller passes the policy result, the run's start timestamp, run ID, period ID, content hash, and envelope reference; this helper produces the new PolicyState value (without writing it). The orchestrator's AdvanceAllPolicyStates writes it via WritePolicyState.
For carry-forward results (where the run did NOT evaluate the policy) the orchestrator skips this function entirely — the existing state shard is preserved verbatim.
func Bootstrap ¶
Bootstrap is a convenience helper for tests and the CLI command: loads the config file and constructs an empty registry set ready for framework registration. The vault is constructed by the caller so tests can inject in-memory backends.
func BulkReadPolicyStates ¶ added in v0.21.0
func BulkReadPolicyStates(ctx context.Context, vault core.Vault, framework string, policyIDs []string) (map[string]*core.PolicyState, []error)
BulkReadPolicyStates fetches state shards for many policies in parallel and returns a map keyed by policy ID. Missing shards are represented as a nil value (not absent from the map) so callers can distinguish "policy in framework but never run" from "policy not in this framework at all."
Parallelism is bounded by stateBulkReadConcurrency. Errors from individual shards are collected; a partial failure does NOT abort the overall load — the orchestrator degrades gracefully by treating an unreadable shard as a first run (with a warning emitted via the logger).
func ListPolicyStates ¶ added in v0.21.0
func ListPolicyStates(ctx context.Context, vault core.Vault, framework string) (map[string]*core.PolicyState, error)
ListPolicyStates enumerates every state shard under a framework's prefix. Used by `sigcomply status`, `sigcomply audit-ledger`, and orphan-shard detection (state for a policy no longer in the bundle).
The vault's List backend is authoritative for the result. An unimplemented List (some test vaults) returns an empty map — that is the correct degradation for "no state to enumerate."
func PolicyStatePath ¶ added in v0.21.0
PolicyStatePath returns the canonical vault path for a single policy's state shard. State shards live OUTSIDE the per-period evidence prefix because they are mutable scheduling state — never signed, never an audit deliverable. See docs/architecture/05- vault-layout.md §State.
Path scheme: state/{framework}/policies/{policy_id}.json
func PolicyStatePrefix ¶ added in v0.21.0
PolicyStatePrefix returns the directory prefix that holds every state shard for a framework. Useful for List operations.
func ReadPolicyState ¶ added in v0.21.0
func ReadPolicyState(ctx context.Context, vault core.Vault, framework, policyID string) (*core.PolicyState, error)
ReadPolicyState fetches one state shard from the vault. A missing shard returns (nil, nil) — the planner treats this as "first run" and evaluates the policy unconditionally. A corrupted shard returns an error so the caller can log-and-degrade explicitly; silently discarding state would mask a real problem (lost run history, bucket misconfiguration).
func WritePolicyState ¶ added in v0.21.0
WritePolicyState persists one state shard with a monotonic guard: the write is accepted iff the new state's LastRunAt is strictly newer than the persisted shard's LastRunAt, OR the two are equal and the new LastRunID sorts lexicographically higher. This prevents an out-of-order CI run (slow clock, late-arriving worker) from clobbering a more-recent successor.
The function performs a read-then-write — a true concurrent collision is rare in CI (most orgs serialize runs against one vault) and the surviving writer wins deterministically. On backends that expose conditional writes (S3 If-Match, GCS generation preconditions, Azure ETag) a future revision can wire those in through the core.Vault interface.
A missing shard is treated as "no prior state" — the new state wins. Returns nil when the write is accepted, nil when it is rejected by the monotonic guard (the caller's perspective: "the vault already has equivalent-or-newer state, which is fine"), and a non-nil error only for true I/O failures.
Types ¶
type Mode ¶ added in v0.21.0
type Mode string
Mode determines the higher-level run shape. ModeManual is the default (one-shot ad-hoc check); ModePR is for PR/push-triggered CI, narrows the plan to on_push policies and uses a generous slot retry budget; ModeScheduled is for cron-triggered CI, reads the per-policy state shards, decides which policies are due, and advances state on success. See docs/architecture/10-cadence-model.md §Modes.
const ( // ModeManual is the default ad-hoc one-shot run shape. ModeManual Mode = "" // ModePR narrows to on_push policies and uses a generous slot retry budget. ModePR Mode = "pr" // ModeScheduled consults per-policy state, gates evaluation by cadence, // and advances state on success. ModeScheduled Mode = "scheduled" )
Mode values.
type Options ¶
type Options struct {
Config *spec.ProjectConfig
Registries *registry.Set
Vault core.Vault
// CLI metadata, stamped on outputs.
CLIVersion string
CommitSHA string
CommitTime time.Time
Branch string
// Output controls.
Stdout io.Writer
Logger *log.Logger
// Submission overrides.
ForceCloud bool
DisableCloud bool
// CapturePayloadPath, when non-empty, writes the SubmissionPayload
// JSON to disk instead of POSTing it. Powers the auditor-facing
// --capture-cloud-payload escape hatch.
CapturePayloadPath string
// Now is the run's reference time. Tests inject deterministic values;
// production callers leave nil.
Now func() time.Time
// Submitter overrides for tests.
SubmitterOpts submitter.Options
// Filter narrows the plan to a subset of policies. The planner
// enforces mutual exclusion across Filter's fields; the orchestrator
// just threads it through. When Mode is ModePR and Filter's cadence
// axes are unset, the orchestrator derives Filter.Cadences from the
// mode (PR → [on_push]).
Filter planner.Filter
// Mode selects the higher-level run shape (manual / pr /
// scheduled). See the Mode type for semantics. ModeManual is
// the default and preserves legacy single-run behavior.
Mode Mode
}
Options is the input to Run. Most fields come from CLI flags or the project config. Registries and Vault are pre-constructed by Bootstrap so tests can inject in-memory backends without redoing config load.
Source Files