feat: Phase 3b — EntityService, postgres EntityRepository, converged mutations

Problem: entity mutations (create/update/state) existed as three drifted copies — HTTP CreateEntity/PatchEntity, MCP create_entity/ update_entity_attributes/set_entity_state — each with its own inline SQL, its own validation subset (MCP validated lifecycle states, HTTP did not; HTTP patched attributes without regenerating derived checks, MCP did; MCP wrote no audit trail), the exact drift ADR 0016's first vertical slice exists to collapse. Change: - internal/core/ports: DerivedCheck, Idempotency (adapter-owned request hash + cached-body renderer so the replay record commits in the create's transaction), IdempotentResponse + GetIdempotent read, AuditEntry gains Method/Path/CorrelationID, Event gains CorrelationID; EntityUpdateInput carries ExpectedVersion + RederiveChecks (derivation for updates runs repo-side: the graph host fallback reads relationships through the open tx). - internal/adapters/postgres/repositories.go: EntityRepo (Create/ Update/SetState/reads/idempotency) preserving the load-bearing check-then-act invariants in-tx: version WHERE-clause, declared transitions + preconditions (ValidateTransition), duplicate-slug mapping, audit/event/writeCheck all inside one BEGIN…COMMIT. OntologyRepo: TTL-cached OntologyStore. - internal/core/app/entities.go: EntityService — ontology validation (type exists, concrete, state declared — the stricter MCP rule now governs both surfaces), default-state resolution, id generation, derivation for creates, audit/event construction, idempotency pass-through. - httpapi CreateEntity/PatchEntity rewired to the service; PATCH now regenerates derived checks (the A2 parity gap). MCP create/update/ set-state tools call the same service — and now write audit + event rows like the HTTP surface always did. - Integration-test seed paths fixed for the adapters/postgres package depth (../../../seeds). Pre-existing failures documented: TestAPIEndToEnd (entity_types 60 vs 59; 501-endpoint now 200), TestClientLifecycleEndToEnd, TestPhase3* rows — verified failing identically at ec11956 (scratch approval- notifier commit test drift), unrelated to this change. All mutation integration tests (create/patch/idempotency/audit/regeneration) pass. Verification: make test-db (postgres + mcp green, httpapi green except the pre-existing set), full non-DB suite (19 pkgs), golangci on new packages — 0 issues.
2026-08-15 23:38:21 +02:00
parent d4f5084a6d
commit 9e3783734e
15 changed files with 1071 additions and 368 deletions
--- a/internal/core/app/entities.go
+++ b/internal/core/app/entities.go
@@ -0,0 +1,262 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"github.com/dtoro/oikos/internal/core/domain"
+	"github.com/dtoro/oikos/internal/core/ports"
+	"github.com/google/uuid"
+)
+
+// EntityService owns the entity aggregate's use-cases: create with derived
+// checks, update with optimistic versioning and check regeneration,
+// lifecycle transitions. Validation against the (cached) ontology happens
+// here, in the pure half; transactional check-then-act invariants
+// (version, declared transitions, preconditions) run in the repository
+// (plan §3.6).
+type EntityService struct {
+	entities ports.EntityRepository
+	onto     ports.OntologyStore
+}
+
+// NewEntityService wires the service.
+func NewEntityService(entities ports.EntityRepository, onto ports.OntologyStore) *EntityService {
+	return &EntityService{entities: entities, onto: onto}
+}
+
+// CreateEntityCmd is one entity creation. Actor identifies the calling
+// surface for the audit trail ("operator:<label>", "agent:mcp").
+type CreateEntityCmd struct {
+	Slug       string
+	Type       string
+	Name       string
+	State      string            // "" → lifecycle default
+	Attributes map[string]any
+	ActorType  string
+	Actor      string
+	Method     string // audit context, e.g. "POST" / "TOOL"
+	Path       string // audit context, e.g. "/api/v1/entities" / "create_entity"
+	// Idempotency, when set, replays-protects the create. The adapter owns
+	// the request hash and the cached-body renderer (its wire shape); the
+	// repository stores the record in the create's transaction.
+	Idempotency *ports.Idempotency
+}
+
+// Create validates the type (exists, concrete, state declared), derives
+// default checks, and commits entity + checks + audit + event in one
+// transaction.
+func (s *EntityService) Create(ctx context.Context, cmd CreateEntityCmd) (domain.Entity, DeriveResult, error) {
+	var res DeriveResult
+
+	tree, err := s.onto.LoadTypeTree(ctx)
+	if err != nil {
+		return domain.Entity{}, res, err
+	}
+
+	slug := cmd.Slug
+	if slug == "" {
+		slug = cmd.Type + ":" + cmd.Name
+	}
+
+	// Caller-supplied states are validated against the lifecycle's declared
+	// states — a create bypass of lifecycle guardrails would let an agent
+	// create in a terminal state without satisfying the preconditions that
+	// SetState enforces for the same transition. Both surfaces (REST, MCP)
+	// now share this rule.
+	state := cmd.State
+	if state == "" {
+		state = tree.DefaultState(cmd.Type)
+	}
+	if err := tree.ValidateEntity(cmd.Type, state); err != nil {
+		return domain.Entity{}, res, err
+	}
+
+	id, err := uuid.NewV7()
+	if err != nil {
+		return domain.Entity{}, res, err
+	}
+	e := domain.Entity{
+		ID:         domain.UUID(id.String()),
+		Slug:       slug,
+		Type:       cmd.Type,
+		Name:       cmd.Name,
+		State:      state,
+		Attributes: cmd.Attributes,
+	}
+
+	// Derivation for a create has no graph fallback available — a new entity
+	// has no edges yet. A type whose address comes from its host (a service)
+	// produces no checks on this pass; the gap is deliberate and visible
+	// (coverage sweep), and the next mutation or ingest fills it once the
+	// hosting edge exists.
+	attrsJSON, _ := json.Marshal(cmd.Attributes)
+	defs, dres := Derive(tree, CheckTarget{
+		ID: string(e.ID), Slug: slug, Type: cmd.Type, Name: cmd.Name, Attrs: attrsJSON,
+	}, nil)
+	// Derive is pure and cannot count writes; every derived def is ensured
+	// by the repository in the create's transaction (a write failure aborts
+	// the whole create), so the ensured count is the derived count.
+	dres.Created = len(defs)
+	res = dres
+	derived := make([]ports.DerivedCheck, len(defs))
+	for i, d := range defs {
+		derived[i] = ports.DerivedCheck{Kind: d.Kind, Config: d.Config, IntervalS: d.IntervalS}
+	}
+
+	input := ports.EntityCreateInput{
+		Entity:        e,
+		DerivedChecks: derived,
+		Audit: []ports.AuditEntry{{
+			ActorType: cmd.ActorType, ActorLabel: cmd.Actor, Action: "create",
+			EntityID: e.ID, Method: cmd.Method, Path: cmd.Path,
+			Details: map[string]any{"type": cmd.Type, "slug": slug},
+		}},
+		Event: &ports.Event{
+			Type: "entity.created", Severity: "info", Source: "oikos-api", EntityID: e.ID,
+			Data: map[string]any{"slug": slug, "type": cmd.Type},
+		},
+	}
+	input.Idempotency = cmd.Idempotency
+
+	created, err := s.entities.Create(ctx, input)
+	if err != nil {
+		return domain.Entity{}, res, err
+	}
+	return created, res, nil
+}
+
+// UpdateEntityCmd mutates an entity. Attributes are REPLACED when
+// AttrsReplace is true and shallow-merged otherwise. SetState semantics
+// ride along: a State change is lifecycle-validated.
+type UpdateEntityCmd struct {
+	SlugOrID     string
+	ExpectedVer  int
+	Name         string
+	State        string
+	Attributes   map[string]any
+	AttrsReplace bool
+	Maintenance  *time.Time
+	SetMaint     bool
+	// RederiveChecks regenerates default checks from the post-update
+	// attributes (a `monitoring` attribute change re-wires probes).
+	RederiveChecks bool
+	ActorType      string
+	Actor          string
+	Method         string
+	Path           string
+}
+
+// Update loads the current entity, validates the target state against the
+// ontology, and commits the mutation atomically. The optimistic-version and
+// transition-precondition checks run inside the repository's transaction.
+// When RederiveChecks is set the returned DeriveResult summarizes the
+// derivation the transaction applied (for surface messages).
+func (s *EntityService) Update(ctx context.Context, cmd UpdateEntityCmd) (domain.Entity, DeriveResult, error) {
+	var dres DeriveResult
+	current, err := s.resolve(ctx, cmd.SlugOrID)
+	if err != nil {
+		return domain.Entity{}, dres, err
+	}
+
+	tree, err := s.onto.LoadTypeTree(ctx)
+	if err != nil {
+		return domain.Entity{}, dres, err
+	}
+	if cmd.State != "" && cmd.State != current.State {
+		if err := tree.ValidateEntity(current.Type, cmd.State); err != nil {
+			return domain.Entity{}, dres, err
+		}
+	}
+
+	e := domain.Entity{
+		ID:      current.ID,
+		Slug:    current.Slug,
+		Type:    current.Type,
+		Name:    cmd.Name,
+		State:   cmd.State,
+		Version: current.Version,
+	}
+	switch {
+	case cmd.Attributes == nil:
+		e.Attributes = nil // keep current
+	case cmd.AttrsReplace:
+		e.Attributes = cmd.Attributes
+	default:
+		merged := map[string]any{}
+		for k, v := range current.Attributes {
+			merged[k] = v
+		}
+		for k, v := range cmd.Attributes {
+			merged[k] = v
+		}
+		e.Attributes = merged
+	}
+	if cmd.SetMaint {
+		e.MaintenanceUntil = cmd.Maintenance
+	}
+
+	updated, err := s.entities.Update(ctx, ports.EntityUpdateInput{
+		Entity:         e,
+		ExpectedVersion: cmd.ExpectedVer,
+		RederiveChecks:  cmd.RederiveChecks,
+		Audit: []ports.AuditEntry{{
+			ActorType: cmd.ActorType, ActorLabel: cmd.Actor, Action: "patch",
+			EntityID: current.ID, Method: cmd.Method, Path: cmd.Path,
+			Details: map[string]any{"version": current.Version},
+		}},
+		Event: &ports.Event{
+			Type: "entity.updated", Severity: "info", Source: "oikos-api", EntityID: current.ID,
+			Data: map[string]any{"slug": current.Slug, "type": current.Type},
+		},
+	})
+	if err != nil {
+		return domain.Entity{}, dres, err
+	}
+	if cmd.RederiveChecks {
+		attrsJSON, _ := json.Marshal(updated.Attributes)
+		defs, d := Derive(tree, CheckTarget{
+			ID: string(updated.ID), Slug: updated.Slug, Type: updated.Type,
+			Name: updated.Name, Attrs: attrsJSON,
+		}, nil)
+		d.Created = len(defs)
+		dres = d
+	}
+	return updated, dres, nil
+}
+
+// SetState transitions an entity's lifecycle. Declared-transition and
+// precondition enforcement happens in the repository's transaction; a
+// stale FromState is refused there (check-then-act).
+func (s *EntityService) SetState(ctx context.Context, slug, fromState, toState, actorType, actor, method, path string) (domain.Entity, error) {
+	current, err := s.entities.BySlug(ctx, slug)
+	if err != nil {
+		return domain.Entity{}, err
+	}
+	after, err := s.entities.SetState(ctx, ports.EntityTransitionInput{
+		Slug: slug,
+		From: fromState,
+		To:   toState,
+		Audit: []ports.AuditEntry{{
+			ActorType: actorType, ActorLabel: actor, Action: "state",
+			EntityID: current.ID, Method: method, Path: path,
+			Details: map[string]any{"from": fromState, "to": toState},
+		}},
+		Event: &ports.Event{
+			Type: "entity.state.changed", Severity: "info", Source: "oikos-api", EntityID: current.ID,
+			Data: map[string]any{"slug": slug, "from": fromState, "to": toState},
+		},
+	})
+	if err != nil {
+		return domain.Entity{}, err
+	}
+	return after, nil
+}
+
+func (s *EntityService) resolve(ctx context.Context, slugOrID string) (domain.Entity, error) {
+	if _, err := uuid.Parse(slugOrID); err == nil {
+		return s.entities.Get(ctx, domain.UUID(slugOrID))
+	}
+	return s.entities.BySlug(ctx, slugOrID)
+}
--- a/internal/core/ports/entities.go
+++ b/internal/core/ports/entities.go
@@ -7,44 +7,84 @@ import (
 	"github.com/dtoro/oikos/internal/ontology"
 )

