@happyvertical/smrt-approvals 0.57.36 → 0.57.38

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-approvals",
-  "packageVersion": "0.57.36",
+  "packageVersion": "0.57.38",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "8cc50def94858a70514e5f15006c8ddc9ce11d1d083567580b9b0de9db11cccc",
-    "packageJson": "4be0f31488269382ec877742b1ed6c24fd3d608f1c0c94aefd3573741f04ebac",
-    "agents": "d97f97c724891f846420dadc8abfc9b73af5e2d453a56ae748816cf1b039d452",
+    "manifest": "d4defe973635c9414b7526ce0fe5a39074e481293204900d0c28cd81568c2c3d",
+    "packageJson": "0558457aa3754fe7df51a9a056dada3e4cc91649e9c485889b7633d2a8c4c466",
+    "agents": "aba637bcff50dd513fd0d2039af397b317cc27e708285aa10d5645e57c08eb53",
     "moduleDoc:agents/approvals.md": "3e2b9ef6441798041de30d39b295886c758053185085174bd430d2f156b81e5a"
   },
   "exports": [
@@ -22,6 +22,8 @@
     "@happyvertical/smrt-tenancy": "workspace:*",
     "@happyvertical/smrt-users": "workspace:*",
     "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-scanner": "workspace:*",
+    "@happyvertical/smrt-types": "workspace:*",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
@@ -30,7 +32,9 @@
   },
   "smrtDependencies": [
     "@happyvertical/smrt-core",
+    "@happyvertical/smrt-scanner",
     "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-types",
     "@happyvertical/smrt-users",
     "@happyvertical/smrt-vitest"
   ],
@@ -121,35 +125,40 @@
           "type": "foreignKey",
           "required": true,
           "related": "ApprovalRequest",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The request this entry belongs to."
         },
         {
           "name": "type",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "What happened: created, approved, rejected, changes requested, cancelled, expired or used."
         },
         {
           "name": "actorId",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "Who did it."
         },
         {
           "name": "actorType",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "Whether a person, an assistant or an automated process did it."
         },
         {
           "name": "reason",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "The reason given, for example why a request was rejected or cancelled."
         },
         {
           "name": "subjectRevisionHash",
@@ -177,7 +186,8 @@
           "type": "datetime",
           "required": false,
           "columnType": "TIMESTAMP",
-          "readonly": true
+          "readonly": true,
+          "description": "When it happened."
         },
         {
           "name": "selfApproved",
@@ -185,7 +195,8 @@
           "required": false,
           "columnType": "BOOLEAN",
           "default": false,
-          "readonly": true
+          "readonly": true,
+          "description": "Whether the person who asked also decided, where that is allowed."
         },
         {
           "name": "selfApprovalPermission",
@@ -218,6 +229,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -296,31 +310,36 @@
           "name": "kind",
           "type": "text",
           "required": true,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The sort of approval these rules apply to."
         },
         {
           "name": "requiredApprovals",
           "type": "integer",
           "required": false,
-          "columnType": "INTEGER"
+          "columnType": "INTEGER",
+          "description": "How many different people must agree. Zero keeps the usual number."
         },
         {
           "name": "ttlMs",
           "type": "integer",
           "required": false,
-          "columnType": "INTEGER"
+          "columnType": "INTEGER",
+          "description": "How long a request stays open, in milliseconds. Zero keeps the usual time."
         },
         {
           "name": "requiredPermission",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "An extra permission a decider must hold. Leave empty for none."
         },
         {
           "name": "updatedBy",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Who last changed these rules."
         }
       ],
       "relationships": [],
