platform

type AuditPrinter interface {
	PrintAudit(w io.Writer, project, repoPath, agentsHome string)
}

type BranchSessionFinder interface {
	FindSessionsOnBranch(home, projectPath, branch string, maxResults int) []BranchSessionInfo
}

type BranchSessionInfo struct {
	SessionID    string
	Timestamp    string
	MessageCount int
}

type BrokenLink struct {
	// PlatformID identifies which platform owns this link (e.g. "cursor").
	PlatformID string
	// LinkPath is the display-friendly path to the broken link — typically
	// repo-relative for project links or home-relative for user-config links.
	LinkPath string
	// Dest is the raw target string returned by the OS (os.Readlink output
	// for symlinks/junctions; empty for hard links whose canonical source
	// could not be matched).
	Dest string
	// DisplayDest is Dest after path resolution and ~/-prefix formatting,
	// suitable for direct rendering by doctor/status.
	DisplayDest string
}

type BrokenLinkReporter interface {
	BrokenLinks(project, repoPath, agentsHome string) []BrokenLink
}

type CanonicalBucket string

type CanonicalBucketSpec struct {
	Name        CanonicalBucket
	Stage       int
	CountDirs   bool
	MarkerFile  string
	Description string
}

type CommitAttribution struct {
	CommitHash           string
	BranchName           string
	ScoredAt             string
	LinesAdded           int
	LinesDeleted         int
	ComposerLinesAdded   int
	ComposerLinesDeleted int
	HumanLinesAdded      int
	V2AIPercentage       float64
}

type DailyUsage struct {
	Date          string
	MessageCount  int
	SessionCount  int
	ToolCallCount int
}

type DirMirrorRootsProvider interface {
	DirMirrorRoots() map[string][]string
}

type HookEmissionMode struct {
	Shape     HookShape
	Transport HookTransport
}

type HookPlatformOverride struct {
	Event   string `yaml:"event"`
	Matcher string `yaml:"matcher"`
	File    string `yaml:"file"`
}

type HookShape string

type HookSourceKind string

type HookSpec struct {
	Name         string
	Scope        string
	SourcePath   string
	SourceBucket string
	SourceKind   HookSourceKind
	Description  string
	When         string
	// WhenEvents, when non-empty, declares a multi-event hook. The
	// loader rejects manifests that set both `when` and `when_events`
	// (mutual exclusion) and manifests with duplicate or unknown
	// canonical events (P1c contract `when_events` rules). At render
	// time the spec is expanded into one rendered action per canonical
	// event the target platform documents.
	WhenEvents        []string
	MatchTools        []string
	MatchExpression   string
	Command           string
	TimeoutMS         int
	EnabledOn         []string
	RequiredOn        []string
	PlatformOverrides map[string]HookPlatformOverride
}

type HookTransport string

type LinkCounter interface {
	CountLinks(project, repoPath, agentsHome string) (ok, broken int)
}

type MCPFileSpec struct {
	Scope      string
	BaseName   string
	SourcePath string
}

type ManagedOutputReporter interface {
	ManagedOutputs() []string
}

type ManagedRenderProjector interface {
	// ManagedRenderDir is the repo-relative directory the platform renders its
	// managed files into (e.g. .codex/agents). Forced into the exact scan even
	// on a one-to-zero pass, so a render dropped to zero is still pruned.
	ManagedRenderDir() string
	// IsManagedRender reports whether path is one of THIS platform's managed
	// rendered files — identity-verified provenance, never a bare name/suffix
	// match — so a user-authored file in the same directory is never pruned.
	IsManagedRender(path string) (bool, error)
}

type ModelTokenUsage struct {
	InputTokens              int
	OutputTokens             int
	CacheReadInputTokens     int
	CacheCreationInputTokens int
}

type OrphanCanonical struct {
	// Name is the entry basename as it appears under ~/.agents/<bucket>/.
	Name string
	// DisplayNote is either "" (plain orphan) or a pre-formatted suffix
	// describing the mis-pointed target. Callers concatenate it directly
	// when rendering.
	DisplayNote string
}

