spec

type BindingEntry struct {
	Source     string         `yaml:"source"`
	SlotParams map[string]any `yaml:"slot_params"`
}

type CIConfig struct {
	FailOnViolation *bool         `yaml:"fail_on_violation"`
	FailSeverity    core.Severity `yaml:"fail_severity"`
}

type CloudConfig struct {
	Enabled *bool  `yaml:"enabled"`
	BaseURL string `yaml:"base_url"`
}

type ControlConfig struct {
	Applicability string `yaml:"applicability"` // "" | applicable | not_applicable
	Reason        string `yaml:"reason"`
	ApprovedBy    string `yaml:"approved_by"`
	// Justification is the reason a control is *included*, the other
	// half of what ISO/IEC 27001:2022 6.1.3 d asks a Statement of
	// Applicability to record. Reason answers "why not this control";
	// Justification answers "why this one". Optional: when it is absent
	// `report --view soa` derives one from the checks standing behind
	// the control, which is accurate but generic — an auditor reading a
	// control the organization reasoned carefully about deserves that
	// reasoning.
	Justification string `yaml:"justification"`
}

type ControlSpec struct {
	ID               string        `yaml:"id"`
	Name             string        `yaml:"name"`
	Description      string        `yaml:"description"`
	Category         string        `yaml:"category"`
	BaselineSeverity core.Severity `yaml:"baseline_severity"`
	// Kind is "catalog" (the default) or "management_system". A
	// project-local framework extension needs this for the same reason
	// the shipped ones do: without it a management-system requirement
	// can be declared not_applicable, which cascades every policy under
	// it to N/A and raises the compliance score for declining to have a
	// management system. Decoding is strict, so an unrecognized value
	// is rejected rather than silently read as the default.
	Kind core.ControlKind `yaml:"kind"`
}

type CustomPeriod struct {
	ID    string `yaml:"id"`
	Start string `yaml:"start"`
	End   string `yaml:"end"`
}

type ExceptionScope struct {
	ResourceID      string `yaml:"resource_id"`
	ResourcePattern string `yaml:"resource_pattern"`
}

type ExtensionsConfig struct {
	Path string `yaml:"path"`
}

type FiscalCalendarConfig struct {
	Type    string         `yaml:"type"`
	Starts  string         `yaml:"starts"`
	Periods []CustomPeriod `yaml:"periods"`
}

type FrameworkSpec struct {
	SchemaVersion string          `yaml:"schema_version"`
	IDValue       string          `yaml:"id"`
	VersionValue  string          `yaml:"version"`
	DisplayName   string          `yaml:"display_name"`
	Description   string          `yaml:"description"`
	ControlsList  []ControlSpec   `yaml:"controls"`
	PoliciesList  []PolicyRefSpec `yaml:"policies"`
}

type OutputConfig struct {
	Format   string `yaml:"format"`
	JSONPath string `yaml:"json_path"`
	Verbose  bool   `yaml:"verbose"`
}

type PeriodConfig struct {
	FiscalCalendar FiscalCalendarConfig `yaml:"fiscal_calendar"`
	TimeBasis      string               `yaml:"time_basis"`
}

type PluginConfigField struct {
	Type        string `yaml:"type"`
	Required    bool   `yaml:"required"`
	Default     any    `yaml:"default"`
	Enum        []any  `yaml:"enum"`
	Description string `yaml:"description"`
}

type PluginCredentialRequirement struct {
	Source string `yaml:"source"`
	EnvVar string `yaml:"env_var,omitempty"`
}

type PluginManifest struct {
	SchemaVersion       string                        `yaml:"schema_version"`
	ID                  string                        `yaml:"id"`
	DisplayName         string                        `yaml:"display_name"`
	Version             string                        `yaml:"version"`
	Description         string                        `yaml:"description"`
	Emits               []string                      `yaml:"emits"`
	Singleton           bool                          `yaml:"singleton"`
	ConfigSchema        map[string]PluginConfigField  `yaml:"config_schema"`
	RequiresCredentials []PluginCredentialRequirement `yaml:"requires_credentials"`
}

type PolicyConfig struct {
	Bindings     map[string][]BindingEntry `yaml:"bindings"`
	Parameters   map[string]any            `yaml:"parameters"`
	Cadence      string                    `yaml:"cadence"`
	EvidenceMode string                    `yaml:"evidence_mode"`
	CatalogEntry string                    `yaml:"catalog_entry"`
	Exceptions   []PolicyException         `yaml:"exceptions"`
}

type PolicyException struct {
	Scope      ExceptionScope `yaml:"scope"`
	State      string         `yaml:"state"`
	Reason     string         `yaml:"reason"`
	ApprovedBy string         `yaml:"approved_by"`
	ApprovedAt string         `yaml:"approved_at"`
	ExpiresAt  string         `yaml:"expires_at"`
}

