memory

type AffectedSection struct {
	File      string `json:"file"`
	SectionID string `json:"section_id,omitempty"`
}

type AllowlistLimits struct {
	MaxBytesPerFile   int // sum of bytes inside all regions
	MaxRegionsPerFile int // count of regions
	MaxBytesPerRegion int // single largest region
}

type AllowlistRegion struct {
	ByteStart int    `json:"byte_start"`
	ByteEnd   int    `json:"byte_end"`
	Reason    string `json:"reason"`
}

type AppendSection struct {
	FilePath        string
	ParentSectionID string
	Heading         string
	Level           int
	Content         []byte
}

type AppendToSection struct {
	FilePath   string
	SectionID  string
	Heading    string
	Level      int
	Occurrence int
	Content    []byte
}

type ApplyResult struct {
	StagingID string        `json:"staging_id"`
	Status    string        `json:"status"`
	Reason    string        `json:"reason,omitempty"`
	Message   string        `json:"message,omitempty"`
	Files     []string      `json:"files,omitempty"`
	Drift     []DriftReport `json:"drift,omitempty"`

	// AutoStage carries git auto-stage / commit outcomes when the apply
	// produced writes AND manifest.git.auto_stage_changes is true. nil
	// on rejection; nil on success when the feature is disabled.
	AutoStage *AutoStageResult `json:"auto_stage,omitempty"`
}

type ArchiveSection struct {
	FilePath    string
	SectionID   string
	Heading     string
	Level       int
	Occurrence  int
	ArchivePath string
	Replacement []byte // new content for the source section (heading + anchor + stub)
}

type AutoStageResult struct {
	// Staged is the list of repo-root-relative paths git add was called
	// with. Forward slashes.
	Staged []string `json:"staged,omitempty"`

	// CommitSHA is non-empty when auto_commit was on AND a commit was
	// actually created (nothing staged ≠ commit).
	CommitSHA string `json:"commit_sha,omitempty"`

	// Errors, if any. Auto-stage NEVER fails an apply — errors are
	// collected for surfacing only. Bytes are durable; git is a
	// best-effort side channel.
	Errors []string `json:"errors,omitempty"`

	// Skipped is true when auto-stage logic ran but produced no work
	// (manifest disabled, not-a-repo, nothing tracked). Distinguishes
	// "ran and did nothing" from "didn't run".
	Skipped bool `json:"skipped,omitempty"`
}

type ContextMetadata struct {
	ActiveBranch    string   `json:"active_branch,omitempty"`
	BudgetUsed      int      `json:"budget_used"`
	BudgetRemaining int      `json:"budget_remaining"`
	StaleWarnings   []string `json:"stale_warnings,omitempty"`
}

type CreateFile struct {
	FilePath string
	Content  []byte
	IfExists string
}

type DriftPolicy int

type DriftReport struct {
	Path      string `json:"path"`
	SectionID string `json:"section_id,omitempty"`
	Policy    string `json:"policy"`
	Expected  string `json:"expected"`
	Found     string `json:"found"`
}

type ErrAmbiguousPrefix struct {
	Prefix     string
	Candidates []string
}

type ExpiredProposal struct {
	StagingID  string `json:"staging_id"`
	Intent     string `json:"intent,omitempty"`
	Rationale  string `json:"rationale,omitempty"`
	StagedAt   string `json:"staged_at,omitempty"`
	AgeSeconds int    `json:"age_seconds"`
}

type ExtraFile struct {
	// Path is the forward-slash, memory-relative destination.
	Path string
	// Content is the full bytes to write. The orchestrator treats the
	// file as new (RequireFileAbsent) and write-once.
	Content []byte
}

type ExtraFileProducer interface {
	// ExtraFiles computes the additional files this op creates, derived
	// from src — the primary file's bytes at the moment the op runs,
	// BEFORE its own splice is applied. (archive_section reads the
	// section it's about to replace; remove_section reads the section it's
	// about to delete.)
	ExtraFiles(src []byte) ([]ExtraFile, error)
}