type OrphanCanonicalReporter interface {
	OrphanCanonicals(project, projectPath, agentsHome, bucket string) []OrphanCanonical
}

type PipelineArtifact struct {
	// Name is the artifact filename relative to the platform's runtime dir
	// (e.g. "profile-driven.swarm.yaml").
	Name string
	// Content is the full file body, terminated by a single trailing newline.
	Content string
}

type PipelineProjector interface {
	// Platform is the projector's target platform id (e.g. "omp").
	Platform() string
	// RuntimeRelDir is the repo-relative directory the projector's artifacts are
	// emitted into (each harness owns its own runtime location).
	RuntimeRelDir() string
	// Emit renders the pipeline artifacts from the spec, or an error when the
	// spec is invalid for this platform.
	Emit(spec PipelineSpec) ([]PipelineArtifact, error)
}

type PipelineSpec struct {
	// Workspace is the absolute repo root the emitted pipeline runs in.
	Workspace string
	// AppType is the app_type this pipeline was specialized for, or "" for the
	// app_type-agnostic maximal skeleton (7 verify + 4 routine slots) that the
	// runtime profile_resolve stage narrows per task.
	AppType string
	// TargetCount is the bounded fold-back re-entry ceiling (craft §3).
	TargetCount int
	// Executor is the executor/default route; it also drives the swarm default
	// model and the gate/reconcile/profile_resolve routes.
	Executor StageRoute
	// Verifiers is the ordered verifier slot routes (1..7). For the skeleton every
	// slot carries the executor route; a specialized projection binds each slot to
	// its verifier_sequence slug's stage_profile.
	Verifiers []StageRoute
	// RoutineLenses is the ordered routine review lens routes (0..4), excluding the
	// cross-family lens.
	RoutineLenses []StageRoute
	// CrossFamily is the blocking cross-family adversarial route, or nil when the
	// app_type's lens_set does not include the cross-harness-adversarial slug.
	CrossFamily *StageRoute
}

type Platform interface {
	// ID returns the platform identifier (e.g. "cursor", "claude").
	ID() string
	// DisplayName returns the human-readable name.
	DisplayName() string
	// IsInstalled checks if this platform is installed on the system.
	IsInstalled() bool
	// Version returns the detected version string, or empty string.
	Version() string
	// CreateLinks creates all managed links for a project in repoPath.
	CreateLinks(project, repoPath string) error
	// RemoveLinks removes all managed links for a project from repoPath.
	RemoveLinks(project, repoPath string) error
	// HasDeprecatedFormat checks if the project has deprecated config files.
	HasDeprecatedFormat(repoPath string) bool
	// DeprecatedDetails returns a description of the deprecated format.
	DeprecatedDetails(repoPath string) string
	// SharedTargetIntents returns the ResourceIntents this platform would write
	// to shared (cross-platform) repo-local targets such as .agents/skills/*.
	// These intents are aggregated by the command layer into a single
	// ResourcePlan so compatible targets are deduped and conflicts are caught
	// before any filesystem writes occur.
	SharedTargetIntents(project string) ([]ResourceIntent, error)
}

type PlatformBadge struct {
	// Name is the human-readable platform name shown in the badge row
	// (e.g. "Cursor", "Claude Code").
	Name string
	// Present is true when this platform has any managed state for the
	// inspected scope (project or user-home).
	Present bool
	// Broken is true when any of the platform's managed links are broken.
	Broken bool
}

type PlatformUsageStats struct {
	PlatformID        string
	TotalSessions     int
	TotalMessages     int
	TokensByModel     map[string]ModelTokenUsage
	DailyActivity     []DailyUsage
	RecentSessions    []SessionSummary
	CommitAttribution []CommitAttribution
}

type PluginKind string

