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 OCI/HTTP packages in the form
	// "source-id:artifact-path@version-spec". Tier constraint: oci|http sources only.
	Packages []PackageRef `json:"packages,omitempty"`
	// Features overrides feature-flag defaults (config-distribution-model §3.6).
	Features map[string]string `json:"features,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:"-"`
}

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 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 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 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 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
}

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
}

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 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"`
}

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"`
}

type MergeCategory int

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 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 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 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 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"`
}

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 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 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 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
}