0.29.0 — code-quality refactor (plan E1–E5): file splits, sqlc migration, SSH unification, test coverage

E1: split monolithic files — cmd/nomos (main.go → server.go + mcp.go + workers.go),
    internal/mcp/tools.go → entity_tools/ops_tools/knowledge_tools/analysis_tools,
    internal/httpapi/impl.go → domain files (entities, events, signals, ontology,
    fleet_health, client_context, client_lifecycle, entity_mutations, query_audit).
E2: migrate raw pool.Exec queries to sqlc (entities/relationships queries + generated).
E3: unify SSH — consolidate crypto/ssh dial into actuator/client.go (+client_test).
E4/E5: add tests — db/lifecycle, checkdefaults/build, ontology/preconditions, policy/risk.

internal/db/lifecycle.go

@@ -5,7 +5,6 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"strings"
 
 	"github.com/dtoro/oikos/internal/db/sqlcgen"
 	"github.com/google/uuid"
@@ -79,35 +78,35 @@ func checkPrecondition(ctx context.Context, tx pgx.Tx, entityID uuid.UUID, entit
 			return fmt.Errorf("%d inbound relationship edges remaining", count)
 		}
 	case "backups-verified", "secrets-revoked", "ingress-dns-removed":
-		var attrs string
-		if err := tx.QueryRow(ctx, "SELECT coalesce(attributes::text,'{}') FROM entities WHERE id = $1", entityID).Scan(&attrs); err != nil {
+		attrs, err := fetchAttrs(ctx, tx, entityID)
+		if err != nil {
 			return err
 		}
 		want := map[string]string{
-			"backups-verified":   "backups_verified",
-			"secrets-revoked":    "secrets_revoked",
+			"backups-verified":    "backups_verified",
+			"secrets-revoked":     "secrets_revoked",
 			"ingress-dns-removed": "ingress_dns_removed",
 		}[check]
-		if !strings.Contains(attrs, want) {
+		if !attrTruthy(attrs, want) {
 			return fmt.Errorf("%s not recorded in entity attributes", want)
 		}
 	case "age-key-enrolled-if-needed":
 		if entityType == "workstation" {
-			var attrs string
-			if err := tx.QueryRow(ctx, "SELECT coalesce(attributes::text,'{}') FROM entities WHERE id = $1", entityID).Scan(&attrs); err != nil {
+			attrs, err := fetchAttrs(ctx, tx, entityID)
+			if err != nil {
 				return err
 			}
-			if !strings.Contains(attrs, "age_pubkey") {
+			if !attrTruthy(attrs, "age_pubkey") {
 				return fmt.Errorf("age key not enrolled (no age_pubkey in attributes)")
 			}
 		}
 	case "mesh-joined-if-needed":
 		if entityType == "workstation" {
-			var attrs string
-			if err := tx.QueryRow(ctx, "SELECT coalesce(attributes::text,'{}') FROM entities WHERE id = $1", entityID).Scan(&attrs); err != nil {
+			attrs, err := fetchAttrs(ctx, tx, entityID)
+			if err != nil {
 				return err
 			}
-			if !strings.Contains(attrs, "mesh_ip") {
+			if !attrTruthy(attrs, "mesh_ip") {
 				return fmt.Errorf("mesh not joined (no mesh_ip in attributes)")
 			}
 		}
@@ -144,3 +143,40 @@ func checkPrecondition(ctx context.Context, tx pgx.Tx, entityID uuid.UUID, entit
 	}
 	return nil
 }
+
+// fetchAttrs loads an entity's JSONB attributes column as a decoded map.
+// Missing attributes decode to an empty map (every key absent).
+func fetchAttrs(ctx context.Context, tx pgx.Tx, entityID uuid.UUID) (map[string]any, error) {
+	var raw string
+	if err := tx.QueryRow(ctx, "SELECT coalesce(attributes::text,'{}') FROM entities WHERE id = $1", entityID).Scan(&raw); err != nil {
+		return nil, err
+	}
+	var attrs map[string]any
+	if err := json.Unmarshal([]byte(raw), &attrs); err != nil {
+		return nil, fmt.Errorf("decode entity attributes: %w", err)
+	}
+	if attrs == nil {
+		attrs = map[string]any{}
+	}
+	return attrs, nil
+}
+
+// attrTruthy reports whether key is present in attrs with a meaningful value.
+// It replaces substring matching on raw JSONB text: a previous strings.Contains
+// check treated {"backups_verified": false} as satisfied (the key text was
+// present) and bypassed the attributes GIN index. Booleans must be true;
+// strings must be non-empty; nil/absent fail.
+func attrTruthy(attrs map[string]any, key string) bool {
+	v, ok := attrs[key]
+	if !ok || v == nil {
+		return false
+	}
+	switch t := v.(type) {
+	case bool:
+		return t
+	case string:
+		return t != ""
+	default:
+		return true // numbers, objects, arrays count as present
+	}
+}

internal/db/lifecycle_test.go

@@ -0,0 +1,55 @@
+package db
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// attrTruthy replaces a previous strings.Contains check over raw JSONB text.
+// The key regression it guards: a literal attribute like
+// {"backups_verified": false} must NOT satisfy the "backups-verified"
+// precondition, even though the key text is present in the column.
+func TestAttrTruthy(t *testing.T) {
+	cases := []struct {
+		name  string
+		attrs map[string]any
+		key   string
+		want  bool
+	}{
+		{"absent", map[string]any{}, "backups_verified", false},
+		{"nil map", nil, "backups_verified", false},
+		{"explicit nil value", map[string]any{"backups_verified": nil}, "backups_verified", false},
+		{"bool true", map[string]any{"backups_verified": true}, "backups_verified", true},
+		{"bool false is the regression case", map[string]any{"backups_verified": false}, "backups_verified", false},
+		{"nonempty string age pubkey", map[string]any{"age_pubkey": "age1abc"}, "age_pubkey", true},
+		{"empty string is falsy", map[string]any{"mesh_ip": ""}, "mesh_ip", false},
+		{"number counts as present", map[string]any{"port": float64(22)}, "port", true},
+		{"other keys present", map[string]any{"backups_verified": true, "unrelated": "x"}, "backups_verified", true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := attrTruthy(tc.attrs, tc.key); got != tc.want {
+				t.Fatalf("attrTruthy(%v, %q) = %v, want %v", tc.attrs, tc.key, got, tc.want)
+			}
+		})
+	}
+}
+
+// fetchAttrs decodes the JSONB column text; verify the decode shape that
+// attrTruthy then evaluates (the DB round-trip itself is covered by make test-db).
+func TestAttrTruthyAfterDecode(t *testing.T) {
+	raw := `{"backups_verified": true, "mesh_ip": "10.0.0.5", "secrets_revoked": false}`
+	var got map[string]any
+	if err := json.Unmarshal([]byte(raw), &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if !attrTruthy(got, "backups_verified") {
+		t.Error("backups_verified should be truthy after decode")
+	}
+	if !attrTruthy(got, "mesh_ip") {
+		t.Error("mesh_ip should be truthy after decode")
+	}
+	if attrTruthy(got, "secrets_revoked") {
+		t.Error("secrets_revoked:false is the regression — must be falsy")
+	}
+}

internal/db/queries/entities.sql

@@ -44,6 +44,36 @@ UPDATE entities SET
 WHERE id = sqlc.arg('id') AND version = sqlc.arg('version')
 RETURNING *;
 
+-- name: MergeEntityAttributes :execrows
+-- Shallow-merge a JSON patch into an entity's attributes (the
+-- update_entity_attributes MCP/HTTP surface). Replaces the raw
+-- `attributes = attributes || $2::jsonb` used in entity_tools.go.
+UPDATE entities SET
+    attributes = attributes || sqlc.arg('patch')::jsonb,
+    updated_at = now()
+WHERE slug = sqlc.arg('slug');
+
+-- name: SetEntityState :execrows
+-- Set an entity's lifecycle state by id (the set_entity_state surface, run
+-- after db.ValidateTransition). Replaces the raw
+-- `UPDATE entities SET state = $2 ... WHERE id = $1`.
+UPDATE entities SET
+    state = sqlc.arg('state'),
+    updated_at = now()
+WHERE id = sqlc.arg('id');
+
 -- blast_radius(): the recursive-CTE traversal function's TABLE return type
 -- is opaque to sqlc's analyzer — that one query stays hand-written pgx in
--- internal/httpapi (see impl.go).
+-- internal/httpapi (see entities.go GetBlastRadius).
+--
+-- Deliberate raw-SQL exceptions (plan E2): the httpapi entity *read* handlers
+-- (ListEntities/GetEntity/GetGraph/queryEntities) project a fixed
+-- `entityCols` column set (entities.* + a LEFT JOIN to entity_status for
+-- health/last_check_at) and scan it positionally into the oapi-generated
+-- gen.Entity shape. sqlc generates its own row struct per query and cannot
+-- emit gen.Entity, so migrating those reads would add a per-call field-by-
+-- field mapping with no compile-time gain and real column-order risk. They
+-- stay hand-written pgx, like blast_radius and the seed/export bulk paths
+-- noted in sqlc.yaml. The mutation/relationship surface (MergeEntityAttributes,
+-- SetEntityState, InsertRelationshipIfAbsent, EndCurrentRelationship) IS
+-- migrated and is what the entity CRUD tools now call.

internal/db/queries/relationships.sql

@@ -25,3 +25,18 @@ ORDER BY r.type, se.slug, te.slug;
 -- name: EndCurrentRelationship :execrows
 UPDATE relationships SET valid_to = now()
 WHERE source_id = $1 AND target_id = $2 AND type = $3 AND valid_to IS NULL;
+
+-- name: InsertRelationshipIfAbsent :execrows
+-- Idempotent relationship insert (the create_relationship surface): no-op if
+-- an active edge of the same source/target/type already exists. Replaces the
+-- raw INSERT...WHERE NOT EXISTS used in entity_tools.go.
+INSERT INTO relationships (source_id, target_id, type, attributes, valid_from)
+SELECT sqlc.arg('source_id'), sqlc.arg('target_id'), sqlc.arg('type'),
+       sqlc.arg('attributes')::jsonb, now()
+WHERE NOT EXISTS (
+    SELECT 1 FROM relationships
+    WHERE source_id = sqlc.arg('source_id')
+      AND target_id = sqlc.arg('target_id')
+      AND type = sqlc.arg('type')
+      AND valid_to IS NULL
+);

internal/db/sqlcgen/entities.sql.go

@@ -177,6 +177,52 @@ func (q *Queries) ListEntities(ctx context.Context, arg ListEntitiesParams) ([]E
 	return items, nil
 }
 
+const mergeEntityAttributes = `-- name: MergeEntityAttributes :execrows
+UPDATE entities SET
+    attributes = attributes || $1::jsonb,
+    updated_at = now()
+WHERE slug = $2
+`
+
+type MergeEntityAttributesParams struct {
+	Patch []byte
+	Slug  string
+}
+
+// Shallow-merge a JSON patch into an entity's attributes (the
+// update_entity_attributes MCP/HTTP surface). Replaces the raw
+// `attributes = attributes || $2::jsonb` used in entity_tools.go.
+func (q *Queries) MergeEntityAttributes(ctx context.Context, arg MergeEntityAttributesParams) (int64, error) {
+	result, err := q.db.Exec(ctx, mergeEntityAttributes, arg.Patch, arg.Slug)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
+const setEntityState = `-- name: SetEntityState :execrows
+UPDATE entities SET
+    state = $1,
+    updated_at = now()
+WHERE id = $2
+`
+
+type SetEntityStateParams struct {
+	State *string
+	ID    uuid.UUID
+}
+
+// Set an entity's lifecycle state by id (the set_entity_state surface, run
+// after db.ValidateTransition). Replaces the raw
+// `UPDATE entities SET state = $2 ... WHERE id = $1`.
+func (q *Queries) SetEntityState(ctx context.Context, arg SetEntityStateParams) (int64, error) {
+	result, err := q.db.Exec(ctx, setEntityState, arg.State, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
 const updateEntity = `-- name: UpdateEntity :one
 UPDATE entities SET
     name = COALESCE($1, name),

internal/db/sqlcgen/relationships.sql.go

@@ -31,6 +31,42 @@ func (q *Queries) EndCurrentRelationship(ctx context.Context, arg EndCurrentRela
 	return result.RowsAffected(), nil
 }
 
+const insertRelationshipIfAbsent = `-- name: InsertRelationshipIfAbsent :execrows
+INSERT INTO relationships (source_id, target_id, type, attributes, valid_from)
+SELECT $1, $2, $3,
+       $4::jsonb, now()
+WHERE NOT EXISTS (
+    SELECT 1 FROM relationships
+    WHERE source_id = $1
+      AND target_id = $2
+      AND type = $3
+      AND valid_to IS NULL
+)
+`
+
+type InsertRelationshipIfAbsentParams struct {
+	SourceID   uuid.UUID
+	TargetID   uuid.UUID
+	Type       string
+	Attributes []byte
+}
+
+// Idempotent relationship insert (the create_relationship surface): no-op if
+// an active edge of the same source/target/type already exists. Replaces the
+// raw INSERT...WHERE NOT EXISTS used in entity_tools.go.
+func (q *Queries) InsertRelationshipIfAbsent(ctx context.Context, arg InsertRelationshipIfAbsentParams) (int64, error) {
+	result, err := q.db.Exec(ctx, insertRelationshipIfAbsent,
+		arg.SourceID,
+		arg.TargetID,
+		arg.Type,
+		arg.Attributes,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
 const listEntityRelations = `-- name: ListEntityRelations :many
 SELECT se.slug AS source_slug, te.slug AS target_slug, r.type, r.attributes,
        r.valid_from, r.valid_to