type PluginMarketplace struct {
	Repo string   `yaml:"repo,omitempty"`
	Tags []string `yaml:"tags,omitempty"`
}

type PluginResources struct {
	Agents   []string `yaml:"agents,omitempty"`
	Skills   []string `yaml:"skills,omitempty"`
	Commands []string `yaml:"commands,omitempty"`
	Hooks    []string `yaml:"hooks,omitempty"`
	MCP      []string `yaml:"mcp,omitempty"`
}

type PluginSpec struct {
	SchemaVersion     int                       `yaml:"schema_version"`
	Kind              PluginKind                `yaml:"kind"`
	Name              string                    `yaml:"name"`
	Version           string                    `yaml:"version,omitempty"`
	DisplayName       string                    `yaml:"display_name,omitempty"`
	Description       string                    `yaml:"description,omitempty"`
	Authors           []string                  `yaml:"authors,omitempty"`
	Homepage          string                    `yaml:"homepage,omitempty"`
	License           string                    `yaml:"license,omitempty"`
	Platforms         []string                  `yaml:"platforms"`
	Resources         PluginResources           `yaml:"resources,omitempty"`
	Marketplace       PluginMarketplace         `yaml:"marketplace,omitempty"`
	Dependencies      map[string]any            `yaml:"dependencies,omitempty"`
	PlatformOverrides map[string]map[string]any `yaml:"platform_overrides,omitempty"`
	Dir               string                    `yaml:"-"`
	ManifestPath      string                    `yaml:"-"`
	Scope             string                    `yaml:"-"`
}

type ResolvedUnit struct {
	// Family is the resource bucket ("skills" | "agents" | "plugins").
	Family string
	// Name is the resource directory name (one canonical segment).
	Name string
	// SourceID is the provenance source id (one canonical segment); used for a
	// stable, source-namespaced intent id so two sources shipping a same-named
	// resource never collide.
	SourceID string
	// Digest is the "sha256:<hex>" content digest THIS project resolved.
	Digest string
	// CASPath is the absolute immutable store path for Digest
	// (config.ArtifactStorePath). Recomputed and asserted by
	// ValidateResolvedUnit, never trusted as passed.
	CASPath string
	// ContentDigest is the OPTIONAL H16 content-integrity anchor
	// (config.BundleContentDigest / the git-tracked "artifact-content" lock
	// value) the caller resolved this unit against. When non-empty,
	// ProjectResolvedUnits re-verifies it — via config.VerifyStoreContentDigest
	// — immediately before the unit's CAS content is actually linked into the
	// project (t3b, closing the verify→link TOCTOU: an earlier batch verify a
	// driver ran before calling ProjectResolvedUnits does not, by itself, catch
	// a store mutation that lands during this call). Left empty, a unit gets
	// no invocation-time re-check — identical to pre-t3b behavior — so an
	// older caller that has not yet threaded its lock's content digest through
	// keeps working unchanged; the anchor is defense-in-depth on top of H13's
	// existing identity/path binding, not a new hard requirement on every
	// caller.
	ContentDigest string
}

type ResourceIntent struct {
	IntentID      string                `json:"intent_id"`
	Project       string                `json:"project"`
	Bucket        string                `json:"bucket"`
	LogicalName   string                `json:"logical_name"`
	TargetPath    string                `json:"target_path"`
	Ownership     ResourceOwnership     `json:"ownership"`
	SourceRef     ResourceSourceRef     `json:"source_ref"`
	Shape         ResourceShape         `json:"shape"`
	Transport     ResourceTransport     `json:"transport"`
	Materializer  string                `json:"materializer"`
	ReplacePolicy ResourceReplacePolicy `json:"replace_policy"`
	PrunePolicy   ResourcePrunePolicy   `json:"prune_policy"`
	Provenance    ResourceProvenance    `json:"provenance"`
	Precedence    int                   `json:"precedence,omitempty"`
	ConflictKey   string                `json:"conflict_key,omitempty"`
	MarkerFiles   []string              `json:"marker_files,omitempty"`
	EnabledOn     []string              `json:"enabled_on,omitempty"`
	ReviewHint    string                `json:"review_hint,omitempty"`
}

