@happyvertical/smrt-approvals 0.0.0-stage → 0.55.10

package/dist/smrt-knowledge.json

@@ -0,0 +1,751 @@
+{
+  "schemaVersion": 1,
+  "sensitiveFieldsExcluded": true,
+  "generatedAt": "1970-01-01T00:00:00.000Z",
+  "packageName": "@happyvertical/smrt-approvals",
+  "packageVersion": "0.55.10",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "ba2e1a9554601128ca9027f1502d3a226c7803cb8a3a00d4c2bac857a5f16b95",
+    "packageJson": "964faf5a4547cdfe20bb134652a70ac18148d74e2b391190c83c7b970fa0ac97",
+    "agents": "d79f62b8c882c0d39aa6d1e2b9c56b4d58bc9270ce4bc656f7ead5df37a275fc",
+    "moduleDoc:agents/approvals.md": "9f5a3a2332617e4e9acd7014c9ffa30d3a5391f4dcf0e0cb8b9df4f824576961"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json"
+  ],
+  "dependencies": {
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@types/node": "24.13.6",
+    "typescript": "6.0.3",
+    "vite": "8.1.4",
+    "vitest": "4.1.10"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-users",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/sql"
+  ],
+  "tags": [
+    "approvals",
+    "audit",
+    "cross-package",
+    "multi-tenant",
+    "quorum",
+    "smrt",
+    "workflow"
+  ],
+  "risks": [
+    "sensitive-fields-excluded"
+  ],
+  "objects": [
+    {
+      "name": "ApprovalEventCollection",
+      "qualifiedName": "@happyvertical/smrt-approvals:ApprovalEventCollection",
+      "collection": "approvalevents",
+      "tableName": "approval_events",
+      "packageName": "@happyvertical/smrt-approvals",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ApprovalPolicyCollection",
+      "qualifiedName": "@happyvertical/smrt-approvals:ApprovalPolicyCollection",
+      "collection": "approvalpolicies",
+      "tableName": "approval_policies",
+      "packageName": "@happyvertical/smrt-approvals",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ApprovalRequestCollection",
+      "qualifiedName": "@happyvertical/smrt-approvals:ApprovalRequestCollection",
+      "collection": "approvalrequests",
+      "tableName": "approval_requests",
+      "packageName": "@happyvertical/smrt-approvals",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ApprovalEvent",
+      "qualifiedName": "@happyvertical/smrt-approvals:ApprovalEvent",
+      "collection": "approvalevents",
+      "description": "One immutable entry in an approval request's history.",
+      "tableName": "approval_events",
+      "packageName": "@happyvertical/smrt-approvals",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "requestId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "ApprovalRequest",
+          "columnType": "UUID"
+        },
+        {
+          "name": "type",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "actorId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "actorType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "reason",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "subjectRevisionHash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "sequence",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "readonly": true
+        },
+        {
+          "name": "voteKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "occurredAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "readonly": true
+        }
+      ],
+      "relationships": [
+        {
+          "name": "requestId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "ApprovalRequest",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "approvalevents.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalEvent",
+          "path": "/approvalevents",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "approvalevents.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalEvent",
+          "path": "/approvalevents/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "mcp",
+          "name": "approvalevent_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalEvent"
+        },
+        {
+          "kind": "mcp",
+          "name": "approvalevent_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalEvent"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalEvent"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ApprovalPolicy",
+      "qualifiedName": "@happyvertical/smrt-approvals:ApprovalPolicy",
+      "collection": "approvalpolicies",
+      "description": "Tenant-level tightening of an approval kind. One row per tenant and kind.",
+      "tableName": "approval_policies",
+      "packageName": "@happyvertical/smrt-approvals",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "requiredApprovals",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "ttlMs",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "requiredPermission",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "updatedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "approvalpolicies.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy",
+          "path": "/approvalpolicies",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "approvalpolicies.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy",
+          "path": "/approvalpolicies/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "mcp",
+          "name": "approvalpolicy_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy"
+        },
+        {
+          "kind": "mcp",
+          "name": "approvalpolicy_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ApprovalRequest",
+      "qualifiedName": "@happyvertical/smrt-approvals:ApprovalRequest",
+      "collection": "approvalrequests",
+      "description": "A request for approval of one subject revision.",
+      "tableName": "approval_requests",
+      "packageName": "@happyvertical/smrt-approvals",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "subjectType",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "subjectId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "subjectRevisionHash",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "requestedBy",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "requestedByType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "summary",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "requiredApprovals",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "readonly": true
+        },
+        {
+          "name": "approvalCount",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "readonly": true
+        },
+        {
+          "name": "requiredPermissions",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        },
+        {
+          "name": "version",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER",
+          "readonly": true
+        },
+        {
+          "name": "expiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "readonly": true
+        },
+        {
+          "name": "decidedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "readonly": true
+        },
+        {
+          "name": "consumedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "readonly": true
+        },
+        {
+          "name": "consumedBy",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "readonly": true
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "delete",
+        "expiresAtMs",
+        "getRequiredPermissions",
+        "isConsumed",
+        "save",
+        "setRequiredPermissions"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "expiresAtMs",
+          "returns": "number"
+        },
+        {
+          "name": "getRequiredPermissions",
+          "returns": "string[]"
+        },
+        {
+          "name": "isConsumed",
+          "returns": "boolean"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "returns": "Promise<this>"
+        },
+        {
+          "name": "setRequiredPermissions",
+          "params": [
+            "slugs: any"
+          ],
+          "returns": "void"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "approvalrequests.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest",
+          "path": "/approvalrequests",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "approvalrequests.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest",
+          "path": "/approvalrequests/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "mcp",
+          "name": "approvalrequest_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+        },
+        {
+          "kind": "mcp",
+          "name": "approvalrequest_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "expiresAtMs",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+        },
+        {
+          "kind": "api",
+          "operation": "getRequiredPermissions",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+        },
+        {
+          "kind": "api",
+          "operation": "isConsumed",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "lifecycle-method",
+          "reason": "`save` is a framework lifecycle method, not a distinct operation",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+        },
+        {
+          "kind": "api",
+          "operation": "setRequiredPermissions",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "approvalevents.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalEvent",
+      "path": "/approvalevents",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "approvalevents.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalEvent",
+      "path": "/approvalevents/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "mcp",
+      "name": "approvalevent_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalEvent"
+    },
+    {
+      "kind": "mcp",
+      "name": "approvalevent_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalEvent"
+    },
+    {
+      "kind": "api",
+      "name": "approvalpolicies.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy",
+      "path": "/approvalpolicies",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "approvalpolicies.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy",
+      "path": "/approvalpolicies/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "mcp",
+      "name": "approvalpolicy_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy"
+    },
+    {
+      "kind": "mcp",
+      "name": "approvalpolicy_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalPolicy"
+    },
+    {
+      "kind": "api",
+      "name": "approvalrequests.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalRequest",
+      "path": "/approvalrequests",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "approvalrequests.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalRequest",
+      "path": "/approvalrequests/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "mcp",
+      "name": "approvalrequest_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+    },
+    {
+      "kind": "mcp",
+      "name": "approvalrequest_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-approvals:ApprovalRequest"
+    }
+  ],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 1,
+    "crossPackageRefFields": 0,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 14
+  },
+  "agentDoc": "# @happyvertical/smrt-approvals\n\nDecision gate plus ledger (slice 1 of #3716): `ApprovalRequest`,\nappend-only `ApprovalEvent`, tighten-only `ApprovalPolicy`, and\n`ApprovalService`, the only write path. Not a workflow engine: no stages, no\nexecutor, no compensation. Read [agents/approvals.md](agents/approvals.md)\nbefore changing a transition, the guard predicates, or the surface.\n\n## Invariants\n\n- Every transition is ONE guarded `UPDATE ... WHERE id AND tenant_id AND\n  status AND version AND expires_at ... RETURNING version` plus one event\n  insert, in one transaction. Zero rows means a concurrent writer won: retry\n  from a fresh read, never write anyway. Keep the predicate the arbiter; the\n  in-transaction reads only classify refusals.\n- Only `human` principals decide; never the requester; one decision per actor\n  (unique `(request_id, vote_key)`); quorum counts distinct approver events.\n  Agents and services may request, consume, and expire.\n- Tenant: every statement names `tenant_id`, the work runs in\n  `withTenant(principal.tenantId)`, and a conflicting active context is\n  refused. Principal tenant ids must be UUIDs.\n- Policy may only tighten (`assertPolicyTightens` on write, `effectiveRules`\n  clamps on read). Quorum and expiry are fixed at request time; decide-time\n  permissions are the request snapshot plus the current kind and policy slugs.\n- Generated surface is `list`/`get` on REST and MCP, no CLI. A collection's\n  `@smrt()` config is applied to its item class by core, so each collection\n  repeats its model's surface exactly; changing one without the other opens\n  or closes the model. `surface.test.ts` holds this.\n- Models refuse re-save and delete of requests and events. Never add an\n  update path for events. Inserts need the service-only capability in\n  `src/write-capability.ts`; never export it or mint it outside the service.\n- The event FK is physical on PostgreSQL and SQLite only: DuckDB runs an\n  indexed-column UPDATE on a referenced row as delete plus insert.\n- No Node built-ins in `src/` (browser gate); use `globalThis.crypto`.\n\n## Validation\n\n```bash\npnpm --filter @happyvertical/smrt-approvals test\npnpm --filter @happyvertical/smrt-approvals typecheck\npnpm --filter @happyvertical/smrt-approvals test:postgres\n```\n\nThe behaviour suite (`src/__tests__/helpers/approval-suite.ts`) runs on\nSQLite, DuckDB, and, through `test:postgres`, a migrated PostgreSQL database.\n",
+  "moduleDocs": [
+    {
+      "path": "agents/approvals.md",
+      "module": "approvals",
+      "content": "# Approvals: transitions, concurrency, and scope\n\nDesign source: the accepted recommendation on smrt#3716. This file records\nthe slice-1 contract (#3741) and what later slices add.\n\n## States and transitions\n\n```\npending --approve (distinct approvers reach quorum)--> approved\napproved --consume (hash matches, unexpired)---------> approved + consumedAt\npending --reject | request_changes-------------------> rejected | changes_requested\npending --cancel (requester or approvals.cancel-any)-> cancelled\npending | approved(unconsumed) --expire (deadline)---> expired\n```\n\n`changes_requested` is terminal in slice 1: the requester opens a new request\nfor the new revision (a new `subjectRevisionHash`). There is no resubmit.\n\nEach transition in `src/service.ts`:\n\n1. Validates input and the principal (`id`, UUID `tenantId`, `type`, `can`).\n2. Refuses a principal whose tenant differs from an active tenant context.\n3. Opens a transaction through core's `withEmbeddedWriteTransaction(db,\n   isEmbeddedDatabase(db), fn)`. On embedded engines (SQLite, DuckDB, libsql)\n   it takes the embedded write queue for the database first, then the\n   adapter's connection lock; the event insert and change-feed append inside\n   re-enter that hold. The reverse order (a raw `db.transaction()`) deadlocks\n   against an unrelated NULL-tenant save, which holds the queue and then\n   opens its own write transaction, until the 30 s transaction-queue timeout,\n   and lets other root writes land inside the transaction. The queue also\n   serializes transitions per database, so no separate chain exists.\n   PostgreSQL is not queued: each transaction gets its own pooled connection.\n4. Reads the request through a transaction-bound collection with an explicit\n   `tenantId` filter, and classifies refusals from that read.\n5. Runs the guarded UPDATE with the version it read. Zero rows: the\n   transaction body returns `retry`, nothing was written, and the loop starts\n   again from a fresh read (up to `maxAttempts`, then `contention`).\n6. Inserts the event with `sequence` = the returned version and appends a\n   change-feed entry (the raw UPDATE bypasses save hooks).\n7. Re-reads the request after commit on the service connection.\n\nOn PostgreSQL the UPDATE takes the row lock; under READ COMMITTED a waiting\nUPDATE re-evaluates `version = ?` after the winner commits, so it matches\nnothing. Unique keys `(request_id, sequence)` and `(request_id, vote_key)`\nare a second line: a violation aborts the attempt and it retries.\n\n`consume({ transaction })` runs steps 4 to 6 on the caller's open\ntransaction, once, without retry or serialization; the caller owns commit.\nOn embedded engines that handle must come from `withEmbeddedWriteTransaction`\nor `SmrtObject.withTransaction()`, never a raw `db.transaction()`, for the\nlock-order reason in step 3.\n\n## Raw SQL boundaries\n\nThe guarded UPDATEs are the only raw SQL. They bind every value (no literal\nUUIDs or empty strings), validate the request id as a UUID first, and name\n`tenant_id`. Reads and inserts go through collections so tenancy\ninterceptors, UUID columns, and the change feed behave as for any model.\n\n## Service-only write capability\n\nOnly `ApprovalService` inserts `ApprovalRequest` and `ApprovalEvent` rows\n(events only in the same transaction as the guarded UPDATE they record). It passes the\nmodule-private `SERVICE_WRITE` symbol (`src/write-capability.ts`, not a public\nexport) as a constructor option; the model records that instance in a\n`WeakSet` and refuses, in `save()` and `validateBeforeSave()`, any insert\nwithout it, and any minted insert that does not start pending, undecided,\nand unconsumed. `new ApprovalRequest({ status: 'approved' }).save()`,\n`ApprovalRequestCollection.create(...)`, and a forged `approved` event\n(which would otherwise count toward quorum) are refused and write nothing. A\nsymbol never arrives from JSON, so REST and MCP input cannot carry it (the\nsmrt-reports `runtime-report.ts` pattern). It guards the in-process API,\nnot raw SQL.\n\n`consume` re-checks the ledger before consuming (defence in depth against a\nstatus written around the service): the `created` event at sequence 1, no\nterminal event, and `approved` events from at least `requiredApprovals`\ndistinct human actors other than the requester; otherwise it refuses\n`unbacked_approval`. Quorum counting in `decide` applies the same filter.\n\n## Out of scope here (later slices of #3716)\n\n- Slice 2: Svelte inbox, panel, decision bar; `approvals.requests` recipe.\n- Slice 3: notification adapter (`UserNotificationService.notify`, sourceRef\n  `approval:<id>:<event>`), profiles `AuditLog` mirror, expiry and reminder\n  job calling `expireDue`.\n- Slice 4: adopters (social, personas, content, subscriptions).\n- Slice 5: agent and MCP request tools (deciding stays human-only).\n- Slice 6: #3667 `pending_approval` hand-off.\n\nKnown gaps: listing every holder of a permission needs a users-package\nhelper (for notifications); a vote stays counted if the approver later loses\nthe permission.\n"
+    }
+  ],
+  "browser": {
+    "status": "server-only",
+    "issues": [
+      "#3617",
+      "#3624",
+      "#3626"
+    ],
+    "via": [
+      "@happyvertical/smrt-profiles",
+      "@happyvertical/smrt-tenancy",
+      "@happyvertical/smrt-users"
+    ]
+  }
+}