type FetchDeps struct {
	Idx       *index.Index
	Schema    *schema.Schema
	Manifest  *config.Manifest
	MemoryDir string // absolute path to .agent-memory/ (the local store's dir)
	Branch    git.BranchInfo

	// Stores lists the cached external stores to federate into the SEARCH path
	// (PR5). Empty → the single-store path, byte-for-byte (the opt-in
	// invariant). The bootstrap path is always local-only. Build with
	// LoadFetchStores.
	Stores []StoreRef

	// ChangedFiles are repo-relative paths with uncommitted changes,
	// resolved by the caller (CLI / MCP) via git.ChangedFiles. Feeds the
	// "decisions/pitfalls referencing changed files" ranking signal. Empty
	// is fine (no boost) — outside a git repo, or on a clean tree.
	ChangedFiles []string

	// Logger is optional; nil → discard. See UpdateDeps.log().
	Logger *slog.Logger
}

type FetchRequest struct {
	Query          string
	Scope          []string
	Budget         int      // characters; 0 = use manifest default
	Include        []string // categories (advisory in M2; M3 enforces)
	ExcludeArchive bool     // hard exclude vs penalize
}

type FetchResponse struct {
	Context              string          `json:"context"`
	IncludedFiles        []IncludedFile  `json:"included_files"`
	Omitted              []OmittedFile   `json:"omitted,omitempty"`
	SuggestedNextQueries []string        `json:"suggested_next_queries,omitempty"`
	ContextMetadata      ContextMetadata `json:"context_metadata"`
}

type Finding struct {
	Type                string `json:"type"`
	Line                int    `json:"line"`
	ApproximateLocation string `json:"approximate_location"`
}

type IncludedFile struct {
	Path         string `json:"path"`
	Reason       string `json:"reason"`
	Freshness    string `json:"freshness,omitempty"`
	Confidence   string `json:"confidence,omitempty"`
	SectionCount int    `json:"section_count,omitempty"`
	// Store + Origin are populated for federated (non-local) results: Store is
	// the manifest store name, Origin is the provenance label "name@<commit>".
	// Local results omit both (single-store output is unchanged).
	Store  string `json:"store,omitempty"`
	Origin string `json:"origin,omitempty"`
}

type Intent string

type MemoryStatus struct {
	MemoryVersion     string              `json:"memory_version"`
	Repo              string              `json:"repo"`
	ActiveBranch      string              `json:"active_branch,omitempty"`
	DurableFiles      int                 `json:"durable_files"`
	ArchiveFiles      int                 `json:"archive_files"`
	LocalSessions     int                 `json:"local_sessions"`
	LocalCurrentFiles int                 `json:"local_current_files"`
	OrphanLocalFiles  []string            `json:"orphan_local_files,omitempty"`
	IndexSizeBytes    int64               `json:"index_size_bytes"`
	CurrentSizeBytes  int64               `json:"current_size_bytes"`
	StagedUpdates     []StagedStatusEntry `json:"staged_updates,omitempty"`

	// StaleNotes lists files flagged "stale" by future per-section
	// freshness tracking. Currently always empty (mechanism unimplemented
	// — see design doc §20.3).
	StaleNotes []string `json:"stale_notes,omitempty"`

	Security MemoryStatusSecurity `json:"security"`
	Git      MemoryStatusGit      `json:"git"`
	Lock     MemoryStatusLock     `json:"lock"`
}

type MemoryStatusGit struct {
	TrackLocal           bool `json:"track_local"`
	TrackSessions        bool `json:"track_sessions"`
	IgnoredLocalState    bool `json:"ignored_local_state"`
	MergeDriverInstalled bool `json:"merge_driver_installed"`
}

type MemoryStatusLock struct {
	Held bool `json:"held"`
	// StaleRecoveriesLast24h would count crash-recovered locks in a 24h
	// window. The kernel handles lock release on process death so this
	// is informational and currently always 0 until persisted.
	StaleRecoveriesLast24h int `json:"stale_recoveries_last_24h"`
}

