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

	// Locks is the §15 D1a authority-axis lock block a layer emits in the
	// policy-authority pass (Phase 1): value_locks (pin a field, rejecting lower
	// writes) and deny_locks (subtract a set member, deny-overrides). force_allow
	// is invalid and aborts the resolve. A lock binds only scopes ranked below
	// its owner's AUTHORITY-RANK (org > team > repo > user). See authority.go.
	Locks *PolicyLockSpec `json:"locks,omitempty"`

	// AuthorityGrants is the §15 D1a source-authority registry block: a per-source
	// allowlist "source-id → scope it may carry." It is honored only when written
	// by a layer whose own authority is at least the conferred scope — a lower
	// scope cannot self-bless authority (a resolve-time rejection). See
	// resolveAuthorityGrants in authority.go.
	AuthorityGrants map[string]AuthorityScope `json:"authority_grants,omitempty"`

	// LayeringPolicy is the scope-attached unified-config-profiles (L1) policy
	// unit: the Phase-1 layering governance a scope emits — precedence, absolute
	// locks (deny/value, no force-allow), the Decision-2 three-state
	// override_permissions, and the Q4 replace-mode marker. Its owning authority
	// scope is SOURCE-derived (set by the resolver from the owning layer), never
	// authored on the unit. See internal/config/profile.go and the
	// unified-config-profiles design (§2.3).
	LayeringPolicy *LayeringPolicy `json:"layering_policy,omitempty"`

	// Manifests are the scope-attached distributable config manifest units (L2),
	// keyed by name; each manifest's absolute ref is <owning-source>:<name>. A
	// manifest REFERENCES (by ref) the sources to pull, the layering policy/profiles
	// that bind, and (optionally) the project-set to manage — it never inlines
	// copies (distributable-config-manifest D1/D2/R2). This lenient typed shape is
	// what round-trips; the strict fail-closed decode (no manifest->manifest edge,
	// no self-declared authority, no force-allow) runs at resolve time in
	// manifest.go. Its owning authority is SOURCE-derived, never authored here (D4).
	Manifests map[string]ManifestSpec `json:"manifests,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"`
	// GraphBackend is facet 4: the graph-backend adapter-ref the profile
	// selects (app-type-profiles §2.6 / §3.1). It is an open adapter-ref of the
	// form `dotagents-builtin:graph/<name>@<constraint>` (or a bare `<name>`),
	// resolved against the graph-backend adapter registry
	// (graph-backend-adapter-contract §4/§8) — not a closed enum. An empty value
	// means the profile inherits the pipeline's default backend (crg). The
	// resolver (commands/config relevance --filter graph) turns this ref into a
	// registered adapter and surfaces whether it resolves.
	GraphBackend string `json:"graph_backend,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 AuthorityScope string

type AuthorityViolation struct {
	Kind   string         `json:"kind"`
	Source string         `json:"source,omitempty"`
	Scope  AuthorityScope `json:"scope,omitempty"`
	Reason string         `json:"reason"`
	Fatal  bool           `json:"fatal"`
}

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

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"`
	// contains filtered or unexported fields
}

type ConfigManifest struct {
	// Ref is the absolute unit ref <source>:<name> — the identity (§15 D2).
	Ref string
	// Scope is the SOURCE-derived authority scope (Decision 1), stamped by the
	// loader, never authored on the unit.
	Scope AuthorityScope
	// Spec is the authored, validated payload.
	Spec ManifestSpec
}