@@ -331,6 +350,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -409,77 +431,88 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "What sort of approval this is, such as publishing a post."
         },
         {
           "name": "subjectType",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "What kind of thing the request is about."
         },
         {
           "name": "subjectId",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "Which thing the request is about."
         },
         {
           "name": "subjectRevisionHash",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "A fingerprint of the exact version that was put up for approval. If the thing changes, the approval no longer applies."
         },
         {
           "name": "requestKey",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "The reference the request is filed under, so asking twice does not open it twice."
         },
         {
           "name": "requestedBy",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "Who asked for the approval."
         },
         {
           "name": "requestedByType",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "Whether a person, an assistant or an automated process asked."
         },
         {
           "name": "summary",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "A short description of what needs approval."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "Where the request stands: waiting, approved, rejected, changes requested, cancelled or expired."
         },
         {
           "name": "requiredApprovals",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "readonly": true
+          "readonly": true,
+          "description": "How many different people must agree."
         },
         {
           "name": "approvalCount",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "readonly": true
+          "readonly": true,
+          "description": "How many people have agreed so far."
         },
         {
           "name": "requiredPermissions",
@@ -500,28 +533,32 @@
           "type": "datetime",
           "required": false,
           "columnType": "TIMESTAMP",
-          "readonly": true
+          "readonly": true,
+          "description": "The deadline. After it the request can no longer be decided."
         },
         {
           "name": "decidedAt",
           "type": "datetime",
           "required": false,
           "columnType": "TIMESTAMP",
-          "readonly": true
+          "readonly": true,
+          "description": "When the request was decided."
         },
         {
           "name": "consumedAt",
           "type": "datetime",
           "required": false,
           "columnType": "TIMESTAMP",
-          "readonly": true
+          "readonly": true,
+          "description": "When the approval was used to let the action go ahead."
         },
         {
           "name": "consumedBy",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "readonly": true
+          "readonly": true,
+          "description": "Who used the approval."
         }
       ],
       "relationships": [],
@@ -554,6 +591,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -743,7 +783,7 @@
     "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; requesters additionally need the kind's\n  explicit `selfApprovalPermission`; 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",
+  "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; requesters additionally need the kind's\n  explicit `selfApprovalPermission`; 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- **Recipe `approvals.requests`** (`src/recipes.ts`, help in `src/requests.recipe.md`): lists requests, history and policies for the planner and other catalog hosts, read-only because the service is the only write path. Fields it shows carry `@field({ description })` in plain words; keep them when editing the models.\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",
@@ -751,6 +791,227 @@
       "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; requester events count only with `selfApproved: true`\nand a valid `selfApprovalPermission` audit slug. 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\n## Permission-gated self-decisions\n\nA kind may opt in with `selfApprovalPermission: 'content.approve-self'`.\nThe requester must be human and hold that permission plus every normal snapshot,\ncurrent kind and tenant-policy decision permission. All three verdicts use this\nallowance. Without the opt-in or grant, `self_approval` remains the refusal.\nSelf-decisions record `selfApproved` and `selfApprovalPermission` on the event;\nordinary events default to false and an empty slug. These fields are service-only,\nnot caller input. Deploy the generated event-column migration before upgrading\nruntime code; existing events default to false/empty and cannot gain self authority.\nLike other votes, an authorized self vote remains counted after permission or kind\nconfiguration changes. It counts once, never bypasses quorum, expiry or tenancy,\nand remains atomic with the guarded transition.\n\nDuckDB deployments on `@happyvertical/sql` 0.103.1 may repeatedly recreate the\nunchanged request/sequence index during migration because index introspection\nretains SQL identifier quotes; see [SDK #1395](https://github.com/happyvertical/sdk/issues/1395).\nThe new audit columns converge and existing ordinary approvals remain consumable.\n"
     }
   ],
