@happyvertical/smrt-expenses 0.55.24 → 0.56.1

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-expenses",
-  "packageVersion": "0.55.24",
+  "packageVersion": "0.56.1",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "063bd603cc7de3325c7ad2ab0756e0b1b6cadafd63a41eb9b9d7fa80e2c7278a",
-    "packageJson": "3cbdb303e505dcb02394dc41fe67e669b70969993281a74580c4d84fee9aa8c8",
-    "agents": "5eceb196cc83aae058b9289b23bc05a8a313b7f2f5975852cdf2924e73dcd772",
+    "manifest": "be805516392b4f8aeddd60fc1a4e454014a52e02b86b68bbf9e4bb067c3754d0",
+    "packageJson": "d43dc00d530ed9c6343137ed9444f2728ac7e50cb7667b94acfe358d0c4b2ab8",
+    "agents": "9ce0e6213406ad655e3490340de494ffe7ac9831982d138c25a09c2936070bdc",
     "moduleDoc:agents/financial-facts-test-matrix.md": "798c9f6c7c5694057ec438cf17252832a38164dd80a47f77c9cd4642b3e5cbd6",
     "moduleDoc:agents/expense-ui.md": "0bdea9e6c627f8cbab2a1f21ef4da3ab7f00409764a1ef48572dd40694fb6785"
   },
@@ -28,6 +28,7 @@
     "@happyvertical/smrt-tenancy": "workspace:*",
     "@happyvertical/smrt-types": "workspace:*",
     "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
@@ -45,6 +46,7 @@
     "@happyvertical/smrt-tenancy",
     "@happyvertical/smrt-types",
     "@happyvertical/smrt-ui",
+    "@happyvertical/smrt-users",
     "@happyvertical/smrt-vitest"
   ],
   "sdkDependencies": [],
@@ -72,11 +74,24 @@
       "fields": [],
       "relationships": [],
       "methods": [
+        "attachReceipt",
         "commitmentPosition",
         "forCostObject",
+        "listReviewedTaxFacts",
+        "record",
+        "recordReimbursement",
+        "recordReview",
         "totalsByCurrency"
       ],
       "methodSignatures": [
+        {
+          "name": "attachReceipt",
+          "async": true,
+          "params": [
+            "options: AttachExpenseReceiptActionInput"
+          ],
+          "returns": "Promise<ExpenseReceipt>"
+        },
         {
           "name": "commitmentPosition",
           "async": true,
@@ -95,6 +110,38 @@
           ],
           "returns": "Promise<Expense[]>"
         },
+        {
+          "name": "listReviewedTaxFacts",
+          "async": true,
+          "params": [
+            "options: ReviewedExpenseTaxFactsOptions"
+          ],
+          "returns": "Promise<ReviewedExpenseTaxFact[]>"
+        },
+        {
+          "name": "record",
+          "async": true,
+          "params": [
+            "options: RecordExpenseActionInput"
+          ],
+          "returns": "Promise<Expense>"
+        },
+        {
+          "name": "recordReimbursement",
+          "async": true,
+          "params": [
+            "options: MarkExpenseReimbursedActionInput"
+          ],
+          "returns": "Promise<Expense>"
+        },
+        {
+          "name": "recordReview",
+          "async": true,
+          "params": [
+            "options: ReviewExpenseActionInput"
+          ],
+          "returns": "Promise<Expense>"
+        },
         {
           "name": "totalsByCurrency",
           "async": true,
@@ -104,7 +151,40 @@
           "returns": "Promise<CurrencyTotals>"
         }
       ],
-      "surfaces": [],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "expenses.record",
+          "operation": "record",
+          "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+          "path": "/expenses/record",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "expenses.attachReceipt",
+          "operation": "attachReceipt",
+          "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+          "path": "/expenses/attachReceipt",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "expenses.recordReview",
+          "operation": "recordReview",
+          "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+          "path": "/expenses/recordReview",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "expenses.recordReimbursement",
+          "operation": "recordReimbursement",
+          "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+          "path": "/expenses/recordReimbursement",
+          "method": "POST"
+        }
+      ],
       "withheldSurfaces": [
         {
           "kind": "api",
@@ -120,6 +200,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-expenses:ExpenseCollection"
         },
+        {
+          "kind": "api",
+          "operation": "listReviewedTaxFacts",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-expenses:ExpenseCollection"
+        },
         {
           "kind": "api",
           "operation": "totalsByCurrency",
@@ -407,7 +494,7 @@
           "name": "commitmentId",
           "type": "crossPackageRef",
           "required": false,
-          "related": "@happyvertical/smrt-commerce:Contract",
+          "related": "@happyvertical/smrt-commerce:PurchaseContract",
           "columnType": "UUID"
         },
         {
@@ -504,7 +591,7 @@
           "name": "commitmentId",
           "type": "crossPackageRef",
           "required": false,
-          "related": "@happyvertical/smrt-commerce:Contract",
+          "related": "@happyvertical/smrt-commerce:PurchaseContract",
           "columnType": "UUID"
         },
         {
@@ -846,7 +933,40 @@
       "risks": []
     }
   ],
-  "surfaces": [],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "expenses.record",
+      "operation": "record",
+      "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+      "path": "/expenses/record",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "expenses.attachReceipt",
+      "operation": "attachReceipt",
+      "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+      "path": "/expenses/attachReceipt",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "expenses.recordReview",
+      "operation": "recordReview",
+      "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+      "path": "/expenses/recordReview",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "expenses.recordReimbursement",
+      "operation": "recordReimbursement",
+      "objectName": "@happyvertical/smrt-expenses:ExpenseCollection",
+      "path": "/expenses/recordReimbursement",
+      "method": "POST"
+    }
+  ],
   "prompts": [],
   "relationshipsV2": {
     "foreignKeyFields": 3,
@@ -856,7 +976,7 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 30
   },
