@happyvertical/smrt-personas 0.38.19 → 0.38.21

package/dist/smrt-knowledge.json

@@ -1,26 +1,35 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-09T02:02:38.275Z",
+  "generatedAt": "2026-07-09T07:04:06.074Z",
   "packageName": "@happyvertical/smrt-personas",
-  "packageVersion": "0.38.19",
+  "packageVersion": "0.38.21",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "94c1c2b447f941e2fa424248a3730976d46141366b5bb6bee4234dd4c0fae506",
-    "packageJson": "57b89b69bd4bc4eefb41852706f1aaa4c9c0d4af1608357a0bebd9112af92ba2",
-    "agents": "ef998dbc563d3d2905c694cd77a99576a6fd2d16d10f675014dbbe9aec1cbf5f"
+    "manifest": "7c20bd9c814a3deef5c573d56a172f40cb6dd594baaa40f2e4b8fd36d56c0d8b",
+    "packageJson": "7fd08960eca95f18b7b58e209e56fae1b46365531551cbb6212a935dbbbdf35c",
+    "agents": "f35cdbfeae2e2235818031815c55c24c59eebbacc3aec00406f079d0f990abd3"
   },
   "exports": [
     ".",
     "./manifest",
-    "./manifest.json"
+    "./manifest.json",
+    "./svelte"
   ],
   "dependencies": {
     "@happyvertical/smrt-agents": "workspace:*",
     "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-prompts": "workspace:*",
     "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
+    "@happyvertical/sql": "catalog:",
     "@happyvertical/smrt-vitest": "workspace:*",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@types/node": "24.13.2",
+    "svelte": "^5.56.4",
+    "svelte-check": "^4.7.1",
     "typescript": "^5.9.3",
     "vite": "^8.1.3",
     "vitest": "^4.1.9"
@@ -28,10 +37,15 @@
   "smrtDependencies": [
     "@happyvertical/smrt-agents",
     "@happyvertical/smrt-core",
+    "@happyvertical/smrt-prompts",
     "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-ui",
+    "@happyvertical/smrt-users",
     "@happyvertical/smrt-vitest"
   ],
-  "sdkDependencies": [],
+  "sdkDependencies": [
+    "@happyvertical/sql"
+  ],
   "tags": [],
   "risks": [],
   "objects": [
@@ -230,6 +244,408 @@
       ],
       "tags": [],
       "risks": []
+    },
+    {
+      "name": "DirectiveProposal",
+      "qualifiedName": "@happyvertical/smrt-personas:DirectiveProposal",
+      "collection": "directiveproposals",
+      "tableName": "directive_proposals",
+      "packageName": "@happyvertical/smrt-personas",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "personaId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgentPersona",
+          "columnType": "UUID"
+        },
+        {
+          "name": "agentClass",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "promptKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "proposedInstructions",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "currentInstructions",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "rationale",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "evidence",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "fingerprint",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "confidence",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "proposedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reviewedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reviewedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "reviewNote",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "activatedOverrideId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "personaId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgentPersona",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "getEvidence",
+        "isPending",
+        "setEvidence"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "directiveproposals.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:DirectiveProposal",
+          "path": "/directiveproposals",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "directiveproposals.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:DirectiveProposal",
+          "path": "/directiveproposals/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "directiveproposal_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+        },
+        {
+          "kind": "cli",
+          "name": "directiveproposal_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+        },
+        {
+          "kind": "mcp",
+          "name": "directiveproposal_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+        },
+        {
+          "kind": "mcp",
+          "name": "directiveproposal_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "DirectiveProposalCollection",
+      "qualifiedName": "@happyvertical/smrt-personas:DirectiveProposalCollection",
+      "collection": "directiveproposals",
+      "tableName": "directive_proposals",
+      "packageName": "@happyvertical/smrt-personas",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByFingerprint",
+        "pending"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "Feedback",
+      "qualifiedName": "@happyvertical/smrt-personas:Feedback",
+      "collection": "feedbacks",
+      "tableName": "agent_feedback",
+      "packageName": "@happyvertical/smrt-personas",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "personaId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgentPersona",
+          "columnType": "UUID"
+        },
+        {
+          "name": "agentClass",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "memoryScope",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "scope",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "key",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "signalType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "source",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "correlationId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "correlationType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "rating",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "metric",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "success",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN"
+        },
+        {
+          "name": "correction",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "comment",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "metadata",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reinforcedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "personaId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "AgentPersona",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "getCorrectionValue",
+        "getMetadata",
+        "isHuman",
+        "setMetadata",
+        "toLearningOutcome",
+        "updateMetadata"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "feedbacks.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:Feedback",
+          "path": "/feedbacks",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "feedbacks.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:Feedback",
+          "path": "/feedbacks/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "feedbacks.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-personas:Feedback",
+          "path": "/feedbacks",
+          "method": "POST"
+        },
+        {
+          "kind": "cli",
+          "name": "feedback_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:Feedback"
+        },
+        {
+          "kind": "cli",
+          "name": "feedback_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:Feedback"
+        },
+        {
+          "kind": "mcp",
+          "name": "feedback_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-personas:Feedback"
+        },
+        {
+          "kind": "mcp",
+          "name": "feedback_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-personas:Feedback"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FeedbackCollection",
+      "qualifiedName": "@happyvertical/smrt-personas:FeedbackCollection",
+      "collection": "feedbacks",
+      "tableName": "agent_feedback",
+      "packageName": "@happyvertical/smrt-personas",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "byCorrelation",
+        "forPersona",
+        "forScope"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
     }
   ],
   "surfaces": [
@@ -296,16 +712,108 @@
       "name": "agentpersona_get",
       "operation": "get",
       "objectName": "@happyvertical/smrt-personas:AgentPersona"
+    },
+    {
+      "kind": "api",
+      "name": "directiveproposals.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:DirectiveProposal",
+      "path": "/directiveproposals",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "directiveproposals.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:DirectiveProposal",
+      "path": "/directiveproposals/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "directiveproposal_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+    },
+    {
+      "kind": "cli",
+      "name": "directiveproposal_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+    },
+    {
+      "kind": "mcp",
+      "name": "directiveproposal_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+    },
+    {
+      "kind": "mcp",
+      "name": "directiveproposal_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:DirectiveProposal"
+    },
+    {
+      "kind": "api",
+      "name": "feedbacks.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:Feedback",
+      "path": "/feedbacks",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "feedbacks.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:Feedback",
+      "path": "/feedbacks/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "feedbacks.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-personas:Feedback",
+      "path": "/feedbacks",
+      "method": "POST"
+    },
+    {
+      "kind": "cli",
+      "name": "feedback_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:Feedback"
+    },
+    {
+      "kind": "cli",
+      "name": "feedback_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:Feedback"
+    },
+    {
+      "kind": "mcp",
+      "name": "feedback_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-personas:Feedback"
+    },
+    {
+      "kind": "mcp",
+      "name": "feedback_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-personas:Feedback"
+    }
+  ],
+  "prompts": [
+    {
+      "filePath": "src/persona-prompt.ts"
     }
   ],
-  "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 0,
+    "foreignKeyFields": 2,
     "crossPackageRefFields": 2,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 5
+    "uuidColumns": 13
   },
-  "agentDoc": "# @happyvertical/smrt-personas\n\nTenant-owned, context-scoped agent personas and their resolution. Layers over\n`@happyvertical/smrt-agents`' `TenantAgent` availability/ceiling gate to decide\n*how* an agent behaves for a given tenant and context (its `TenantAgent` binding\ndecides *whether* it runs and caps its capabilities).\n\nThis is the L2 foundation of the \"learning agents\" epic (#1885). Foundation\nonly: `AgentPersona` + `PersonaResolver`. `ExecuteAsPrincipal`, feedback, the\nreflection runner, and multi-instance routing are separate issues\n(#1888/#1889/#1890).\n\n## Models\n\n- **AgentPersona** (`@TenantScoped({ mode: 'required' })`, table `agent_personas`):\n  a behavioral profile for one agent class within one tenant. Many per\n  `(tenant, agentClass)`; unique on `(tenant_id, agent_class, name)` via\n  `conflictColumns`. Fields:\n  - `agentClass` — canonical qualified agent type (e.g.\n    `@happyvertical/smrt-agents:Praeco`); stored canonical so it lines up with\n    `TenantAgent.agentClass`.\n  - `name` — persona name, unique per `(tenant, agentClass)`.\n  - `contextType` / `contextId` — optional scoping. No `contextType` = a\n    tenant-wide default; `contextType` only = type-scoped; both = exact context.\n  - `instructions` — system prompt layered onto the agent.\n  - `allowedTools` — JSON array of tool ids stored as a string; use\n    `getAllowedTools()` / `setAllowedTools()` (tolerant `try/catch` parse).\n  - `runAsUserId` — `@crossPackageRef('@happyvertical/smrt-users:User')`, the\n    principal the persona runs as.\n  - `actsAsProfileId` — optional `@crossPackageRef('@happyvertical/smrt-profiles:Profile')`,\n    a `Bot` identity for audit/attribution.\n  - `memoryScope` — memory/reflection partition key (empty → resolver-derived).\n  - `priority` — integer; higher wins among personas that apply at the same\n    tenant level.\n  - `enabled` — boolean; only enabled personas are resolved.\n\n## Collection\n\n`AgentPersonaCollection`:\n\n- `byTenantAndClass(tenantId, agentClass)` — all personas for the pair\n  (canonicalized), ordered by descending priority then name.\n- `findActive(tenantId, agentClass, context?)` — enabled personas applicable to\n  a context, same ordering.\n\n## PersonaResolver\n\n`resolve(tenantId, agentClass, context, options) → ResolvedPersona` layers,\nbottom to top: **manifest defaults → `TenantAgent` gate/ceiling → AgentPersona**.\n\n- **Hierarchy inheritance** mirrors `TenantAgentCollection.resolveForTenant`:\n  walks the requesting tenant then its ancestors (`options.getAncestorIds`,\n  nearest first). The nearest level with any applicable persona wins (a closer\n  level shadows a farther one).\n- **Selection within a level**: most context-specific first\n  (exact > type-scoped > tenant-wide), then highest `priority`, then name.\n- **Ceiling**: `options.availability` (a `PersonaAvailabilityGate`) gates\n  availability and intersects the resolved `allowedTools`. Build one from a\n  `ResolvedAgentAvailability` with `availabilityFromResolvedAgent()`.\n- **Default fallback**: when no persona applies, returns a defined default\n  (`source: 'default'`, `name: 'default'`) from manifest defaults + the gate.\n\nBecause the walk reads personas across tenants, `resolve()` is intended for a\nsystem/admin path where cross-tenant reads are allowed — not inside a strict\nper-tenant interceptor context (same expectation as `resolveForTenant`).\n\n## Dependencies\n\nLeaf package (acyclic by construction — nothing depends back on it):\n\n- Runtime: `@happyvertical/smrt-core`, `@happyvertical/smrt-tenancy`,\n  `@happyvertical/smrt-agents` (the `TenantAgent` type it bridges).\n- `runAsUserId` / `actsAsProfileId` reference `@happyvertical/smrt-users` and\n  `@happyvertical/smrt-profiles` via `@crossPackageRef` string ids only — no\n  package edge (keeps the DAG minimal). No inter-`smrt-*` `peerDependencies`.\n\n## Gotchas\n\n- **`conflictColumns` replaces the default `(slug, context)` unique index** — the\n  unique key is `(tenant_id, agent_class, name)`, so same-named personas across\n  tenants are allowed and tenant isolation is preserved.\n- **`allowedTools` is text, not `type: 'json'`** — stored as a JSON string and\n  read through the helpers, so it never auto-hydrates to an object.\n- **Resolver runs outside strict tenant context** — it deliberately crosses\n  tenants to walk the hierarchy.\n"
+  "agentDoc": "# @happyvertical/smrt-personas\n\nTenant-owned, context-scoped agent personas and their resolution. Layers over\n`@happyvertical/smrt-agents`' `TenantAgent` availability/ceiling gate to decide\n*how* an agent behaves for a given tenant and context (its `TenantAgent` binding\ndecides *whether* it runs and caps its capabilities).\n\nThis is the L2 layer of the \"learning agents\" epic (#1885): the persona foundation\n(`AgentPersona` + `PersonaResolver`), the **persona learning & adaptation loop**\n(#1889) — feedback → confidence-scored reinforcement → a scheduled reflection\nrunner that emits pending directive proposals → a permission-gated approval\nsurface that activates an approved rewrite as a tenant/persona-scoped prompt\noverride — and the persona-as-durable-instance / multi-instance helpers (#1890,\nbelow). `ExecuteAsPrincipal` remains a separate issue (#1888).\n\n## Models\n\n- **AgentPersona** (`@TenantScoped({ mode: 'required' })`, table `agent_personas`):\n  a behavioral profile for one agent class within one tenant. Many per\n  `(tenant, agentClass)`; unique on `(tenant_id, agent_class, name)` via\n  `conflictColumns`. Fields:\n  - `agentClass` — canonical qualified agent type (e.g.\n    `@happyvertical/smrt-agents:Praeco`); stored canonical so it lines up with\n    `TenantAgent.agentClass`.\n  - `name` — persona name, unique per `(tenant, agentClass)`.\n  - `contextType` / `contextId` — optional scoping. No `contextType` = a\n    tenant-wide default; `contextType` only = type-scoped; both = exact context.\n  - `instructions` — system prompt layered onto the agent.\n  - `allowedTools` — JSON array of tool ids stored as a string; use\n    `getAllowedTools()` / `setAllowedTools()` (tolerant `try/catch` parse).\n  - `runAsUserId` — `@crossPackageRef('@happyvertical/smrt-users:User')`, the\n    principal the persona runs as.\n  - `actsAsProfileId` — optional `@crossPackageRef('@happyvertical/smrt-profiles:Profile')`,\n    a `Bot` identity for audit/attribution.\n  - `memoryScope` — memory/reflection partition key (empty → resolver-derived).\n  - `priority` — integer; higher wins among personas that apply at the same\n    tenant level.\n  - `enabled` — boolean; only enabled personas are resolved.\n\n- **Feedback** (`@TenantScoped({ mode: 'optional' })`, table `agent_feedback`):\n  one reinforcement signal against a persona and the learning episode it judges.\n  Human signals (`accept` / `reject` / `correction` / `rating`) and autonomous\n  signals (`outcome` / `metric`) each carry a required **`correlationId`** (+\n  optional `correlationType`) back to the AI call / dispatch / job. `scope` /\n  `key` name the `LearningMemory` episode; `toLearningOutcome()` maps the signal\n  onto a `LearningOutcome` (feeds reinforcement, #1886). `FeedbackCollection`:\n  `forPersona`, `forScope`, `byCorrelation`.\n\n- **DirectiveProposal** (`@TenantScoped({ mode: 'required' })`, table\n  `directive_proposals`): a pending, human-reviewable proposed edit to a\n  persona's `instructions`. Read-only generated surface (`api`/`cli`/`mcp` =\n  `list`/`get`) — writes go through the gated approval service, not CRUD. Key\n  fields: `promptKey`, `proposedInstructions`, `currentInstructions` (diff),\n  `rationale`, `evidence` (JSON: episode + feedback ids), `status`\n  (`pending`/`approved`/`rejected`/`superseded`), `fingerprint` (dedup so a\n  rejected rewrite is never re-surfaced), `proposedBy`, `reviewedBy` /\n  `reviewedAt` / `activatedOverrideId`. `DirectiveProposalCollection`:\n  `pending(...)` (the review queue), `findByFingerprint(...)`.\n\n## Learning loop (#1889)\n\n- **Persona instructions via prompt overrides** (`persona-prompt.ts`): a\n  persona's instructions apply through a per-persona registered prompt key\n  (`persona.<id>.instructions`, neutral empty base template) plus a\n  tenant-scoped `prompt_override`. Two personas of the same tenant/class resolve\n  different instructions without colliding on the override `(key, context)`\n  identity. `ensurePersonaInstructionsPrompt` (idempotent registration,\n  `editable` configurable), `applyPersonaInstructions` /\n  `upsertPromptTemplateOverride` (write the override — flows through\n  `PromptOverride.save()` → `validatePromptOverride`, so a non-editable template\n  is refused), `resolvePersonaInstructions`.\n- **Memory scoping** (`persona-memory.ts`): `personaLearningMemory` routes a\n  `LearningMemory` by the persona's `memoryScope` (used as `owner_id`), so\n  personas learn independently. `reinforceFromFeedback` applies a `Feedback`\n  signal to memory as automatic, confidence-only reinforcement (ungated).\n- **ReflectionRunner** (`reflection-runner.ts`): a schedulable pass that, under\n  the autonomous reflection principal (which **lacks**\n  `personas.activate-directive`), reinforces recent feedback, consolidates\n  episodes + feedback via an injected `reflect` boundary (the AI call, mocked in\n  tests), and records a **pending** `DirectiveProposal` (deduped by fingerprint).\n  It cannot activate anything.\n- **The gate = a permission split** (`directive-principal.ts`,\n  `directive-approval.ts`): activating a directive is the permissioned operation\n  `personas.activate-directive` (contributed to the manifest permission catalog\n  via `registerPermissionDefinitions`). `DirectiveApprovalService.approve` /\n  `reject` first `assertCanActivate(principal)`; approval writes the\n  persona-scoped override and records an `accept` signal, rejection records a\n  `reject` signal and closes the proposal. A `DirectivePrincipal` is built from\n  granted slugs (`principalFromPermissions`) or a `PermissionResolver`\n  (`resolveDirectivePrincipal`).\n\n## Svelte UI\n\n`@happyvertical/smrt-personas/svelte` ships a minimal, presentational\n`DirectiveReviewQueue` component (Svelte 5): it lists pending proposals with a\ncurrent-vs-proposed diff and Approve/Reject actions, delegating to `onApprove`\n(optionally with reviewer-edited text) / `onReject` callbacks a host wires to\nthe gated `DirectiveApprovalService`. Built with `svelte-package`; Svelte tests\nrun in CI only.\n\n## Collection\n\n`AgentPersonaCollection`:\n\n- `byTenantAndClass(tenantId, agentClass)` — all personas for the pair\n  (canonicalized), ordered by descending priority then name.\n- `findActive(tenantId, agentClass, context?)` — enabled personas applicable to\n  a context, same ordering.\n\n## PersonaResolver\n\n`resolve(tenantId, agentClass, context, options) → ResolvedPersona` layers,\nbottom to top: **manifest defaults → `TenantAgent` gate/ceiling → AgentPersona**.\n\n- **Hierarchy inheritance** mirrors `TenantAgentCollection.resolveForTenant`:\n  walks the requesting tenant then its ancestors (`options.getAncestorIds`,\n  nearest first). The nearest level with any applicable persona wins (a closer\n  level shadows a farther one).\n- **Selection within a level**: most context-specific first\n  (exact > type-scoped > tenant-wide), then highest `priority`, then name.\n- **Ceiling**: `options.availability` (a `PersonaAvailabilityGate`) gates\n  availability and intersects the resolved `allowedTools`. Build one from a\n  `ResolvedAgentAvailability` with `availabilityFromResolvedAgent()`.\n- **Default fallback**: when no persona applies, returns a defined default\n  (`source: 'default'`, `name: 'default'`) from manifest defaults + the gate.\n\nBecause the walk reads personas across tenants, `resolve()` is intended for a\nsystem/admin path where cross-tenant reads are allowed — not inside a strict\nper-tenant interceptor context (same expectation as `resolveForTenant`).\n\n## Persona as Durable Instance (#1890)\n\nA persona is a **durable instance** of an agent class — N per tenant, each\nindependently scheduled, memory-scoped, and permission-scoped. `persona-instance.ts`\nwires that to the `@happyvertical/smrt-agents` multi-instance primitives (which are\nper-package opt-in via `static multiInstance`, singleton by default):\n\n- **Identity** — `personaInstanceKey(persona)` returns the persona id, or `null`\n  for the `default` persona (`DEFAULT_PERSONA_NAME`). A `null` key reuses the\n  **singleton** runtime identity (class-keyed dispatch subscriber + un-suffixed\n  memory scope). `agentOptionsForPersona(persona)` projects `{ instanceKey,\n  tenantId }` to spread into the agent constructor.\n- **Scheduling** — `schedulePersonaInstance(schedules, persona, { cron, … })`\n  creates an `AgentSchedule` for the instance. The instance key rides in\n  `agentConfig` (which the scheduler spreads into the agent constructor →\n  `AgentOptions.instanceKey`); `agentId` is left **null** on purpose, because the\n  scheduler copies `agentId`→`SmrtJob.objectId` and the `TaskRunner`\n  `loadFromId()`s it against the agent's STI table — a persona id is not a row\n  there. The default persona carries no key → runs the singleton.\n- **Admin** — `buildPersonaInstanceAdmin(personas, { tenantId, agentClass,\n  manifest })` renders the class's `uiSlots`/`adminRoutes` **once per instance**\n  (with the per-instance dispatch subscriber); `addPersonaInstance()` /\n  `removePersonaInstance(personaId)` are the add/remove affordances.\n- **Non-destructive upgrade** — `upgradeSingletonToDefaultPersona(personas, {\n  tenantId, agentClass, runAsUserId, … })` maps an existing singleton to a single\n  `default` persona. It's null-keyed, so the running agent's dispatch subscriber,\n  memory, and config are untouched; idempotent (a second call returns the\n  existing default with `created: false` and never overwrites it).\n\n## Dependencies\n\nLeaf package (acyclic by construction — nothing depends back on it):\n\n- Runtime: `@happyvertical/smrt-core`, `@happyvertical/smrt-tenancy`,\n  `@happyvertical/smrt-agents` (the `TenantAgent` type it bridges, plus the\n  `AgentSchedule`/multi-instance surface `persona-instance.ts` builds on),\n  `@happyvertical/smrt-prompts` (persona instructions via `PromptOverride` +\n  `resolvePrompt`), `@happyvertical/smrt-users` (the permission catalog slug +\n  `PermissionResolver` principal), and `@happyvertical/sql` (`DatabaseInterface`\n  type). These edges are all acyclic (none of those packages depend on personas).\n- Svelte peer + `@happyvertical/smrt-ui` for the optional `./svelte` review-queue\n  component.\n- `runAsUserId` / `actsAsProfileId` reference `@happyvertical/smrt-users` and\n  `@happyvertical/smrt-profiles` via `@crossPackageRef` string ids only. No\n  inter-`smrt-*` `peerDependencies`.\n\n## Gotchas\n\n- **`conflictColumns` replaces the default `(slug, context)` unique index** — the\n  unique key is `(tenant_id, agent_class, name)`, so same-named personas across\n  tenants are allowed and tenant isolation is preserved.\n- **`allowedTools` is text, not `type: 'json'`** — stored as a JSON string and\n  read through the helpers, so it never auto-hydrates to an object.\n- **Resolver runs outside strict tenant context** — it deliberately crosses\n  tenants to walk the hierarchy.\n- **The gate is the permission split, not a bespoke check** — the reflection\n  principal simply lacks `personas.activate-directive`, so it can only propose;\n  everything privileged in `DirectiveApprovalService` calls `assertCanActivate`\n  first. Instruction rewrites are gated; confidence-only reinforcement is not.\n- **Persona instructions live in the override layer, not the base prompt** — the\n  per-persona prompt key registers a neutral empty template, so re-registration\n  stays idempotent as instructions change; the tenant-scoped override carries the\n  actual text. Activation still honours `validatePromptOverride` editability.\n- **Directive dedup is by fingerprint across all statuses** — the runner skips a\n  proposal whose `(personaId, promptKey, proposedInstructions)` fingerprint\n  already exists (pending, approved, or rejected), so a rejected rewrite is never\n  re-surfaced.\n"
 }