application

type Access string

type AccessResolver interface {
	ResolvePrincipal(context.Context, RequestIdentity) (Principal, error)
	// ResolveParticipant names the graph participant the principal appears as
	// in the project — the name framing, authorship, and WIP markers carry. It
	// is asked once the project is known, because a person may appear under a
	// different name per project (s-cpt-ny6).
	ResolveParticipant(context.Context, Principal, ProjectID) (string, error)
	ListProjects(context.Context, Principal) (ProjectList, error)
	ResolveProject(context.Context, Principal, ProjectID, Access) (*ProjectRuntime, error)
	// ResolveDependency maps one dependency the project declares — a repo ID
	// from its committed configuration — to the runtime of the project that
	// carries it, or refuses. The declared string and the resolved project's
	// ID coincide only in the local composition. The application asks per
	// declared dependency, on every view over the horizon and on every
	// dependency-closure walk; a composition whose answer is costly caches it
	// itself, since only it knows when a mapping goes stale.
	ResolveDependency(context.Context, Principal, ProjectID, string) (*ProjectRuntime, error)
	// AuthorizeSession answers whether the actor may continue the session.
	// Membership in the session's home project is asked separately, so a
	// shared session never admits anyone into a project they cannot read.
	AuthorizeSession(context.Context, SessionAccessRequest) error
}

type AcquiredSnapshot struct {
	Snapshot    *Snapshot
	Attachments AttachmentPageReader
	// Config is immutable committed configuration from this source revision.
	// Nil explicitly uses runtime configuration; configuration read failures
	// must be returned by the adapter, never converted to nil.
	Config  *ProjectConfig
	Release func() error
}

type AcquiredTarget struct {
	Target     MutationTarget
	Graph      GraphStore
	Finalizers []MutationFinalizer
	Release    func() error
}

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

type ApplicationError struct {
	Code       ErrorCode
	Message    string
	Project    ProjectRef
	Action     *ProjectAction
	ApplyState ApplyState
	Revision   string
	Version    uint32
	Cause      error
	// Ended carries the act that ended the session on an ErrorSessionEnded, so
	// the caller can be told who/when/why.
	Ended *SessionEnd
}

type ApplicationOptions struct {
	Access      AccessResolver
	Sessions    SessionStore
	StagedBlobs StagedBlobStore
	Clock       Clock
	// PrepareSearch runs once after authorized semantic-search snapshots are
	// selected. nil preserves SyncMode preparation. Returning nil claims no
	// coverage; SDD reads publication afterwards. Callback failures propagate.
	PrepareSearch func(context.Context, SearchTarget) error
}

type AppliedMutation struct {
	Project  ProjectID
	BatchID  string
	Revision string
	Batch    MutationBatch
}

type ApplyResult struct {
	State    ApplyState
	Revision string
}

type ApplyState string

type Attachment struct {
	Subject       string
	ClientName    string
	ClientVersion string
	LastActivity  time.Time
}

type AttachmentMaterialization struct {
	BlobID      string
	Digest      BlobDigest
	Size        int64
	SourceName  string
	LogicalPath string
}

type AttachmentPage struct {
	// LocalPath is an optional absolute path supplied by the attachment source
	// for clients sharing its filesystem. It does not extend source retention.
	LocalPath  string
	Filename   string
	Content    []byte
	Offset     int64
	NextOffset int64
	TotalSize  int64
	More       bool
	Digest     BlobDigest
}

type AttachmentPageReader interface {
	ReadAttachmentPage(context.Context, string, string, int64, int) (AttachmentPage, error)
}

type Author struct {
	Name  string
	Email string
}

type BlobDigest struct {
	Algorithm string
	Value     string
}

type BranchValidator interface {
	ValidateBranch(context.Context, MutationTarget) error
}

type BranchValidatorFunc func(context.Context, MutationTarget) error

type CanonicalChunk = types.CanonicalChunk

type ChooserKind string

type Clock interface{ Now() time.Time }

type ClockFunc func() time.Time

type CollectSessionsCmd struct {
	Retention time.Duration
	Limit     int
	After     SessionID
}

