config

type Agent struct {
	Enabled bool   `json:"enabled"`
	Version string `json:"version,omitempty"`
}

type AgentsRC struct {
	Schema   string           `json:"$schema,omitempty"`
	Version  int              `json:"version"`
	Project  string           `json:"project,omitempty"`
	Skills   []string         `json:"skills,omitempty"`
	Rules    []string         `json:"rules,omitempty"`
	Agents   []string         `json:"agents,omitempty"`
	Hooks    StringsOrBool    `json:"hooks"`
	MCP      StringsOrBool    `json:"mcp"`
	Settings bool             `json:"settings"`
	Sources  []Source         `json:"sources"`
	KG       *AgentsRCKG      `json:"kg,omitempty"`
	Refresh  *RefreshMetadata `json:"refresh,omitempty"`

	// RepoID is the canonical repository identity (e.g. "github.com/acme/manager-ui").
	// Protected: imported layers cannot override it. See org-config-resolution §5.
	RepoID string `json:"repo_id,omitempty"`
	// Extends references config layers in the form "source-id:layer-path[@version]".
	// Each entry may be a plain string or an object form `{"ref": "...", "optional": true}`.
	// Tier constraint (enforced at schema validation): extends entries must reference
	// git|http|local sources — see config-distribution-model §4.
	Extends []LayerRef `json:"extends,omitempty"`
	// Packages references executable artifact bundles in the form
	// `source-id:artifact-path@version-spec`. Any source kind (git|local|http|oci)
	// may supply an artifact (config-distribution-model §15 D8).
	Packages []PackageRef `json:"packages,omitempty"`
	// Features overrides feature-flag defaults (config-distribution-model §3.6).
	Features map[string]string `json:"features,omitempty"`
	// ExecutionProfile is the config-v2 §15-shaped, scope-mergeable layer that
	// routes a task's workflow execution shape (unit relevance + topology +
	// lenses) by app_type. It is a kind=layer policy fragment — see
	// internal/config/execution_profile.go and the
	// skill-relevance-filter design.
	ExecutionProfile *ExecutionProfile `json:"execution_profile,omitempty"`
	// PRSource is the config-driven pull-request event producer config
	// (pr-event-source design D4). It configures the generic internal/events
	// producer engine — a fetch+field-map per platform — so PR state becomes
	// event.pr.* events with no per-platform Go. `gh` is the zero-config default;
	// an org layer can override the default via the config-v2 scope layers.
	PRSource *AgentsRCPRSource `json:"pr_source,omitempty"`

	// StageProfiles are named per-stage prompt-composition profiles, keyed by
	// stage (executor | verifier | reviewer | orchestrator) then by slug. Each
	// profile's prompt_files is source-aware (config-v2 Q1 ruling, Option B): an
	// entry is a typed {source, path, version} object, with the bare-string legacy
	// form still accepted on read (see PromptFileRef). The verifier and reviewer
	// stages supersede the deprecated verifier_profiles / reviewer_profiles maps,
	// and topology.verifier_sequence supersedes app_type_verifier_map; all three
	// legacy keys are still read and folded in here for back-compat (see
	// UnmarshalJSON / foldLegacyProfiles) and are never re-emitted.
	StageProfiles map[string]map[string]StageProfile `json:"stage_profiles,omitempty"`

	// PreconditionPolicies is the top-level named registry of verifier
	// precondition policies (verifier-precondition-policy plan, Slice B). Each
	// entry is a named policy = an ordered list of predicates over the unified
	// event/signal contract. A stage profile references a policy by name via
	// StageProfile.PreconditionPolicy; the verifier reads the resolved policy
	// from the lockfile. Absent ⇒ the built-in `default` gate applies.
	PreconditionPolicies map[string]PreconditionPolicySpec `json:"precondition_policies,omitempty"`

	// ExtraFields captures unknown JSON keys so Save() can round-trip them
	// instead of silently dropping legacy or custom fields.
	ExtraFields map[string]json.RawMessage `json:"-"`

	// LegacyKeys lists the deprecated v1 JSON keys observed in the source
	// manifest during UnmarshalJSON (verifier_profiles / reviewer_profiles /
	// app_type_verifier_map). These keys are silently folded into the unified
	// stage_profiles / execution_profile model (see foldLegacyProfiles) and
	// never re-emitted; recording them here lets `da init` / `da doctor`
	// surface a deprecation warning without re-parsing the file (config-v2
	// §15.3 deprecation cadence). Not serialized.
	LegacyKeys []string `json:"-"`
}

