@happyvertical/smrt-timesheets 0.56.0 → 0.56.2

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-timesheets",
-  "packageVersion": "0.56.0",
+  "packageVersion": "0.56.2",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "b5ad32209145ad0e72befacafda2eef579b565f2fb2052323522f03f0d1ed9b3",
-    "packageJson": "dc9177b3dcd6f28aad203d0e7c0be58abfbf863be6b93ff56486db7c62fea31f",
-    "agents": "5ea9c547ff79ab402ab8b1942e1760344bb312dbd9148e4435bb32e14dfecaf9",
+    "manifest": "758a908da24db7967e18896d23983514e45a4c5ee3df46e83113176bed939839",
+    "packageJson": "c349b624889d708bcfded901c47cb4fa444d32752994417f6809c27f4f4539b2",
+    "agents": "67979245cd75faa81e381084a73ab20fd166fbd875345a8c01e3a3da2ec8ffaf",
     "moduleDoc:agents/period-rollup.md": "7e693235a49e8354a8910f480cde8a7aecdc4f28afaa6d778fd4bfaf67119b46"
   },
   "exports": [
@@ -26,6 +26,7 @@
     "@happyvertical/smrt-tenancy": "workspace:*",
     "@happyvertical/smrt-types": "workspace:*",
     "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/smrt-users": "workspace:*",
     "@happyvertical/sql": "catalog:",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@sveltejs/package": "^2.5.8",
@@ -42,6 +43,7 @@
     "@happyvertical/smrt-tenancy",
     "@happyvertical/smrt-types",
     "@happyvertical/smrt-ui",
+    "@happyvertical/smrt-users",
     "@happyvertical/smrt-vitest"
   ],
   "sdkDependencies": [
@@ -1293,7 +1295,6 @@
       "name": "ServiceChargeSnapshotCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:ServiceChargeSnapshotCollection",
       "collection": "servicechargesnapshots",
-      "description": "Collection over service_charge_snapshots.",
       "tableName": "service_charge_snapshots",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -1311,7 +1312,6 @@
       "name": "ServiceCompensationSnapshotCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:ServiceCompensationSnapshotCollection",
       "collection": "servicecompensationsnapshots",
-      "description": "Collection over service_compensation_snapshots.",
       "tableName": "service_compensation_snapshots",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -1711,10 +1711,21 @@
       "fields": [],
       "relationships": [],
       "methods": [
+        "approve",
         "forWork",
-        "pendingApproval"
+        "pendingApproval",
+        "record",
+        "submit"
       ],
       "methodSignatures": [
+        {
+          "name": "approve",
+          "async": true,
+          "params": [
+            "options: ServiceTimeEntryActionTarget"
+          ],
+          "returns": "Promise<ServiceTimeEntry>"
+        },
         {
           "name": "forWork",
           "async": true,
@@ -1728,36 +1739,64 @@
           "name": "pendingApproval",
           "async": true,
           "returns": "Promise<ServiceTimeEntry[]>"
+        },
+        {
+          "name": "record",
+          "async": true,
+          "params": [
+            "options: RecordServiceTimeActionInput"
+          ],
+          "returns": "Promise<ServiceTimeEntry>"
+        },
+        {
+          "name": "submit",
+          "async": true,
+          "params": [
+            "options: ServiceTimeEntryActionTarget"
+          ],
+          "returns": "Promise<ServiceTimeEntry>"
         }
       ],
       "surfaces": [
         {
           "kind": "api",
-          "name": "servicetimeentries.forWork",
-          "operation": "forWork",
+          "name": "servicetimeentries.record",
+          "operation": "record",
           "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
-          "path": "/servicetimeentries/forWork",
+          "path": "/servicetimeentries/record",
           "method": "POST"
         },
         {
           "kind": "api",
-          "name": "servicetimeentries.pendingApproval",
-          "operation": "pendingApproval",
+          "name": "servicetimeentries.submit",
+          "operation": "submit",
           "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
-          "path": "/servicetimeentries/pendingApproval",
+          "path": "/servicetimeentries/submit",
           "method": "POST"
         },
         {
-          "kind": "cli",
-          "name": "servicetimeentrycollection_forWork",
+          "kind": "api",
+          "name": "servicetimeentries.approve",
+          "operation": "approve",
+          "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
+          "path": "/servicetimeentries/approve",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "servicetimeentries.forWork",
           "operation": "forWork",
-          "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection"
+          "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
+          "path": "/servicetimeentries/forWork",
+          "method": "POST"
         },
         {
-          "kind": "cli",
-          "name": "servicetimeentrycollection_pendingApproval",
+          "kind": "api",
+          "name": "servicetimeentries.pendingApproval",
           "operation": "pendingApproval",
-          "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection"
+          "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
+          "path": "/servicetimeentries/pendingApproval",
+          "method": "POST"
         },
         {
           "kind": "mcp",
@@ -2548,31 +2587,43 @@
     },
     {
       "kind": "api",
-      "name": "servicetimeentries.forWork",
-      "operation": "forWork",
+      "name": "servicetimeentries.record",
+      "operation": "record",
       "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
-      "path": "/servicetimeentries/forWork",
+      "path": "/servicetimeentries/record",
       "method": "POST"
     },
     {
       "kind": "api",
-      "name": "servicetimeentries.pendingApproval",
-      "operation": "pendingApproval",
+      "name": "servicetimeentries.submit",
+      "operation": "submit",
       "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
-      "path": "/servicetimeentries/pendingApproval",
+      "path": "/servicetimeentries/submit",
       "method": "POST"
     },
     {
-      "kind": "cli",
-      "name": "servicetimeentrycollection_forWork",
+      "kind": "api",
+      "name": "servicetimeentries.approve",
+      "operation": "approve",
+      "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
+      "path": "/servicetimeentries/approve",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "servicetimeentries.forWork",
       "operation": "forWork",
-      "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection"
+      "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
+      "path": "/servicetimeentries/forWork",
+      "method": "POST"
     },
     {
-      "kind": "cli",
-      "name": "servicetimeentrycollection_pendingApproval",
+      "kind": "api",
+      "name": "servicetimeentries.pendingApproval",
       "operation": "pendingApproval",
-      "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection"
+      "objectName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
+      "path": "/servicetimeentries/pendingApproval",
+      "method": "POST"
     },
     {
       "kind": "mcp",
@@ -2596,7 +2647,7 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 92
   },
-  "agentDoc": "# smrt-timesheets\n\nShared time entries: who (a `smrt-profiles` Profile, or an agent) worked how\nlong on what (a generic work reference), whether it was approved, and the\nimmutable charge / compensation snapshots taken at approval. Moved out of\n`smrt-projects` / `smrt-support` in #3288 so shops, builders, and service\ndesks share one model instead of re-implementing it.\n\nThis package contains **layer 1 (entry)**, **layer 2 (attendance)**, and\n**layer 3 (period rollup)**.\n`src/attendance/` owns punches, breaks, atomic transitions and durable offline\nreceipts; `./attendance` is the public subpath. Period rollup belongs in this\npackage too, never projects or support. See the README attendance contract.\nAttendance services accept trusted session actors, serialize mutations per\nactor, and bind every write to one executor. The new tables use non-null unique\nopen slots, not nullable unique keys. A linked entry is draft evidence, and\nrollups must deduplicate `AttendancePunch.serviceTimeEntryId`.\n`AttendanceSegment` (`attendance_segments`) is a running work interval inside a\npunch: queryable `workRef*`/`taskRef*`/`kind` columns, one open per punch\n(`openSlot`), closed by `startBreak`/`punchOut`/`autoClose`, never overlapping\nbreaks or each other, immutable once closed. It creates no `ServiceTimeEntry`.\nClosed punches, breaks and segments change only through\n`AttendanceCorrectionService` (`attendance/correction-service.ts`), which sets a\nper-instance capability (`attendance/write.ts`, not exported) that lifts the\nmodels' closed-interval checks for one save, validates the whole punch layout,\nrecomputes durations and appends an `AttendanceCorrection` (append-only ledger,\nno generated operations; only a first acknowledgement by the subject may update\na row). Never export `write.ts`. Punch `source`/`deviceRef*` and break `kind` are immutable except through corrections; `autoCloseReason` is write-once via `persistAutoClose`. A confirmed `PeriodTimecard` is honoured by the\nopt-in `confirmedTimecardGuard` (`rollup/correction-guard.ts`), which refuses\nwhile a card is submitted or confirmed. `PeriodRollupService.reopen()` returns\nsuch a card to `open` and appends a `TimecardReopening` (`timecard_reopenings`,\nappend-only, service-only via `rollup/write.ts`); `submit()` is the optional\nopen -> submitted step (`requireSubmission` makes it mandatory) (#3950).\nSegment transitions live in `attendance/segments.ts`; compose them with other\nattendance writes via `AttendanceService.withTransaction`. Any new attendance\ntable must be added to the `includeObjects` lists in the `*.optional.test.ts`\nfiles.\n\n## Models\n\n| Model | Table | Notes |\n|---|---|---|\n| `ServiceTimeEntry` | `service_time_entries` | `workRefType` + `workRefId`, `participantKind` (`human` \\| `agent`), `participantProfileId` / `agentRef`, `source`, `startedAt` / `endedAt` / `durationSeconds`, status machine, `correctionOfId` |\n| `ServiceChargeSnapshot` | `service_charge_snapshots` | Client charge, integer minor units (#2401), one per entry |\n| `ServiceCompensationSnapshot` | `service_compensation_snapshots` | Provider earning, integer minor units, one per entry |\n\n`ServiceEvidenceService` records, submits, approves (writing both snapshots\nthrough a `ServiceCommercialResolver`), and corrects. `smrt-projects` supplies\n`SubscriptionServiceCommercialResolver` for #1925 pricing.\n\n## Invariants\n\n- **No domain foreign key on the base.** Work context is the generic\n  `workRefType` (qualified class name) + `workRefId`. A domain adds its own\n  context by subclassing over the same table — smrt-support's\n  `ServiceTimeEntry` adds `caseId` / `specialistId` and extends\n  `frozenFieldNames()` so they freeze on approval.\n- **Entries carry no rate.** Money lives only on the snapshots, `= 0`\n  integer initializers (INTEGER columns). Never `= 0.0`. Snapshot `save()`\n  rejects an `amount` that is not a safe integer (`VALIDATION_INVALID_VALUE`),\n  so SQLite cannot silently store `19.99`; fix a fractional resolver at its\n  source rather than rounding here.\n- **Approved evidence never changes.** `save()` enforces\n  `SERVICE_TIME_ENTRY_STATUS_TRANSITIONS` and compares the frozen fields with\n  the stored row. A correction is a new row (`correctionOfId`), the original\n  flips to `corrected`. Snapshots are immutable after their first save.\n- **Old qualified names are aliases.** Each model declares its pre-#3288\n  `@happyvertical/smrt-projects:*` name in `previousQualifiedNames` (#3338;\n  `packages/core/agents/model-moves.md`). smrt-projects must never list these\n  classes in its manifests again (`CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`),\n  and no subtype (smrt-support's, or a consumer's closing subclass) may\n  redeclare an alias (two claimants). Known gap: a same-named subtype that\n  replaces a moved class drops that class's alias, and the replaced class's\n  own `@happyvertical/smrt-timesheets:*` name stops resolving too — guidance\n  for apps with smrt-support must name `@happyvertical/smrt-support:ServiceTimeEntry`.\n  Support's vitest environment keeps both classes registered, so verify this\n  against built packages, not package tests. `projects/src/__tests__/legacy-qualified-identity.test.ts` pins\n  the projects-only contract.\n- **Table names are a compatibility contract.** `service_time_entries` and the\n  two snapshot tables hold existing production rows from smrt-projects /\n  smrt-support; renaming any of them, or adding a discriminator, is a data\n  migration.\n\n## One table family\n\nClasses may share a table only as one inheritance chain. Core resolves\nsame-named subclasses by constructor ancestry at runtime and qualified manifest\nancestry at build registration; the deepest subtype wins across N levels.\nSibling or unrelated types cannot share the table. `smrt-projects` re-exports\nthe base; `smrt-support` subclasses it directly.\n\nConsumers closing package routes should call\n`ObjectRegistry.registerOverride(qualifiedName, { api: false, mcp: false,\ncli: false, tenancy: { mode: 'required' } })` after importing the model and before\nconstructing transports. This tightens the existing registration without a new\nsubtype. See core's README for startup order, static route generation, and reset\nsemantics. `src/__tests__/consumer-closed-surface.test.ts` also covers existing\nmanifest subclass consumers. The snapshots' explicit `time_entry_id` conflict\nkey is not rewritten when a consumer requires tenancy; widening it remains a\nconsumer schema change.\n\nSubclasses restate their fields: package-isolated manifest scanning does not\nread dependency sources, so an unrestated subclass manifest has no columns.\n\n## Svelte UI\n\n`./svelte` exports `TimeEntryCard`, `TimeEntryList`, `TimeSummary`,\n`DurationDisplay`, and `TimeEntryApprovalQueue` (props-driven, plain view\nobjects, `smrt-ui` primitives, `smrtRawPrimitives: \"strict\"`). smrt-projects\nand smrt-support re-export them from their own `./svelte` subpaths.\nCard/list/summary message keys keep their `projects.*` namespace: tenant\nlanguage overrides are stored by key, and renaming would orphan them. New\nkeys use `timesheets.*`.\n\nDisplay components keep the legacy one-decimal hours format by default. A\nconsumer that retains more precise source evidence supplies `hoursFormatter`;\ncard/list/queue detail snippets carry domain evidence without widening the base\nview. ApprovalQueue's optional action snippet replaces its callback controls so\nthe host can own a native form, request identity, authorization and retry flow.\nDisplay currency codes are open ISO strings and amounts remain integer minor\nunits; never put private rates into a view that should not expose them.\n\n## Validation\n\n```sh\npnpm --filter @happyvertical/smrt-timesheets test\npnpm --filter @happyvertical/smrt-timesheets test:postgres\npnpm --filter @happyvertical/smrt-timesheets typecheck\npnpm --filter @happyvertical/smrt-timesheets build\npnpm --filter @happyvertical/smrt-projects test\npnpm --filter @happyvertical/smrt-support test\n```\n\nSchema-affecting edits must keep `service-time-entry-compat.test.ts` (projects,\nsupport) and `service-time-entry-migration-plan.test.ts` (support) green: a\npre-move table must plan no DDL.\n\n## Period rollup\n\nLayer 3 lives under `src/rollup/` and the `./rollup` subpath. See\n[period-rollup.md](agents/period-rollup.md) for resolver, source clipping,\nconfirmation, attributed adjustments, isolation, and transaction contracts.\nTimecards and adjustments have closed generated surfaces and service-only\nmodel writes; never bypass the instance capability with generic persistence.\n\nReplay hashes the tap AS SENT (action, device `at`, paid, work, and `source`/`device`/`kind` only when present, so older receipts still match) so retries match;\n`replay(taps, { resolveAt, now, refusal })` only changes the stored time and\nreason. Never hash the resolved time. Work actions (`startWork`, `switchWork`,\n`stopWork`, `resumeWork`) run in the tap's transaction via `apply()`. Refusals store\n`code` from `AttendanceConflict.code`; give new conflicts a code.\n",
+  "agentDoc": "# smrt-timesheets\n\nShared time entries: who (a `smrt-profiles` Profile, or an agent) worked how\nlong on what (a generic work reference), whether it was approved, and the\nimmutable charge / compensation snapshots taken at approval. Moved out of\n`smrt-projects` / `smrt-support` in #3288 so shops, builders, and service\ndesks share one model instead of re-implementing it.\n\nThis package contains **layer 1 (entry)**, **layer 2 (attendance)**, and\n**layer 3 (period rollup)**.\n`src/attendance/` owns punches, breaks, atomic transitions and durable offline\nreceipts; `./attendance` is the public subpath. Period rollup belongs in this\npackage too, never projects or support. See the README attendance contract.\nAttendance services accept trusted session actors, serialize mutations per\nactor, and bind every write to one executor. The new tables use non-null unique\nopen slots, not nullable unique keys. A linked entry is draft evidence, and\nrollups must deduplicate `AttendancePunch.serviceTimeEntryId`.\n`AttendanceSegment` (`attendance_segments`) is a running work interval inside a\npunch: queryable `workRef*`/`taskRef*`/`kind` columns, one open per punch\n(`openSlot`), closed by `startBreak`/`punchOut`/`autoClose`, never overlapping\nbreaks or each other, immutable once closed. It creates no `ServiceTimeEntry`.\nClosed punches, breaks and segments change only through\n`AttendanceCorrectionService` (`attendance/correction-service.ts`), which sets a\nper-instance capability (`attendance/write.ts`, not exported) that lifts the\nmodels' closed-interval checks for one save, validates the whole punch layout,\nrecomputes durations and appends an `AttendanceCorrection` (append-only ledger,\nno generated operations; only a first acknowledgement by the subject may update\na row). Never export `write.ts`. Punch `source`/`deviceRef*` and break `kind` are immutable except through corrections; `autoCloseReason` is write-once via `persistAutoClose`. A confirmed `PeriodTimecard` is honoured by the\nopt-in `confirmedTimecardGuard` (`rollup/correction-guard.ts`), which refuses\nwhile a card is submitted or confirmed. `PeriodRollupService.reopen()` returns\nsuch a card to `open` and appends a `TimecardReopening` (`timecard_reopenings`,\nappend-only, service-only via `rollup/write.ts`); `submit()` is the optional\nopen -> submitted step (`requireSubmission` makes it mandatory) (#3950).\nSegment transitions live in `attendance/segments.ts`; compose them with other\nattendance writes via `AttendanceService.withTransaction`. Any new attendance\ntable must be added to the `includeObjects` lists in the `*.optional.test.ts`\nfiles.\n\n## Models\n\n| Model | Table | Notes |\n|---|---|---|\n| `ServiceTimeEntry` | `service_time_entries` | `workRefType` + `workRefId`, `participantKind` (`human` \\| `agent`), `participantProfileId` / `agentRef`, `source`, `startedAt` / `endedAt` / `durationSeconds`, status machine, `correctionOfId` |\n| `ServiceChargeSnapshot` | `service_charge_snapshots` | Client charge, integer minor units (#2401), one per entry |\n| `ServiceCompensationSnapshot` | `service_compensation_snapshots` | Provider earning, integer minor units, one per entry |\n\n`ServiceEvidenceService` records, submits, approves (writing both snapshots\nthrough a `ServiceCommercialResolver`), and corrects. `smrt-projects` supplies\n`SubscriptionServiceCommercialResolver` for #1925 pricing.\n\n## Generated write actions (#4001)\n\nGenerated CRUD writes stay closed. `ServiceTimeEntryCollection` hosts the only\ngenerated writes, `record` / `submit` / `approve` (`POST\n/servicetimeentries/<action>`, body `{ entryId }` for submit/approve), on REST\nonly; MCP and CLI stay read-only until per-operation MCP authorization (#4004).\n`services/time-entry-actions.ts` delegates each to `ServiceEvidenceService`, so\nthe trail and snapshots are set in one place. `services/action-principal.ts`\ntakes identity from the tenancy ALS, then the smrt-users session ALS, never the\nbody; authorizes `servicetimeentries.<action>` with `assertOperationPermission`\n(system context never bypasses; `approve` refuses super-admin bypass); and\nstamps the user's linked profile. Only the participant records/submits their\nown time unless the caller holds `approve`. `approve` prices with the host's\n`setServiceTimeEntryCommercialResolver()` — a factory called per request with\nthe collection's options, so a writing resolver shares the request executor;\nwithout one it is a 409 and writes nothing. The runtime REST transport gates\na collection-hosted action on the ITEM's `api.include`, SvelteKit on the\ncollection's, so both list the actions;\na consumer closing them overrides both registrations. The collection and both\nsnapshot collections carry their own `@smrt()` surface: undecorated, they\npublished generated create/update/delete MCP tools. `reject` waits for #3994.\n\n## Recipe\n\n`src/recipes.ts` declares one `SmrtRecipe`, `timesheets.time-entries`\n(label \"Time entries\", section `work`), emitted into the built\n`manifest.json` and `smrt-knowledge.json` `recipes`. It shows\n`ServiceTimeEntry` alone, with the generic work reference, evidence, agent\nand approval-trail fields hidden; attendance and rollup models stay out of\nit. `status` and its trail are hidden and locked, and the help never says to\nset them: `save()` accepts a bare transition, so submit and approve must go\nthrough `ServiceEvidenceService` (the recipe declares no surface for that). Help lives in `src/time-entries.recipe.md` (#3591); keep it and the recipe\nin plain language. See [core recipes](../core/agents/recipes.md).\n\n## Invariants\n\n- **No domain foreign key on the base.** Work context is the generic\n  `workRefType` (qualified class name) + `workRefId`. A domain adds its own\n  context by subclassing over the same table — smrt-support's\n  `ServiceTimeEntry` adds `caseId` / `specialistId` and extends\n  `frozenFieldNames()` so they freeze on approval.\n- **Entries carry no rate.** Money lives only on the snapshots, `= 0`\n  integer initializers (INTEGER columns). Never `= 0.0`. Snapshot `save()`\n  rejects an `amount` that is not a safe integer (`VALIDATION_INVALID_VALUE`),\n  so SQLite cannot silently store `19.99`; fix a fractional resolver at its\n  source rather than rounding here.\n- **Approved evidence never changes.** `save()` enforces\n  `SERVICE_TIME_ENTRY_STATUS_TRANSITIONS` and compares the frozen fields with\n  the stored row. A correction is a new row (`correctionOfId`), the original\n  flips to `corrected`. Snapshots are immutable after their first save.\n- **Old qualified names are aliases.** Each model declares its pre-#3288\n  `@happyvertical/smrt-projects:*` name in `previousQualifiedNames` (#3338;\n  `packages/core/agents/model-moves.md`). smrt-projects must never list these\n  classes in its manifests again (`CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`),\n  and no subtype (smrt-support's, or a consumer's closing subclass) may\n  redeclare an alias (two claimants). Known gap: a same-named subtype that\n  replaces a moved class drops that class's alias, and the replaced class's\n  own `@happyvertical/smrt-timesheets:*` name stops resolving too — guidance\n  for apps with smrt-support must name `@happyvertical/smrt-support:ServiceTimeEntry`.\n  Support's vitest environment keeps both classes registered, so verify this\n  against built packages, not package tests. `projects/src/__tests__/legacy-qualified-identity.test.ts` pins\n  the projects-only contract.\n- **Table names are a compatibility contract.** `service_time_entries` and the\n  two snapshot tables hold existing production rows from smrt-projects /\n  smrt-support; renaming any of them, or adding a discriminator, is a data\n  migration.\n\n## One table family\n\nClasses may share a table only as one inheritance chain. Core resolves\nsame-named subclasses by constructor ancestry at runtime and qualified manifest\nancestry at build registration; the deepest subtype wins across N levels.\nSibling or unrelated types cannot share the table. `smrt-projects` re-exports\nthe base; `smrt-support` subclasses it directly.\n\nConsumers closing package routes should call\n`ObjectRegistry.registerOverride(qualifiedName, { api: false, mcp: false,\ncli: false, tenancy: { mode: 'required' } })` after importing the model and before\nconstructing transports. This tightens the existing registration without a new\nsubtype. See core's README for startup order, static route generation, and reset\nsemantics. `src/__tests__/consumer-closed-surface.test.ts` also covers existing\nmanifest subclass consumers. The snapshots' explicit `time_entry_id` conflict\nkey is not rewritten when a consumer requires tenancy; widening it remains a\nconsumer schema change.\n\nSubclasses restate their fields: package-isolated manifest scanning does not\nread dependency sources, so an unrestated subclass manifest has no columns.\n\n## Svelte UI\n\n`./svelte` exports `TimeEntryCard`, `TimeEntryList`, `TimeSummary`,\n`DurationDisplay`, and `TimeEntryApprovalQueue` (props-driven, plain view\nobjects, `smrt-ui` primitives, `smrtRawPrimitives: \"strict\"`). smrt-projects\nand smrt-support re-export them from their own `./svelte` subpaths.\nCard/list/summary message keys keep their `projects.*` namespace: tenant\nlanguage overrides are stored by key, and renaming would orphan them. New\nkeys use `timesheets.*`.\n\nDisplay components keep the legacy one-decimal hours format by default. A\nconsumer that retains more precise source evidence supplies `hoursFormatter`;\ncard/list/queue detail snippets carry domain evidence without widening the base\nview. ApprovalQueue's optional action snippet replaces its callback controls so\nthe host can own a native form, request identity, authorization and retry flow.\nDisplay currency codes are open ISO strings and amounts remain integer minor\nunits; never put private rates into a view that should not expose them.\n\n## Validation\n\n```sh\npnpm --filter @happyvertical/smrt-timesheets test\npnpm --filter @happyvertical/smrt-timesheets test:postgres\npnpm --filter @happyvertical/smrt-timesheets typecheck\npnpm --filter @happyvertical/smrt-timesheets build\npnpm --filter @happyvertical/smrt-projects test\npnpm --filter @happyvertical/smrt-support test\n```\n\nSchema-affecting edits must keep `service-time-entry-compat.test.ts` (projects,\nsupport) and `service-time-entry-migration-plan.test.ts` (support) green: a\npre-move table must plan no DDL.\n\n## Period rollup\n\nLayer 3 lives under `src/rollup/` and the `./rollup` subpath. See\n[period-rollup.md](agents/period-rollup.md) for resolver, source clipping,\nconfirmation, attributed adjustments, isolation, and transaction contracts.\nTimecards and adjustments have closed generated surfaces and service-only\nmodel writes; never bypass the instance capability with generic persistence.\n\nReplay hashes the tap AS SENT (action, device `at`, paid, work, and `source`/`device`/`kind` only when present, so older receipts still match) so retries match;\n`replay(taps, { resolveAt, now, refusal })` only changes the stored time and\nreason. Never hash the resolved time. Work actions (`startWork`, `switchWork`,\n`stopWork`, `resumeWork`) run in the tap's transaction via `apply()`. Refusals store\n`code` from `AttendanceConflict.code`; give new conflicts a code.\n",
   "moduleDocs": [
     {
       "path": "agents/period-rollup.md",
@@ -2604,14 +2655,159 @@
       "content": "# Period timecards\n\n`@happyvertical/smrt-timesheets/rollup` exports `PeriodRollupService`,\n`PeriodTimecard`, `TimecardAdjustment`, their collections, and resolver types.\nThe package root also exports them. SQLite and PostgreSQL are supported.\nCreate application tables through normal migrations; neither service provisions\nschema. The attendance option additionally requires the attendance tables.\n\nConstruct a service only after authenticating and authorizing its trusted\n`{ tenantId, profileId }` scope. A conflicting ambient tenant is rejected.\n`options.actorProfileId` records a separately authorized supervisor; it defaults\nto the subject profile for self confirmation/correction. Never accept this\ntrusted scope or attribution unchecked from request input. Profile authorization\nis consumer-owned; the service filters every source/card/adjustment read by its\ntrusted subject and tenant. Generic API, CLI and MCP surfaces are closed by\ndefault; consumer registry overrides may further restrict them (#3318).\n\n## Resolver contract\n\n`periodFor(at, actor)` supplies half-open UTC `startsAt`/`endsAt`, an IANA\n`timezone`, a nonempty policy `version`, and a JSON `rules` snapshot.\nThe consumer owns period length, calendar start day, timezone and DST, overtime\nthresholds, holidays and classification. The requested instant must be inside\nthe window. Overlapping windows for existing cards are rejected: introduce a new\ncalendar at a boundary after existing windows, and use adjustments for already\nconfirmed periods.\n\n`classify(period, sources, actor)` returns nonnegative safe integer\n`regularSeconds` and `overtimeSeconds`, whose sum must equal source seconds.\nInputs are detached so resolver mutation cannot rewrite evidence. Resolver\nexceptions, malformed windows, invalid timezone, fractional/unsafe totals and\nnonconserving classification abort the transaction. No Alberta or other\njurisdiction rule is assumed, and no pay rate or money is stored.\n\nA configurable UTC calendar example (illustrative policy, not payroll advice):\n\n```ts\nimport { PeriodRollupService, type PeriodRulesResolver } from\n  '@happyvertical/smrt-timesheets/rollup';\n\nconst settings = {\n  lengthDays: 14, startDay: 1, timezone: 'UTC', // 0 = Sunday\n  anchor: '2026-01-05T00:00:00Z', // aligned Monday; anchors fortnight phase\n  thresholdSeconds: 80 * 3600,\n  holidays: ['2026-12-25'],\n};\nconst resolver: PeriodRulesResolver = {\n  async periodFor(at) {\n    const anchor = new Date(settings.anchor);\n    if (anchor.getUTCDay() !== settings.startDay || settings.timezone !== 'UTC')\n      throw new Error('Use a timezone-aware calendar resolver for local periods');\n    const length = settings.lengthDays * 86400000;\n    const start = anchor.getTime() +\n      Math.floor((at.getTime() - anchor.getTime()) / length) * length;\n    return {\n      startsAt: new Date(start), endsAt: new Date(start + length),\n      timezone: settings.timezone, version: 'shop-policy-v1', rules: settings,\n    };\n  },\n  async classify(period, sources) {\n    const rules = period.rules as typeof settings;\n    // This example assigns a contribution to its clipped start's UTC date.\n    // Local daily rules should split contributions at their own local midnight.\n    let regular = 0;\n    let holiday = 0;\n    for (const source of sources) {\n      if (rules.holidays.includes(source.startsAt.slice(0, 10))) holiday += source.seconds;\n      else regular += source.seconds;\n    }\n    return {\n      regularSeconds: Math.min(regular, rules.thresholdSeconds),\n      overtimeSeconds: holiday + Math.max(0, regular - rules.thresholdSeconds),\n    };\n  },\n};\nconst rollups = new PeriodRollupService(db, authorizedSubject, resolver,\n  { attendance: true, actorProfileId: authenticatedSupervisorProfileId });\nconst card = await rollups.rollup(new Date());\nawait rollups.confirm(card.id!);\nawait rollups.adjust(card.id!, {\n  operationId: requestId, regularSeconds: 900, overtimeSeconds: 0,\n  reason: 'Approved correction after confirmation',\n});\nconst effectiveSeconds = await rollups.totals(card.id!);\n```\n\nA timezone-aware resolver must compute each local boundary separately: a local\nday crossing DST is not necessarily 86400 seconds. Resolvers can use an app's\nexisting calendar library; no new timezone dependency or implicit default is\nintroduced here.\n\n## Evidence and immutability\n\nDecimal-hours-only entries have no measured integer seconds. The seconds-only\nrollup rejects these sources explicitly when their approval instant falls in the\nrequested period; it never rounds them or counts null as\nzero. Use an hours-aware consumer policy for that source representation.\n\nOnly approved human `ServiceTimeEntry` rows for the subject count; corrected\nancestors do not. Correction chains must remain within that subject/tenant and\npoint to corrected parents. Multiple approved descendants of one root are\nrejected as ambiguous rather than double-counted. Entries with both `startedAt`\nand `endedAt` allocate their declared seconds\nproportionally across the period using exact integer prefix division, preserving\nseconds over adjacent periods. Unbounded entries count at `startedAt`, or, when\nabsent, `approvedAt`; an end-only timestamp does not create an interval. Missing\nboth attribution timestamps is an error. This is time attribution, not a\nclaim that a manual entry has a continuous wall-clock duration.\n\nWith `attendance: true`, closed punches without `reviewRequired` count, excluding\nunpaid breaks and retaining paid breaks. Open/review-required punches do not\ncount. Linked attendance is authoritative: its evidence entry and any approved\ncorrection descendants are excluded, including when the punch is still under\nreview or outside the requested period. Unlinked approved work entries and\nattendance both count; consumers must link overlapping evidence explicitly.\nSource snapshots preserve each paid attendance segment and entry identity.\n\nRepeated rollup updates one open card per tenant/person/start; a confirmed card\ncannot be recomputed. Confirmation is attributed and idempotent. Model save,\ncollection create/update/upsert and object/collection delete cannot bypass the\nservice. Model mutation capabilities are per-instance and not exported.\nDirect SQL is a trusted administrative boundary, not an exposed application API.\nProfile/card foreign keys restrict deletion to preserve history.\n\nAdjustments contain signed integer regular/overtime deltas, reason, operation\nkey and actor attribution. A retry reuses its row only for the exact same\npayload and actor. Effective totals may never become negative or unsafe.\nAdjustments never alter the confirmed row or source snapshot. Undo an adjustment\nwith a separately attributed compensating adjustment, never deletion.\n\nAll service mutations use a root transaction, transaction-bound collections,\nembedded writer serialization or a PostgreSQL tenant/person advisory lock.\nOutputs are reloaded on the root executor after commit. Rollup reads are an\napplication snapshot: subsequent source approvals/corrections appear on the\nnext open rollup, and confirmed cards require explicit adjustments.\n\n## Lifecycle: submit, confirm, reopen (#3950)\n\n`open` (draft) -> `submitted` (optional) -> `confirmed`. `submit(id)` freezes an\nopen card for review; `confirm(id)` accepts an open card too unless the service\nis built with `{ requireSubmission: true }`. Submitted and confirmed cards are\nnot re-rolled.\n\n`reopen(id, { operationId, reason })` returns a submitted or confirmed card to\n`open` (clearing its submission/confirmation attribution) and appends a\n`TimecardReopening`: actor, reason, prior status and a JSON snapshot of the\nprevious base, adjustment and effective seconds (`getPrevious()`). It is\nidempotent per `operationId` and refuses a blank reason. `reopenings(id)` lists\nthe history. The consumer authorizes the actor; give reopening its own\npermission. Existing adjustments stay and keep counting in `totals()`: after a\nre-roll, offset ones the correction made redundant with a new adjustment.\n`confirmedTimecardGuard` refuses corrections while a card is submitted or\nconfirmed and allows them once it is reopened. The new `timecard_reopenings`\ntable, and nullable `submitted_at`/`submitted_by_profile_id` columns on\n`period_timecards`, need a migration.\n"
     }
   ],
+  "recipes": [
+    {
+      "id": "timesheets.time-entries",
+      "className": "TimeEntriesRecipe",
+      "label": "Time entries",
+      "summary": "Record who worked how long on what, for approval.",
+      "synonyms": [
+        "timesheets",
+        "time tracking",
+        "hours",
+        "billable hours",
+        "timecards"
+      ],
+      "models": [
+        "@happyvertical/smrt-timesheets:ServiceTimeEntry"
+      ],
+      "nav": [
+        {
+          "label": "Time entries",
+          "model": "@happyvertical/smrt-timesheets:ServiceTimeEntry",
+          "icon": "fileText",
+          "description": "Hours worked, by person and by job, from draft to approved."
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "work",
+        "label": "Work",
+        "icon": "wrench",
+        "description": "Time and costs: the work behind each job."
+      },
+      "options": {
+        "@happyvertical/smrt-timesheets:ServiceTimeEntry": {
+          "fields": {
+            "participantProfileId": {
+              "label": "Person",
+              "order": 1
+            },
+            "description": {
+              "order": 2,
+              "help": "What the time was spent on, in a few words."
+            },
+            "startedAt": {
+              "label": "Started",
+              "order": 3
+            },
+            "endedAt": {
+              "label": "Ended",
+              "order": 4
+            },
+            "durationSeconds": {
+              "label": "Duration (seconds)",
+              "order": 5,
+              "help": "Whole seconds: 3600 is one hour."
+            },
+            "workRefId": {
+              "label": "Work reference",
+              "order": 6,
+              "help": "The job, project or case this time belongs to."
+            },
+            "workRefType": {
+              "visibility": "hidden"
+            },
+            "participantKind": {
+              "default": "human",
+              "visibility": "hidden"
+            },
+            "agentRef": {
+              "visibility": "hidden"
+            },
+            "source": {
+              "default": "manual",
+              "visibility": "hidden"
+            },
+            "evidence": {
+              "visibility": "hidden"
+            },
+            "status": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "submittedAt": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "submittedByProfileId": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "approvedAt": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "approvedByProfileId": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "approvalPath": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "rejectedAt": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "rejectedByProfileId": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "rejectionReason": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "correctionOfId": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nTime entries record who worked how long on what. Each entry names the person,\nwhat they did and when, and moves from draft to submitted to approved.\n\n## Tasks\n\n### Record time\n\n1. Create a new time entry.\n2. Pick the **{field:participantProfileId}** who did the work.\n3. Write a short **{field:description}** of what was done.\n4. Enter when it **{field:startedAt}** and **{field:endedAt}**, or type the\n   **{field:durationSeconds}** directly (3600 is one hour).\n\n### Send it for approval\n\nApproval is not something you change on this form. It runs through your\napp's approval screen, which records who did each step and when.\n\n1. When an entry is ready to check, the person who did the work submits it.\n2. An approver, someone your app allows to approve time, approves it or sends\n   it back with a reason. Approving fixes what the hours are charged and paid\n   at, so an approved entry never changes; correct it with a new entry.\n3. If your app has no approval screen yet, entries stay as drafts until one is\n   added.\n",
+        "fieldRefs": [
+          "description",
+          "durationSeconds",
+          "endedAt",
+          "participantProfileId",
+          "startedAt"
+        ]
+      },
+      "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-profiles, @happyvertical/smrt-tenancy, @happyvertical/smrt-users, which do not build for a browser (#3617, #3624, #3626)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [
-      "#3624"
+      "#3617",
+      "#3624",
+      "#3626"
     ],
     "reason": "node:crypto",
     "via": [
-      "@happyvertical/smrt-tenancy"
+      "@happyvertical/smrt-profiles",
+      "@happyvertical/smrt-tenancy",
+      "@happyvertical/smrt-users"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-timesheets",
-  "version": "0.56.0",
+  "version": "0.56.2",
   "smrtJsdoc": "strict",
   "description": "Shared time entries for the SMRT framework: who worked how long on what, approval and correction, with immutable charge and compensation snapshots",
   "type": "module",
@@ -39,11 +39,12 @@
     }
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.56.0",
-    "@happyvertical/smrt-tenancy": "0.56.0",
-    "@happyvertical/smrt-types": "0.56.0",
-    "@happyvertical/smrt-ui": "0.56.0",
-    "@happyvertical/sql": "^0.103.6"
+    "@happyvertical/smrt-core": "0.56.2",
+    "@happyvertical/smrt-tenancy": "0.56.2",
+    "@happyvertical/smrt-types": "0.56.2",
+    "@happyvertical/smrt-ui": "0.56.2",
+    "@happyvertical/smrt-users": "0.56.2",
+    "@happyvertical/sql": "^0.103.7"
   },
   "peerDependencies": {
     "svelte": "^5.57.0"
@@ -54,7 +55,7 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.56.0",
+    "@happyvertical/smrt-vitest": "0.56.2",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",