type CollectSessionsResult struct {
	RemovedSessions []SessionID
	RemovedStaged   []SessionRef
	DrainedIntents  int
	Skipped         []SessionID
	Next            SessionID
}

type CreateEntryResult struct {
	Project  ProjectRef
	Binding  SessionBinding
	EntryID  string
	Summary  string
	Findings []Finding
}

type DiscoverSearchEntriesQuery struct {
	// The caller owns the lease and releases it after consuming the iterator.
	Source *AcquiredSnapshot
	Cursor SearchDiscoveryCursor
	// EntryIDs selects canonical full IDs. Nil means all; nonnil empty is invalid.
	EntryIDs []string
}

type DocumentChange struct {
	LogicalPath    string
	Document       *EntryDocument
	CanonicalBytes []byte
	Delete         bool
}

type DocumentIssue struct {
	LogicalPath string
	Message     string
}

type EntryDocument struct {
	LogicalPath string
	Frontmatter map[string]any
	Body        string
	Attachments []string
}

type EntryDraft struct {
	Target            MutationTarget
	Kind              string
	Layer             string
	Intent            string
	Body              string
	Refs              []EntryRef
	Closes            []string
	Supersedes        []string
	Participants      []string
	Confidence        string
	Topics            []string
	Index             *FactIndex
	AttachmentHandles []string
	// Canonical and Aliases carry a kind: actor signal's identity; Actor carries
	// a kind: role decision's bound actor canonical; Class carries a
	// kind: procedure decision's execution role. Mirrors the CLI-side
	// NewEntryCmd fields — a value on the wrong kind is a blocking finding at
	// the construction boundary.
	Canonical string
	Aliases   []string
	Actor     string
	Class     string
	// ProcedureSpec carries a kind: procedure decision's workflow declaration
	// as one structured document — {params?, state?, steps, framing?} —
	// converted strictly at draft-to-entry assembly. Interpretation stays
	// with the engine.
	ProcedureSpec map[string]any
	// FocusActors, FocusWhen, and Involvement carry a kind: focus decision's
	// advances list and its focus-level defaults. Mirrors the CLI-side
	// NewEntryCmd fields — ignored on other kinds, written onto the entry so
	// the model-layer validator sees the required involvement frontmatter.
	FocusActors   []string
	FocusWhen     *types.FocusWhen
	Involvement   []types.Involvement
	SkipPreflight bool
}

type EntryRef struct {
	ID   string
	Kind string
	Desc string
}

type ErrorCode string

type FactIndex struct {
	Title string `json:"title"`
	Topic string `json:"topic"`
}

type FactIndexRow struct {
	ID    string
	Title string
	Topic string
}

type FinalizerOutcome struct {
	Name      string
	Succeeded bool
	Message   string
}

type Finding struct {
	Severity    string
	Category    string
	Observation string
}

type FixedTargetAcquirer struct {
	Target     MutationTarget
	Graph      GraphStore
	Finalizers []MutationFinalizer
}

type GraphStore interface {
	Current(context.Context) (*Snapshot, error)
	Apply(context.Context, string, MutationBatch, StagedBlobReader) (ApplyResult, error)
	Reconcile(context.Context, string, string) (ApplyResult, error)
	ReadAttachmentPage(context.Context, string, string, int64, int) (AttachmentPage, error)
}

type GuideFinding struct {
	Reasoning string
	Axis      string
	Quote     string
	Repair    string
	Severity  string
}

type IndexNamespace = types.IndexNamespace

type IndexSearchEntryCmd = command.IndexSearchEntryCmd

type IndexedChunk = types.IndexedChunk

type InfoRequest struct {
	Branch            string
	BranchFromSession bool
}

type InfoResult struct {
	Project     ProjectRef
	Participant string
	Language    string
	Search      string
	Recovery    string
}

type MutationBatch struct {
	ID          string
	Digest      string
	Changes     []DocumentChange
	Attachments []AttachmentMaterialization
	Message     string
	Author      Author
}

type MutationFinalizer interface {
	Name() string
	Finalize(context.Context, AppliedMutation) error
}

