engine

type ActivitySink interface {
	// RegisterSoftwareAgent find-or-creates is the caller's concern; the engine
	// only registers its own stable agent once if absent.
	RegisterSoftwareAgent(namespace, name, version, source string) (provenance.SoftwareAgent, error)
	// StartActivityWithID records an activity under a caller-supplied id with
	// ON CONFLICT(id) DO NOTHING, so a replayed emission collapses to one row.
	StartActivityWithID(id provenance.ActivityID, agentID provenance.AgentID, phase provenance.Phase, stage provenance.Stage, notes string) (provenance.Activity, error)
}

type AdvanceStep struct {
	// ToPhase is the target phase for this transition.
	ToPhase protocol.PhaseId
	// TriggeredBy identifies who/what drove the transition (recorded as the
	// forensic row's role; defaults to the epoch role when empty).
	TriggeredBy string
	// ConditionMet describes the satisfied transition condition.
	ConditionMet string
	// Votes are recorded (in order) before the advance, to satisfy the
	// consensus gate at p4/p10.
	Votes []protocol.ReviewVoteSignal
	// BlockerDelta adjusts the blocker count before the advance: a positive
	// value records that many new blockers, a negative value resolves that
	// many. Used to exercise the p10 blocker gate.
	BlockerDelta int
}

type Config struct {
	// DBPath is the unified pasture.db path. Required.
	DBPath string
	// ApplicationVersion is the pinned DBOS application version. REQUIRED:
	// DBOS recovery is filtered by it, and it defaults to a binary hash, so a
	// rebuilt binary would skip recovery of an in-flight epoch unless this is
	// pinned to a stable value across builds. New rejects an empty value.
	ApplicationVersion string
	// ExecutorID overrides DefaultExecutorID. Pinned across restarts.
	ExecutorID string
	// AppName overrides DefaultAppName.
	AppName string
	// Trail is the forensic sink for one audit row per transition. When nil,
	// New opens an owned SQLite trail on DBPath (also migrating the file to the
	// current schema, which creates the dedup_key column).
	Trail audit.Trail
	// SkipMigrations opens DBPath as a pre-migrated database when Trail is nil.
	// The audit layer still asserts the schema version. This is intended for
	// tests that copy a current golden database; production callers should leave
	// it false so the real migrator runs.
	SkipMigrations bool
	// Specs overrides the canonical phase transition table (for tests). nil →
	// protocol.PhaseSpecs.
	Specs map[protocol.PhaseId]protocol.PhaseSpec
	// Logger is the DBOS logger. nil → slog.Default().
	Logger *slog.Logger
	// OnTransition, when set, runs INSIDE the durable step for each successful
	// transition, AFTER the projection + forensic audit row are written and
	// BEFORE the step returns. It is the step-bracketing seam: idempotent
	// activity recording wires here (it shares the step's replay semantics, so
	// any external write it makes must be idempotent — e.g. a deterministic-id
	// ON CONFLICT insert). Returning an error fails the step (and so the
	// transition's durable commit).
	//
	// stepSeq is the deterministic per-transition step sequence (the same value
	// the audit dedup key is derived from). It is threaded in from the workflow
	// body because it cannot be recovered inside the hook: DBOS exposes it only
	// in the workflow body, and a replay re-runs only the crashed step, so a
	// hook-local counter would not be replay-stable. Hooks derive their own
	// deterministic keys from it via protocol.DedupKey.
	OnTransition func(ctx context.Context, epochId string, rec *protocol.TransitionRecord, stepSeq string) error
	// Tracker, when set, makes the engine record one PROV-O activity per
	// transition with a deterministic id (exactly-once across replay). nil ⇒
	// activities are not recorded and the engine behaves as it did without this
	// field. The engine resolves a stable software-agent id at New() so the
	// deterministic insert always references a present agent row.
	Tracker ActivitySink
	// SliceConcurrency is the per-executor concurrency limit K for the slice
	// queue. It bounds the number of slice and review sub-workflows that the
	// local executor runs concurrently, providing backpressure on the single
	// SQLite WAL writer bottleneck. <= 0 uses DefaultSliceQueueConcurrency.
	//
	// See DefaultSliceQueueConcurrency in internal/engine/queue.go for the
	// full trade-off rationale and tuning guidance.
	SliceConcurrency int
	// QueueBasePollingInterval overrides the DBOS queue base polling interval.
	// Zero keeps the DBOS production default. Tests may set a shorter interval
	// to keep bounded-concurrency assertions fast without changing production
	// queue cadence.
	QueueBasePollingInterval time.Duration
	// HooksMgr, when set, receives slice lifecycle events (SliceStarted,
	// SliceCompleted, SliceFailed) dispatched by slice sub-workflows. nil ⇒
	// hook dispatch is skipped (no observability events; the sub-workflow still
	// runs correctly).
	//
	// pastured wires HooksMgr when it hosts the engine. Callers that don't need
	// slice lifecycle observability (e.g. the local CLI, unit tests) may leave
	// this nil.
	HooksMgr *hooks.Manager
	Timeouts timeouts.Profile
}

type ControlInput struct {
	EpochId string
}

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

type EpochInput struct {
	EpochId  string
	Advances []AdvanceStep
}

type ReviewInput struct {
	// EpochId is the parent epoch this review belongs to.
	EpochId string `json:"epochId"`
	// PhaseId identifies which review phase this is (e.g. "review" or "code-review").
	PhaseId string `json:"phaseId"`
	// Round is the review-cycle counter for this (epochId, phaseId) pair. It
	// starts at 1 and increments each time a review returns REVISE and the
	// protocol re-enters the review phase. Supplying the round ensures each
	// re-review runs a fresh DBOS sub-workflow (a different id) rather than
	// returning the memoized result of a prior round.
	//
	// The round value MUST come from a deterministic, replay-stable counter
	// tracked in workflow state, NOT from wall-clock time or a random value.
	// Default 0 is treated as round 1 by EnqueueReview for backwards
	// compatibility (existing callers that don't set Round still get the
	// correct first-round workflow id).
	Round int `json:"round,omitempty"`
}

type ReviewResult struct {
	// PhaseId echoes the input for correlation on the parent side.
	PhaseId string `json:"phaseId"`
	// Success is true when all review axes received an ACCEPT vote.
	Success bool `json:"success"`
	// VoteResult is the per-axis vote map collected by the sub-workflow.
	VoteResult map[protocol.ReviewAxis]protocol.VoteType `json:"voteResult"`
}

type SliceInput struct {
	// EpochId is the parent epoch this slice belongs to. Used for hook dispatch
	// and the parent progress signal.
	EpochId string `json:"epochId"`
	// SliceId is the unique identifier for this slice. It doubles as the
	// sub-workflow's id so start_slice / complete_slice signals address it.
	SliceId string `json:"sliceId"`
	// ParentWorkflowId is the id of the epoch control workflow that dispatched
	// this slice. When non-empty, the sub-workflow delivers a slice_progress
	// signal to it on completion.
	ParentWorkflowId string `json:"parentWorkflowId"`
}

type SliceResult struct {
	// SliceId echoes the input for correlation on the parent side.
	SliceId string `json:"sliceId"`
	// Success is true when the slice completed without error.
	Success bool `json:"success"`
	// Output holds a human-readable success message (non-empty when Success is true).
	Output string `json:"output,omitempty"`
	// Error holds the failure reason (non-empty when Success is false).
	Error *string `json:"error,omitempty"`
}