-  "agentDoc": "# @happyvertical/smrt-expenses\n\nIncurred costs against a cost object, with deduplicated receipts, an explicit\nreview, reimbursement recording, and smrt-commerce commitment drawdown (#3289).\n\n## Models\n\n- **Expense** (`expenses`): `costObjectType` (qualified class name) +\n  `costObjectId` (bare string), `category` (lowercase kebab-case; suggestions\n  in `SUGGESTED_EXPENSE_CATEGORIES`), `amount` integer minor units + ISO 4217\n  `currency`, `incurredOn` (`YYYY-MM-DD` text: a calendar date, not an\n  instant), `recordedAt`, `recordedByProfileId`, `paidBy` (`company` |\n  `person` | `third-party`) + `paidByProfileId` / `paidByName`, `vendorId`, `commitmentId` /\n  `commitmentLineId`, review fields, `reimbursable` / `reimbursedAt` /\n  `reimbursementReference`.\n- **ExpenseReceipt** (`expense_receipts`): noun-specific asset join\n  (`expenseId` → Expense, `assetId` → smrt-assets Asset) with uploader,\n  `filename`, `mimeType`, `byteCount`, `contentSha256`. Collection extends\n  `SmrtJunction` (left expense, right asset, ordered by `created_at`).\n\n## Invariants\n\n- **Review is method-only.** `review()`, `reject()`, `markDuplicate()`,\n  `reopen()` read the persisted status, check the move, and authorize exactly\n  one save through a module `WeakMap`. Every transition assigns every review\n  field, and the token carries that complete resulting state, so a field set\n  directly beside `review()`/`reject()` (e.g. an injected `duplicateOfId`)\n  is refused. A `reviewed` expense never carries `duplicateOfId`. `save()` compares every review field\n  (status, reviewer, time, note, `duplicateOfId`) with the stored row and\n  refuses an unauthorized change (`EXPENSE_REVIEW_FIELDS_LOCKED`), including\n  on a brand-new row. Review fields are also `readonly` for generated writes.\n- **Writes are pinned to the guarded row.** The guards read the row stored\n  under `id`, but core's natural-key save adopts any same-owner row on\n  `(tenant_id, slug, context)` and upserts it with no revision predicate;\n  these models' slugs come from the id. So `pinNaturalKey()` lets a fresh\n  (not `isPersisted`) instance only INSERT (`requireInsertOnSave()`): naming\n  an existing row's id is `EXPENSE_IDENTITY_CONFLICT`, and a row appearing\n  mid-save fails the INSERT instead of being adopted. An existing row changes\n  only through a loaded instance (revision compare-and-swap) that keeps its\n  slug/context. Never `create({ id: <existing> })` or `getOrUpsert()` these\n  models; load and save instead.\n- **Reviewed money is frozen.** While the stored status is `reviewed`,\n  `LOCKED_WHEN_REVIEWED` fields (money, currency, both dates, cost object,\n  vendor, commitment, payer) cannot change; `reopen()` first. `recordedAt` is\n  compared as an instant, since drivers return it as a `Date` or a string.\n- **Drawdown counts once.** `ExpenseCollection.commitmentPosition()` sums only\n  `reviewed` rows with no `duplicateOfId`, in the commitment's currency, deduped\n  by id. Committed is the contract's `totalAmount` (or the line's `amount`).\n- **Currencies never mix.** A commitment match must share the currency and\n  tenant (`EXPENSE_COMMITMENT_MISMATCH`), checked when the match, line or\n  currency is set or changed — not on every save, so a later commitment edit\n  never blocks e.g. `markReimbursed()`. `totalsByCurrency()` keys by currency.\n  Rows left in another currency by a later commitment change land in\n  `otherCurrencies`, never in `drawn`.\n- **Duplicate receipts.** Same `(expense, sha256)` is refused by a pre-insert\n  read plus the unique index `expense_receipts_expense_sha256_key`\n  `(expense_id, content_sha256)`; a unique violation is rethrown as\n  `DuplicateReceiptError`, classified from the error itself (violated key\n  name, or `details.fieldName` columns on core's typed error) because on\n  PostgreSQL the violation aborts a caller's transaction and nothing can be\n  re-read; only an error naming no key falls back to a re-read. The index omits `tenant_id` deliberately: the\n  expense already fixes the tenant, and a nullable leading `tenant_id` would\n  leave NULL-tenant (global) receipts unenforced. Same hash on different\n  expenses is allowed; `findDuplicateReceipts()` reports it (facet on\n  `contentSha256`, count > 1). Receipt `tenantId` (derived from the\n  expense on insert), `expenseId`, `assetId` and `contentSha256` are\n  immutable. The inherited `SmrtJunction.attach()` and\n  `setLinks()` are overridden to throw (`setLinks()` would delete every\n  receipt, then fail to re-attach without hashes); `attachReceipt()` adds and\n  `detach()` removes a link, keeping the asset. Because `ExpenseReceipt`\n  overrides `save()`, `hasBaseJunctionLifecycle()` is false and no batch\n  junction path can write a hashless row around it.\n- **Vendor ownership.** `vendorId` is a `crossPackageRef` (no FK, no\n  validation), so `assertVendor()` checks the vendor is visible in and owned\n  by the expense's tenant whenever it is set or changed\n  (`EXPENSE_VENDOR_MISMATCH`).\n- **Tenant never moves.** Expense and receipt tenants are fixed once\n  stored, compared as `effectiveTenant()` (the field, or the active context\n  the `beforeSave` interceptor would fill an unset one from; unset is falsy,\n  so `''` counts). `normalizeTenantId()` stores `''` as NULL (global), never\n  as a pseudo-tenant, matching core/tenancy's falsy \"unset\". Otherwise a\n  global (NULL-tenant) row saved inside `withTenant()` would be silently\n  populated and split from its global expense or receipts.\n- **Tenancy.** Optional (`@TenantScoped({ mode: 'optional' })`, nullable\n  `tenantId`), like smrt-commerce. A receipt takes its expense's tenant; its\n  expense and asset must be visible in that tenant. A commitment must belong\n  to the expense's tenant; before `super.save()` that is\n  `tenantId ?? getTenantId()`, because the interceptor has not populated it.\n  Consumers make it required with a qualified\n  `registerTenantScopedClass(…, { mode: 'required' })`.\n- **Closed generated surface.** Models AND collections declare\n  `api: { include: [] }`, `mcp: { include: [] }`, `cli: false`. Collection\n  classes are registered too: an undecorated collection publishes its CRUD and\n  public methods as MCP tools. Core has no consumer-side switch to reopen a\n  package model's surface; consumers write their own routes.\n- **Cost object is not dereferenced on save.** `getCostObject()` resolves it\n  through the registry and returns `null` for a foreign-tenant row. One cost\n  object per expense (columns, not a `SmrtPolymorphicAssociation` join) so a\n  cost can never roll up into two jobs.\n\n## Optional financial facts\n\n`financialBreakdown` is guarded JSON text (`get/setFinancialBreakdown`), absent\nfor legacy rows. Exact `getCostBasis()` returns null without facts. Complete facts\nreconcile subtotal + signed tax components to amount/currency; recoverable amounts\nare explicit. No tax law or customer pricing is inferred. `third-party` payer\nrequires `paidByName` and is not reimbursable. Negative amounts require `refundOfId`\n(same-owner/currency positive source, checked through the bound executor).\nSource edits also check inbound same-owner refunds: a referenced source stays\npositive, non-refund, and in their currency. `save()` encloses guards and write\nin the public `withTransaction()` boundary; PostgreSQL locks its row and proposed\nsource in id order before either refund check, while SQLite serializes writes.\nThe inbound projected lookup uses the existing `refund_of_id` index and an\nexplicit owner filter. Keep caller transaction affinity and per-row revision\nchecks; neither an unlocked lookup nor revision CAS alone protects this pair.\nAll three fields participate in the reviewed-money freeze. See the README and\n[financial facts test matrix](agents/financial-facts-test-matrix.md).\n\nLinking a new refund (or changing its source) also claims the source revision in\nthat same transaction through `claimRevision(source.updated_at)`. This makes a\nsource edit under an older PostgreSQL `REPEATABLE READ` snapshot fail with a\nserialization error instead of missing the new refund. Reload a source after\nlinking a refund before editing/reviewing it; on a serialization failure, retry\nthe entire caller transaction with fresh instances. Failed outer transactions\nroll back both the refund and the source revision claim. Existing-link saves do\nnot advance the source revision.\n\n## Cross-package references\n\n- `vendorId` → `@crossPackageRef('@happyvertical/smrt-commerce:Vendor')`\n- `commitmentId` → `…smrt-commerce:Contract` (usually a `PurchaseOrder`)\n- `commitmentLineId` → `…smrt-commerce:ContractLineItem`\n- `assetId` → `…smrt-assets:Asset`\n- profile ids → `…smrt-profiles:Profile` (no dependency; references only)\n- `expenseId`, `duplicateOfId` → `@foreignKey` within the package\n\n## Scope\n\nAllowance (a planned amount) is not an expense kind; it belongs with\nbudget/commitment records. Labour belongs to `@happyvertical/smrt-timesheets`\n(#3288). No OCR, no accounting-provider posting.\n\n## Validation\n\n```bash\npnpm --filter @happyvertical/smrt-expenses test\npnpm --filter @happyvertical/smrt-expenses typecheck\npnpm --filter @happyvertical/smrt-expenses test:postgres\n```\n\n`src/__tests__/helpers/expense-suite.ts` is the shared behaviour suite: the\nSQLite file and the PostgreSQL lane (`*.optional.test.ts`, schema from\n`migrateSmrtSchemas` plus live parity) both run it. Use UUID tenant and\nprofile ids in tests: PostgreSQL stores them as `uuid`.\n\n## UI\n\n`src/svelte/` owns native expense entry and review presentation. See\n[the UI contract](agents/expense-ui.md) for DTOs, native payloads and recovery.\nDraft amounts are lossless currency-unit text; model/review amounts remain integer\nminor units. Receipt upload is composed from Assets, never reimplemented here.\n`test` includes backend and UI SSR; `test:e2e` proves native browser submissions.\n",
+  "agentDoc": "# @happyvertical/smrt-expenses\n\nIncurred costs against a cost object, with deduplicated receipts, an explicit\nreview, reimbursement recording, and smrt-commerce commitment drawdown (#3289).\n\n## Models\n\n- **Expense** (`expenses`): `costObjectType` (qualified class name) +\n  `costObjectId` (bare string), `category` (lowercase kebab-case; suggestions\n  in `SUGGESTED_EXPENSE_CATEGORIES`), `amount` integer minor units + ISO 4217\n  `currency`, `incurredOn` (`YYYY-MM-DD` text: a calendar date, not an\n  instant), `recordedAt`, `recordedByProfileId`, `paidBy` (`company` |\n  `person` | `third-party`) + `paidByProfileId` / `paidByName`, `vendorId`, `commitmentId` /\n  `commitmentLineId`, review fields, `reimbursable` / `reimbursedAt` /\n  `reimbursementReference`.\n- **ExpenseReceipt** (`expense_receipts`): noun-specific asset join\n  (`expenseId` → Expense, `assetId` → smrt-assets Asset) with uploader,\n  `filename`, `mimeType`, `byteCount`, `contentSha256`. Collection extends\n  `SmrtJunction` (left expense, right asset, ordered by `created_at`).\n\n## Recipe\n\n`src/recipes.ts` declares one `SmrtRecipe`, `expenses.tracking` (label\n\"Expenses\", section `accounting`, shared with `ledgers.bookkeeping`), emitted\ninto the built `manifest.json` and `smrt-knowledge.json` `recipes`. It brings\n`Expense` with `ExpenseReceipt` as a child model, hides the cost-object type,\ncommitment and reviewer plumbing, and leaves the read-only review fields as\nthey are (review is method-only; see below). Help lives in\n`src/tracking.recipe.md` (#3591). See [core recipes](../core/agents/recipes.md).\n\n## Invariants\n\n- **Review is method-only.** `review()`, `reject()`, `markDuplicate()`,\n  `reopen()` read the persisted status, check the move, and authorize exactly\n  one save through a module `WeakMap`. Every transition assigns every review\n  field, and the token carries that complete resulting state, so a field set\n  directly beside `review()`/`reject()` (e.g. an injected `duplicateOfId`)\n  is refused. A `reviewed` expense never carries `duplicateOfId`. `save()` compares every review field\n  (status, reviewer, time, note, `duplicateOfId`) with the stored row and\n  refuses an unauthorized change (`EXPENSE_REVIEW_FIELDS_LOCKED`), including\n  on a brand-new row. Review fields are also `readonly` for generated writes.\n- **Writes are pinned to the guarded row.** The guards read the row stored\n  under `id`, but core's natural-key save adopts any same-owner row on\n  `(tenant_id, slug, context)` and upserts it with no revision predicate;\n  these models' slugs come from the id. So `pinNaturalKey()` lets a fresh\n  (not `isPersisted`) instance only INSERT (`requireInsertOnSave()`): naming\n  an existing row's id is `EXPENSE_IDENTITY_CONFLICT`, and a row appearing\n  mid-save fails the INSERT instead of being adopted. An existing row changes\n  only through a loaded instance (revision compare-and-swap) that keeps its\n  slug/context. Never `create({ id: <existing> })` or `getOrUpsert()` these\n  models; load and save instead.\n- **Reviewed money is frozen.** While the stored status is `reviewed`,\n  `LOCKED_WHEN_REVIEWED` fields (money, currency, both dates, cost object,\n  vendor, commitment, payer) cannot change; `reopen()` first. `recordedAt` is\n  compared as an instant, since drivers return it as a `Date` or a string.\n- **Drawdown counts once.** `ExpenseCollection.commitmentPosition()` sums only\n  `reviewed` rows with no `duplicateOfId`, in the commitment's currency, deduped\n  by id. Committed is the contract's `totalAmount` (or the line's `amount`).\n- **Currencies never mix.** A commitment match must share the currency and\n  tenant (`EXPENSE_COMMITMENT_MISMATCH`), checked when the match, line or\n  currency is set or changed — not on every save, so a later commitment edit\n  never blocks e.g. `markReimbursed()`. `totalsByCurrency()` keys by currency.\n  Rows left in another currency by a later commitment change land in\n  `otherCurrencies`, never in `drawn`.\n- **Duplicate receipts.** Same `(expense, sha256)` is refused by a pre-insert\n  read plus the unique index `expense_receipts_expense_sha256_key`\n  `(expense_id, content_sha256)`; a unique violation is rethrown as\n  `DuplicateReceiptError`, classified from the error itself (violated key\n  name, or `details.fieldName` columns on core's typed error) because on\n  PostgreSQL the violation aborts a caller's transaction and nothing can be\n  re-read; only an error naming no key falls back to a re-read. The index omits `tenant_id` deliberately: the\n  expense already fixes the tenant, and a nullable leading `tenant_id` would\n  leave NULL-tenant (global) receipts unenforced. Same hash on different\n  expenses is allowed; `findDuplicateReceipts()` reports it (facet on\n  `contentSha256`, count > 1). Receipt `tenantId` (derived from the\n  expense on insert), `expenseId`, `assetId` and `contentSha256` are\n  immutable. The inherited `SmrtJunction.attach()` and\n  `setLinks()` are overridden to throw (`setLinks()` would delete every\n  receipt, then fail to re-attach without hashes); `attachReceipt()` adds and\n  `detach()` removes a link, keeping the asset. Because `ExpenseReceipt`\n  overrides `save()`, `hasBaseJunctionLifecycle()` is false and no batch\n  junction path can write a hashless row around it.\n- **Vendor ownership.** `vendorId` is a `crossPackageRef` (no FK, no\n  validation), so `assertVendor()` checks the vendor is visible in and owned\n  by the expense's tenant whenever it is set or changed\n  (`EXPENSE_VENDOR_MISMATCH`).\n- **Tenant never moves.** Expense and receipt tenants are fixed once\n  stored, compared as `effectiveTenant()` (the field, or the active context\n  the `beforeSave` interceptor would fill an unset one from; unset is falsy,\n  so `''` counts). `normalizeTenantId()` stores `''` as NULL (global), never\n  as a pseudo-tenant, matching core/tenancy's falsy \"unset\". Otherwise a\n  global (NULL-tenant) row saved inside `withTenant()` would be silently\n  populated and split from its global expense or receipts.\n- **Tenancy.** Optional (`@TenantScoped({ mode: 'optional' })`, nullable\n  `tenantId`), like smrt-commerce. A receipt takes its expense's tenant; its\n  expense and asset must be visible in that tenant. A commitment must belong\n  to the expense's tenant; before `super.save()` that is\n  `tenantId ?? getTenantId()`, because the interceptor has not populated it.\n  Consumers make it required with a qualified\n  `registerTenantScopedClass(…, { mode: 'required' })`.\n- **Closed generated surface.** Models AND collections declare\n  `mcp: { include: [] }`, `cli: false` and no generated CRUD or reads\n  (generated reads check no read permission, and cost visibility is\n  permission-gated). Collection classes are registered too: an undecorated\n  collection publishes its CRUD and public methods as MCP tools. Core has no\n  consumer-side switch to reopen a package model's surface.\n- **Generated write actions (#4001).** `ExpenseCollection` hosts the only\n  generated writes, on REST: `record`, `attachReceipt`, `recordReview`\n  (`decision: 'approve' | 'reject'`, reject needs `reason`) and\n  `recordReimbursement`. `Expense` and `ExpenseCollection` both list them in\n  `api.include` (runtime REST gates on the item, SvelteKit on the collection).\n  Their names differ from `Expense.review()` / `markReimbursed()` on purpose:\n  allowlisting a collection action must never open an instance method that\n  takes the actor from its input. `src/actions/` delegates to the guarded\n  model flow; identity comes from the tenancy/session ALS, never the body;\n  each authorizes `expenses.<action>` via `assertOperationPermission` (system\n  context never bypasses; review and reimbursement refuse super-admin bypass).\n  Acting on someone else's expense needs `recordReview`. There is no submit\n  state: a recorded expense is `unreviewed`, i.e. awaiting review.\n- **Cost object is not dereferenced on save.** `getCostObject()` resolves it\n  through the registry and returns `null` for a foreign-tenant row. One cost\n  object per expense (columns, not a `SmrtPolymorphicAssociation` join) so a\n  cost can never roll up into two jobs.\n\n## Optional financial facts\n\n`financialBreakdown` is guarded JSON text (`get/setFinancialBreakdown`), absent\nfor legacy rows. Exact `getCostBasis()` returns null without facts. Complete facts\nreconcile subtotal + signed tax components to amount/currency; recoverable amounts\nare explicit. No tax law or customer pricing is inferred. `third-party` payer\nrequires `paidByName` and is not reimbursable. Negative amounts require `refundOfId`\n(same-owner/currency positive source, checked through the bound executor).\nSource edits also check inbound same-owner refunds: a referenced source stays\npositive, non-refund, and in their currency. `save()` encloses guards and write\nin the public `withTransaction()` boundary; PostgreSQL locks its row and proposed\nsource in id order before either refund check, while SQLite serializes writes.\nThe inbound projected lookup uses the existing `refund_of_id` index and an\nexplicit owner filter. Keep caller transaction affinity and per-row revision\nchecks; neither an unlocked lookup nor revision CAS alone protects this pair.\n\n`ExpenseCollection.listReviewedTaxFacts({ tenantId, from, to, currency? })`\nis the reporting input for supplier facts: it returns only that tenant's reviewed,\nnon-duplicate expenses in the inclusive calendar-date range. A null\n`financialBreakdown` remains an unknown legacy fact, never zero tax.\nEach fact carries `expenseId` as the commerce reporting identity; `id` remains\nthe compatible owner alias.\nAll three fields participate in the reviewed-money freeze. See the README and\n[financial facts test matrix](agents/financial-facts-test-matrix.md).\n\nLinking a new refund (or changing its source) also claims the source revision in\nthat same transaction through `claimRevision(source.updated_at)`. This makes a\nsource edit under an older PostgreSQL `REPEATABLE READ` snapshot fail with a\nserialization error instead of missing the new refund. Reload a source after\nlinking a refund before editing/reviewing it; on a serialization failure, retry\nthe entire caller transaction with fresh instances. Failed outer transactions\nroll back both the refund and the source revision claim. Existing-link saves do\nnot advance the source revision.\n\n## Cross-package references\n\n- `vendorId` → `@crossPackageRef('@happyvertical/smrt-commerce:Vendor')`\n- `commitmentId` → `…smrt-commerce:PurchaseContract` (`PurchaseOrder` or `ProductionOrder`)\n- `commitmentLineId` → `…smrt-commerce:ContractLineItem`\n- `assetId` → `…smrt-assets:Asset`\n- profile ids → `…smrt-profiles:Profile` (no dependency; references only)\n- `expenseId`, `duplicateOfId` → `@foreignKey` within the package\n\n## Scope\n\nAllowance (a planned amount) is not an expense kind; it belongs with\nbudget/commitment records. Labour belongs to `@happyvertical/smrt-timesheets`\n(#3288). No OCR, no accounting-provider posting.\n\n## Validation\n\n```bash\npnpm --filter @happyvertical/smrt-expenses test\npnpm --filter @happyvertical/smrt-expenses typecheck\npnpm --filter @happyvertical/smrt-expenses test:postgres\n```\n\n`src/__tests__/helpers/expense-suite.ts` is the shared behaviour suite: the\nSQLite file and the PostgreSQL lane (`*.optional.test.ts`, schema from\n`migrateSmrtSchemas` plus live parity) both run it. Use UUID tenant and\nprofile ids in tests: PostgreSQL stores them as `uuid`.\n\n## UI\n\n`src/svelte/` owns native expense entry and review presentation. See\n[the UI contract](agents/expense-ui.md) for DTOs, native payloads and recovery.\nDraft amounts are lossless currency-unit text; model/review amounts remain integer\nminor units. Receipt upload is composed from Assets, never reimplemented here.\n`test` includes backend and UI SSR; `test:e2e` proves native browser submissions.\n",
   "moduleDocs": [
     {
       "path": "agents/financial-facts-test-matrix.md",
@@ -869,21 +989,168 @@
       "content": "# Expense entry and receipt review\n\nImport `ExpenseForm`, `ExpenseReviewPanel` and their named Props types from\n`@happyvertical/smrt-expenses/svelte`. Registry slots are `expense-form` and\n`expense-review`. `@happyvertical/smrt-expenses/ui` exposes metadata without\nSvelte; `./playground` exposes an interactive retained-draft/review example.\n\n`ExpenseDraftValues` is a complete set of native strings: `amount`, `currency`,\n`incurredOn`, `description`, `category`, `vendorId`, `commitmentId`, `paidBy`,\n`paidByProfileId`, and `correctionReason`. Initialize unused fields to `''`.\nAmount is ordinary currency text (`'125.00'` CAD), distinct from the public\nExpense model's integer minor-unit `amount` (`12500`). Server adapters parse\ncurrency precision, safe integer range and business rules. Calendar dates stay\nlossless text, normally `YYYY-MM-DD`; invalid amounts/dates never disappear due\nto browser number/date coercion. Every validation failure returns original\nstrings, not reconstructed saved-model values.\n\n```svelte\n<script lang=\"ts\">\n  import { ExpenseForm, ExpenseReviewPanel } from '@happyvertical/smrt-expenses/svelte';\n  let { data, form } = $props();\n</script>\n<ExpenseForm\n  action=\"?/save\"\n  title=\"Record purchase\"\n  values={form?.values ?? data.values}\n  errors={form?.errors}\n  message={form?.message}\n  canEdit={data.mayEdit}\n  correcting={data.correcting}\n  vendors={data.authorizedVendors}\n  commitments={data.authorizedCommitments}\n  hiddenFields={[\n    { name: 'requestId', value: form?.requestId ?? data.requestId },\n    { name: 'costObjectId', value: data.costObjectId },\n    { name: 'expectedTenantId', value: data.tenantId },\n  ]}\n/>\n<ExpenseReviewPanel\n  expense={data.expenseSummary}\n  duplicates={data.authorizedDuplicateCandidates}\n  history={data.history}\n  receipts={data.receiptPanel}\n/>\n```\n\nVendor and commitment options are authorized Commerce `{id, label}` projections.\nResolve Profile names and application-specific award lineage in the consumer.\nUnknown retained references remain selectable/postable; selecting a reference\nnever establishes tenant ownership or commitment eligibility. `fields` maps\nlogical keys to native names; `errors` always uses logical keys. Submitter\n`intentField`/`intent` default to `intent=save`. `hiddenFields` preserves exact\nvalues and repeated names. Avoid field-name collisions. `children` adds\napplication-owned package allocation, quantity, reimbursement and correction\npolicy fields. `correcting` shows a retained reason, but does not implement a\nnew Expense correction model. The caller applies its own correction/history\npolicy and invokes existing guarded methods where appropriate.\n\nThe base form performs native POST by default, with or without JavaScript.\n`onsubmit` allows optional enhancement. `pending` or a supplied\n`smrt-ui/form-retry` `retryStatus` controls progress presentation without clearing\nvalues or creating/rotating request keys. `canEdit=false` disables fields and\nhides save; server-side authorization and replay enforcement remain mandatory.\n\nCurrency uses the shared `CurrencySelect`, localized by the active smrt-ui i18n\ncontext. It preserves the exact retained draft string and the field name from\n`fields.currency`, including native no-JavaScript correction flows. Pass\n`currencyOptions` only when the caller must restrict the shared currency catalog.\n\n`ExpenseReviewSummary` projects public Expense description, integer minor-unit\namount, currency and incurredOn, with caller-localized `statusLabel` and `note`.\n`duplicates` and `history` are explicit authorized presentation DTOs, not a\nparallel ledger. The server supplies findings from ExpenseReceipt duplicate\nqueries and application history. Unknown labels render verbatim. No state or\naction is inferred: `canReview`, `action`, `actions` and hidden fingerprints\nexplicitly provide a native review form. `action=\"\"` posts to the current page;\nomitting `action` hides the review form; `children` can supply retained reason\nor duplicate-selection inputs. A server must reauthorize, reload the model and\ninvoke `review()`, `reject()`, `markDuplicate()` or `reopen()` under its policy.\nNever assign review fields through UI payload binding. Reviewed money remains\nfrozen by the existing model; UI props cannot bypass it.\n\n`receipts` is exactly the public Assets `AttachmentPanelProps`, supporting\nprivate view/download URLs, version notes, native upload and recovery. It is\nrendered outside the review form so upload and review remain separate native\nactions. Use authorized receipt projections; attaching a file does not review\nan expense, mark a duplicate, or change invoice approval. Assets owns file\nselection and reselect-file help; Expenses does not duplicate uploads/storage.\n\nValidation: `pnpm --filter @happyvertical/smrt-expenses test`, `test:ui`,\n`test:e2e`, `typecheck`, `build`, and `verify:pack`. PostgreSQL model validation\nremains in the existing opt-in `test:postgres` lane; this UI does not alter it.\n\n`visibleFields` optionally limits the logical `ExpenseDraftValues` fields rendered by `ExpenseForm`. Omitted renders all existing fields; an empty array renders none. Excluded fields do not emit hidden fallbacks, including `correctionReason`; fixed values can be supplied explicitly through `hiddenFields` without duplicate names. This supports policy-fixed payer fields and domain-owned reference selectors. Visibility is presentation, never authority: endpoints must validate every fixed or submitted value. Unknown retained values and validation errors remain visible for included fields.\n\nComposition validation: native Svelte SSR contracts cover defaults, omitted fields, retained malformed values, caller identity, no duplicate fixed inputs, correction/read-only/pending behavior. No persistence, transaction, tenant authority or external provider changes occur; those matrix dimensions are N/A for this presentation-only extension. Node26/Svelte5 native POST markup is the supported runtime edge.\n\n## Cost-object lifecycle (#3462)\n\nThe existing #3423/#3429 entry and review controls are extended with\n`ExpenseList`, `ExpenseReceiptCapture` and `ExpenseReviewQueue` in the same\n`./svelte` export. Their registry slots are `expense-list`,\n`expense-receipt-capture` and `expense-review-queue`; named Props and row types\nare public. The playground composes these with the existing controls.\n\n`ExpenseForm` defaults to an optional touch keypad beside amount entry. It is\navailable after hydration, with ordinary text/keyboard entry and native POST\navailable without JavaScript. `amountKeypad=false` hides it. Digits, decimal and\nbackspace edit the exact currency-unit string at its selection; no parsing or\nrounding occurs. The server validates currency precision and safe minor units.\n`costObject={{ type, id }}` enables two editable native reference inputs, with\n`costObjectFields` name adapters and `costObjectErrors` retained server errors.\nOmit it when references are fixed in `hiddenFields` (the existing consumer\ncontract). Do not supply the same reference both ways. Qualified type and bare\nid are caller strings and must be validated/authorized by the endpoint.\n\n`ExpenseList` takes caller-authorized `ExpenseListItem[]` plus exact\n`costObjectType`/`costObjectId`; both keys must match. It displays each amount\nin its own currency, never sums different currencies, and retains unknown\n`statusLabel`, optional `note`, authorized `href`, empty and load-error states.\nFiltering is presentation only: do not pass unauthorized rows to the browser.\n\n`ExpenseReceiptCapture` is a separate multipart POST action, with\n`canAttach=false` by default. `fileField` defaults to `receipt`, submitter to\n`intent=attach-receipt`. It forwards `hiddenFields` exactly, including the\nexpense and caller-owned request tokens. A native file picker works without\nJavaScript; “Use camera” mounts the existing smrt-ui `CameraCapture` only after\nan explicit click. Capture/retake/commit and stream cleanup are owned by that\nshared component. Toggle back to file selection to recover from camera denial\nor unsupported APIs. Switching modes discards the previous file; selection is\nnever uploaded automatically. Pending prevents another upload or mode change;\na committed camera photo remains held for retry. Navigation cannot restore\nfile inputs: select the file again after a failed upload or page reload. The\nserver authenticates, validates file content/limits and expense visibility,\nstores the Asset and uses `ExpenseReceiptCollection.attachReceipt()` with its\nduplicate guard; this component performs no storage, deduplication or model\nmutation. Do not place this component inside another form.\n\n`ExpenseReviewQueue` takes authorized `ExpenseReviewQueueItem[]` in caller order.\nDecisions require both queue `canReview=true`, row `canReview=true`, and a row\n`action` (empty string explicitly means this page). Each row posts its own\n`expenseId`, retained `reason`, hidden request context and clicked\n`intent=approve|reject`. Field and intent names are configurable. Rejection\nrequires a reason in native browser validation; approval bypasses that browser\nrequirement. The server must enforce the reason and reauthorize/reload before\ncalling `review()` or `reject()`; these UI gates provide no authority. Return\nrow `reason`, `message` and original request tokens after rejection or an\nuncertain outcome. Pending disables decisions. No action is inferred from\nstatus, no submitted row is removed optimistically, and no request key rotates.\nAvoid collisions between hidden field names and component identity/reason/intent\nfields. Empty, read-only, unknown status and load-error states remain visible.\n\nLifecycle evidence is in the maintained `test:ui` SSR contracts and `test:e2e`\nChromium proofs: 390px keypad, exact cost-object payload, native multipart file\nselection with and without JavaScript, camera denial recovery, and native queue\napprove/reject with retained reason and row request identity. Persistence,\ntransaction affinity and tenant authorization remain existing server contracts;\nno database/model surface is changed by these presentation components.\n"
     }
   ],