type MutationResult struct {
	Project ProjectRef
	Binding SessionBinding
}

type MutationTarget struct {
	Project ProjectID `json:"project"`
	Branch  string    `json:"branch"`
}

type PreparedTransition struct {
	Version uint32
	Target  MutationTarget
	// ExpectedGraphRevision is prepare-time provenance only. The apply CAS
	// operand is the freshly revalidated revision (see applyOnAcquired), so a
	// concurrent unrelated append merges cleanly instead of failing the pin.
	ExpectedGraphRevision string
	Batch                 MutationBatch
	// Staged keeps its persisted name so an in-flight intent stays replayable
	// across an upgrade.
	Staged  SessionRef `json:"BlobOwner"`
	BlobIDs []string
}

type Principal struct {
	Subject string
}

type ProcedureListRequest struct{}

type ProcedureListResult struct {
	Project    ProjectRef
	Procedures string
}

type ProjectAction struct {
	ID          string
	DisplayName string
	State       ProjectState
	ActionURL   string
	Reason      string
}

type ProjectConfig struct {
	RepoID        string
	Dependencies  []string
	DefaultBranch string
	Language      string
	// GraphDir is repository-relative, .sdd/graph when the file leaves it unset.
	GraphDir string
}

type ProjectConfigDocument struct {
	LogicalPath string
	Fields      map[string]any
}

type ProjectID = types.ProjectID

type ProjectList struct {
	Actions  []ProjectAction
	Projects []ProjectSummary
}

type ProjectRef struct {
	ID          ProjectID
	DisplayName string
}

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

type ProjectRuntimeOptions struct {
	Project       ProjectRef
	DefaultBranch string
	Language      string
	Dependencies  []string
	Graph         GraphStore
	Targets       TargetAcquirer
	Branches      BranchValidator
	Recovery      RecoveryAuthorizer
	// Embedder and LLM are the two model dependencies, each a pkg/llm port
	// injected as an instance that arrives already composed — observed,
	// bounded, and rate-limited by the host's decorators. Routing, deadlines,
	// and recording are the host's composition duty (20260830-234501-d-cpt-q6n,
	// 20260902-114838-d-tac-cov); application contributes only the facts it
	// alone holds: the Purpose and the prompts, or the texts.
	Embedder    embed.Embedder
	SearchIndex SearchIndexStore
	LLM         llm.Runner
	Finalizers  []MutationFinalizer
	// ExcludeEmbeddedFromIndex mirrors the CLI's excludeEmbedded semantics for
	// the vector index: connected-repo runtimes set it so binary-shipped base
	// entries embed once per machine (in the base store) rather than once per
	// connected repo. The base runtime leaves it false — its store includes
	// embedded entries. The rule is applied identically at index and read time.
	ExcludeEmbeddedFromIndex bool
}

type ProjectState string

type ProjectSummary struct {
	ProjectRef
	SourceID string
	CanRead  bool
	CanWrite bool
	State    ProjectState
}

type ReadAttachmentRequest struct {
	Branch            string
	BranchFromSession bool
	EntryID           string
	Filename          string
	Offset            int64
	MaxBytes          int
}

type ReadAttachmentResult struct {
	Project   ProjectRef
	Page      AttachmentPage
	Available []string
}

type ReconcileSearchIndexCmd = command.ReconcileSearchIndexCmd

type RecoveryAccessRequest struct {
	Actor           Principal
	Target          MutationTarget
	Verb            RecoveryVerb
	OriginalSubject string
	OriginalSession SessionID
}

type RecoveryAuthorizer interface {
	AuthorizeRecovery(context.Context, RecoveryAccessRequest) error
}

type RecoveryAuthorizerFunc func(context.Context, RecoveryAccessRequest) error

