@happyvertical/smrt-timesheets 0.55.23 → 0.56.0

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
 
@@ -122,3 +142,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

@@ -269,7 +269,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 +288,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 +321,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 +373,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 +408,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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"}

package/dist/attendance/models.d.ts

@@ -8,7 +8,14 @@ export declare class AttendancePunch extends SmrtObject {
     durationSeconds: number;
     unpaidBreakSeconds: number;
     reviewRequired: boolean;
+    /** Why the scheduler closed this punch; empty unless `autoClose` did. Write-once. */
+    autoCloseReason: string;
     recordedOffline: boolean;
+    /** Optional short consumer-owned capture label (`device`, `web`, `import`, ...); `''` when unknown. */
+    source: string;
+    /** Qualified type of the device that captured the punch; both device columns or neither. */
+    deviceRefType: string;
+    deviceRefId: string;
     serviceTimeEntryId: string | null;
     /** Unique while open; closed rows retain independent non-null slots on every dialect. */
     openSlot: string;
@@ -22,15 +29,60 @@ export declare class AttendanceBreak extends SmrtObject {
     startedAt: Date;
     endedAt: Date | null;
     paid: boolean;
+    /** Optional short consumer-owned label (`meal`, `rest`, ...); `''` when unspecified. */
+    kind: string;
     openSlot: string;
     save(): Promise<this>;
     private saveConsistent;
+    delete(): Promise<void>;
+}
+declare const SEGMENT_CLOSE_REASONS: readonly ["stop", "switch", "break", "punchOut"];
+/** Why a work segment ended; `''` while it is open. */
+export type AttendanceSegmentCloseReason = (typeof SEGMENT_CLOSE_REASONS)[number] | '';
+/**
+ * A running unit of work inside one attendance punch: a work reference plus an
+ * optional second (task) reference as queryable columns, so job costing can
+ * index and join them. At most one segment is open per punch (`openSlot`). A
+ * segment never spans a break; `startBreak` and `punchOut` close it. Segments
+ * are attendance evidence and are not themselves service time entries.
+ */
+export declare class AttendanceSegment extends SmrtObject {
+    tenantId: string;
+    punchId: string;
+    /** Qualified class name of the work context (for example a work order). */
+    workRefType: string;
+    workRefId: string;
+    /** Optional second reference (for example an operation); both or neither. */
+    taskRefType: string;
+    taskRefId: string;
+    /** Optional short consumer lane label. */
+    kind: string;
+    description: string;
+    startedAt: Date;
+    endedAt: Date | null;
+    /** Elapsed whole seconds, set when the segment closes. */
+    durationSeconds: number;
+    /** `stop`, `switch`, `break` or `punchOut` once closed; `''` while open. */
+    closedReason: AttendanceSegmentCloseReason;
+    /** Set when a replay time policy asked for review of this segment's boundary. */
+    reviewRequired: boolean;
+    openSlot: string;
+    save(): Promise<this>;
+    private saveConsistent;
+    delete(): Promise<void>;
 }
 /** Durable success or conflict; conflicts do not mutate attendance. */
 export interface AttendanceReplayOutcome {
     clientId: string;
     punchId?: string;
+    /** Work segment a replayed work action started, switched to, stopped or resumed. */
+    segmentId?: string;
+    /** Effective time stored when a `resolveAt` policy changed it (ISO 8601). */
+    resolvedAt?: string;
+    /** Refusal message (with `code`); present exactly when the tap was refused. */
     error?: string;
+    /** Typed refusal reason; see `AttendanceRefusalCode`. */
+    code?: string;
 }
 /** Durable offline-tap outcome; never exposed through generated operations. */
 export declare class AttendanceReplay extends SmrtObject {
@@ -52,8 +104,13 @@ export declare class AttendancePunchCollection extends SmrtCollection<Attendance
 export declare class AttendanceBreakCollection extends SmrtCollection<AttendanceBreak> {
     static readonly _itemClass: typeof AttendanceBreak;
 }
+/** Work segments for job costing and attendance review. */
+export declare class AttendanceSegmentCollection extends SmrtCollection<AttendanceSegment> {
+    static readonly _itemClass: typeof AttendanceSegment;
+}
 /** Internal durable replay ledger. */
 export declare class AttendanceReplayCollection extends SmrtCollection<AttendanceReplay> {
     static readonly _itemClass: typeof AttendanceReplay;
 }
+export {};
 //# sourceMappingURL=models.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/attendance/models.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,cAAc,EACd,UAAU,EAGX,MAAM,0BAA0B,CAAC;AA4BlC,4EAA4E;AAC5E,qBAca,eAAgB,SAAQ,UAAU;IACjC,QAAQ,SAAM;IAC+B,SAAS,SAAM;IACxE,SAAS,EAAE,IAAI,CAAc;IAC7B,OAAO,EAAE,IAAI,GAAG,IAAI,CAAQ;IAC5B,eAAe,SAAK;IACpB,kBAAkB,SAAK;IACvB,cAAc,UAAS;IACvB,eAAe,UAAS;IAE4B,kBAAkB,EAClE,MAAM,GACN,IAAI,CAAQ;IAChB,yFAAyF;IAC9D,QAAQ,SAAM;IAE1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAMtB,cAAc;CA0D7B;AAED,0DAA0D;AAC1D,qBAca,eAAgB,SAAQ,UAAU;IACjC,QAAQ,SAAM;IACG,OAAO,SAAM;IAC1C,SAAS,EAAE,IAAI,CAAc;IAC7B,OAAO,EAAE,IAAI,GAAG,IAAI,CAAQ;IAC5B,IAAI,UAAS;IACc,QAAQ,SAAM;IAE1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAMtB,cAAc;CA6C7B;AAED,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAiBD,+EAA+E;AAC/E,qBAQa,gBAAiB,SAAQ,UAAU;IAClC,QAAQ,SAAM;IACe,SAAS,SAAM;IAC/B,OAAO,SAAM;IACb,OAAO,SAAQ;IAExC,qFAAqF;IACrF,UAAU,IAAI,uBAAuB;IAOrC,uEAAuE;IACvE,UAAU,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI;IAMjC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAIrC;AAED,gDAAgD;AAChD,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,eAAe,CAAC;IAC5E,MAAM,CAAC,QAAQ,CAAC,UAAU,yBAAmB;CAC9C;AACD,4DAA4D;AAC5D,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,eAAe,CAAC;IAC5E,MAAM,CAAC,QAAQ,CAAC,UAAU,yBAAmB;CAC9C;AACD,sCAAsC;AACtC,qBAAa,0BAA2B,SAAQ,cAAc,CAAC,gBAAgB,CAAC;IAC9E,MAAM,CAAC,QAAQ,CAAC,UAAU,0BAAoB;CAC/C"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/attendance/models.ts"],"names":[],"mappings":"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"}

package/dist/attendance/segments.d.ts

@@ -0,0 +1,20 @@
+import { type AttendanceContext, type AttendanceWork } from './context.js';
+import type { AttendancePunch, AttendanceSegment, AttendanceSegmentCloseReason } from './models.js';
+/** The open segment of a punch, or null. */
+export declare function openSegment(tx: AttendanceContext, punch: AttendancePunch): Promise<AttendanceSegment | null>;
+/** All segments of a punch, oldest first. */
+export declare function listSegments(tx: AttendanceContext, punch: AttendancePunch): Promise<AttendanceSegment[]>;
+/** Close the punch's open segment, if any. Returns it, or null when none was open. */
+export declare function closeOpenSegment(tx: AttendanceContext, punch: AttendancePunch, at: Date, reason: Exclude<AttendanceSegmentCloseReason, ''>): Promise<AttendanceSegment | null>;
+/** Open a segment; refuses while a break or another segment is open. */
+export declare function beginSegment(tx: AttendanceContext, punch: AttendancePunch, at: Date, work: AttendanceWork): Promise<AttendanceSegment>;
+/** Atomically close the open segment and open the next at the same instant. */
+export declare function replaceSegment(tx: AttendanceContext, punch: AttendancePunch, at: Date, work: AttendanceWork): Promise<AttendanceSegment>;
+/** Close the open segment (`stop`); refuses when none is open. */
+export declare function endSegment(tx: AttendanceContext, punch: AttendancePunch, at: Date): Promise<AttendanceSegment>;
+/**
+ * Reopen the work a break interrupted: a new segment with the same references
+ * as the latest segment, which must have been closed by `startBreak`.
+ */
+export declare function continueSegment(tx: AttendanceContext, punch: AttendancePunch, at: Date): Promise<AttendanceSegment>;
+//# sourceMappingURL=segments.d.ts.map