type ConfigProfile struct {
	// Ref is the absolute unit ref <source>:<name> — the identity and the
	// deterministic same-scope tie-break key (Decision 6).
	Ref string
	// Kind selects the bundle-merge discipline (deep-map vs capability-union).
	Kind ProfileKind
	// Scope is the SOURCE-derived authority scope (Decision 1). It is not
	// authored on the unit; the loader stamps it from the source registry.
	Scope AuthorityScope
	// Order is the VALUE-axis merge position of the contributing layer — lower
	// merges first (lower precedence), so a higher-Order fragment wins scalar
	// conflicts. The snapshot bridge sets it to the layer's index in the
	// value-precedence-ordered stack (product → user → extends → repo →
	// project-local), so imported (extends) fragments merge BELOW repo for VALUES
	// exactly as the legacy resolveSnapshot does — independent of the fragment's
	// AUTHORITY scope (which governs only locks). When Order ties (e.g. engine
	// tests that leave it 0), the value-precedence rank of Scope breaks the tie.
	Order int
	// Selector constrains the context this fragment applies to (Decision 5).
	Selector ProfileSelector
	// Bundle is the config payload the profile contributes — a kind-agnostic
	// object so one engine carries app_type facets, stage composition, and
	// capability sets without a per-kind resolver.
	Bundle map[string]any
	// Authored marks a profile WRITTEN directly as a kind:profile unit (a
	// user-authored profile declared in a layer's `profiles` block) as opposed to
	// one SYNTHESIZED from the legacy execution_profile / stage_profiles surfaces
	// (profile_migration.go). The two share one engine, but an authored profile is
	// addressable and orderable distinctly from a derived one (see Key): a derived
	// fragment is a projection of legacy config and must never collide in the
	// addressable namespace with a profile a human wrote.
	Authored bool
}

type Decision string

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

type EditScope string