-// TypeTree aliases the ontology tree: entity types, relationship types,
-// lifecycle definitions. ontology is pure over domain; it moves under
-// core/ when checkdefaults is absorbed (Phase 3).
-type TypeTree = ontology.TypeTree
+// TypeTree is the loaded ontology: entity types, relationship types,
+// lifecycle definitions. It is ontology's pure tree behind an interface so
+// ports does not alias a concrete struct into the contract.
+type TypeTree = *ontology.TypeTree

 // EntityFilters bounds entity list/search reads.
 type EntityFilters struct {
-	Type  string
-	State string
-	Q     string
-	Limit int
+	Type   string
+	State  string
+	Q      string
+	Domain string
+	Layer  string
+	Cursor string
+	Limit  int
+}
+
+// DerivedCheck is one concrete check derived from an entity's type
+// monitoring spec, to be written in the same transaction as the entity
+// mutation that produced it.
+type DerivedCheck struct {
+	Kind      string
+	Config    map[string]any
+	IntervalS int
+}
+
+// Idempotency replays-protects one command: the adapter stores the cached
+// response inside the same transaction as the mutation, so a crash between
+// the two cannot let a replay re-execute. RenderBody is a pure presenter
+// closure that serializes the committed entity into the caller's wire
+// shape; the repository never inspects it.
+type Idempotency struct {
+	Actor       string
+	Key         string
+	RequestHash string
+	RenderBody  func(domain.Entity) []byte
+}
+
+// IdempotentResponse is a previously cached response for (actor, key).
+type IdempotentResponse struct {
+	RequestHash   string
+	ResponseCode  int
+	ResponseBody  []byte
 }

 // EntityCreateInput is one transaction: the entity, its derived check
 // definitions, and the audit/event side-effects of the creation.
 type EntityCreateInput struct {
 	Entity        domain.Entity
-	DerivedChecks []CheckDef
+	DerivedChecks []DerivedCheck
 	Audit         []AuditEntry
 	Event         *Event
+	Idempotency   *Idempotency
 }