type MemoryStatusSecurity struct {
	// LastSecretScan is one of "passed" | "n/a" | "failed". Currently
	// always "n/a" — there's no per-write scan history persisted. Future
	// work (M8b2) will populate this from a scan log.
	LastSecretScan string `json:"last_secret_scan"`

	// AllowlistedRegions is the total count of secret-scan allowlist
	// regions discovered across all durable .md files at status time.
	AllowlistedRegions int `json:"allowlisted_regions"`

	// UntrustedSources counts proposals with sources of type
	// "external" or "inference" recorded against durable files. Not yet
	// persisted; always 0 until proposal history tracking lands.
	UntrustedSources int `json:"untrusted_sources"`
}

type OmittedFile struct {
	Path   string `json:"path"`
	Reason string `json:"reason"`
	// Store + Origin mirror IncludedFile's provenance for non-local candidates,
	// so a dropped landscape section is as traceable as an included one (useful
	// for budget/dedup/stale-cache debugging and the PR6 eval). Local omits
	// leave both empty.
	Store  string `json:"store,omitempty"`
	Origin string `json:"origin,omitempty"`
}

type Operation interface {
	// Kind returns the operation type ("create_file", "replace_section", ...).
	Kind() string

	// Path returns the target memory-relative file path (forward-slash).
	Path() string

	// Validate runs op-specific structural checks: content parses as
	// Markdown, required fields are present, paths are well-formed.
	// The schema is passed so an op can consult per-category policy.
	// Category-level checks (server_managed, agent_writable) are the
	// orchestrator's responsibility.
	Validate(sch *schema.Schema) error

	// Targets returns the drift-check targets the staging engine should
	// verify at apply time. May be empty for ops with no drift concern.
	Targets() []OperationTarget

	// Plan returns the byte-range splice that, applied via
	// markdown.Splice(src, []SpliceOp{plan}), produces the desired
	// post-state. For create_file with if_exists=reject, src is expected
	// to be nil (file doesn't exist) and the splice covers [0, 0).
	Plan(src []byte) (agentmd.SpliceOp, error)
}

type OperationInput struct {
	Op              string `json:"operation"`
	Path            string `json:"path"`
	SectionID       string `json:"section_id,omitempty"`
	Heading         string `json:"heading,omitempty"`
	HeadingLevel    int    `json:"heading_level,omitempty"`
	Occurrence      int    `json:"occurrence,omitempty"`
	ParentSectionID string `json:"parent_section_id,omitempty"`
	Content         string `json:"content,omitempty"`
	IfExists        string `json:"if_exists,omitempty"`
	IfMissing       string `json:"if_missing,omitempty"`

	// M4 archival/rename fields.
	ArchivePath     string `json:"archive_path,omitempty"`      // archive_section, remove_section
	Replacement     string `json:"replacement,omitempty"`       // archive_section: new source-section body
	Reason          string `json:"reason,omitempty"`            // remove_section: why it's gone
	NewHeading      string `json:"new_heading,omitempty"`       // rename_heading
	NewHeadingLevel int    `json:"new_heading_level,omitempty"` // rename_heading; 0 = keep current
}

type OperationTarget struct {
	Path      string      `json:"path"`
	SectionID string      `json:"section_id,omitempty"`
	Policy    DriftPolicy `json:"policy"`
	Hash      string      `json:"hash,omitempty"`
}

type OwnerInfo struct {
	ID   string `json:"id,omitempty"`
	Kind string `json:"kind,omitempty"` // "agent" | "cli" | ...
	OpID string `json:"op_id,omitempty"`
}

type ProposeRequest struct {
	Intent     Intent           `json:"intent"`
	Rationale  string           `json:"rationale,omitempty"`
	Operations []OperationInput `json:"operations"`
	Sources    []Source         `json:"sources,omitempty"`
	Confidence string           `json:"confidence,omitempty"`
	Owner      OwnerInfo        `json:"owner,omitempty"`
}

