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.

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

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
 }

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()