+  "recipes": [
+    {
+      "id": "approvals.requests",
+      "className": "ApprovalsRecipe",
+      "label": "Approvals",
+      "summary": "See what is waiting for a yes, who decided what, and the rules each kind of approval follows.",
+      "synonyms": [
+        "approvals",
+        "approval requests",
+        "sign-off",
+        "sign off",
+        "authorisation",
+        "authorization",
+        "review queue",
+        "waiting for approval"
+      ],
+      "models": [
+        "@happyvertical/smrt-approvals:ApprovalRequest",
+        "@happyvertical/smrt-approvals:ApprovalEvent",
+        "@happyvertical/smrt-approvals:ApprovalPolicy"
+      ],
+      "nav": [
+        {
+          "label": "Requests",
+          "model": "@happyvertical/smrt-approvals:ApprovalRequest",
+          "icon": "fileText",
+          "description": "Everything waiting for a yes or already decided, and where each one stands.",
+          "noun": "request"
+        },
+        {
+          "label": "History",
+          "model": "@happyvertical/smrt-approvals:ApprovalEvent",
+          "icon": "book",
+          "description": "Who did what on each request, and when.",
+          "noun": "history entry"
+        },
+        {
+          "label": "Policies",
+          "model": "@happyvertical/smrt-approvals:ApprovalPolicy",
+          "icon": "settings",
+          "description": "The rules for each kind of approval: how many people must agree and how long a request lasts.",
+          "noun": "policy"
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "approvals",
+        "label": "Approvals",
+        "icon": "briefcase",
+        "description": "Who has to say yes before something happens."
+      },
+      "options": {
+        "@happyvertical/smrt-approvals:ApprovalRequest": {
+          "fields": {
+            "summary": {
+              "order": 1
+            },
+            "kind": {
+              "order": 2
+            },
+            "status": {
+              "order": 3
+            },
+            "requestedBy": {
+              "label": "Requested by",
+              "order": 4
+            },
+            "requestedByType": {
+              "label": "Requested by a",
+              "order": 5
+            },
+            "expiresAt": {
+              "label": "Expires",
+              "order": 6
+            },
+            "decidedAt": {
+              "label": "Decided on",
+              "order": 7
+            },
+            "subjectType": {
+              "label": "What it is about",
+              "visibility": "advanced"
+            },
+            "subjectId": {
+              "label": "Which one",
+              "visibility": "advanced"
+            },
+            "requiredApprovals": {
+              "label": "Approvals needed",
+              "visibility": "advanced"
+            },
+            "approvalCount": {
+              "label": "Approvals so far",
+              "visibility": "advanced"
+            },
+            "consumedAt": {
+              "label": "Used on",
+              "visibility": "advanced"
+            },
+            "consumedBy": {
+              "label": "Used by",
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "subjectRevisionHash": {
+              "visibility": "hidden"
+            },
+            "requestKey": {
+              "visibility": "hidden"
+            },
+            "requiredPermissions": {
+              "visibility": "hidden"
+            },
+            "version": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-approvals:ApprovalEvent": {
+          "fields": {
+            "requestId": {
+              "label": "Request",
+              "order": 1
+            },
+            "type": {
+              "label": "What happened",
+              "order": 2
+            },
+            "actorId": {
+              "label": "Who",
+              "order": 3
+            },
+            "actorType": {
+              "label": "Who it was",
+              "order": 4
+            },
+            "reason": {
+              "order": 5
+            },
+            "occurredAt": {
+              "label": "When",
+              "order": 6
+            },
+            "selfApproved": {
+              "label": "Decided by the requester",
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "subjectRevisionHash": {
+              "visibility": "hidden"
+            },
+            "sequence": {
+              "visibility": "hidden"
+            },
+            "voteKey": {
+              "visibility": "hidden"
+            },
+            "selfApprovalPermission": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-approvals:ApprovalPolicy": {
+          "fields": {
+            "kind": {
+              "order": 1
+            },
+            "requiredApprovals": {
+              "label": "Approvals needed",
+              "order": 2
+            },
+            "ttlMs": {
+              "label": "Time limit in milliseconds",
+              "order": 3
+            },
+            "requiredPermission": {
+              "label": "Extra permission needed",
+              "order": 4
+            },
+            "updatedBy": {
+              "label": "Last changed by",
+              "order": 5
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nApprovals is where you see who has to say yes before something happens, such\nas publishing a post or sending an order. Each request names what needs\napproval, who asked and where it stands: waiting, approved, rejected, changes\nrequested, cancelled or expired. The history keeps every step taken on a\nrequest, and the policies show the rules each kind of approval follows.\n\n## Tasks\n\nRequests are raised by the app or by an assistant through the approval\nservice, decisions are recorded by the same service, and policies are set by\nan administrator through it. Nothing here is created or changed by hand in the\napp. Here you find a request, see where it stands and read what happened.\n\n### Find a request\n\n1. Open the list of requests.\n2. Look at the **{field:ApprovalRequest.summary}** to see what needs approval, and the **{field:ApprovalRequest.kind}** to see what sort of approval it is.\n3. Check **{field:ApprovalRequest.requestedBy}** to see who asked.\n\n### See where a request stands\n\n1. Open the request.\n2. Its **{field:ApprovalRequest.status}** shows whether it is still waiting, approved, rejected, sent back for changes, cancelled or expired.\n3. **{field:ApprovalRequest.expiresAt}** is the deadline: after it a request can no longer be decided.\n4. Once decided, **{field:ApprovalRequest.decidedAt}** shows when.\n\n### Read the history of a request\n\n1. Open the history.\n2. Find the entries for the **{field:ApprovalEvent.requestId}** you are interested in.\n3. Each entry shows **{field:ApprovalEvent.type}**, who did it in **{field:ApprovalEvent.actorId}**, and **{field:ApprovalEvent.occurredAt}**, oldest first.\n4. A rejection or cancellation carries its **{field:ApprovalEvent.reason}**.\n\n### Read the rules for a kind of approval\n\n1. Open the policies.\n2. Find the **{field:ApprovalPolicy.kind}** you want to know about.\n3. **{field:ApprovalPolicy.requiredApprovals}** is how many different people must agree, and **{field:ApprovalPolicy.ttlMs}** is how long a request stays open.\n4. **{field:ApprovalPolicy.requiredPermission}** names any extra permission a decider must hold.\n",
+        "fieldRefs": [
+          "ApprovalEvent.actorId",
+          "ApprovalEvent.occurredAt",
+          "ApprovalEvent.reason",
+          "ApprovalEvent.requestId",
+          "ApprovalEvent.type",
+          "ApprovalPolicy.kind",
+          "ApprovalPolicy.requiredApprovals",
+          "ApprovalPolicy.requiredPermission",
+          "ApprovalPolicy.ttlMs",
+          "ApprovalRequest.decidedAt",
+          "ApprovalRequest.expiresAt",
+          "ApprovalRequest.kind",
+          "ApprovalRequest.requestedBy",
+          "ApprovalRequest.status",
+          "ApprovalRequest.summary"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-profiles, @happyvertical/smrt-tenancy, @happyvertical/smrt-users, which do not build for a browser (#3617, #3624, #3626)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-approvals",
-  "version": "0.57.36",
+  "version": "0.57.38",
   "description": "Approval decision gate for the SMRT framework: revision-bound, single-use approvals with quorum, expiry, and an append-only event ledger",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,13 +20,15 @@
     "./manifest.json": "./dist/manifest.json"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.57.36",
-    "@happyvertical/smrt-tenancy": "0.57.36",
-    "@happyvertical/smrt-users": "0.57.36",
-    "@happyvertical/sql": "^0.109.0"
+    "@happyvertical/smrt-core": "0.57.38",
+    "@happyvertical/smrt-tenancy": "0.57.38",
+    "@happyvertical/smrt-users": "0.57.38",
+    "@happyvertical/sql": "^0.110.0"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.57.36",
+    "@happyvertical/smrt-scanner": "0.57.38",
+    "@happyvertical/smrt-types": "0.57.38",
+    "@happyvertical/smrt-vitest": "0.57.38",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
     "vite": "8.1.6",