@happyvertical/smrt-timesheets 0.55.24 → 0.56.1

package/AGENTS.md

@@ -15,6 +15,26 @@ Attendance services accept trusted session actors, serialize mutations per
 actor, and bind every write to one executor. The new tables use non-null unique
 open slots, not nullable unique keys. A linked entry is draft evidence, and
 rollups must deduplicate `AttendancePunch.serviceTimeEntryId`.
+`AttendanceSegment` (`attendance_segments`) is a running work interval inside a
+punch: queryable `workRef*`/`taskRef*`/`kind` columns, one open per punch
+(`openSlot`), closed by `startBreak`/`punchOut`/`autoClose`, never overlapping
+breaks or each other, immutable once closed. It creates no `ServiceTimeEntry`.
+Closed punches, breaks and segments change only through
+`AttendanceCorrectionService` (`attendance/correction-service.ts`), which sets a
+per-instance capability (`attendance/write.ts`, not exported) that lifts the
+models' closed-interval checks for one save, validates the whole punch layout,
+recomputes durations and appends an `AttendanceCorrection` (append-only ledger,
+no generated operations; only a first acknowledgement by the subject may update
+a 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
+opt-in `confirmedTimecardGuard` (`rollup/correction-guard.ts`), which refuses
+while a card is submitted or confirmed. `PeriodRollupService.reopen()` returns
+such a card to `open` and appends a `TimecardReopening` (`timecard_reopenings`,
+append-only, service-only via `rollup/write.ts`); `submit()` is the optional
+open -> submitted step (`requireSubmission` makes it mandatory) (#3950).
+Segment transitions live in `attendance/segments.ts`; compose them with other
+attendance writes via `AttendanceService.withTransaction`. Any new attendance
+table must be added to the `includeObjects` lists in the `*.optional.test.ts`
+files.
 
 ## Models
 
@@ -28,6 +48,40 @@ rollups must deduplicate `AttendancePunch.serviceTimeEntryId`.
 through a `ServiceCommercialResolver`), and corrects. `smrt-projects` supplies
 `SubscriptionServiceCommercialResolver` for #1925 pricing.
 
+## Generated write actions (#4001)
+
+Generated CRUD writes stay closed. `ServiceTimeEntryCollection` hosts the only
+generated writes, `record` / `submit` / `approve` (`POST
+/servicetimeentries/<action>`, body `{ entryId }` for submit/approve), on REST
+only; MCP and CLI stay read-only until per-operation MCP authorization (#4004).
+`services/time-entry-actions.ts` delegates each to `ServiceEvidenceService`, so
+the trail and snapshots are set in one place. `services/action-principal.ts`
+takes identity from the tenancy ALS, then the smrt-users session ALS, never the
+body; authorizes `servicetimeentries.<action>` with `assertOperationPermission`
+(system context never bypasses; `approve` refuses super-admin bypass); and
+stamps the user's linked profile. Only the participant records/submits their
+own time unless the caller holds `approve`. `approve` prices with the host's
+`setServiceTimeEntryCommercialResolver()` — a factory called per request with
+the collection's options, so a writing resolver shares the request executor;
+without one it is a 409 and writes nothing. The runtime REST transport gates
+a collection-hosted action on the ITEM's `api.include`, SvelteKit on the
+collection's, so both list the actions;
+a consumer closing them overrides both registrations. The collection and both
+snapshot collections carry their own `@smrt()` surface: undecorated, they
+published generated create/update/delete MCP tools. `reject` waits for #3994.
+
+## Recipe
+
+`src/recipes.ts` declares one `SmrtRecipe`, `timesheets.time-entries`
+(label "Time entries", section `work`), emitted into the built
+`manifest.json` and `smrt-knowledge.json` `recipes`. It shows
+`ServiceTimeEntry` alone, with the generic work reference, evidence, agent
+and approval-trail fields hidden; attendance and rollup models stay out of
+it. `status` and its trail are hidden and locked, and the help never says to
+set them: `save()` accepts a bare transition, so submit and approve must go
+through `ServiceEvidenceService` (the recipe declares no surface for that). Help lives in `src/time-entries.recipe.md` (#3591); keep it and the recipe
+in plain language. See [core recipes](../core/agents/recipes.md).
+
 ## Invariants
 
 - **No domain foreign key on the base.** Work context is the generic
@@ -122,3 +176,9 @@ Layer 3 lives under `src/rollup/` and the `./rollup` subpath. See
 confirmation, attributed adjustments, isolation, and transaction contracts.
 Timecards and adjustments have closed generated surfaces and service-only
 model writes; never bypass the instance capability with generic persistence.
+
+Replay 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;
+`replay(taps, { resolveAt, now, refusal })` only changes the stored time and
+reason. Never hash the resolved time. Work actions (`startWork`, `switchWork`,
+`stopWork`, `resumeWork`) run in the tap's transaction via `apply()`. Refusals store
+`code` from `AttendanceConflict.code`; give new conflicts a code.

package/README.md

@@ -131,10 +131,41 @@ recording facade remains seconds-based; its shared entry view uses
 `TimeEntryApprovalQueue` are props-driven: hosts load entries and pass plain
 view objects (`TimeEntry`, `TimeEntryApprovalView`).
 
+## Generated write actions
+
+Generated CRUD writes are closed. The write path a generated app can call is
+three service-backed REST actions on `ServiceTimeEntryCollection` (#4001):
+
+| Route | Body | Permission |
+|---|---|---|
+| `POST /servicetimeentries/record` | work ref, `source` (`manual`/`timer`), times or `durationSeconds`/`durationHours`, optional `participantProfileId` | `servicetimeentries.record` |
+| `POST /servicetimeentries/submit` | `{ entryId }` | `servicetimeentries.submit` |
+| `POST /servicetimeentries/approve` | `{ entryId }` | `servicetimeentries.approve` (no super-admin bypass) |
+
+Each delegates to `ServiceEvidenceService`, so `submittedAt`/`submittedBy`,
+`approvedAt`/`approvedBy`/`approvalPath` (`operator`) and both snapshots are
+set exactly as the service sets them. The tenant and the acting profile come
+from the authenticated session, never the body. Recording or submitting
+someone else's time needs `approve` as well. Install pricing for `approve`
+as a factory, so a resolver that writes (client charges) runs on the request's
+executor and transaction:
+
+```ts
+import { setServiceTimeEntryCommercialResolver } from '@happyvertical/smrt-timesheets';
+
+setServiceTimeEntryCommercialResolver(({ options }) =>
+  SubscriptionServiceCommercialResolver.create(options, provider),
+);
+```
+
+Without a resolver, `approve` answers 409 `approval_not_configured`. MCP and
+CLI stay read-only; there is no `reject` action yet (#3994).
+
 ## Closing the generated surface
 
 The entry and both snapshots expose generated `list` / `get` on REST, CLI,
-and MCP, with optional tenant scoping. An application that routes all time
+and MCP, with optional tenant scoping, and the entry's collection the write
+actions above. An application that routes all time
 and money through its own permission-gated services can close those surfaces
 without declaring replacement models:
 
@@ -144,6 +175,8 @@ import '@happyvertical/smrt-timesheets';
 
 for (const name of [
   'ServiceTimeEntry',
+  // Hosts the record/submit/approve actions on generated SvelteKit routes.
+  'ServiceTimeEntryCollection',
   'ServiceChargeSnapshot',
   'ServiceCompensationSnapshot',
 ]) {
@@ -269,7 +302,7 @@ and are unchanged.
 ## Attendance
 
 The `@happyvertical/smrt-timesheets/attendance` subpath adds `AttendancePunch`,
-`AttendanceBreak`, and `AttendanceService`. Apply migrations for the new tables
+`AttendanceBreak`, `AttendanceSegment`, and `AttendanceService`. Apply migrations for the new tables
 before enabling the module. Existing entry and snapshot tables are unchanged.
 Attendance supports SQLite and PostgreSQL. DuckDB cannot enforce the required
 `ON UPDATE CASCADE` foreign-key contract used by attendance and existing entry
@@ -288,7 +321,7 @@ reads without replacing the models or changing their schema:
 import { ObjectRegistry } from '@happyvertical/smrt-core';
 import '@happyvertical/smrt-timesheets/attendance';
 
-for (const model of ['AttendancePunch', 'AttendanceBreak']) {
+for (const model of ['AttendancePunch', 'AttendanceBreak', 'AttendanceSegment']) {
   ObjectRegistry.registerOverride(`@happyvertical/smrt-timesheets:${model}`, {
     api: false, cli: false, mcp: false,
   });
@@ -321,6 +354,49 @@ pattern per punch. Persisted ownership/start and closed intervals are immutable.
 Direct ORM saves serialize against the parent punch and reject a close while a
 break remains open or ends outside the punch.
 
+### Running work segments
+
+A shift is one punch; inside it a person works on a sequence of things. An
+`AttendanceSegment` (table `attendance_segments`) is one running interval of work
+inside a punch, with queryable columns `workRefType`/`workRefId`, an optional
+second reference `taskRefType`/`taskRefId` (for example an operation; both or
+neither), a short `kind` lane label, `description`, `startedAt`/`endedAt`,
+`durationSeconds` and `closedReason` (`stop`, `switch`, `break`, `punchOut`).
+Indexes on `(tenantId, workRefType, workRefId)` and `(tenantId, taskRefType,
+taskRefId)` serve job costing; a unique `(tenantId, punchId, openSlot)` index
+allows one open segment per punch. Segments never overlap each other or a break.
+
+```ts
+await attendance.punchIn(t(8));
+await attendance.startWork(t(8), { workRefType: '@acme:WorkOrder', workRefId: 'WO-1',
+  taskRefType: '@acme:Operation', taskRefId: 'SHEAR', description: 'Shear' });
+await attendance.switchWork(t(10), { workRefType: '@acme:WorkOrder', workRefId: 'WO-2',
+  taskRefType: '@acme:Operation', taskRefId: 'WELD', description: 'Weld' });
+await attendance.startBreak(t(12));                        // closes the segment
+await attendance.endBreak(t(13), { resumeWork: true });    // or attendance.resumeWork(t(13))
+await attendance.punchOut(t(16));                          // closes the segment
+```
+
+`startWork`, `switchWork` (closes the open segment and opens the next at the same
+instant), `stopWork`, `resumeWork` (reopens the work a break interrupted),
+`currentWork()` and `segments(punchId)` are the service surface. `startBreak`,
+`punchOut`, `autoClose` and replayed taps close the open segment. Closed segments
+are immutable; ownership, references and start are immutable always. Closing a
+punch with an open segment, or a segment outside the punch, is refused.
+
+Segments are attendance evidence, not service time entries: they do not create
+`ServiceTimeEntry` rows and `punchOut(at, work?)` is unchanged (one draft entry
+for the whole punch; `taskRef*` and `kind` ride in its `metadata`). A consumer that
+costs jobs from segments should not also cost the punch-level entry. Rollups
+still deduplicate `serviceTimeEntryId`.
+
+To compose segment work with other attendance mutations (corrections, custom
+replay actions) atomically, use `attendance.withTransaction(async (tx) => ...)`
+and the exported helpers `openSegment`, `listSegments`, `beginSegment`,
+`replaceSegment`, `endSegment`, `continueSegment` and `closeOpenSegment`, which
+take the `AttendanceContext` (`tx.punches`, `tx.breaks`, `tx.segments`, `tx.db`)
+and an open punch.
+
 A work reference is optional: attendance alone is not billable evidence. Passing
 one on close, or calling `linkServiceTimeEntry(punch.id, work)` later, creates
 one draft `ServiceTimeEntry` atomically and records `serviceTimeEntryId` on the
@@ -330,14 +406,30 @@ refused. Approval still uses the entry layer. Rollups must deduplicate this link
 not count both attendance and its entry. Zero-net-duration punches cannot create
 service evidence.
 
-`autoClose(now, maxOpenSeconds)` closes a due open punch at its configured
-maximum duration and sets `reviewRequired`. It returns null before the deadline
-or when already closed. If later committed attendance would be truncated it
-refuses the operation for manual review. A scheduler calls this per authorized
-actor; the package does not choose overtime, payroll, or shop-time-zone rules.
-
-`replay(taps)` accepts `{ clientId, action, at, paid?, work? }`, where `action` is
-`punchIn`, `punchOut`, `startBreak`, or `endBreak`. It sorts each batch by device
+`autoClose(now, deadline)` closes a due open punch and sets `reviewRequired`.
+`deadline` is either a fixed maximum open duration in seconds (reason
+`maxDuration`) or a per-punch resolver `(punch) => Date | { deadline, reason? }
+| null`, for example the end of the shop day in the shop's time zone or the
+scheduled shift end; `null` leaves the punch open. The open work segment and
+break close at the deadline and the punch records `autoCloseReason` (write-once,
+only through `autoClose`). It returns null before the deadline or when already
+closed, and refuses a resolved deadline before the punch started. If later
+committed attendance would be truncated it refuses the operation for manual
+review. A scheduler calls this per authorized actor; the package does not choose
+overtime, payroll, or shop-time-zone rules.
+
+Provenance is optional and consumer-owned (no enum; at most 64 characters, trimmed):
+`punchIn(at, { source, device: { type, id } })` stores `source`, `deviceRefType` and
+`deviceRefId` on the punch (device type and id together, indexed with the tenant), and
+`startBreak(at, paid, { kind })` stores `kind` on the break. They are immutable once
+saved except through `AttendanceCorrectionService` (`addPunch({ source, device })`,
+`saveBreak({ kind })`). All columns default to `''`, so existing rows and calls are unchanged.
+Provenance, `kind` and `autoCloseReason` are additive columns on `attendance_punches` and `attendance_breaks`:
+migrate them as `TEXT NOT NULL DEFAULT ''` (a NULL left on an older row is read as `''`).
+
+`replay(taps, options?)` accepts `{ clientId, action, at, paid?, work?, source?, device?, kind? }`, where `action` is
+`punchIn`, `punchOut`, `startBreak`, `endBreak`, or a work action (`startWork`,
+`switchWork` (both require `work`), `stopWork`, `resumeWork`). It sorts each batch by device
 time, then client id. Client ids are durable and scoped to tenant/profile.
 Successful taps set `recordedOffline` and `reviewRequired`. The conflict policy
 is **committed attendance wins**: an event predating committed activity, or
@@ -349,10 +441,96 @@ are treated as supplied evidence, not server authentication; consumers should
 apply device drift policy before replay. Replay receipts must be retained for as
 long as clients can retry their ids.
 
+Work actions replay under the same client id and in the same transaction as punch
+and break changes; the outcome carries `segmentId`. Replay options:
+
+```ts
+await attendance.replay(taps, {
+  // Choose each tap's effective time. Called once per tap without a receipt.
+  resolveAt: ({ tap, deviceAt, serverNow, waitedMs, actor }) =>
+    waitedMs <= 12 * 3600_000
+      ? { at: deviceAt, reviewRequired: false }
+      : { at: serverNow, reviewRequired: true },
+  // Optionally name the stored reason of a refused tap.
+  refusal: (tap, error) => ({ code: 'device_busy', message: 'Finish current task first' }),
+});
+```
+
+The receipt hashes the tap as sent, so a retry with the same `clientId` still
+matches even though the stored time differs; the outcome then has `resolvedAt`.
+Punches are always flagged `reviewRequired`; `reviewRequired: true` from the
+resolver also flags the resulting work segment (`AttendanceSegment.reviewRequired`,
+a new column). A refused outcome stores `{ error, code }`: `code` defaults to the
+`AttendanceConflict.code` (`predates_committed`, `punch_open`, `no_open_punch`,
+`break_open`, `no_open_break`, `during_break`, `work_open`, `no_open_work`,
+`no_resumable_work`, or `conflict`), so a device screen can say why. Resolved times
+that break chronology are refused like any other tap.
+
+### Correcting closed attendance
+
+Closed punches, breaks and segments are immutable to every direct write.
+`AttendanceCorrectionService` is the one sanctioned path around that, and it
+leaves a paper trail. Construct it with the **correcting** person as `actor`;
+each request names the `subjectProfileId` whose time it is. As with
+`AttendanceService`, your application authorizes the actor (and decides whether
+they may correct this subject) first.
+
+```ts
+import { AttendanceCorrectionService } from '@happyvertical/smrt-timesheets/attendance';
+import { confirmedTimecardGuard } from '@happyvertical/smrt-timesheets/rollup';
+
+const fix = new AttendanceCorrectionService(
+  db,
+  { tenantId, profileId: foremanId },
+  { guard: confirmedTimecardGuard }, // optional, see below
+);
+const base = { subjectProfileId: welderId, reason: 'forgot to clock out' };
+
+await fix.correctPunch({ ...base, punchId, endedAt: new Date('2026-10-01T15:30:00Z'),
+  acknowledgementRequired: true });
+await fix.addPunch({ ...base, reason: 'missed punch', startedAt, endedAt });
+await fix.saveBreak({ ...base, punchId, startedAt, endedAt, paid: false }); // add
+await fix.saveBreak({ ...base, punchId, breakId, endedAt });                // change
+await fix.removeBreak({ ...base, breakId });
+await fix.saveSegment({ ...base, punchId, startedAt, endedAt, work });      // add
+await fix.saveSegment({ ...base, punchId, segmentId, endedAt });            // change
+await fix.removeSegment({ ...base, segmentId });
+
+// the welder, constructing the service as themselves:
+await new AttendanceCorrectionService(db, { tenantId, profileId: welderId })
+  .acknowledge(correctionId);
+```
+
+Every method runs in one transaction serialized with the subject's own taps. It
+validates the resulting layout (everything inside its punch, no overlapping
+breaks, segments or other punches, no segment across a break), recomputes
+`durationSeconds` and `unpaidBreakSeconds`, and appends an `AttendanceCorrection`
+row (`attendance_corrections`: `kind`, `subjectProfileId`, `actorProfileId`,
+`punchId`, `targetId`, `beforeState`/`afterState` JSON, a required non-blank
+`reason`, `acknowledgementRequired`, `acknowledgedAt`/`acknowledgedByProfileId`).
+Rows are append-only: the only later change is the subject's single
+`acknowledge()`, and `listForPunch(punchId)` / `pendingAcknowledgements()` read
+the ledger. The ledger has no generated operations, and every ledger,
+closed-break and closed-segment write (insert, acknowledge, delete) is
+service-only: a generic `save()`, `delete()` or collection `create()` is refused. Notes:
+
+- Only **closed** punches are corrected; an open one is `AttendanceService`'s.
+  Moving a punch edge past a break or segment is refused: correct those first.
+- `correctPunch` clears `reviewRequired` (a person reviewed it). A linked
+  *draft* `ServiceTimeEntry` is kept in step; a submitted or approved one
+  refuses the correction until it is corrected with `ServiceEvidenceService`.
+- **Confirmed timecards.** A confirmed `PeriodTimecard` never changes, so
+  correcting its sources would leave card and attendance disagreeing for good.
+  Pass `confirmedTimecardGuard` (from `./rollup`) and a correction overlapping a
+  confirmed (or submitted) card is refused before any write; call
+  `PeriodRollupService.reopen()` first, correct, then `rollup()` again. Any other lock can be supplied as `guard`.
+- Closed `AttendanceBreak`/`AttendanceSegment` rows can no longer be deleted
+  directly; `removeBreak`/`removeSegment` are the path.
+
 ## Period timecards
 
 `./rollup` provides per-person integer-second regular/overtime rollups, immutable
-confirmation, and attributed append-only adjustments. Consumer resolvers own
+confirmation (with an optional submitted step), audited reopening, and attributed append-only adjustments. Consumer resolvers own
 calendar/timezone, holiday and overtime rules. See the [contract and example](agents/period-rollup.md).
 
 ## Effective-dated labour pricing

package/agents/period-rollup.md

@@ -133,3 +133,23 @@ embedded writer serialization or a PostgreSQL tenant/person advisory lock.
 Outputs are reloaded on the root executor after commit. Rollup reads are an
 application snapshot: subsequent source approvals/corrections appear on the
 next open rollup, and confirmed cards require explicit adjustments.
+
+## Lifecycle: submit, confirm, reopen (#3950)
+
+`open` (draft) -> `submitted` (optional) -> `confirmed`. `submit(id)` freezes an
+open card for review; `confirm(id)` accepts an open card too unless the service
+is built with `{ requireSubmission: true }`. Submitted and confirmed cards are
+not re-rolled.
+
+`reopen(id, { operationId, reason })` returns a submitted or confirmed card to
+`open` (clearing its submission/confirmation attribution) and appends a
+`TimecardReopening`: actor, reason, prior status and a JSON snapshot of the
+previous base, adjustment and effective seconds (`getPrevious()`). It is
+idempotent per `operationId` and refuses a blank reason. `reopenings(id)` lists
+the history. The consumer authorizes the actor; give reopening its own
+permission. Existing adjustments stay and keep counting in `totals()`: after a
+re-roll, offset ones the correction made redundant with a new adjustment.
+`confirmedTimecardGuard` refuses corrections while a card is submitted or
+confirmed and allows them once it is reopened. The new `timecard_reopenings`
+table, and nullable `submitted_at`/`submitted_by_profile_id` columns on
+`period_timecards`, need a migration.

package/dist/attendance/context.d.ts

@@ -0,0 +1,80 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { AttendanceBreakCollection, AttendancePunchCollection, AttendanceReplayCollection, AttendanceSegmentCollection } from './models.js';
+/** Resolve these identifiers from the authenticated session, never from tap input. */
+export interface AttendanceActor {
+    tenantId: string;
+    profileId: string;
+}
+/**
+ * Explicit work attribution for a closed punch's draft evidence entry or for a
+ * running work segment. `taskRefType`/`taskRefId` (both or neither) name an
+ * optional second reference such as an operation; `kind` is an optional short
+ * consumer lane label.
+ */
+export interface AttendanceWork {
+    workRefType: string;
+    workRefId: string;
+    description: string;
+    taskRefType?: string;
+    taskRefId?: string;
+    kind?: string;
+}
+/**
+ * Where a punch was captured: a consumer-owned type (for example a class name
+ * such as a station or tablet) and that device's id. Both or neither.
+ */
+export interface AttendanceDeviceRef {
+    type: string;
+    id: string;
+}
+/** Optional provenance recorded when a punch opens. */
+export interface AttendancePunchOptions {
+    /** Short consumer-owned label such as `device`, `web`, `import`, `correction`. */
+    source?: string;
+    /** The device that captured the punch. */
+    device?: AttendanceDeviceRef;
+}
+/** Optional detail recorded when a break starts. */
+export interface AttendanceBreakOptions {
+    /** Short consumer-owned label such as `meal` or `rest`. */
+    kind?: string;
+}
+/** Validate an optional short label (`source`, `kind`, device type); returns the stored form. */
+export declare function attendanceLabel(value: unknown, name: string): string;
+/** Validate punch provenance; returns the stored column values. */
+export declare function attendanceProvenance(options?: AttendancePunchOptions): {
+    source: string;
+    deviceRefType: string;
+    deviceRefId: string;
+};
+/** Expected state conflict, distinct from retryable database failures. */
+export declare class AttendanceConflict extends Error {
+    /**
+     * Stable machine-readable reason (see {@link AttendanceRefusalCode}); stored
+     * on a refused replay outcome so a device screen can say why.
+     */
+    readonly code: AttendanceRefusalCode;
+    constructor(message: string, code?: AttendanceRefusalCode);
+}
+/**
+ * Built-in refusal codes. Consumers may store any other string through the
+ * `refusalCode` replay hook.
+ */
+export type AttendanceRefusalCode = 'conflict' | 'invalid' | 'predates_committed' | 'punch_open' | 'no_open_punch' | 'break_open' | 'no_open_break' | 'during_break' | 'work_open' | 'no_open_work' | 'no_resumable_work' | (string & {});
+/**
+ * Collections bound to one transaction executor. Handed to
+ * `AttendanceService.withTransaction` callbacks and to the segment helpers so
+ * corrections and replay can compose several mutations atomically.
+ */
+export type AttendanceContext = {
+    db: DatabaseInterface;
+    punches: AttendancePunchCollection;
+    breaks: AttendanceBreakCollection;
+    segments: AttendanceSegmentCollection;
+    replays: AttendanceReplayCollection;
+};
+/** Validate a work reference; throws {@link AttendanceConflict}. */
+export declare function validateAttendanceWork(work: AttendanceWork): void;
+/** Canonicalize a tenant/profile id: PostgreSQL requires UUIDs, other adapters take it verbatim. */
+export declare function attendanceIdentity(db: DatabaseInterface, value: string): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/attendance/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/attendance/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,EAC5B,MAAM,aAAa,CAAC;AAErB,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AACD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED,oDAAoD;AACpD,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpE;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAaA;AAED,0EAA0E;AAC1E,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,qBAAkC;CAItE;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,SAAS,GACT,oBAAoB,GACpB,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,eAAe,GACf,cAAc,GACd,WAAW,GACX,cAAc,GACd,mBAAmB,GACnB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,iBAAiB,CAAC;IACtB,OAAO,EAAE,yBAAyB,CAAC;IACnC,MAAM,EAAE,yBAAyB,CAAC;IAClC,QAAQ,EAAE,2BAA2B,CAAC;IACtC,OAAO,EAAE,0BAA0B,CAAC;CACrC,CAAC;AAEF,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAmBjE;AAED,oGAAoG;AACpG,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,iBAAiB,EACrB,KAAK,EAAE,MAAM,GACZ,MAAM,CAMR"}

package/dist/attendance/correction-models.d.ts

@@ -0,0 +1,39 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/** What a correction did. Punch kinds target the punch itself. */
+export declare const ATTENDANCE_CORRECTION_KINDS: readonly ["punch.corrected", "punch.added", "break.added", "break.changed", "break.removed", "segment.added", "segment.changed", "segment.removed"];
+export type AttendanceCorrectionKind = (typeof ATTENDANCE_CORRECTION_KINDS)[number];
+/**
+ * One append-only change to closed attendance: who changed whose time, why, and
+ * the before/after values as JSON (`null` for an addition's before or a
+ * removal's after). Written only by `AttendanceCorrectionService`, in the same
+ * transaction as the change. After insert only the acknowledgement may be set,
+ * once, by the subject; rows are never deleted.
+ */
+export declare class AttendanceCorrection extends SmrtObject {
+    tenantId: string;
+    /** Whose time was corrected. */
+    subjectProfileId: string;
+    /** Who made the correction. */
+    actorProfileId: string;
+    kind: AttendanceCorrectionKind;
+    punchId: string;
+    /** The break or segment id for those kinds; the punch id for punch kinds. */
+    targetId: string;
+    beforeState: string;
+    afterState: string;
+    reason: string;
+    acknowledgementRequired: boolean;
+    acknowledgedAt: Date | null;
+    acknowledgedByProfileId: string | null;
+    /** The values before the change, or null for an addition. */
+    getBefore<T = Record<string, unknown>>(): T | null;
+    /** The values after the change, or null for a removal. */
+    getAfter<T = Record<string, unknown>>(): T | null;
+    save(): Promise<this>;
+    delete(): Promise<void>;
+}
+/** The correction ledger. */
+export declare class AttendanceCorrectionCollection extends SmrtCollection<AttendanceCorrection> {
+    static readonly _itemClass: typeof AttendanceCorrection;
+}
+//# sourceMappingURL=correction-models.d.ts.map

package/dist/attendance/correction-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correction-models.d.ts","sourceRoot":"","sources":["../../src/attendance/correction-models.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAMlC,kEAAkE;AAClE,eAAO,MAAM,2BAA2B,qJAS9B,CAAC;AACX,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAc/C;;;;;;GAMG;AACH,qBAkBa,oBAAqB,SAAQ,UAAU;IACtC,QAAQ,SAAM;IAC1B,gCAAgC;IAEhC,gBAAgB,SAAM;IACtB,+BAA+B;IAE/B,cAAc,SAAM;IACK,IAAI,EAAE,wBAAwB,CAAqB;IAC/C,OAAO,SAAM;IAC1C,6EAA6E;IAC7E,QAAQ,SAAM;IACW,WAAW,SAAU;IACrB,UAAU,SAAU;IACpB,MAAM,SAAM;IACrC,uBAAuB,UAAS;IAChC,cAAc,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEnC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE9C,6DAA6D;IAC7D,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI;IAGlD,0DAA0D;IAC1D,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI;IAIlC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsDrB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvC;AAED,6BAA6B;AAC7B,qBAAa,8BAA+B,SAAQ,cAAc,CAAC,oBAAoB,CAAC;IACtF,MAAM,CAAC,QAAQ,CAAC,UAAU,8BAAwB;CACnD"}

package/dist/attendance/correction-service.d.ts

@@ -0,0 +1,118 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type AttendanceActor, type AttendanceContext, type AttendancePunchOptions, type AttendanceWork } from './context.js';
+import { AttendanceCorrection } from './correction-models.js';
+/** A closed time range a correction touches, for period-lock checks. */
+export interface AttendanceCorrectionInterval {
+    startsAt: Date;
+    endsAt: Date;
+}
+/**
+ * Optional period lock, run on the correction's transaction before any write.
+ * Return a message to refuse the correction (for example "overlaps a confirmed
+ * timecard"), or null to allow it. `confirmedTimecardGuard` in `./rollup` is the
+ * ready-made one.
+ */
+export type AttendanceCorrectionGuard = (tx: AttendanceContext, subject: AttendanceActor, intervals: readonly AttendanceCorrectionInterval[]) => Promise<string | null>;
+export interface AttendanceCorrectionOptions {
+    guard?: AttendanceCorrectionGuard;
+}
+/** Fields every correction carries. */
+export interface AttendanceCorrectionRequest {
+    /** Whose time is being corrected. */
+    subjectProfileId: string;
+    /** Required, non-blank. Stored verbatim (trimmed) on the ledger row. */
+    reason: string;
+    /** When true the subject must `acknowledge()` the correction. */
+    acknowledgementRequired?: boolean;
+}
+export interface CorrectPunchInput extends AttendanceCorrectionRequest {
+    punchId: string;
+    startedAt?: Date;
+    endedAt?: Date;
+}
+export interface AddPunchInput extends AttendanceCorrectionRequest, AttendancePunchOptions {
+    startedAt: Date;
+    endedAt: Date;
+}
+/** Adds a break when `breakId` is absent; otherwise changes that break. */
+export interface SaveBreakInput extends AttendanceCorrectionRequest {
+    punchId: string;
+    breakId?: string;
+    startedAt?: Date;
+    endedAt?: Date;
+    paid?: boolean;
+    /** Short consumer-owned label (for example `meal`); omit to keep, `''` to clear. */
+    kind?: string;
+}
+export interface RemoveBreakInput extends AttendanceCorrectionRequest {
+    breakId: string;
+}
+/**
+ * Adds a segment when `segmentId` is absent (`startedAt`, `endedAt` and `work`
+ * are then required); otherwise changes that segment, keeping what is omitted.
+ */
+export interface SaveSegmentInput extends AttendanceCorrectionRequest {
+    punchId: string;
+    segmentId?: string;
+    startedAt?: Date;
+    endedAt?: Date;
+    work?: AttendanceWork;
+}
+export interface RemoveSegmentInput extends AttendanceCorrectionRequest {
+    segmentId: string;
+}
+/**
+ * Corrections to closed attendance, with a paper trail.
+ *
+ * `actor` is who makes the change; each request names the `subjectProfileId`
+ * whose time it is. The application authorizes the actor (and decides whether
+ * they may correct this subject) before constructing the service, exactly as
+ * for `AttendanceService`. This service is the only path that may change a
+ * closed punch, break or segment: each method validates the resulting layout
+ * (everything inside its punch, no overlapping breaks, segments or punches,
+ * no segment across a break), recomputes `durationSeconds` and
+ * `unpaidBreakSeconds`, keeps a still-draft linked service entry in step, and
+ * appends an `AttendanceCorrection` row, all in one transaction serialized with
+ * the subject's own taps. Open punches are not corrected here: use
+ * `AttendanceService`.
+ */
+export declare class AttendanceCorrectionService {
+    private readonly db;
+    private readonly options;
+    private readonly actor;
+    constructor(db: DatabaseInterface, actor: AttendanceActor, options?: AttendanceCorrectionOptions);
+    /** Change a closed punch's start and/or end. A reviewed punch no longer needs review. */
+    correctPunch(input: CorrectPunchInput): Promise<AttendanceCorrection>;
+    /** Record a missed punch retroactively, as an already-closed interval. */
+    addPunch(input: AddPunchInput): Promise<AttendanceCorrection>;
+    /** Add a break to a closed punch, or change one (times and/or paid). */
+    saveBreak(input: SaveBreakInput): Promise<AttendanceCorrection>;
+    /** Remove a break from a closed punch. */
+    removeBreak(input: RemoveBreakInput): Promise<AttendanceCorrection>;
+    /** Add a work segment to a closed punch, or change one (times and/or work attribution). */
+    saveSegment(input: SaveSegmentInput): Promise<AttendanceCorrection>;
+    /** Remove a work segment from a closed punch. */
+    removeSegment(input: RemoveSegmentInput): Promise<AttendanceCorrection>;
+    /**
+     * The subject confirms they have seen a correction that required it. Only
+     * the subject (this service's actor) may; it can be done once.
+     */
+    acknowledge(correctionId: string, at?: Date): Promise<AttendanceCorrection>;
+    /** Corrections to one punch, oldest first. */
+    listForPunch(punchId: string): Promise<AttendanceCorrection[]>;
+    /** Corrections of the actor's own time that still await their acknowledgement. */
+    pendingAcknowledgements(): Promise<AttendanceCorrection[]>;
+    private attendance;
+    private read;
+    private run;
+    private closedPunch;
+    private children;
+    private layout;
+    private attribute;
+    private guard;
+    /** The punch's still-draft evidence entry, refusing when it is no longer editable. */
+    private editableEntry;
+    /** Recompute the punch's durations from its breaks and persist it and its draft entry. */
+    private settle;
+}
+//# sourceMappingURL=correction-service.d.ts.map

package/dist/attendance/correction-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correction-service.d.ts","sourceRoot":"","sources":["../../src/attendance/correction-service.ts"],"names":[],"mappings":"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"}