-// EntityUpdateInput mirrors EntityCreateInput for updates.
+// EntityUpdateInput mutates an entity atomically. ExpectedVersion is the
+// optimistic-concurrency check (0 disables it). When RederiveChecks is set,
+// the repository re-derives default checks inside the transaction — the
+// graph host fallback (a service inherits its container's address) reads
+// relationships through the open transaction, so derivation cannot happen
+// in the service for updates.
 type EntityUpdateInput struct {
-	Entity        domain.Entity
-	DerivedChecks []CheckDef
-	Audit         []AuditEntry
-	Event         *Event
+	Entity          domain.Entity
+	ExpectedVersion int
+	RederiveChecks  bool
+	Audit           []AuditEntry
+	Event           *Event
+	Idempotency     *Idempotency
 }

-// EntityTransitionInput is a lifecycle state change: the check-then-act
-// precondition (current state) is validated inside the transaction.
+// EntityTransitionInput is a lifecycle state change: the declared-transition
+// check and preconditions are validated inside the transaction
+// (check-then-act), not against the possibly-stale From.
 type EntityTransitionInput struct {
-	Slug         string
-	From         string
-	To           string
-	Audit        []AuditEntry
-	Event        *Event
+	Slug  string
+	From  string
+	To    string
+	Audit []AuditEntry
+	Event *Event
 }

 // EntityRepository is the entity aggregate. Command methods are