type PolicyRefSpec struct {
	ID string `yaml:"id"`
}

type ProjectConfig struct {
	SchemaVersion string                    `yaml:"schema_version"`
	Framework     string                    `yaml:"framework"`
	Period        PeriodConfig              `yaml:"period"`
	Vault         VaultConfig               `yaml:"vault"`
	Sources       map[string]map[string]any `yaml:"sources"`

	// Policies holds all per-policy configuration as one object per
	// policy ID — bindings, parameter overrides, cadence override,
	// evidence_mode override, and scoped exceptions co-located in a single
	// place. This replaces the former family of parallel policy-ID-keyed
	// maps (bindings/policy_parameters/policy_cadences/policy_overrides/
	// exceptions). The shape is what makes the config extensible without a
	// schema bump: a new per-policy dimension (severity, scope, owner) is a
	// new optional field on PolicyConfig — additive, never a new top-level
	// section. See docs/architecture/08-project-config.md §The binding model.
	Policies map[string]PolicyConfig `yaml:"policies"`

	// Controls holds control-level decisions — the coarse, governance
	// axis that is naturally per-control, not per-check: applicability
	// (the ISO Statement of Applicability), and room for ownership and
	// inheritance. A control marked not_applicable cascades to every
	// policy that maps to it (planner sets status=na). Fine-grained,
	// resource-scoped waivers stay under Policies[id].exceptions.
	Controls map[string]ControlConfig `yaml:"controls"`

	Cloud         CloudConfig      `yaml:"cloud"`
	CIEnvironment map[string]any   `yaml:"ci_environment"`
	Output        OutputConfig     `yaml:"output"`
	CI            CIConfig         `yaml:"ci"`
	Extensions    ExtensionsConfig `yaml:"extensions"`

	// Experimental is the forward-compatibility escape hatch. The loader
	// runs with KnownFields(true) so a typo in a recognized key is a loud
	// error — but that strictness would also make any *new* top-level key
	// break older CLIs that predate it. New, not-yet-stable fields are
	// introduced under `experimental:` first: every CLI version that has
	// this field tolerates (and ignores) experimental subkeys it does not
	// understand, so a newer config never hard-fails an older pinned CLI.
	// A field graduates from `experimental.<name>` to a first-class
	// top-level key in a later release. The loader does not interpret
	// anything in here; individual features opt in by reading their own
	// key. See docs/architecture/08-project-config.md §Config evolution.
	Experimental map[string]any `yaml:"experimental"`

	// ProjectLocalPolicies are PolicyRefs for policies discovered under
	// .sigcomply/policies/*/policy.yaml at bootstrap and registered into
	// the policy registry. The planner unions these with the active
	// framework's own Policies() so a customer-authored YAML policy is
	// actually planned and evaluated. yaml:"-" — populated by the
	// orchestrator's project-local loader, never decoded from the file.
	ProjectLocalPolicies []core.PolicyRef `yaml:"-"`
}

type Risk struct {
	// ID is a short stable slug, e.g. "r-001" or "laptop_theft".
	ID string `yaml:"id"`
	// Description is what the risk actually is, in the operator's words.
	Description string `yaml:"description"`
	// Owner is the person accountable for the risk — ISO 27001 6.1.2 c)
	// requires every risk to have one.
	Owner string `yaml:"owner"`
	// Level is the evaluated risk level before treatment.
	Level string `yaml:"level"`
	// Treatment is the chosen option: modify, retain, avoid or share.
	Treatment string `yaml:"treatment"`
	// Controls names the Annex A control IDs chosen to treat this risk.
	// This is the edge the Statement of Applicability joins on, and the
	// whole reason the register exists.
	Controls []string `yaml:"controls"`
	// ResidualLevel is the level that remains after treatment.
	ResidualLevel string `yaml:"residual_level"`
	// AcceptedBy and AcceptanceRationale record who signed off on
	// retaining a risk and why. Required when Treatment is "retain",
	// which is the only option that produces no control.
	AcceptedBy          string `yaml:"accepted_by"`
	AcceptanceRationale string `yaml:"acceptance_rationale"`
	// AssessedAt is the date this risk was last assessed (YYYY-MM-DD).
	// Compared arithmetically against the audit period — the only thing
	// that catches a register nobody has revisited in three years.
	AssessedAt string `yaml:"assessed_at"`
}

type RiskRegister struct {
	// DeclaredBy and DeclaredAt are an optional audit trail: who last
	// reviewed the register and when.
	DeclaredBy string
	DeclaredAt string

	// Risks is the declared register, sorted by ID.
	Risks []Risk

	// UnknownKeys names subkeys under experimental.risks the loader did
	// not recognize, so a typo is reported rather than silently ignored.
	UnknownKeys []string
}