type EffectivePolicy struct {
	// Precedence is the effective scope ordering low→high (later wins scalars).
	Precedence []AuthorityScope
	// Locks are the effective absolute constraints, each tagged with its owner.
	Locks []ProfileLock
	// Permissions is the effective Decision-2 cap (nil ⇒ no restriction).
	Permissions *OverridePermissions
	// Replaced records the scope that issued a replace (Q4), or "" when none did.
	Replaced AuthorityScope
}

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 LayeringPolicy struct {
	// Scope is the authority scope that owns this policy (set by the loader).
	Scope AuthorityScope `json:"-"`
	// Precedence orders scopes low→high for Phase-2 value resolution (later wins
	// scalar conflicts). Empty ⇒ fall back to the canonical AUTHORITY-RANK order.
	Precedence []AuthorityScope `json:"precedence,omitempty"`
	// Locks are the absolute constraints this scope emits (Decision 4).
	Locks []ProfileLock `json:"locks,omitempty"`
	// OverridePermissions is the Decision-2 three-state cap. A nil pointer is the
	// OMITTED state; presence is preserved (see OverridePermissions).
	OverridePermissions *OverridePermissions `json:"override_permissions,omitempty"`
	// Mode is the Q4 replace-mode marker (Decision 3). Empty ⇒ narrow.
	Mode PolicyMode `json:"mode,omitempty"`
}

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 LockCollision struct {
	Field     string         `json:"field"`
	Attempted any            `json:"attempted"`
	Winning   any            `json:"winning"`
	Owner     AuthorityScope `json:"owner"`
	OwnerRank int            `json:"owner_rank"`
	Kind      string         `json:"kind"`
}

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 ManifestSpec struct {
	// Sources are the canonical source refs the manifest pulls
	// (<source>:<path>@<version>, §15 D2). They are NAMES only — a private source
	// carries no credential (F6/NEW-FORK-B): auth is threaded ambient-first at
	// init --from, never embedded here.
	Sources []string `json:"sources,omitempty"`
	// Binds are the refs of the layering_policy + profile units that bind (R2b).
	// Empty ⇒ the manifest binds whatever policy the scope chain resolves; a
	// non-empty set narrows the bound fragments to exactly those refs.
	Binds []string `json:"binds,omitempty"`
	// ProjectSet is the OPTIONAL ref of a kind:project-set unit (R2c/D6). The
	// project-set IS the home-config portable identity registry (built by L3); the
	// manifest only references it. Empty ⇒ a manifest with no project-set, which is
	// valid and resolves (item 3).
	ProjectSet string `json:"project_set,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 OverridePermissions struct {
	// contains filtered or unexported fields
}

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 PolicyLockSpec struct {
	// ValueLocks pins a field path to a value. A lower-authority scope that
	// writes a different value has its write rejected (the lock wins).
	ValueLocks map[string]json.RawMessage `json:"value_locks,omitempty"`
	// DenyLocks subtracts set members, each "field:member" (e.g.
	// "skills:risky-skill"). deny-overrides: a lower-scope union-add of the
	// member is dropped.
	DenyLocks []string `json:"deny_locks,omitempty"`
	// ForceAllow is ALWAYS invalid. Any entry is a resolve-time validation
	// error — the no-force-allow invariant.
	ForceAllow []string `json:"force_allow,omitempty"`
}

type PolicyMode 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 ProfileConflict struct {
	Field  string         `json:"field"`
	Scope  AuthorityScope `json:"scope"`
	Winner string         `json:"winner"`
	Refs   []string       `json:"refs"`
}

type ProfileContext struct {
	Role       string
	AppType    string
	Stage      string
	Harness    string
	ScopeChain []AuthorityScope
}

type ProfileDriftKind string

type ProfileDriftResult struct {
	// HasDrift is true when the projection is stale: the source digest moved OR a
	// field-level difference exists between the projection and the resolved bundle.
	HasDrift bool `json:"has_drift"`
	// DigestMatch reports whether the projection's recorded source digest still
	// equals the freshly resolved digest (Decision 7) — the cheap primary signal.
	DigestMatch bool `json:"digest_match"`
	// ProjectedDigest is the projection's recorded source digest (stale when drift).
	ProjectedDigest string `json:"projected_digest"`
	// ResolvedDigest is the freshly resolved bundle digest.
	ResolvedDigest string `json:"resolved_digest"`
	// Changes is every drifted leaf, sorted by path. Empty when the projection is
	// byte-current with the resolution.
	Changes []ProfileFieldDrift `json:"changes,omitempty"`
}

type ProfileFieldDrift struct {
	// Path is the dot-path of the drifted leaf.
	Path string `json:"path"`
	// Kind classifies the drift (changed / added / removed).
	Kind ProfileDriftKind `json:"kind"`
	// Projected is the value the materialized projection carries (nil for added).
	Projected any `json:"projected,omitempty"`
	// Resolved is the value the engine now resolves (nil for removed).
	Resolved any `json:"resolved,omitempty"`
}

type ProfileKind string

type ProfileLock struct {
	// Field is the dot-path the lock governs (e.g. "tools.allow", "model").
	Field string `json:"field"`
	// Deny lists set members forced OUT of Field and forbidden from lower-scope
	// re-grant (the deny-lock). Mutually exclusive with Value.
	Deny []string `json:"deny,omitempty"`
	// Value pins Field to a fixed scalar (the value-lock). A lower scope writing
	// a different value is rejected.
	Value json.RawMessage `json:"value,omitempty"`
	// Selector optionally scopes the lock to a context (empty = all contexts).
	Selector ProfileSelector `json:"selector,omitempty"`
	// Owner is the authority scope that declared the lock (set by the resolver,
	// not authored). Higher owner binds lower scopes.
	Owner AuthorityScope `json:"-"`
}

type ProfileLockDelta struct {
	// Key is the profile's namespaced addressable key (authored profiles carry the
	// "authored:" prefix), matching how the lock units are keyed.
	Key        string
	Status     ProfileLockStatus
	LockDigest string
	LiveDigest string
}

type ProfileLockStatus string

type ProfileProjection struct {
	// SourceDigest is ResolvedProfile.Digest at projection time — the pin the
	// drift check compares a fresh resolution against.
	SourceDigest string `json:"source_digest"`
	// Refs is the sorted set of absolute refs that contributed to the projected
	// bundle, captured so a provenance change (Decision 7) registers as drift even
	// when values coincide.
	Refs []string `json:"contributing_refs"`
	// Bundle is the canonical (deep-copied) effective fragment that was
	// materialized. It is independent of the source ResolvedProfile so a later
	// mutation of either side does not silently alias the other.
	Bundle map[string]any `json:"bundle"`
}

type ProfileSelector struct {
	Role    string `json:"role,omitempty"`
	AppType string `json:"app_type,omitempty"`
	Stage   string `json:"stage,omitempty"`
	Harness string `json:"harness,omitempty"`
}

type ProfileSet struct {
	Profiles []ConfigProfile
	Policies []LayeringPolicy
}

type Project struct {
	// RepoID is the canonical git repo_id used as the portable rebind key.
	// It is recorded ONLY when the project's git origin is unambiguous (R12);
	// otherwise it is empty and rebinding falls back to the logical id (the
	// registry map key).
	RepoID string `json:"repo_id,omitempty"`
}

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 ResolvedLockInfo struct {
	Field string         `json:"field"`
	Kind  string         `json:"kind"`
	Owner AuthorityScope `json:"owner"`
	Deny  []string       `json:"deny,omitempty"`
	Value any            `json:"value,omitempty"`
}

type ResolvedManifest struct {
	// Ref is the manifest's absolute identity.
	Ref string `json:"ref"`
	// Scope is the source-derived authority the manifest resolved at.
	Scope AuthorityScope `json:"scope"`
	// Sources is the sorted referenced source-set the manifest pulls (R3 step 1).
	Sources []string `json:"sources"`
	// Policy is the bound layering policy + resolved fragment, produced by the L1
	// ResolveProfile engine — composed, not forked (R3 step 2 / DC6).
	Policy ResolvedProfile `json:"policy"`
	// ProjectSet is the referenced project-set ref, or "" when the manifest has
	// none (item 3 — a manifest without a project-set still resolves).
	ProjectSet string `json:"project_set,omitempty"`
	// HasProjectSet distinguishes "no project-set referenced" from a future empty
	// ref, so consumers (L3 init --from) branch explicitly rather than on "".
	HasProjectSet bool `json:"has_project_set"`
	// Digest is the transitive-pin digest over the manifest ref, the referenced
	// ref-set, and the resolved policy digest (F5): "same digest ⇒ identical
	// setup" (R4).
	Digest string `json:"digest"`
}

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 ResolvedProfile struct {
	// Bundle is the effective config fragment for the context.
	Bundle map[string]any `json:"bundle"`
	// Contributing is the sorted set of absolute refs that contributed.
	Contributing []string `json:"contributing_refs"`
	// Locks is the effective binding lock set (owner-tagged), as resolved by the
	// §15 authority pass.
	Locks []ResolvedLockInfo `json:"locks"`
	// Collisions is the §15 lock collisions: each lower-scope write a value-lock or
	// deny-lock rejected, with attempted/winning/owner provenance.
	Collisions []LockCollision `json:"collisions,omitempty"`
	// Permissions is the effective permission map (scope→fields), nil-omitted.
	Permissions map[AuthorityScope][]string `json:"permissions,omitempty"`
	// Conflicts records same-scope value conflicts: both contributors are shown,
	// not just the winner (Decision 6).
	Conflicts []ProfileConflict `json:"conflicts,omitempty"`
	// PolicyMode is "replace" when a scope superseded the inherited policy (Q4),
	// else "narrow".
	PolicyMode PolicyMode `json:"policy_mode"`
	// ReplacedBy names the scope that issued a replace, when PolicyMode==replace.
	ReplacedBy AuthorityScope `json:"replaced_by,omitempty"`
	// Digest hashes bundle + contributing refs + effective policy version
	// (Decision 7).
	Digest string `json:"digest"`
}

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 ScopeOrdering struct {
	// AuthorityRank is the Phase-1 total order (highest authority first): who
	// may emit locks/caps. deny-overrides; higher binds lower.
	AuthorityRank []AuthorityScope `json:"authority_rank"`
	// ValuePrecedence is the Phase-2 value-merge order (lowest precedence
	// first): whose VALUE wins within the locks Phase 1 leaves surviving. This
	// is the verbatim preservation of the original D1 chain.
	ValuePrecedence []AuthorityScope `json:"value_precedence"`
}

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"`
	// LockCollisions holds the §15 D1a authority-pass rejections: a lower-scope
	// write a higher-scope value-lock or deny-lock rejected. Each entry carries
	// the attempted value, the winning (locked) value, and the owning scope so
	// `da config explain` can surface why the lower write did not win. Always
	// non-nil so JSON marshals to [].
	LockCollisions []LockCollision `json:"lock_collisions"`
	// AuthorityViolations holds non-fatal §15 D1a authority-pass notes (an inert
	// public grant, a zero-authority lock that bound nothing). Fatal violations
	// (self-blessing, force-allow) abort the resolve instead of landing here.
	// Always non-nil so JSON marshals to [].
	AuthorityViolations []AuthorityViolation `json:"authority_violations"`
}

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
	// ProfileUnits is the kind:profile contribution (R2): the resolved profile
	// fragments projected to LockedUnit entries (ProfileLockUnits), keyed by the
	// profile's namespaced key. It is folded INTO the persisted "units" section by
	// WriteUnitsLock so a kind:profile unit is a first-class lock entry alongside
	// layer/artifact units — making a profile resolution reproducible from the lock
	// without re-resolving. Nil for a caller that records no profiles (the section
	// then carries only Units, exactly as before).
	ProfileUnits map[string]LockedUnit
}

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
}