type ProposeResponse struct {
	Status               string                    `json:"status"`
	Reason               string                    `json:"reason,omitempty"`
	Message              string                    `json:"message,omitempty"`
	Routing              Routing                   `json:"routing,omitempty"`
	StagingID            string                    `json:"staging_id,omitempty"`
	Files                []string                  `json:"files,omitempty"`
	Findings             []Finding                 `json:"findings,omitempty"`
	Violations           []schema.SectionViolation `json:"violations,omitempty"`
	ProvenanceViolations []string                  `json:"provenance_violations,omitempty"`

	// --- Applied output (design §15.2) ---
	// AppliedAt is the RFC3339 UTC timestamp of the write. Set on apply.
	AppliedAt string `json:"applied_at,omitempty"`
	// AffectedSections lists the (file, section_id) pairs the proposal's
	// operations touched. Set on apply.
	AffectedSections []AffectedSection `json:"affected_sections,omitempty"`
	// IndexUpdated reports whether the FTS shadow was refreshed. Set on
	// apply (true when deps.Idx was present).
	IndexUpdated bool `json:"index_updated,omitempty"`
	// Warnings carries non-fatal advisories. Always present on apply
	// (possibly empty) so consumers can rely on the field.
	Warnings []string `json:"warnings,omitempty"`

	// --- Staged output (design §15.2) ---
	// StagingTTLSeconds is the manifest's staging.ttl_seconds. Set on stage.
	StagingTTLSeconds int `json:"staging_ttl_seconds,omitempty"`
	// HumanApprovalRequired is always true on the staged path (staging
	// means a human must review). Set on stage.
	HumanApprovalRequired bool `json:"human_approval_required,omitempty"`
	// ReviewCommand is the exact CLI invocation to inspect the staged
	// proposal. Set on stage.
	ReviewCommand string `json:"review_command,omitempty"`

	// AutoStage reports git auto-stage / auto-commit outcomes when the
	// applied path produced a write AND manifest.git.auto_stage_changes
	// is true. nil on stage or reject; nil on apply when the feature is
	// off. See internal/memory/autostage.go.
	AutoStage *AutoStageResult `json:"auto_stage,omitempty"`
}

type ProvenanceContext struct {
	// Sources from the proposal.
	Sources []Source

	// Confidence from the proposal. May be empty.
	Confidence string

	// IsNewSection is true when the operation creates a new section (e.g.,
	// append_section, replace_section with if_missing=append) rather than
	// modifying an existing one. Used by Provenance.RequiredForNewSections.
	IsNewSection bool
}

type RebaseResult struct {
	StagingID string        `json:"staging_id"`
	Status    string        `json:"status"`
	Reason    string        `json:"reason,omitempty"`
	Message   string        `json:"message,omitempty"`
	Forced    bool          `json:"forced,omitempty"`
	Drift     []DriftReport `json:"drift,omitempty"`
	Files     []string      `json:"files,omitempty"`    // staged files updated by rebase
	Findings  []Finding     `json:"findings,omitempty"` // populated on rebase_secret_detected
}

type RejectionEntry struct {
	RejectedAt string   `json:"rejected_at"` // RFC3339 UTC
	Reason     string   `json:"reason"`      // one of RejectionReason* constants
	StagingID  string   `json:"staging_id"`
	Intent     string   `json:"intent,omitempty"` // copied from the staged Request
	Rationale  string   `json:"rationale,omitempty"`
	Files      []string `json:"files,omitempty"`
	StagedAt   string   `json:"staged_at,omitempty"`   // when the proposal was originally staged
	AgeSeconds int      `json:"age_seconds,omitempty"` // RejectedAt - StagedAt
}

type RemoveSection struct {
	FilePath    string
	SectionID   string
	Heading     string
	Level       int
	Occurrence  int
	ArchivePath string
	Reason      string // why it's being removed; recorded as a comment in the archive
}

type RenameHeading struct {
	FilePath        string
	SectionID       string
	Heading         string
	Level           int
	Occurrence      int
	NewHeading      string
	NewHeadingLevel int // 0 = keep current level
}

type ReplaceSection struct {
	FilePath   string
	SectionID  string
	Heading    string
	Level      int
	Occurrence int
	Content    []byte
	IfMissing  string // "reject" (default) | "append" | "create_file"
}