type ResourceOwnership string

type ResourcePlan struct {
	Resources []plannedResource
}

type ResourceProvenance struct {
	Emitter   string `json:"emitter,omitempty"`
	Operation string `json:"operation,omitempty"`
	Detail    string `json:"detail,omitempty"`
}

type ResourcePrunePolicy string

type ResourceReplacePolicy string

type ResourceShape string

type ResourceSourceKind string

type ResourceSourceRef struct {
	Scope        string             `json:"scope"`
	Bucket       string             `json:"bucket"`
	RelativePath string             `json:"relative_path"`
	Kind         ResourceSourceKind `json:"kind"`
	Origin       string             `json:"origin,omitempty"`
}

type ResourceTransport string

type RuleFileSpec struct {
	Scope      string
	BaseName   string // full file name, e.g. rules.mdc
	SourcePath string
}

type SessionReader interface {
	// AIAgentPrefix returns the harness prefix used in the AI_AGENT env var
	// convention (e.g. "claude-code" for AI_AGENT=claude-code_2-1-138_agent).
	// Returns "" if this platform does not follow the AI_AGENT convention.
	AIAgentPrefix() string
	// SessionEnvs lists env var names (in preference order) that carry the
	// active session ID. First non-empty value wins.
	SessionEnvs() []string
	// EntrypointEnvs lists env var names for the session launch entrypoint.
	EntrypointEnvs() []string
	// ResolveModel scans the platform's session store for the model active in
	// the given session. Returns "" when unavailable or not yet implemented.
	ResolveModel(home, projectPath, sessionID string) string
}

type SessionSummary struct {
	ID        string
	Name      string
	UpdatedAt string
}

type SessionTokenMetrics struct {
	InputTokens         int
	OutputTokens        int
	CacheReadTokens     int
	CacheCreationTokens int
	ReasoningTokens     int     // Codex o-series reasoning tokens; 0 for Claude Code
	CacheHitRate        float64 // CacheReadTokens/(CacheReadTokens+CacheCreationTokens); 0 = unavailable
	MessageCount        int
}

type SessionTokenScanner interface {
	ScanSessionTokens(home, projectPath, sessionID, afterTimestamp string) SessionTokenMetrics
}

type SettingsFileSpec struct {
	Scope      string
	BaseName   string
	SourcePath string
}

type SingleFileLinkSpec struct {
	// LinkPath is the absolute path to the managed file link.
	LinkPath string
	// CanonicalPaths is the ordered list of acceptable sources. The first
	// hard-linked match wins; if none match and the link exists, the link
	// is reported as broken.
	CanonicalPaths []string
}

type SourcedAgentFileProjector interface {
	// SourcedAgentFileIntents returns the CAS-direct ResourceIntents this
	// platform's file-shaped agents surface needs for units — implementations
	// filter to Family == "agents" themselves (units may carry other families).
	SourcedAgentFileIntents(project string, units []ResolvedUnit) []ResourceIntent
}

type SourcedAgentFilePruneRootProvider interface {
	SourcedAgentFilePruneRoot() string
}

type StageRoute struct {
	Slug        string
	Model       string
	ModelFamily string
}

type StatsReader interface {
	ReadUsageStats(home string) *PlatformUsageStats
}

type StatusBadger interface {
	Badge(project, repoPath, agentsHome string) PlatformBadge
}

type UserConfigReporter interface {
	// UserBrokenLinks returns broken managed links under the user's home
	// directory for this platform. Consumer: doctor.collectBrokenUserLinks.
	UserBrokenLinks(home string) []BrokenLink
	// UserBadge returns the user-config badge for the platform. Consumer:
	// status.collectUserConfigPlatforms.
	UserBadge(home string) PlatformBadge
}