proposal

type AcceptAdapter interface {
	// ReadPending fetches the proposal row the adapter was constructed for,
	// scoped to the backend's configured workspace, translating the
	// backend's own not-found signal into this package's ErrNotFound.
	ReadPending(ctx context.Context) (*db.PendingProposal, error)

	// PrepareOutOfBand performs any work that must NOT run inside a database
	// transaction — currently only TypeKnowledge's embedding generation
	// (external network call) plus its cosine-similarity dedup check (see
	// ADR 0003's G1 "先算後寫": compute before write, so a transaction never
	// wraps an external network call). Called BEFORE BeginTx. The other 6
	// proposal types are no-ops — see BaseAcceptAdapter, embedded by both
	// production adapters so they don't each write an empty override. On
	// success, prepared is an opaque adapter-private value handed back to
	// Materialize unchanged (currently a knowledge.PreparedItem for
	// TypeKnowledge, nil for everything else).
	PrepareOutOfBand(ctx context.Context, prop *db.PendingProposal) (prepared any, err error)

	// BeginTx opens the transaction used for materialise + resolve.
	BeginTx(ctx context.Context) error

	// Materialize creates the concrete entity (goal/project/concept/decision/
	// task/knowledge/playbook) inside the open tx, dispatching on prop.Type.
	// prepared is whatever PrepareOutOfBand returned. created is the entity
	// to surface to the caller (nil for types with no representable "created"
	// value); a non-nil error aborts the whole Accept call — the deferred
	// Rollback fires and the proposal stays pending.
	Materialize(ctx context.Context, prop *db.PendingProposal, prepared any) (created any, err error)

	// ResolveAccepted flips the proposal (the one the adapter was
	// constructed for) to accepted inside the open tx.
	ResolveAccepted(ctx context.Context) (*db.PendingProposal, error)

	// Commit commits the open tx.
	Commit(ctx context.Context) error

	// Rollback rolls back the open tx. Safe to call after the tx has already
	// been closed by Commit (both pgx.Tx and database/sql.Tx guarantee a
	// redundant Rollback is a no-op), so AcceptOrchestration defers it
	// unconditionally rather than tracking its own committed flag.
	Rollback(ctx context.Context)
}

type BaseAcceptAdapter struct{}

type BatchConfirmResult struct {
	Results []BatchItemResult `json:"results"`
	// Accepted is the count of proposals successfully resolved to the requested action.
	Accepted int `json:"accepted"`
	// Failed is the count of proposals that could not be resolved (not found,
	// already resolved, or other error). On the Postgres path a single failure
	// triggers a full rollback and all entries become failed.
	Failed int `json:"failed"`
}

type BatchItemResult struct {
	ID     string `json:"id"`
	OK     bool   `json:"ok"`
	ErrMsg string `json:"error,omitempty"`
}

type ConceptCandidate struct {
	Title          string   `json:"title"`
	Content        string   `json:"content"`
	Tags           []string `json:"tags,omitempty"`
	SourceItemID   string   `json:"source_item_id,omitempty"`   // knowledge_items.id that triggered the proposal
	SourceItemType string   `json:"source_item_type,omitempty"` // "article" / "til" / etc.
}

type ConceptPayload struct {
	Title   string   `json:"title"`
	Content string   `json:"content"`
	Tags    []string `json:"tags,omitempty"`
}

type CreateParams struct {
	WorkspaceID *uuid.UUID // nil → unscoped (Phase B1: always nil; B2 wires real workspace)
	Type        Type
	Payload     []byte // JSON-encoded proposal body (entity-specific shape)
	ProposedBy  string // empty → NULL; e.g. "claude-code", "discord-bot"
}

type DecisionProposerPayload struct {
	Title        string   `json:"title"`
	Decision     string   `json:"decision"`
	Rationale    string   `json:"rationale"`
	Alternatives []string `json:"alternatives,omitempty"`
	SessionID    string   `json:"session_id"`
	TriggerTool  string   `json:"trigger_tool"`
}

type KnowledgePayload struct {
	Title   string   `json:"title"`
	Content string   `json:"content"`
	Tags    []string `json:"tags,omitempty"`
	// SourceEntityID is an opaque foreign entity UUID (as string; NEVER a real
	// FK per CLAUDE.md red-line #9) that scheduler jobs stamp so a follow-up
	// run can SQL-dedup against it via payload->>'source_entity_id' instead of
	// re-scanning application-side. Mirrors TaskPayload.SourceEntityID's same
	// rationale — see its doc comment. Written by
	// scheduler.runKnowledgeToSkillCandidate (keyed on knowledge_items.id) to
	// prevent the job from re-proposing the same high-recall item every run.
	// Empty for non-scheduler producers (weekly_goal_review,
	// behavior_rule_candidate, reflection/consolidation crons — none of those
	// dedup on a source entity today).
	SourceEntityID string `json:"source_entity_id,omitempty"`
}

type PgAcceptDeps struct {
	Pool      *pgxpool.Pool
	Proposal  *Store
	GTD       *gtd.Store
	Learning  *learning.Store
	Decision  *decision.Store
	Knowledge *knowledge.Store
}

type Status string

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

type StoreIface interface {
	Create(ctx context.Context, p CreateParams) (*db.PendingProposal, error)
	Get(ctx context.Context, id uuid.UUID) (*db.PendingProposal, error)
	ListPending(ctx context.Context) ([]db.PendingProposal, error)
	// ListAll returns all proposals of the given type regardless of status,
	// newest first, up to limit rows. Used by GET /api/proposals?status=.
	ListAll(ctx context.Context, proposalType string, limit int32) ([]db.PendingProposal, error)
	Resolve(ctx context.Context, id uuid.UUID, status Status) (*db.PendingProposal, error)
	// BatchConfirm resolves multiple proposals to the given status in a single
	// operation. On Postgres the entire batch runs inside one transaction —
	// any individual failure rolls back the whole batch. On SQLite each ID is
	// processed independently (best-effort). Callers MUST validate ids length
	// (1–100) and status before invoking.
	BatchConfirm(ctx context.Context, ids []uuid.UUID, status Status) (BatchConfirmResult, error)
	AutoProposeConceptFromKnowledge(ctx context.Context, item *db.KnowledgeItem, proposedBy string) (*db.PendingProposal, error)
}

type TaskPayload struct {
	Title               string `json:"title"`
	SourceTool          string `json:"source_tool"`
	ArgSummary          string `json:"arg_summary,omitempty"`
	ResultSummary       string `json:"result_summary,omitempty"`
	ClassifierRationale string `json:"classifier_rationale,omitempty"`
	SuggestedKind       string `json:"suggested_kind,omitempty"`
	Description         string `json:"description,omitempty"`
	// SourceEntityID is an opaque foreign entity UUID (as string; NEVER a real
	// FK per CLAUDE.md red-line #9) that scheduler jobs stamp so a follow-up
	// run can SQL-dedup against it via payload->>'source_entity_id' instead of
	// re-scanning application-side. Currently written by
	// scheduler.runDecisionOutcomeReview (keyed on decisions.id) to prevent the
	// daily job from re-proposing the same decision every run. Empty for
	// non-scheduler producers (MCP auto-capture, handler autolog).
	SourceEntityID string `json:"source_entity_id,omitempty"`
}

type Type string