@happyvertical/smrt-timesheets 0.55.6 → 0.55.8

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-timesheets",
-  "packageVersion": "0.55.6",
+  "packageVersion": "0.55.8",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "dca77590390720e2538030f3de93961230cdbffeb295bf70856666998768c05e",
-    "packageJson": "b5603254e13ce010538aa70aa50285fca380f95904a423d1717b9172103b2883",
+    "manifest": "692d7363f11574b95c854605f49dd62c91e02a539c1a969498b2449a31873b4e",
+    "packageJson": "2263f0db0c684223c4f6ea65602f43c114a6aa3b52d51d0e33282017eebf2b1e",
     "agents": "46a4e8437424b494645e90ce4a4869be04956c5da6a42f89697cbd3ab2199a7e",
     "moduleDoc:agents/period-rollup.md": "5fb741659d81dbef2e4850c10c2d65f09e3f5a83e8a88e2e0f19585f25158a6a"
   },
@@ -65,6 +65,7 @@
       "name": "AttendancePunch",
       "qualifiedName": "@happyvertical/smrt-timesheets:AttendancePunch",
       "collection": "attendancepunches",
+      "description": "A tenant-scoped interval of attendance, independent of billable work.",
       "tableName": "attendance_punches",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -235,6 +236,7 @@
       "name": "AttendanceBreak",
       "qualifiedName": "@happyvertical/smrt-timesheets:AttendanceBreak",
       "collection": "attendancebreaks",
+      "description": "A paid or unpaid break inside one attendance punch.",
       "tableName": "attendance_breaks",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -369,6 +371,7 @@
       "name": "AttendanceReplay",
       "qualifiedName": "@happyvertical/smrt-timesheets:AttendanceReplay",
       "collection": "attendancereplays",
+      "description": "Durable offline-tap outcome; never exposed through generated operations.",
       "tableName": "attendance_replays",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -466,6 +469,7 @@
       "name": "AttendancePunchCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:AttendancePunchCollection",
       "collection": "attendancepunches",
+      "description": "Punches for attendance and period rollup.",
       "tableName": "attendance_punches",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -483,6 +487,7 @@
       "name": "AttendanceBreakCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:AttendanceBreakCollection",
       "collection": "attendancebreaks",
+      "description": "Break intervals for net duration and period clipping.",
       "tableName": "attendance_breaks",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -500,6 +505,7 @@
       "name": "AttendanceReplayCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:AttendanceReplayCollection",
       "collection": "attendancereplays",
+      "description": "Internal durable replay ledger.",
       "tableName": "attendance_replays",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -520,6 +526,7 @@
         "@happyvertical/smrt-projects:ServiceChargeSnapshot"
       ],
       "collection": "servicechargesnapshots",
+      "description": "Immutable client-charge snapshot for one approved time entry. Money is integer minor units, consistent with smrt-commerce (#2401).",
       "tableName": "service_charge_snapshots",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -686,6 +693,7 @@
         "@happyvertical/smrt-projects:ServiceCompensationSnapshot"
       ],
       "collection": "servicecompensationsnapshots",
+      "description": "Immutable provider-compensation snapshot for one approved time entry, kept separate from the client charge so the margin is charge - compensation.",
       "tableName": "service_compensation_snapshots",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -837,6 +845,7 @@
       "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",
@@ -854,6 +863,7 @@
       "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",
@@ -874,6 +884,7 @@
         "@happyvertical/smrt-projects:ServiceTimeEntry"
       ],
       "collection": "servicetimeentries",
+      "description": "A person or agent worked this long on this thing, and someone approved it.",
       "tableName": "service_time_entries",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -1245,6 +1256,7 @@
       "name": "ServiceTimeEntryCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:ServiceTimeEntryCollection",
       "collection": "servicetimeentries",
+      "description": "Collection over service_time_entries.",
       "tableName": "service_time_entries",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -1322,6 +1334,7 @@
       "name": "PeriodTimecard",
       "qualifiedName": "@happyvertical/smrt-timesheets:PeriodTimecard",
       "collection": "periodtimecards",
+      "description": "One person's immutable-on-confirmation period snapshot, in integer seconds.",
       "tableName": "period_timecards",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -1503,6 +1516,7 @@
       "name": "TimecardAdjustment",
       "qualifiedName": "@happyvertical/smrt-timesheets:TimecardAdjustment",
       "collection": "timecardadjustments",
+      "description": "Attributed append-only signed seconds; the confirmed base card never changes.",
       "tableName": "timecard_adjustments",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtObject",
@@ -1632,6 +1646,7 @@
       "name": "PeriodTimecardCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:PeriodTimecardCollection",
       "collection": "periodtimecards",
+      "description": "Scoped persistence collection; mutations must use PeriodRollupService.",
       "tableName": "period_timecards",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -1649,6 +1664,7 @@
       "name": "TimecardAdjustmentCollection",
       "qualifiedName": "@happyvertical/smrt-timesheets:TimecardAdjustmentCollection",
       "collection": "timecardadjustments",
+      "description": "Scoped append-only adjustment collection.",
       "tableName": "timecard_adjustments",
       "packageName": "@happyvertical/smrt-timesheets",
       "extends": "SmrtCollection",
@@ -1921,5 +1937,15 @@
       "module": "period-rollup",
       "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"
     }
-  ]
+  ],
+  "browser": {
+    "status": "server-only",
+    "issues": [
+      "#3624"
+    ],
+    "reason": "node:crypto",
+    "via": [
+      "@happyvertical/smrt-tenancy"
+    ]
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-timesheets",
-  "version": "0.55.6",
+  "version": "0.55.8",
   "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,11 @@
     }
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.55.6",
-    "@happyvertical/smrt-tenancy": "0.55.6",
-    "@happyvertical/smrt-types": "0.55.6",
-    "@happyvertical/smrt-ui": "0.55.6",
-    "@happyvertical/sql": "^0.102.4"
+    "@happyvertical/smrt-core": "0.55.8",
+    "@happyvertical/smrt-tenancy": "0.55.8",
+    "@happyvertical/smrt-types": "0.55.8",
+    "@happyvertical/smrt-ui": "0.55.8",
+    "@happyvertical/sql": "^0.103.1"
   },
   "peerDependencies": {
     "svelte": "^5.57.0"
@@ -54,7 +54,7 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.55.6",
+    "@happyvertical/smrt-vitest": "0.55.8",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",