type RecoveryItem struct {
	Session         SessionID
	MutationID      string
	Digest          string
	Target          MutationTarget
	OriginalSubject string
	State           RecoveryState
	// Reason qualifies State: what delivery waits on while pending, or which
	// decision ended it while abandoned. Empty when delivered.
	Reason RecoveryReason
	// Recovered records that recovery machinery touched this mutation — a
	// reconciliation or a verb. It is provenance, not state: a recovered write is
	// delivered exactly like one that never needed help.
	Recovered        bool
	LegacyUnroutable bool
	EntryIDs         []string
	LastEvidence     string
	// Cause is the terminal's structured cause (e.g. graph-contention for an
	// engine-recorded discard), empty for participant decisions and open items.
	Cause string
}

type RecoveryList struct {
	Project ProjectRef
	Items   []RecoveryItem
}

type RecoveryReason string

type RecoveryReconcileRequest struct {
	Session    SessionID
	MutationID string
}

type RecoveryRequest struct {
	Session    SessionID
	MutationID string
	Verb       RecoveryVerb
	Reason     string
	Target     MutationTarget
}

type RecoveryResult struct {
	Project    ProjectRef
	Item       RecoveryItem
	Transition TransitionResult
}

type RecoveryState string

type RecoveryVerb string

type RegistryFunction struct {
	Name   string
	Class  string
	Doc    string
	Reads  []string
	Writes []string
}

type RequestIdentity struct {
	Subject    string
	Scopes     []string
	Attributes map[string]any
}

type ScoredChunkHit = types.ScoredChunkHit

type SearchCoverage struct {
	Project   ProjectID `json:"project"`
	Revision  string    `json:"revision"`
	Required  int       `json:"required"`
	Published int       `json:"published"`
	Complete  bool      `json:"complete"`
}

type SearchDiscoveryCursor = query.SearchDiscoveryCursor

type SearchEntryDescriptor = types.SearchEntryDescriptor

type SearchEntryRequirement = query.SearchEntryRequirement

type SearchEntryVersion = types.SearchEntryVersion

type SearchIndexEntryManifest interface {
	IndexedEntries(context.Context, IndexNamespace) ([]StoredEntryRef, error)
}

type SearchIndexEntryStore interface {
	EntryPublished(context.Context, SearchEntryVersion) (bool, error)
	PublishEntry(context.Context, SearchEntryVersion, []IndexedChunk) error
}

type SearchIndexStore interface {
	Manifest(context.Context, IndexNamespace) ([]StoredChunkRef, error)
	Reconcile(context.Context, IndexNamespace, string, []IndexedChunk, []string) error
	Nearest(context.Context, []IndexNamespace, []float32, int) ([]ScoredChunkHit, error)
}

type SearchIndexStoreFuncs struct {
	ManifestFunc  func(context.Context, IndexNamespace) ([]StoredChunkRef, error)
	ReconcileFunc func(context.Context, IndexNamespace, string, []IndexedChunk, []string) error
	NearestFunc   func(context.Context, []IndexNamespace, []float32, int) ([]ScoredChunkHit, error)
}

type SearchRequest struct {
	// IncludesRevision asks the source to observe a revision containing this write.
	IncludesRevision string
	// SyncMode is required, including for text-only requests.
	SyncMode          SearchSyncMode
	Terms             []string
	Phrase            string
	Branch            string
	BranchFromSession bool
	Type              string
	Layer             string
	Kind              string
	IncludeSuperseded bool
	Limit             int
	MaxCitations      int
	Repos             []string
	AllRepos          bool
}

type SearchResult struct {
	Coverage []SearchCoverage
	Notice   string
	Project  ProjectRef
	Results  string
	EntryIDs []string
}

type SearchSyncMode = query.SearchSyncMode

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

type SearchTargetProject struct {
	Project  ProjectID
	Revision string
}

type SessionAccessRequest struct {
	Actor   Principal
	Owner   Principal
	Session SessionID
	Project ProjectID
}

type SessionAppend struct {
	Metadata *SessionMetadata
	Events   []StoredEvent
}

type SessionBinding struct {
	SessionID SessionID
	Subject   string
	Project   ProjectID
	Version   uint64
}

type SessionEnd struct {
	Act     SessionEndAct
	EndedAt time.Time
	Reason  string `json:",omitempty"`
}

type SessionEndAct string

type SessionFilter struct {
	Subject     string
	Project     ProjectID
	EndedBefore *time.Time
	After       SessionID
	Limit       int
}