type ReplaceSectionContent struct {
	FilePath   string
	SectionID  string
	Heading    string
	Level      int
	Occurrence int
	Content    []byte // body only; must NOT start with a heading
}

type Routing struct {
	Mode   schema.ApprovalMode
	Reason string
}

type ScanOpts struct {
	// Allowlist excludes the listed byte ranges from scanning. Build it
	// with ExtractAllowlistRegions over the same content.
	Allowlist []AllowlistRegion

	// EntropyThreshold and EntropyMinLength enable Shannon-entropy
	// detection over alphanumeric tokens. Tokens shorter than
	// EntropyMinLength are skipped. Tokens whose entropy meets or exceeds
	// EntropyThreshold are flagged as type "high_entropy".
	//
	// Set both to zero to disable entropy scanning. Recommended starting
	// values per design doc §23.2: threshold=4.5, min_length=32. Tighter
	// thresholds reduce false positives at the cost of catching fewer
	// real-but-unrecognised tokens.
	EntropyThreshold float64
	EntropyMinLength int

	// PIIScanSSNAndCC enables high-confidence PII detection (SSN shape +
	// credit card with Luhn validation). Both patterns are extremely rare
	// in legitimate technical content; default-on in DefaultManifest.
	PIIScanSSNAndCC bool

	// PIIScanEmail enables email-address detection. Opt-in because emails
	// appear legitimately in documentation (maintainer addresses, support
	// contacts, example syntax). Use allowlist regions for legitimate
	// occurrences when this is on.
	PIIScanEmail bool
}

type Source struct {
	Type string `json:"type"`          // file | test | user | session | inference | external
	Ref  string `json:"ref,omitempty"` // file path, test name, etc.
}

type StagedProposal struct {
	StagingID string         `json:"staging_id"`
	StagedAt  string         `json:"staged_at"`
	Request   ProposeRequest `json:"request"`
	Routing   Routing        `json:"routing"`
	Files     []string       `json:"files"`
}

type StagedStatusEntry struct {
	ID                  string   `json:"id"`
	Intent              string   `json:"intent"`
	AgeSeconds          int      `json:"age_seconds"`
	TTLRemainingSeconds int      `json:"ttl_remaining_seconds"`
	TargetFiles         []string `json:"target_files"`
	DriftDetected       bool     `json:"drift_detected"`
}

type StatusDeps struct {
	MemoryDir     string
	Manifest      *config.Manifest
	Schema        *schema.Schema
	Branch        agentgit.BranchInfo
	MemoryVersion string // "0.X.Y" or "dev"
}

type StoreRef struct {
	Name               string  // manifest store name (= index store tag); never "local"
	Dir                string  // abs path to the cached store dir (meta/cache/stores/<name>/)
	Origin             string  // provenance label, e.g. "platform@a1b2c3"
	PriorityMultiplier float64 // applied to the negative BM25 score; <1 penalises (default 0.8)
}

type StoreSyncResult struct {
	Name           string
	ResolvedCommit string
	Unlocked       bool
	Reused         bool // reproduced the previously-locked commit (no re-pin)
	Err            error
}

type SweepResult struct {
	DryRun  bool              `json:"dry_run,omitempty"`
	Expired []ExpiredProposal `json:"expired,omitempty"`
	Removed []string          `json:"removed,omitempty"`
}

type SyncDeps struct {
	MemoryDir string // absolute path to the consuming repo's .agent-memory/
	Manifest  *config.Manifest
	Logger    *slog.Logger
	// Update, when true, moves each git store's pin forward to the latest of
	// its requested revision instead of reproducing the locked commit.
	Update bool
	// Now is injectable for deterministic tests; nil → time.Now.
	Now func() time.Time
}

type UpdateDeps struct {
	Manifest  *config.Manifest
	Schema    *schema.Schema
	MemoryDir string       // absolute path to .agent-memory/
	Idx       *index.Index // optional

	// Logger receives structured events from the orchestrator + staging
	// engine. Optional: nil → a discard logger (see log()). NEVER logs
	// matched secret bytes; only Finding.Type / .Line.
	Logger *slog.Logger
}