type RosterConfig struct {
	// Source is the designated roster source ID. Required when the
	// block is present. Bracketed multi-instance IDs are not supported.
	Source string

	// Aliases maps source ID → lowercased account name → roster email,
	// for accounts whose own email is absent or differs from the
	// roster's. Account names match a record's id or payload.username,
	// case-insensitively.
	Aliases map[string]map[string]string

	// NonHuman maps source ID → lowercased account names that are not
	// people (CI bots, deploy users). Sorted and de-duplicated.
	NonHuman map[string][]string

	// UnknownKeys are subkeys of experimental.roster this CLI does not
	// understand — tolerated, never fatal, but surfaced as warnings.
	UnknownKeys []string
}

type ScopeConfig struct {
	// DeclaredBy and DeclaredAt are the audit trail for the assertion,
	// matching the approved_by/approved_at idiom used by exceptions and
	// control applicability. Both optional.
	DeclaredBy string
	DeclaredAt string

	// RequiredSources lists the source IDs this project asserts are in
	// scope. Sorted on load so the derived report is deterministic
	// (Core Principle #7 — auditors diff runs).
	RequiredSources []string

	// UnknownKeys are subkeys of experimental.scope this CLI does not
	// understand. They are tolerated, never fatal — that tolerance is
	// the whole point of the experimental: hatch — but they are
	// surfaced so a typo is loud without breaking the run.
	UnknownKeys []string
}

type VaultConfig struct {
	Backend string
	Config  map[string]any
}

type Vendor struct {
	// ID is the stable slug used to derive this vendor's policy ID and
	// evidence folder. Changing it re-files the vendor's evidence, so it
	// is deliberately separate from Name.
	ID string

	// Name is the third party as a human names it, used in policy
	// descriptions and the `evidence due` listing.
	Name string

	// Tier is the organization's risk assessment. See the tier
	// constants for what it obliges.
	Tier string

	// Subservice marks a vendor that performs part of the service
	// itself — a SOC 2 subservice organization — rather than merely
	// supplying the organization. It is what makes the complementary
	// user entity controls (CUECs) in the vendor's own report relevant,
	// so the CUEC mapping entry is the place those are reconciled.
	Subservice bool

	// Services is a free-text note on what the vendor does for the
	// organization. Optional, advisory, never evaluated.
	Services string

	// AssurancePeriodEnd is the last day the vendor's own assurance
	// report actually covers — the end of the SOC 2 Type II period, or
	// the certificate's expiry.
	//
	// This is what closes the single most common CC9.2 finding. The
	// temporal window only proves *when the file was uploaded*, so
	// without this a FY2023 Type II uploaded this morning passes, and
	// goes on passing every year forever. Comparing a declared coverage
	// date against the audit period catches that arithmetically.
	//
	// It is DECLARED, never parsed: the CLI does not open the PDF and
	// will not claim to. What it gives an auditor is an assertion
	// recorded in version control, checked for currency on every run.
	// Optional — absent means the freshness check does not run, and the
	// guide says so in those words.
	AssurancePeriodEnd string

	// TierRationale and ApprovedBy are why this vendor sits at this
	// tier, and who signed that off. Required for TierLow, which is the
	// only tier that discharges its obligation with words instead of an
	// artifact. Optional (but encouraged) elsewhere.
	TierRationale string
	ApprovedBy    string

	// Providers names the configured sources this vendor supplies —
	// either a provider token ("aws", "github") or a full source ID
	// ("aws.iam"). It exists for one purpose: to let the planner check
	// the register against something observable.
	//
	// Nothing else can. A vendor the operator simply leaves out is
	// invisible, because the register is a declaration with no
	// counterpart to diff. But every *configured source* is itself a
	// vendor the project demonstrably depends on, so the sources block
	// is a baseline the register must at least cover. Joining the two
	// needs a field, and this is it.
	//
	// Advisory, never fatal, and it discovers nothing: it cross-checks
	// the register against sources the operator already declared, so it
	// stays inside the operator-chosen estate. Optional — a vendor that
	// supplies no configured source (a payroll processor, a law firm)
	// leaves it empty, and that is the normal case.
	Providers []string
}

type VendorRegister struct {
	// DeclaredBy and DeclaredAt are the audit trail for the assertion,
	// matching the approved_by/approved_at idiom used by exceptions,
	// control applicability and the scope declaration. Both optional.
	DeclaredBy string
	DeclaredAt string

	// Vendors is the register itself, sorted by ID on load so every
	// derived artifact is deterministic (Core Principle #7 — auditors
	// diff runs).
	Vendors []Vendor

	// UnknownKeys are subkeys of experimental.vendors this CLI does not
	// understand. Tolerated, never fatal — that tolerance is the point
	// of the experimental: hatch — but surfaced so a typo is loud
	// without breaking the run.
	UnknownKeys []string
}