type SessionID string

type SessionMetadata struct {
	ID          SessionID
	Subject     string
	Project     ProjectID
	Participant string
	Label       string
	// Branch is the session's explicit branch binding. Empty means unbound;
	// compositions without a branch concept leave it empty.
	Branch     string `json:"branch,omitempty"`
	Attachment *Attachment
	// Ended is the session's single terminal record. Its presence is what makes
	// a session ended; nothing else about a session ends it (d-cpt-rw7).
	Ended     *SessionEnd `json:",omitempty"`
	UpdatedAt time.Time
}

type SessionPage struct {
	Sessions []StoredSession
	Next     SessionID
}

type SessionRef struct {
	Subject string
	Session SessionID
}

type SessionStore interface {
	Create(context.Context, SessionMetadata) (StoredSession, error)
	Load(context.Context, SessionID) (StoredSession, error)
	List(context.Context, SessionFilter) (SessionPage, error)
	Append(context.Context, SessionID, uint64, SessionAppend) (uint64, error)
	Delete(context.Context, SessionID) error
}

type ShowRequest struct {
	IDs               []string
	UpDepth           int
	DownDepth         int
	Branch            string
	BranchFromSession bool
	// Budget bounds each direction's chain expansion on the serve path; the
	// zero value is unbounded — explicit pulls arrive complete (d-tac-rzi).
	Budget types.ShowTreeBudget
}

type ShowResult struct {
	Project    ProjectRef
	Entries    string
	FullIDs    []string
	SummaryIDs []string
}

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

type SnapshotData struct {
	Project  ProjectID
	Revision string
	// Config retains stored document data only. Effective read configuration
	// comes exclusively from AcquiredSnapshot.Config or explicit runtime compatibility.
	Config  ProjectConfigDocument
	Entries []EntryDocument
	WIP     []WIPDocument
	// Unreadable records documents a store could not decode into structured
	// form — a file whose YAML frontmatter would not parse, for example. They
	// are carried as data rather than aborting the load: BuildSnapshot turns
	// each into a graph load issue surfaced through Snapshot.Health, so one
	// malformed file no longer makes an entire graph (and every session over
	// it) unopenable.
	Unreadable []DocumentIssue
}

type SnapshotReadQuery struct {
	Branch           string
	ExactRevision    string
	IncludesRevision string
}

type SnapshotReader interface {
	AcquireSnapshot(context.Context, SnapshotReadQuery) (*AcquiredSnapshot, error)
}

type StagedBlob struct {
	ID        string
	Session   SessionRef
	Digest    BlobDigest
	Size      int64
	Filename  string
	CreatedAt time.Time
}

type StagedBlobReader interface {
	Open(context.Context, string) (io.ReadCloser, error)
}

type StagedBlobStore interface {
	Stage(context.Context, SessionRef, string, io.Reader) (StagedBlob, error)
	Stat(context.Context, SessionRef, string) (StagedBlob, error)
	Open(context.Context, SessionRef, string) (io.ReadCloser, error)
	Retain(context.Context, SessionRef, string, []string) error
	Release(context.Context, SessionRef, string) error
	StagedSessions(ctx context.Context, after SessionRef, limit int) (StagedSessionPage, error)
	DeleteStaged(context.Context, SessionRef) error
}

type StagedSessionPage struct {
	Sessions []SessionRef
	Next     SessionRef
}

type StoredChunkRef = types.StoredChunkRef

type StoredEntryRef = types.StoredEntryRef

type StoredEvent struct {
	CodecVersion uint32
	Code         string
	Payload      json.RawMessage
}

type StoredSession struct {
	Metadata SessionMetadata
	Version  uint64
	Events   []StoredEvent
}

type TargetAcquirer interface {
	Acquire(context.Context, MutationTarget) (*AcquiredTarget, error)
}

type TargetAcquirerFunc func(context.Context, MutationTarget) (*AcquiredTarget, error)

type TransitionResult struct {
	Project    ProjectRef
	Binding    SessionBinding
	Apply      ApplyResult
	Finalizers []FinalizerOutcome
}