type AgentsRCKG struct {
	// GraphHome overrides KG_HOME env var for this project. Defaults to ~/.knowledge-graph.
	GraphHome string `json:"graph_home,omitempty"`
	// Backend selects the storage backend: "sqlite" (default) or "postgres".
	// Postgres requires KG_POSTGRES_URL.
	Backend string `json:"backend,omitempty"`
	// Bridge configures workflow/kg bridge query behaviour for this project.
	Bridge AgentsRCKGBridge `json:"bridge"`
}

type AgentsRCKGBridge struct {
	Enabled        bool     `json:"enabled"`
	AllowedIntents []string `json:"allowed_intents,omitempty"`
}

type AgentsRCPRFetch struct {
	Argv    []string          `json:"argv,omitempty"`
	URL     string            `json:"url,omitempty"`
	Method  string            `json:"method,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
	Each    string            `json:"each,omitempty"`
	Map     map[string]string `json:"map,omitempty"`
}

type AgentsRCPRSource struct {
	// Producer selects the named producer: "gh" (default), "exec", "http", or a
	// registered code producer.
	Producer string `json:"producer,omitempty"`
	// List fetches the open PR list and maps it onto canonical PR fields.
	List *AgentsRCPRFetch `json:"list,omitempty"`
	// Comments fetches one PR's comments. Optional.
	Comments *AgentsRCPRFetch `json:"comments,omitempty"`
	// PollIntervalS is the producer poll cadence in seconds.
	PollIntervalS int `json:"poll_interval_s,omitempty"`
}

type AppTypeProfile struct {
	// Relevance is facet 1 (the noise filter): per-stage core/situational/noise
	// classification of skills/agents/lenses. The map key is the stage name
	// (e.g. "orchestrate", "verify", "review").
	Relevance map[string]RelevanceClasses `json:"relevance,omitempty"`
	// Topology is facet 2: the executor:verifier:reviewer fan-out shape. It is the
	// successor to the retired flat app_type_verifier_map — verifier_sequence lives
	// here, and legacy app_type_verifier_map entries are folded in on load.
	Topology Topology `json:"topology,omitempty"`
	// Lenses is facet 3: the review-lens config folded in from
	// lens-evidence-policy (lens_set + lens_concurrency).
	Lenses Lenses `json:"lenses,omitempty"`
}

type AuditEmitter interface {
	// Emit records one audit event. Implementations must not block resolution.
	Emit(AuditEvent)
}

type AuditEvent struct {
	// Timestamp is when the event was produced (UTC).
	Timestamp time.Time `json:"timestamp"`
	// Actor is the emitting component (always auditActor for this package).
	Actor string `json:"actor"`
	// Principal is the human/service identity on whose behalf resolution ran,
	// or "" when not attributed.
	Principal string `json:"principal,omitempty"`
	// Action is one of the config.* action constants.
	Action string `json:"action"`
	// Target is the subject of the action (source id, layer ref, field path, or
	// repo id depending on Action).
	Target string `json:"target"`
	// Outcome is the disposition (success, dropped, failure, skipped).
	Outcome string `json:"outcome"`
	// TraceID correlates every event emitted within a single Resolve call.
	TraceID string `json:"trace_id"`
	// Fields holds the action-specific structured attributes.
	Fields map[string]any `json:"fields,omitempty"`
}

type CacheKeyGit struct {
	// Commit pins the key on the resolved commit hash (the git default fact).
	Commit bool `json:"commit,omitempty"`
	// Tags pins the key on the set of tags pointing at the resolved commit, so a
	// re-tag (without a commit change) is a new key.
	Tags bool `json:"tags,omitempty"`
}

type CacheKeyInputs struct {
	// ResolvedCommit is the resolved git commit hash for a git or local source.
	ResolvedCommit string
	// WorktreeDirty reports whether a local source's working tree has
	// uncommitted changes (§7A.4: local keys on commit PLUS working-tree state).
	WorktreeDirty bool
	// WorktreeContentHash is an optional precise hash of the local working
	// tree's content; when set it makes the local key sensitive to the exact
	// uncommitted bytes, not just the dirty flag. Empty falls back to the dirty
	// marker alone.
	WorktreeContentHash string
	// Tags are the git tags pointing at ResolvedCommit, used by the {git:{tags}}
	// selector. Order-insensitive (sorted before hashing).
	Tags []string
	// ETag is the http source's upstream ETag validator (the preferred http key).
	ETag string
	// LastModified is the http source's Last-Modified validator (used when no
	// ETag is sent).
	LastModified string
	// ContentDigest is the fallback content hash for an http source whose server
	// sent neither ETag nor Last-Modified.
	ContentDigest string
	// OCIDigest is the oci manifest digest (the content-addressed oci key).
	OCIDigest string
	// FileContents maps a Source.cache_keys file/glob entry to its resolved
	// content hash, for the {file} selector. The caller hashes the matched
	// files; this layer only folds the hashes into the composite key.
	FileContents map[string]string
	// EnvValues maps a Source.cache_keys env name to its current value, for the
	// {env} selector. A missing var is recorded as absent.
	EnvValues map[string]string
	// DirPresent maps a Source.cache_keys dir entry to whether it exists, for
	// the {dir} selector.
	DirPresent map[string]bool
}

type CacheKeyOptions struct {
	// Refresh is the per-unit `--refresh` force escape: when true the effective
	// key is AlwaysRevalidate, so this resolve re-checks upstream unconditionally
	// even if nothing else changed.
	Refresh bool
}

type CacheKeys struct {
	// Files lists tracked file paths or globs whose content pins the key — a
	// change to any matched file is a new key (uv `cache-keys = [{file=...}]`).
	Files []string `json:"file,omitempty"`
	// Git selects which git facts (commit and/or tags) pin the key. Nil means
	// the git facts do not participate in the override.
	Git *CacheKeyGit `json:"git,omitempty"`
	// Env lists environment variable names whose values pin the key — a changed
	// value (e.g. a credential or feature flag) is a new key.
	Env []string `json:"env,omitempty"`
	// Dir lists directory paths whose presence pins the key — a {dir} marker is
	// "exists" / "absent", catching a source that appears or disappears.
	Dir []string `json:"dir,omitempty"`
	// AlwaysRevalidate is the config-declared force escape (§7A.4 / R6): when
	// true the effective key is the AlwaysRevalidate sentinel, so the resolver
	// re-checks upstream on every resolve regardless of the recorded digest.
	AlwaysRevalidate bool `json:"always_revalidate,omitempty"`
}

type Checker struct {
	// Authorizer is the pluggable policy implementation. When nil, no backend
	// is wired and governed scopes fall back to the safe default.
	Authorizer WriteAuthorizer
}

type ClassifiedUnit struct {
	// Unit is the candidate skill/agent/lens id.
	Unit string `json:"unit"`
	// Class is the resolved relevance class: "core", "situational", or "noise".
	Class string `json:"class"`
}

type Config struct {
	Version  int                `json:"version"`
	Defaults Defaults           `json:"defaults,omitempty"`
	Projects map[string]Project `json:"projects"`
	Agents   map[string]Agent   `json:"agents,omitempty"`
	Features Features           `json:"features,omitempty"`
}

type Decision string

type Defaults struct {
	Agent string `json:"agent,omitempty"`
}

type EditScope string

type EnsureOpts struct {
	// Locked asserts the lock is fresh: a stale lock yields ErrLockWouldChange
	// and no write (CI gate).
	Locked bool
	// Frozen uses the lock as-is and skips the staleness check entirely.
	Frozen bool
	// NoSync skips the caller's outputs/projection step. It does not affect the
	// lock decision here; it is recorded on the result for the caller.
	NoSync bool
	// Offline resolves from lock/cache only and never contacts the network.
	Offline bool

	// UserLocalPath is the resolver's user-local manifest seam, threaded into the
	// staleness inputs_digest computation so it honors the same override the
	// resolver uses. Empty ⇒ default <AgentsHome>/.agentsrc.json.
	UserLocalPath string
	// UnitDigest is the staleness per-unit digest seam (staleness.go). Nil skips
	// the per-unit digest driver event (inputs_digest + declared-set only).
	UnitDigest UnitDigestFunc
	// Resolver overrides the resolver seam (test injection of a fake). Nil ⇒ a
	// default NewLayeredResolver(). Both Resolve (rewrites the lock) and
	// ResolveLocked (read-only) stay behind this interface so tests never touch
	// the network.
	Resolver EnsureResolverSeam
}

type EnsureResolverSeam interface {
	// Resolve rebuilds the layer stack and REWRITES the lock.
	Resolve(projectPath string) (*Snapshot, error)
	// ResolveLocked rebuilds the snapshot from the lock/cache WITHOUT any fetch
	// or write.
	ResolveLocked(projectPath string) (*Snapshot, error)
}

type EnsureResult struct {
	// Snapshot is the resolved effective config. Always non-nil on a nil error.
	Snapshot *Snapshot
	// ReResolved is true when the default-mode stale path ran Resolve and
	// rewrote the lock. It is false for the Frozen, Offline, fresh, and (error)
	// Locked paths — none of which write.
	ReResolved bool
	// Fresh is true when the staleness check reported no driver event. It is
	// false in Frozen mode (the check is skipped) and on any stale path.
	Fresh bool
	// NoSync echoes EnsureOpts.NoSync so the caller can gate its outputs step
	// without re-deriving it.
	NoSync bool
	// Reasons lists the driver events that made the lock stale (empty when fresh
	// or Frozen). Surfaced so the caller can explain why a re-resolve happened.
	Reasons []StalenessReason
}

type ExecutionProfile struct {
	// ByAppType maps an app_type string (e.g. "go-cli", "ideation") to its
	// resolved execution shape. Each task in a plan picks its profile by
	// naming an app_type; unmatched app_types fall back to caller defaults.
	ByAppType map[string]AppTypeProfile `json:"by_app_type,omitempty"`
	// DefaultClass is the relevance class assigned to any unit not explicitly
	// listed in a stage's RelevanceClasses. It defaults to "situational" so a
	// unit is never silently dropped from the working set — see ClassOf and
	// DefaultRelevanceClass.
	DefaultClass string `json:"default_class,omitempty"`
}

type Features struct {
	Tasks   bool `json:"tasks,omitempty"`
	History bool `json:"history,omitempty"`
	Sync    bool `json:"sync,omitempty"`
}

type FetchedArtifact struct {
	// Data is the raw artifact blob.
	Data []byte
	// Digest is the canonical "sha256:<hex>" content digest (spec §7.2).
	Digest string
	// CacheHit reports whether Data came from the local package cache.
	CacheHit bool
	// Posture is the signing posture applied to this pull.
	Posture SigningPosture
	// KeyInputs carries the resolved facts for the source's effective content
	// cache key (config-distribution-model §7A.4): the manifest digest for oci,
	// the digest (plus any ETag/Last-Modified validator) for http-as-packages, so
	// the package resolver can derive an effective key via EffectiveCacheKey. A
	// zero value falls back to the kind default keyed on Digest.
	KeyInputs CacheKeyInputs
}

type FetchedLayer struct {
	// Data is the raw layer.json bytes.
	Data []byte
	// ResolvedSHA is the git commit SHA (git) or content hash (http/local) the
	// layer was fetched at. It is the cache key and the lockfile resolved_sha.
	ResolvedSHA string
	// CacheHit reports whether Data came from the local cache.
	CacheHit bool
	// KeyInputs carries the resolved facts the fetcher observed for this source
	// (git commit, http ETag/Last-Modified/digest, local commit + worktree
	// state), so the resolver can derive the source's effective content cache key
	// (config-distribution-model §7A.4) via EffectiveCacheKey without re-running
	// the fetch. A zero value falls back to the kind default keyed on ResolvedSHA.
	KeyInputs CacheKeyInputs
}

type Fetcher interface {
	// Fetch returns the layer bytes for parts.LayerPath from src. cacheDir is
	// the content-addressed cache root for this source+layer
	// (~/.agents/cache/config/<source-id>/<layer-path>); the fetcher writes its
	// resolved <sha>/layer.json beneath it and returns the resolved SHA.
	Fetch(src Source, parts LayerRefParts, cacheDir string) (FetchedLayer, error)
}

type FieldProvenance struct {
	// ActiveLayer is the winning layer id, or "" when the field is unset
	// everywhere.
	ActiveLayer string `json:"active_layer"`
	// Layers is the ordered (lowest precedence first) per-layer stack. Always
	// a non-nil slice so JSON marshals to [] not null.
	Layers []LayerValue `json:"layers"`
}

type FlatResolver struct {
	// ProductDefaults is the lowest-precedence layer. When nil, an empty object
	// is used so the layer is always present in the stack (Present=true) even
	// when it carries no fields, which keeps explain output stable.
	ProductDefaults map[string]any
	// contains filtered or unexported fields
}

type GitRepo interface {
	// IsRepo reports whether dir is a git work tree.
	IsRepo(dir string) bool
	// Init initializes a new git repository rooted at dir.
	Init(dir string) error
	// Resolve returns the HEAD commit hash and working-tree dirtiness for the
	// repo at dir. An unborn branch yields ("", dirty, nil).
	Resolve(dir string) (commit string, dirty bool, err error)
}

type ImportError struct {
	// Ref is the failing extends/packages entry, e.g. "acme:org/base".
	Ref string
	// SourceID is the source the ref was expected from.
	SourceID string
	// Reason is the failure category.
	Reason ImportFailReason
	// Err is the underlying cause, if any.
	Err error
}

type ImportFailReason string

type LayerLockStatus struct {
	Ref        string `json:"ref"`
	SourceID   string `json:"source_id,omitempty"`
	SourceType string `json:"source_type,omitempty"` // local | git | http | oci
	Optional   bool   `json:"optional,omitempty"`
	// Locked is true when the lockfile has an entry for Ref with a non-empty SHA.
	Locked bool   `json:"locked"`
	SHA    string `json:"sha,omitempty"`
	// Cached is true when the cached layer.json exists at the locked SHA. Applies
	// to every source type — git/http/local layers are all content-hashed and
	// written to the same content-addressed cache.
	Cached    bool   `json:"cached"`
	CachePath string `json:"cache_path,omitempty"`
	// Problem is empty when the layer verifies; otherwise a short, actionable
	// reason (missing lock entry, cache miss, bad ref, undeclared source).
	Problem string `json:"problem,omitempty"`
}

type LayerRef struct {
	// Ref is the layer reference string "source-id:layer-path[@version]".
	Ref string `json:"ref"`
	// Optional marks the layer as non-fatal on fetch failure.
	Optional bool `json:"optional,omitempty"`
}

type LayerRefParts struct {
	SourceID  string
	LayerPath string
	Version   string
}

type LayerValue struct {
	// Layer is the layer identifier (LayerProductDefaults, …).
	Layer string `json:"layer"`
	// Value is the JSON-decoded value this layer contributed, or nil if the
	// layer did not set this field.
	Value any `json:"value"`
	// Active marks the winning layer for the field.
	Active bool `json:"active"`
}

type LayeredResolver struct {
	// contains filtered or unexported fields
}

type Lenses struct {
	// LensSet is the ordered review lenses applied (e.g.
	// "architecture-standards", "acceptance-invariants", "adversarial").
	LensSet []string `json:"lens_set,omitempty"`
	// LensConcurrency is how the lens set runs: "parallel", "gated", or
	// "tiered".
	LensConcurrency string `json:"lens_concurrency,omitempty"`
}

type LocalSource struct {
	// Root is the absolute path of the local source repo (`~/.agents`).
	Root string
	// Git is the seam over git operations; never nil after NewLocalSource.
	Git GitRepo
}

type LockDriftResult struct {
	// LockPresent is true when a .agentsrc.lock file exists for the project.
	LockPresent bool
	// HasDeclaredUnits is true when the manifest declares at least one `extends`
	// or `packages` unit (lock drift is only applicable to such manifests).
	HasDeclaredUnits bool
	// Units holds one record per ref in the union of declared and locked units,
	// sorted by Ref. Records with LockStatusOK are included so callers can render
	// a healthy summary count.
	Units []LockUnitDrift
}

type LockDriftStatus string

type LockUnitDrift struct {
	// Ref is the declared unit reference ("source-id:path[@version]").
	Ref string
	// Status classifies this unit's drift.
	Status LockDriftStatus
	// Digest is the locked content digest, empty for missing-from-lock entries.
	Digest string
	// Kind is the locked unit kind (layer|artifact), empty for
	// missing-from-lock entries.
	Kind string
}

type LockedLayer struct {
	// ResolvedSHA is the git commit SHA or content hash at fetch time.
	ResolvedSHA string `json:"resolved_sha"`
	// FetchedAt is the RFC3339 timestamp the layer was fetched.
	FetchedAt string `json:"fetched_at"`
	// TTLExpiresAt is when the SHA should be re-checked, derived from the
	// source cache_ttl. Empty means never re-check automatically (requires an
	// explicit `da config sync`).
	TTLExpiresAt string `json:"ttl_expires_at,omitempty"`
	// CacheKey is the effective content cache key the layer resolved at
	// (config-distribution-model §7A.4), derived from the source's cache_keys
	// override and the kind default via EffectiveCacheKey. On a later resolve it is
	// compared against the freshly-derived key (CacheKeyStale): a mismatch — or the
	// AlwaysRevalidate sentinel from a `--refresh` / always_revalidate force escape
	// — means the SHA-addressed cache may no longer be served and the upstream must
	// be re-checked. Omitted for a pre-cache-key lock (treated as stale on read).
	CacheKey string `json:"cache_key,omitempty"`
}

type LockedUnit struct {
	// Kind is UnitKindLayer or UnitKindArtifact.
	Kind string `json:"kind"`
	// Digest is the content hash recorded at fetch time ("sha256:…").
	Digest string `json:"digest"`
	// FetchedAt is the RFC3339 timestamp the unit was fetched.
	FetchedAt string `json:"fetched_at"`
	// LastCheckedAt is the RFC3339 timestamp of the last explicit upstream
	// re-check; it powers a doctor/explain review-nudge and never drives
	// auto-invalidation (§7A.3). Empty when never re-checked since fetch.
	LastCheckedAt string `json:"last_checked_at,omitempty"`
	// CacheKey is the effective content cache key the unit resolved at
	// (config-distribution-model §7A.4). It is the cache-key staleness axis —
	// orthogonal to the content-hash driver events — that CacheKeyStaleForLayer
	// compares on a later resolve. Carried on the units model (not just the
	// retired legacy "config" section) so the §7A units-lock cutover does NOT
	// drop the §7A.4 cache-key gate: a `--refresh`/always_revalidate force escape
	// and a cache_keys override edit both still register. Omitted for a unit
	// resolved without a cache key (e.g. a legacy lock migrated on read).
	CacheKey string `json:"cache_key,omitempty"`
}

type MergeCategory int

type MigrationResult struct {
	// ManifestPath is the absolute path to the .agentsrc.json that was inspected.
	ManifestPath string
	// BackupPath is where the original v1 bytes were (or would be) copied.
	BackupPath string
	// AlreadyV2 is true when the manifest is already clean v2 — no version bump
	// and no legacy keys — so migration is a no-op.
	AlreadyV2 bool
	// FromVersion is the manifest's declared schema version before migration.
	FromVersion int
	// ToVersion is the schema version after migration (always CurrentManifestVersion
	// when a migration is needed; equal to FromVersion on a no-op).
	ToVersion int
	// FoldedKeys lists the deprecated v1 keys that were folded away (dropped from
	// the rewritten manifest); empty when only a version bump was needed.
	FoldedKeys []string
	// V2JSON is the rewritten v2 manifest bytes (with a trailing newline). On a
	// no-op it is the manifest's current canonical serialization.
	V2JSON []byte
	// DryRun is true when this result was produced without writing.
	DryRun bool
	// WroteFile / WroteBackup report whether the migration actually wrote the v2
	// manifest and the backup sidecar. Both false on a no-op or a dry run.
	WroteFile   bool
	WroteBackup bool
}

type PackageFetcher interface {
	// FetchArtifact returns the artifact blob for parts.ArtifactPath@VersionSpec
	// from src, content-addressed and cached under the packages cache root.
	FetchArtifact(src Source, parts PackageRefParts) (FetchedArtifact, error)
}

type PackageRef struct {
	// Ref is the package reference string "source-id:artifact-path@version-spec".
	Ref string `json:"ref"`
}

type PackageRefParts struct {
	SourceID     string
	ArtifactPath string
	VersionSpec  string
}

type PreconditionPolicySpec struct {
	Predicates []PredicateSpec `json:"predicates"`
}

type PredicateSpec struct {
	Signal string            `json:"signal"`
	Args   map[string]string `json:"args,omitempty"`
}

type Principal struct {
	// ID is the stable identifier of the actor (e.g. a user handle).
	ID string
	// Groups are the team/org memberships the principal holds. A governed
	// source whose Owner is in Groups is one the principal may be authorized
	// to write — the policy backend has the final say.
	Groups []string
}

type Project struct {
	Path  string    `json:"path"`
	Added time.Time `json:"added"`
}

type PromptFileRef struct {
	// Source is the source id the prompt file is fetched from. Empty means
	// local resolution across the repo/home search path.
	Source string `json:"source,omitempty"`
	// Path is the prompt file path, relative to the source (or to the local
	// prompt search path when Source is empty). Required.
	Path string `json:"path"`
	// Version pins a source-relative revision. Empty means "as resolved".
	Version string `json:"version,omitempty"`
}

type Proposal struct {
	SchemaVersion int    `yaml:"schema_version"`
	ID            string `yaml:"id"`
	Status        string `yaml:"status"`
	Type          string `yaml:"type"`
	Action        string `yaml:"action"`
	Target        string `yaml:"target"`
	Rationale     string `yaml:"rationale"`
	Content       string `yaml:"content"`
	CreatedAt     string `yaml:"created_at"`
	CreatedBy     string `yaml:"created_by"`
	ReviewedAt    string `yaml:"reviewed_at"`
	ReviewReason  string `yaml:"review_reason"`
}

type ProvenanceWarning struct {
	// FieldPath is the dot-separated path of the offending field.
	FieldPath string `json:"field_path"`
	// AttemptedByLayer is the layer that tried to set a protected field.
	AttemptedByLayer string `json:"attempted_by_layer"`
	// Outcome is the disposition of the attempt; always "dropped" today.
	Outcome string `json:"outcome"`
}

type RefreshMetadata struct {
	Version     string `json:"version,omitempty"`
	Commit      string `json:"commit,omitempty"`
	Describe    string `json:"describe,omitempty"`
	RefreshedAt string `json:"refreshedAt,omitempty"`
}

type RelevanceClasses struct {
	// Core units are the always-relevant working set for this stage.
	Core []string `json:"core,omitempty"`
	// Situational units are conditionally useful; also the default for any
	// unlisted unit (DefaultRelevanceClass).
	Situational []string `json:"situational,omitempty"`
	// Noise units are suppressed from the working set for this stage. The
	// suppression is a reversible view, not a delete.
	Noise []string `json:"noise,omitempty"`
}

type ResolvedLayer struct {
	// ID is the layer identifier (LayerProductDefaults, …).
	ID string `json:"id"`
	// Present reports whether the layer existed (file on disk / built-in stub).
	Present bool `json:"present"`
	// Raw is the layer's decoded top-level object, or nil when absent.
	Raw map[string]any `json:"raw,omitempty"`
}

type ResolvedPreconditionPolicy struct {
	// Name is the resolved policy's registry key, or "default" when the
	// resolution fell back to the built-in gate.
	Name string
	// Predicates is the ordered predicate set. Empty ⇒ built-in default.
	Predicates []ResolvedPredicate
}

type ResolvedPredicate struct {
	// Signal is the registered kind, e.g. "event.pr.open", "gate.quality.sonar".
	Signal string
	// Args are kind-specific parameters, e.g. {"equals":"green"}.
	Args map[string]string
}

type Resolver interface {
	// Resolve produces the effective Snapshot for the project at projectPath.
	// A fatal error (e.g. repo-local manifest fails to parse) is returned;
	// non-fatal events (protected-field violations) surface in Snapshot.Warnings.
	Resolve(projectPath string) (*Snapshot, error)
}

type ReviewNudge struct {
	// Ref is the resolved unit ref ("source:path@version").
	Ref string
	// LastCheckedAt is the RFC3339 timestamp of the last upstream re-check
	// (falls back to fetched_at when never re-checked since fetch). Empty when
	// the unit records neither.
	LastCheckedAt string
	// SinceLastCheck is how long ago the last re-check was, relative to the
	// injected `now`. Zero when LastCheckedAt is empty or unparseable.
	SinceLastCheck time.Duration
}

type SigningPosture string

type Snapshot struct {
	// Effective is the merged manifest after applying every layer per the
	// category merge rules (org-config-resolution §7.2).
	Effective AgentsRC `json:"effective"`
	// Provenance maps a dot-separated field path to its full layer stack. Only
	// top-level manifest keys are pre-populated; explain surfaces may request
	// deeper paths via FieldAt.
	Provenance map[string]FieldProvenance `json:"provenance"`
	// Layers is the ordered (lowest precedence first) set of input layers.
	Layers []ResolvedLayer `json:"layers"`
	// Warnings holds non-fatal resolution events (protected-field violations).
	// Always non-nil ([]ProvenanceWarning{}) so JSON marshals to [].
	Warnings []ProvenanceWarning `json:"warnings"`
}

type Source struct {
	Type string `json:"type"`           // "local" | "git" | "http" | "oci"
	Path string `json:"path,omitempty"` // override path for "local"
	URL  string `json:"url,omitempty"`  // repository URL for "git" / "http" / "oci"
	Ref  string `json:"ref,omitempty"`  // branch/tag for "git", or OCI tag

	// ID is the stable local identifier used in extends/packages refs.
	// Required for v2 sources referenced by extends or packages; optional for
	// bare v1-style sources that exist only for legacy compatibility.
	ID string `json:"id,omitempty"`
	// CacheTTL is a duration string (e.g. "4h") governing tier-1 layer TTL.
	// Ignored for oci sources (which are strictly content-addressed per spec §8).
	CacheTTL string `json:"cache_ttl,omitempty"`
	// Auth is an opaque pass-through block whose schema is owned by the
	// external-agent-sources spec. The config layer treats it as an arbitrary
	// JSON object and does not introspect it.
	Auth json.RawMessage `json:"auth,omitempty"`
	// CacheKeys overrides the kind-default content cache key for this source
	// (config-distribution-model §7A.4, the uv `cache-keys` analog). Absent ⇒
	// the source uses its kind default (git→commit, local→commit+worktree,
	// http→ETag/Last-Modified else digest, oci→digest). See cache_keys.go for
	// the derivation; a *CacheKeys pointer keeps a defaulting source byte-stable
	// (no cache_keys object emitted). Omitted on a v1 source.
	CacheKeys *CacheKeys `json:"cache_keys,omitempty"`
}

type SourceKind string

type StageProfile struct {
	// Label is the human-readable profile name shown in fanout/explain output.
	Label string `json:"label,omitempty"`
	// PromptFiles is the base-first ordered prompt composition for the profile.
	PromptFiles []PromptFileRef `json:"prompt_files,omitempty"`
	// PreconditionPolicy names the verifier precondition policy (a key in the
	// top-level precondition_policies registry) that gates this profile's
	// in_progress → awaiting_agent_review transition. Unset ⇒ the built-in
	// `default` gate (verifier-precondition-policy plan, Slice B).
	PreconditionPolicy string `json:"precondition_policy,omitempty"`
}

type StalenessReason string

type StalenessResult struct {
	// Fresh is true when no driver event fired — the lock matches every local
	// input and may be used as-is (the `--frozen`/no-op path of EnsureResolved).
	Fresh bool
	// Reasons lists the distinct driver events that made the lock stale, in a
	// stable order. Empty when Fresh.
	Reasons []StalenessReason
	// ExpectedInputsDigest is the inputs_digest computed from the current local
	// scopes; doctor/explain surface it next to the lock's recorded value.
	ExpectedInputsDigest string
}

type StringsOrBool struct {
	All   bool
	Names []string
}

type Topology struct {
	// Executors is the number of parallel executor workers for the task.
	Executors int `json:"executors,omitempty"`
	// VerifiersPerExecutor is the verifier fan-out per executor (n exec →
	// VerifiersPerExecutor·n verifiers).
	VerifiersPerExecutor int `json:"verifiers_per_executor,omitempty"`
	// Reviewers is the reviewer fan-out: a keyword ("per_verifier",
	// "per_executor") or a stringified integer count. Kept as a string so the
	// keyword and fixed-count forms share one field.
	Reviewers string `json:"reviewers,omitempty"`
	// VerifierSequence is the ordered verifier-profile ids for this app_type; each
	// id references a stage_profiles.verifier slug. It is the successor to the
	// retired flat app_type_verifier_map (legacy entries fold in on load).
	VerifierSequence []string `json:"verifier_sequence,omitempty"`
}

type UnitDigestFunc func(ref string) (digest string, ok bool)

type UnitsLock struct {
	// Units is keyed by "source:path@resolved-version".
	Units map[string]LockedUnit
	// InputsDigest is the top-level whole-normalized local-scope hash. Empty
	// when no local scope has been hashed yet.
	InputsDigest string
}

type V1DeprecationWarning struct {
	// Detected reports whether any v1 marker was found. When false the other
	// fields are empty and callers should emit nothing.
	Detected bool
	// Version is the manifest's declared schema version (0 when absent).
	Version int
	// LegacyVersion is true when Version is below CurrentManifestVersion.
	LegacyVersion bool
	// LegacyKeys lists the deprecated v1 keys present in the manifest (sorted).
	LegacyKeys []string
}

type Verdict struct {
	Decision Decision
	// Reason explains the decision in operator-facing terms.
	Reason string
	// Scope is the editability scope that produced the decision. For a derived
	// project source this is the scope it derived TO (ScopeLocal for a personal
	// project, the governing tier for an owned one).
	Scope EditScope
}

type WorkingSet struct {
	// Units is every candidate in input order, each tagged with its resolved
	// relevance class. This is the load-bearing field; the helper methods are
	// pure projections of it.
	Units []ClassifiedUnit `json:"units,omitempty"`
}

type WriteAuthorizer interface {
	// Authorize returns the verdict for a governed source. Implementations
	// should return DecisionAllow/DecisionDeny per their policy; returning a
	// non-nil error signals the backend could not reach a decision (e.g. the
	// policy service was unreachable), which the Checker treats as a safe
	// fail-closed prompt rather than an allow.
	Authorize(p Principal, s WriteTarget) (Verdict, error)
}

type WriteTarget struct {
	// ID is the stable local source identifier (the `id` in the `sources`
	// array, §3) used by `--source`.
	ID string
	// Scope is the source's editability scope (ownership tier).
	Scope EditScope
	// Owner names the team/org that owns a governed (team/org) source, or the
	// owner of a project source when project ownership is a team/org. Empty
	// Owner on a project scope means a personal/unowned project, which derives
	// to local-writable.
	Owner string
}