+  "recipes": [
+    {
+      "id": "expenses.tracking",
+      "className": "ExpensesRecipe",
+      "label": "Expenses",
+      "summary": "Record what the business spends, with receipts, and review it.",
+      "synonyms": [
+        "costs",
+        "receipts",
+        "spending",
+        "reimbursements"
+      ],
+      "models": [
+        "@happyvertical/smrt-expenses:Expense",
+        "@happyvertical/smrt-expenses:ExpenseReceipt"
+      ],
+      "nav": [
+        {
+          "label": "Expenses",
+          "model": "@happyvertical/smrt-expenses:Expense",
+          "icon": "receipt",
+          "description": "Costs you have paid, with the receipt and who paid."
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "accounting",
+        "label": "Accounting",
+        "icon": "bank",
+        "description": "Your books: accounts, journals and balances."
+      },
+      "options": {
+        "@happyvertical/smrt-expenses:Expense": {
+          "fields": {
+            "description": {
+              "order": 1,
+              "required": true
+            },
+            "amount": {
+              "order": 2
+            },
+            "currency": {
+              "order": 3
+            },
+            "incurredOn": {
+              "label": "Date",
+              "order": 4,
+              "help": "The date on the receipt, as YYYY-MM-DD."
+            },
+            "category": {
+              "order": 5,
+              "help": "One word, such as material, travel, freight or other."
+            },
+            "vendorId": {
+              "label": "Vendor",
+              "order": 6
+            },
+            "paidBy": {
+              "order": 7
+            },
+            "paidByProfileId": {
+              "label": "Person who paid",
+              "order": 8,
+              "help": "Who paid out of their own pocket, when a person paid."
+            },
+            "paidByName": {
+              "order": 9
+            },
+            "reimbursable": {
+              "order": 10
+            },
+            "costObjectId": {
+              "label": "Charged to",
+              "order": 11,
+              "help": "The job, project or client the cost belongs to."
+            },
+            "costObjectType": {
+              "visibility": "hidden"
+            },
+            "financialBreakdown": {
+              "visibility": "hidden"
+            },
+            "refundOfId": {
+              "visibility": "hidden"
+            },
+            "recordedByProfileId": {
+              "visibility": "hidden"
+            },
+            "commitmentId": {
+              "visibility": "hidden"
+            },
+            "commitmentLineId": {
+              "visibility": "hidden"
+            },
+            "reviewedByProfileId": {
+              "visibility": "hidden"
+            },
+            "duplicateOfId": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-expenses:ExpenseReceipt": {
+          "fields": {
+            "contentSha256": {
+              "visibility": "hidden"
+            },
+            "byteCount": {
+              "visibility": "hidden"
+            },
+            "uploadedByProfileId": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nExpenses are the costs the business pays: a receipt, who paid it and what it\nwas for. Each expense is reviewed once, and a reimbursable one is marked when\nthe person is paid back.\n\n## Tasks\n\n### Record an expense\n\n1. Create a new expense and write a short **{field:description}**.\n2. Enter the **{field:amount}** and its **{field:currency}**.\n3. Set the **{field:incurredOn}** date from the receipt and pick a\n   **{field:category}**.\n4. Choose who **{field:paidBy}**: the company, a person or a third party.\n5. When a person paid, pick the **{field:paidByProfileId}** and tick\n   **{field:reimbursable}** when they are owed the money back.\n\n### Review it\n\n1. Open the expense and check the receipt attached to it.\n2. **{field:reviewStatus}** moves from unreviewed to reviewed, or to rejected,\n   when someone reviews it. A rejected expense can be reopened.\n",
+        "fieldRefs": [
+          "amount",
+          "category",
+          "currency",
+          "description",
+          "incurredOn",
+          "paidBy",
+          "paidByProfileId",
+          "reimbursable",
+          "reviewStatus"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: node:crypto; and its package depends on @happyvertical/smrt-agents, @happyvertical/smrt-commerce, @happyvertical/smrt-jobs, @happyvertical/smrt-ledgers, @happyvertical/smrt-products, @happyvertical/smrt-profiles, @happyvertical/smrt-reports, @happyvertical/smrt-secrets, @happyvertical/smrt-subscriptions, @happyvertical/smrt-tenancy, @happyvertical/smrt-users, which do not build for a browser (#3615, #3616, #3617, #3624, #3625, #3626, #3627)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [
       "#3615",
+      "#3616",
+      "#3617",
       "#3624",
+      "#3625",
       "#3626",
       "#3627"
     ],
     "reason": "node:crypto",
     "via": [
+      "@happyvertical/smrt-agents",
       "@happyvertical/smrt-commerce",
       "@happyvertical/smrt-jobs",
       "@happyvertical/smrt-ledgers",
+      "@happyvertical/smrt-products",
+      "@happyvertical/smrt-profiles",
+      "@happyvertical/smrt-reports",
+      "@happyvertical/smrt-secrets",
       "@happyvertical/smrt-subscriptions",
-      "@happyvertical/smrt-tenancy"
+      "@happyvertical/smrt-tenancy",
+      "@happyvertical/smrt-users"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-expenses",
-  "version": "0.55.24",
+  "version": "0.56.1",
   "description": "Expense records for the SMRT framework - reviewed costs against a cost object, deduplicated receipts, and commitment drawdown",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,15 +33,16 @@
     }
   },
   "dependencies": {
-    "@happyvertical/smrt-assets": "0.55.24",
-    "@happyvertical/smrt-commerce": "0.55.24",
-    "@happyvertical/smrt-core": "0.55.24",
-    "@happyvertical/smrt-tenancy": "0.55.24",
-    "@happyvertical/smrt-types": "0.55.24",
-    "@happyvertical/smrt-ui": "0.55.24"
+    "@happyvertical/smrt-assets": "0.56.1",
+    "@happyvertical/smrt-commerce": "0.56.1",
+    "@happyvertical/smrt-core": "0.56.1",
+    "@happyvertical/smrt-tenancy": "0.56.1",
+    "@happyvertical/smrt-types": "0.56.1",
+    "@happyvertical/smrt-ui": "0.56.1",
+    "@happyvertical/smrt-users": "0.56.1"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.55.24",
+    "@happyvertical/smrt-vitest": "0.56.1",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
     "vite": "8.1.4",