type ValidationError struct {
	Warnings []types.Warning
}

type ViewRequest struct {
	Layout            string
	Branch            string
	BranchFromSession bool
	Repos             []string
	AllRepos          bool
	// Budget bounds the view's scaling parts on the serve path; the zero
	// value is unbounded — explicit pulls arrive complete (d-tac-rzi).
	Budget types.ViewBudget
	// OmitRecovery skips the appended recovery notices — for injected lanes
	// whose session already carries them via sessionInfo, so a pending
	// recovery is served once, not once per lane.
	OmitRecovery bool
}

type ViewResult struct {
	Project  ProjectRef
	Sections string
	// MatchedCount is the total primary units the layout produced across the
	// local graph and any queried dependency repos. Zero means the pipeline
	// matched nothing — surfaces distinguish an empty result from a failure
	// (an agent over MCP cannot tell a blank string from a broken call).
	MatchedCount int
	// KnownParticipants names the graph's canonical participants, populated
	// only when the result was empty and the layout carried a participant
	// filter — so an empty participant() view can say what names exist rather
	// than leaving an exact-match miss indistinguishable from no data.
	KnownParticipants []string
}

type WIPDocument struct {
	LogicalPath string
	Content     string
}

type WorkflowAbandonResult struct {
	Abandoned   bool
	Session     SessionID
	Label       string
	Discarded   []WorkflowInstanceSummary
	HeldMarkers []string
	Base        *WorkflowServe
}

type WorkflowAdvanceRequest struct {
	Instance string
	Report   map[string]any
	Label    string
}

type WorkflowChooser struct {
	Chooser string
	Kind    ChooserKind
	Options []WorkflowChooserOption
}

type WorkflowChooserOption struct {
	Choice  string
	Collect []string
}

type WorkflowInstanceSummary struct {
	Instance  string
	Procedure string
	Step      string
}

type WorkflowOpenRequest struct {
	ClientName    string
	ClientVersion string
	Shell         string
	Label         string
}

type WorkflowParkResult struct {
	Instance  string
	Procedure string
	Step      string
	Base      *WorkflowServe
}

type WorkflowResumeRequest struct {
	SessionID     SessionID
	ClientName    string
	ClientVersion string
}

type WorkflowResumeResult struct {
	Session      SessionID
	Participant  string
	Label        string
	Branch       string
	Open         []WorkflowServe
	Instructions string
}

type WorkflowServe struct {
	Session SessionID
	// Project is the project the served instance targets — the home project
	// unless the move was started in a dependency (d-cpt-yjc).
	Project        ProjectID
	Branch         string
	Instance       string
	Procedure      string
	Status         string
	Step           string
	Goal           string
	Instructions   string
	Missing        []string
	ReportSchema   map[string]any
	PendingChooser *WorkflowChooser
	Execution      string
	Produced       map[string]any
	Diagnostics    []string
	// InstructionLanes are the unit's rendered lanes in order — what the MCP
	// layer dedups independently; Instructions is their join plus diagnostics.
	InstructionLanes []types.ServeLane
	// Sizes is the engine's per-part byte accounting for this serve, read by
	// the serve-budget measurement (d-tac-qwc).
	Sizes []types.PartSize
	Base  *WorkflowServe
	// Collected is the instance's already-gathered param and state values,
	// projected only onto resume serves so a newly attached or reoriented
	// agent sees what this instance holds — the anchor, chosen scope, and
	// reported judgments that persist across a handover (d-cpt-0tm). Empty on
	// door, next, and base-junction serves, which stay unchanged.
	Collected map[string]any
}

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

type WorkflowSessionSummary struct {
	Session      SessionID
	Label        string
	Participant  string
	Branch       string
	Anchor       string
	Open         []WorkflowInstanceSummary
	LastActivity time.Time
	Attachment   *Attachment
	Active       bool
}

type WorkflowStartRequest struct {
	Canonical string
	Params    map[string]any
	Label     string
	Parent    string
	// Project pins the project the new instance targets. Empty leaves it to
	// the dispatching parent's project, else the home project.
	Project ProjectID
}