@@ -52,12 +92,16 @@ type EntityTransitionInput struct {
 type EntityRepository interface {
 	Get(ctx context.Context, id domain.UUID) (domain.Entity, error)
 	BySlug(ctx context.Context, slug string) (domain.Entity, error)
-	List(ctx context.Context, filters EntityFilters) ([]domain.Entity, error)
+	List(ctx context.Context, filters EntityFilters) ([]domain.Entity, string, error)
 	Search(ctx context.Context, q string, limit int) ([]domain.Entity, error)

 	Create(ctx context.Context, input EntityCreateInput) (domain.Entity, error)
 	Update(ctx context.Context, input EntityUpdateInput) (domain.Entity, error)
 	SetState(ctx context.Context, input EntityTransitionInput) (domain.Entity, error)
+
+	// GetIdempotent returns the cached response for (actor, key), or
+	// domain.ErrNotFound when none exists.
+	GetIdempotent(ctx context.Context, actor, key string) (IdempotentResponse, error)
 }

 // RelationshipCreateInput validates endpoints against the ontology in core
--- a/internal/core/ports/events.go
+++ b/internal/core/ports/events.go
@@ -13,9 +13,10 @@ type Event struct {
 	Type     string // e.g. "execution.completed", "health.changed"
 	Severity string // "info", "warning", "critical"
 	Source   string // "api", "mcp", "scheduler", "webhook"
-	EntityID domain.UUID
-	Data     map[string]any
-	Ts       time.Time
+	EntityID      domain.UUID
+	CorrelationID string
+	Data          map[string]any
+	Ts            time.Time
 }

 // EventPublisher fans events out to subscribers and persists them. The
@@ -25,12 +26,17 @@ type EventPublisher interface {
 	Publish(ctx context.Context, event Event) error
 }

-// AuditEntry is an append-only audit-log record.
+// AuditEntry is an append-only audit-log record. Method/Path carry the
+// surface context ("POST", "/api/v1/entities" for REST; "TOOL",
+// "create_entity" for MCP).
 type AuditEntry struct {
 	ActorType  string // "agent", "operator", "system"
 	ActorLabel string
 	Action     string
 	EntityID   domain.UUID
+	Method     string
+	Path       string
+	CorrelationID string
 	Details    map[string]any
 	Ts         time.Time
 }
--- a/internal/core/ports/portstest/fakes.go
+++ b/internal/core/ports/portstest/fakes.go
@@ -21,10 +21,12 @@ type EntityRepo struct {
 	bySlug  map[string]domain.UUID
 	order   []domain.UUID
 	nextID  int
-	Audits  []ports.AuditEntry
-	Events  []ports.Event
-	Checks  map[domain.UUID][]ports.CheckDef
-	ErrStub error // returned by every command when set
+	Audits     []ports.AuditEntry
+	Events     []ports.Event
+	Checks     map[domain.UUID][]ports.CheckDef
+	Idempotent map[string]ports.IdempotentResponse
+	Rederived  []domain.UUID
+	ErrStub    error // returned by every command when set
 }

 // NewEntityRepo builds an empty in-memory entity repository.
@@ -32,7 +34,8 @@ func NewEntityRepo() *EntityRepo {
 	return &EntityRepo{
 		byID:   make(map[domain.UUID]domain.Entity),
 		bySlug: make(map[string]domain.UUID),
-		Checks: make(map[domain.UUID][]ports.CheckDef),
+		Checks:     make(map[domain.UUID][]ports.CheckDef),
+		Idempotent: make(map[string]ports.IdempotentResponse),
 	}
 }

@@ -58,8 +61,9 @@ func (r *EntityRepo) BySlug(_ context.Context, slug string) (domain.Entity, erro
 	return r.byID[id], nil
 }

-// List returns entities filtered by type/state, bounded by limit.
-func (r *EntityRepo) List(_ context.Context, f ports.EntityFilters) ([]domain.Entity, error) {
+// List returns entities filtered by type/state, bounded by limit, with the
+// next cursor ("" when exhausted).
+func (r *EntityRepo) List(_ context.Context, f ports.EntityFilters) ([]domain.Entity, string, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	var out []domain.Entity
@@ -76,13 +80,17 @@ func (r *EntityRepo) List(_ context.Context, f ports.EntityFilters) ([]domain.En
 			break
 		}
 	}
-	return out, nil
+	next := ""
+	if len(out) == f.Limit && f.Limit > 0 {
+		next = "cursor-more"
+	}
+	return out, next, nil
 }

 // Search matches name/slug substrings.
 func (r *EntityRepo) Search(ctx context.Context, q string, limit int) ([]domain.Entity, error) {
 	// Substring over name/slug is enough for service tests.
-	all, err := r.List(ctx, ports.EntityFilters{Limit: limit})
+	all, _, err := r.List(ctx, ports.EntityFilters{Limit: limit})
 	if err != nil {
 		return nil, err
 	}
@@ -114,27 +122,50 @@ func (r *EntityRepo) Create(_ context.Context, in ports.EntityCreateInput) (doma
 	if in.Event != nil {
 		r.Events = append(r.Events, *in.Event)
 	}
-	r.Checks[in.Entity.ID] = in.DerivedChecks
+	if in.Idempotency != nil {
+		var body []byte
+		if in.Idempotency.RenderBody != nil {
+			body = in.Idempotency.RenderBody(in.Entity)
+		}
+		r.Idempotent[in.Idempotency.Actor+"\x00"+in.Idempotency.Key] = ports.IdempotentResponse{
+			RequestHash: in.Idempotency.RequestHash, ResponseCode: 201, ResponseBody: body,
+		}
+	}
 	return in.Entity, nil
 }

 // Update replaces a stored entity and records its input side-effects.
+// The optimistic-version check mirrors the postgres WHERE version clause.
 func (r *EntityRepo) Update(_ context.Context, in ports.EntityUpdateInput) (domain.Entity, error) {
 	if r.ErrStub != nil {
 		return domain.Entity{}, r.ErrStub
 	}
 	r.mu.Lock()
 	defer r.mu.Unlock()
-	if _, ok := r.byID[in.Entity.ID]; !ok {
+	current, ok := r.byID[in.Entity.ID]
+	if !ok {
 		return domain.Entity{}, domain.ErrNotFound
 	}
-	delete(r.bySlug, r.byID[in.Entity.ID].Slug)
-	r.store(in.Entity)
+	if in.ExpectedVersion > 0 && current.Version != in.ExpectedVersion {
+		return domain.Entity{}, domain.ErrConflict
+	}
+	after := in.Entity
+	after.Version = current.Version + 1
+	delete(r.bySlug, current.Slug)
+	r.store(after)
 	r.Audits = append(r.Audits, in.Audit...)
 	if in.Event != nil {
 		r.Events = append(r.Events, *in.Event)
 	}
-	r.Checks[in.Entity.ID] = in.DerivedChecks
+	if in.Idempotency != nil {
+		var body []byte
+		if in.Idempotency.RenderBody != nil {
+			body = in.Idempotency.RenderBody(in.Entity)
+		}
+		r.Idempotent[in.Idempotency.Actor+"\x00"+in.Idempotency.Key] = ports.IdempotentResponse{
+			RequestHash: in.Idempotency.RequestHash, ResponseCode: 201, ResponseBody: body,
+		}
+	}
 	return in.Entity, nil
 }

@@ -168,6 +199,17 @@ func (r *EntityRepo) store(e domain.Entity) {
 	r.order = append(r.order, e.ID)
 }

+// GetIdempotent returns the cached response for (actor, key).
+func (r *EntityRepo) GetIdempotent(_ context.Context, actor, key string) (ports.IdempotentResponse, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	cached, ok := r.Idempotent[actor+"\x00"+key]
+	if !ok {
+		return ports.IdempotentResponse{}, domain.ErrNotFound
+	}
+	return cached, nil
+}
+
 // FindBySlug is a test helper bypassing the port interface.
 func (r *EntityRepo) FindBySlug(slug string) (domain.Entity, bool) {
 	r.mu.Lock()