@happyvertical/smrt-timesheets 0.53.1 → 0.53.3

package/AGENTS.md

@@ -6,9 +6,15 @@ immutable charge / compensation snapshots taken at approval. Moved out of
 `smrt-projects` / `smrt-support` in #3288 so shops, builders, and service
 desks share one model instead of re-implementing it.
 
-This package is **layer 1 (entry)**. Attendance (punches, breaks, offline
-replay) and period rollup (per-person timecards) are planned as later modules
-of this same package; do not add them to projects or support.
+This package contains **layer 1 (entry)**, **layer 2 (attendance)**, and
+**layer 3 (period rollup)**.
+`src/attendance/` owns punches, breaks, atomic transitions and durable offline
+receipts; `./attendance` is the public subpath. Period rollup belongs in this
+package too, never projects or support. See the README attendance contract.
+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`.
 
 ## Models
 
@@ -57,24 +63,21 @@ through a `ServiceCommercialResolver`), and corrects. `smrt-projects` supplies
 
 ## One table family
 
-Classes may share a table only as one inheritance chain, and the registry
-resolves a chain of same-named classes by "child wins" on the simple name.
-That works for exactly one subtype level per table (base → subtype); a third
-same-named level makes the middle class look like it extends its own child on
-the manifest path (`CONFIG_TABLE_NAME_COLLISION`). Therefore:
-
-- `smrt-projects` **re-exports** these classes (no projects subclass).
-- `smrt-support` subclasses `ServiceTimeEntry` directly from this package.
-- A consumer that needs its own surface (e.g. teamworks-os closing every
-  generated route with `api: { include: [] }` and
-  `@TenantScoped({ mode: 'required' })`) declares a same-named subclass over
-  `service_time_entries`; its manifest entry replaces the package's. It cannot
-  also install smrt-support's subtype on the same table.
-  The same applies to both snapshots;
-  `src/__tests__/consumer-closed-surface.test.ts` holds that contract for all
-  three models. The snapshots' explicit `time_entry_id` conflict key is not
-  rewritten when a consumer requires tenancy; widening it is the consumer's
-  schema change, never a package default.
+Classes may share a table only as one inheritance chain. Core resolves
+same-named subclasses by constructor ancestry at runtime and qualified manifest
+ancestry at build registration; the deepest subtype wins across N levels.
+Sibling or unrelated types cannot share the table. `smrt-projects` re-exports
+the base; `smrt-support` subclasses it directly.
+
+Consumers closing package routes should call
+`ObjectRegistry.registerOverride(qualifiedName, { api: false, mcp: false,
+cli: false, tenancy: { mode: 'required' } })` after importing the model and before
+constructing transports. This tightens the existing registration without a new
+subtype. See core's README for startup order, static route generation, and reset
+semantics. `src/__tests__/consumer-closed-surface.test.ts` also covers existing
+manifest subclass consumers. The snapshots' explicit `time_entry_id` conflict
+key is not rewritten when a consumer requires tenancy; widening it remains a
+consumer schema change.
 
 Subclasses restate their fields: package-isolated manifest scanning does not
 read dependency sources, so an unrestated subclass manifest has no columns.
@@ -103,3 +106,11 @@ pnpm --filter @happyvertical/smrt-support test
 Schema-affecting edits must keep `service-time-entry-compat.test.ts` (projects,
 support) and `service-time-entry-migration-plan.test.ts` (support) green: a
 pre-move table must plan no DDL.
+
+## Period rollup
+
+Layer 3 lives under `src/rollup/` and the `./rollup` subpath. See
+[period-rollup.md](agents/period-rollup.md) for resolver, source clipping,
+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.

package/README.md

@@ -88,68 +88,45 @@ view objects (`TimeEntry`, `TimeEntryApprovalView`).
 
 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 money through its own permission-gated services declares a same-named
-subclass over each table and closes it:
+and money through its own permission-gated services can close those surfaces
+without declaring replacement models:
 
 ```ts
-import {
-  ServiceChargeSnapshot as SharedServiceChargeSnapshot,
-  ServiceCompensationSnapshot as SharedServiceCompensationSnapshot,
-  ServiceTimeEntry as SharedServiceTimeEntry,
-} from '@happyvertical/smrt-timesheets';
-
-const CLOSED = { include: [] };
-
-@TenantScoped({ mode: 'required' })
-@smrt({
-  tableName: 'service_time_entries',
-  api: CLOSED,
-  cli: CLOSED,
-  mcp: CLOSED,
-})
-export class ServiceTimeEntry extends SharedServiceTimeEntry {
-  // restate the fields — see AGENTS.md
-}
-
-@TenantScoped({ mode: 'required' })
-@smrt({
-  tableName: 'service_charge_snapshots',
-  conflictColumns: ['time_entry_id'],
-  api: CLOSED,
-  cli: CLOSED,
-  mcp: CLOSED,
-})
-export class ServiceChargeSnapshot extends SharedServiceChargeSnapshot {
-  // restate the fields — see AGENTS.md
-}
-
-@TenantScoped({ mode: 'required' })
-@smrt({
-  tableName: 'service_compensation_snapshots',
-  conflictColumns: ['time_entry_id'],
-  api: CLOSED,
-  cli: CLOSED,
-  mcp: CLOSED,
-})
-export class ServiceCompensationSnapshot extends SharedServiceCompensationSnapshot {
-  // restate the fields — see AGENTS.md
+import { ObjectRegistry } from '@happyvertical/smrt-core';
+import '@happyvertical/smrt-timesheets';
+
+for (const name of [
+  'ServiceTimeEntry',
+  'ServiceChargeSnapshot',
+  'ServiceCompensationSnapshot',
+]) {
+  ObjectRegistry.registerOverride(`@happyvertical/smrt-timesheets:${name}`, {
+    api: false,
+    cli: false,
+    mcp: false,
+    tenancy: { mode: 'required' },
+  });
 }
 ```
 
-Do not copy `previousQualifiedNames` into these subclasses: an old name may
-have only one claimant. Replacing the timesheets classes drops their
-smrt-projects aliases (see the known gap under "Stored and declared class
-names").
-
-Restate `conflictColumns` exactly as shown unless you mean to change it. The
-snapshots' conflict key is `time_entry_id` alone — one snapshot per entry —
-and, being an explicit key, it is never rewritten to lead with `tenant_id`
-when you require tenancy. That is safe as long as entry ids are unique across
-tenants (they are UUIDs). Widening it to `['tenant_id', 'time_entry_id']` is
-your decision, and it is a schema change for your database (a new unique
-index replacing `service_*_snapshots_time_entry_id_idx`), so it goes through
-`smrt db:migrate` like any other key change; the package default stays
-`['time_entry_id']`.
+Register overrides after importing the models and before constructing or
+emitting generated transports. Use the currently registered qualified name:
+when smrt-support has replaced `ServiceTimeEntry`, target
+`@happyvertical/smrt-support:ServiceTimeEntry` instead. Overrides accept only
+closed surfaces and required tenancy; they cannot reopen a surface or weaken
+tenancy. They survive registration replay and are reset by
+`ObjectRegistry.clear()`. Existing static route files must be regenerated with
+the closed configuration; changing the registry does not rewrite deployed files.
+
+This preserves the model's fields, indexes, conflict keys, and aliases. Same-named
+subclasses remain available when an application needs to change the model itself;
+see AGENTS.md for field restatement and the alias gap below.
+
+The snapshots' conflict key remains `time_entry_id` alone — one snapshot per
+entry — and is never rewritten to lead with `tenant_id` when tenancy becomes
+required. Entry ids are UUIDs unique across tenants. Widening that key to
+`['tenant_id', 'time_entry_id']` is a consumer schema change requiring a new
+unique index through `smrt db:migrate`; runtime overrides do not change schema.
 
 ## Migrating from smrt-projects / smrt-support
 
@@ -223,7 +200,7 @@ and are unchanged.
 
 > **Known gap: same-named subtypes drop the alias.** A same-named subclass
 > over a moved table — smrt-support's `ServiceTimeEntry`, or an
-> application's closing subclass (see "Closing the generated surface") —
+> application's replacement subclass —
 > replaces the timesheets class in the registry, and that class's alias does
 > not carry over to it yet. With smrt-support installed,
 > `@happyvertical/smrt-projects:ServiceTimeEntry` therefore does not resolve
@@ -241,3 +218,92 @@ and are unchanged.
   `SubscriptionServiceCommercialResolver` pricing for these entries.
 - [`smrt-support`](../support/README.md) — support-case time on the same table.
 - [`smrt-profiles`](../profiles/README.md) — the participants.
+
+## Attendance
+
+The `@happyvertical/smrt-timesheets/attendance` subpath adds `AttendancePunch`,
+`AttendanceBreak`, 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
+corrections; schema creation deliberately fails rather than omitting constraints.
+
+Construct a service with your database and the **authorized session's**
+`{ tenantId, profileId }`. The application resolves Profile membership and
+operation permissions before this boundary; never pass request-supplied actor
+identifiers. A conflicting active tenant is refused. The service cannot read or
+link another profile's punch. Generated punch/break surfaces default to reads
+only; the replay ledger has no generated operations and is excluded from change
+feeds. Before constructing generated transports, consumers can close the remaining
+reads without replacing the models or changing their schema:
+
+```ts
+import { ObjectRegistry } from '@happyvertical/smrt-core';
+import '@happyvertical/smrt-timesheets/attendance';
+
+for (const model of ['AttendancePunch', 'AttendanceBreak']) {
+  ObjectRegistry.registerOverride(`@happyvertical/smrt-timesheets:${model}`, {
+    api: false, cli: false, mcp: false,
+  });
+}
+```
+
+Required tenant scoping remains in effect after closing these surfaces.
+
+```ts
+import { AttendanceService } from '@happyvertical/smrt-timesheets/attendance';
+
+const attendance = new AttendanceService(db, { tenantId, profileId });
+await attendance.punchIn(new Date('2026-10-01T08:00:00Z'));
+await attendance.startBreak(new Date('2026-10-01T12:00:00Z')); // unpaid
+await attendance.endBreak(new Date('2026-10-01T12:30:00Z'));
+const punch = await attendance.punchOut(new Date('2026-10-01T16:00:00Z'), {
+  workRefType: '@acme/jobs:WorkPackage', workRefId: 'wp-7', description: 'Framing',
+});
+```
+
+Timestamps retain device milliseconds. `durationSeconds` is elapsed time minus
+unpaid breaks, rounded once to the nearest whole second; paid breaks remain
+included. Local time zone and payroll rounding policy belong to the consumer. Closing also ends an active break. New punches have the
+non-null `openSlot` value `open`, with a unique database index on tenant, profile
+and slot. Closed punches use a slot derived from their id, so PostgreSQL and
+SQLite enforce one open punch without differing nullable-unique semantics.
+The index compares native UUID owner columns directly, including PostgreSQL
+UUID normalization. Breaks use the same
+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.
+
+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
+punch. Only the three declared work fields are copied; extra request fields cannot
+replace the trusted tenant or participant. Repeating the same link returns that entry; changing attribution is
+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
+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
+invalid for the current state, gets a durable error outcome. Identical retries
+return that outcome even after later shifts; changed payloads using the same id
+are rejected. Database failures roll back the tap and receipt together and can
+be retried. Earlier committed taps in the batch remain committed. Device clocks
+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.
+
+## Period timecards
+
+`./rollup` provides per-person integer-second regular/overtime rollups, immutable
+confirmation, and attributed append-only adjustments. Consumer resolvers own
+calendar/timezone, holiday and overtime rules. See the [contract and example](agents/period-rollup.md).

package/agents/period-rollup.md

@@ -0,0 +1,130 @@
+# Period timecards
+
+`@happyvertical/smrt-timesheets/rollup` exports `PeriodRollupService`,
+`PeriodTimecard`, `TimecardAdjustment`, their collections, and resolver types.
+The package root also exports them. SQLite and PostgreSQL are supported.
+Create application tables through normal migrations; neither service provisions
+schema. The attendance option additionally requires the attendance tables.
+
+Construct a service only after authenticating and authorizing its trusted
+`{ tenantId, profileId }` scope. A conflicting ambient tenant is rejected.
+`options.actorProfileId` records a separately authorized supervisor; it defaults
+to the subject profile for self confirmation/correction. Never accept this
+trusted scope or attribution unchecked from request input. Profile authorization
+is consumer-owned; the service filters every source/card/adjustment read by its
+trusted subject and tenant. Generic API, CLI and MCP surfaces are closed by
+default; consumer registry overrides may further restrict them (#3318).
+
+## Resolver contract
+
+`periodFor(at, actor)` supplies half-open UTC `startsAt`/`endsAt`, an IANA
+`timezone`, a nonempty policy `version`, and a JSON `rules` snapshot.
+The consumer owns period length, calendar start day, timezone and DST, overtime
+thresholds, holidays and classification. The requested instant must be inside
+the window. Overlapping windows for existing cards are rejected: introduce a new
+calendar at a boundary after existing windows, and use adjustments for already
+confirmed periods.
+
+`classify(period, sources, actor)` returns nonnegative safe integer
+`regularSeconds` and `overtimeSeconds`, whose sum must equal source seconds.
+Inputs are detached so resolver mutation cannot rewrite evidence. Resolver
+exceptions, malformed windows, invalid timezone, fractional/unsafe totals and
+nonconserving classification abort the transaction. No Alberta or other
+jurisdiction rule is assumed, and no pay rate or money is stored.
+
+A configurable UTC calendar example (illustrative policy, not payroll advice):
+
+```ts
+import { PeriodRollupService, type PeriodRulesResolver } from
+  '@happyvertical/smrt-timesheets/rollup';
+
+const settings = {
+  lengthDays: 14, startDay: 1, timezone: 'UTC', // 0 = Sunday
+  anchor: '2026-01-05T00:00:00Z', // aligned Monday; anchors fortnight phase
+  thresholdSeconds: 80 * 3600,
+  holidays: ['2026-12-25'],
+};
+const resolver: PeriodRulesResolver = {
+  async periodFor(at) {
+    const anchor = new Date(settings.anchor);
+    if (anchor.getUTCDay() !== settings.startDay || settings.timezone !== 'UTC')
+      throw new Error('Use a timezone-aware calendar resolver for local periods');
+    const length = settings.lengthDays * 86400000;
+    const start = anchor.getTime() +
+      Math.floor((at.getTime() - anchor.getTime()) / length) * length;
+    return {
+      startsAt: new Date(start), endsAt: new Date(start + length),
+      timezone: settings.timezone, version: 'shop-policy-v1', rules: settings,
+    };
+  },
+  async classify(period, sources) {
+    const rules = period.rules as typeof settings;
+    // This example assigns a contribution to its clipped start's UTC date.
+    // Local daily rules should split contributions at their own local midnight.
+    let regular = 0;
+    let holiday = 0;
+    for (const source of sources) {
+      if (rules.holidays.includes(source.startsAt.slice(0, 10))) holiday += source.seconds;
+      else regular += source.seconds;
+    }
+    return {
+      regularSeconds: Math.min(regular, rules.thresholdSeconds),
+      overtimeSeconds: holiday + Math.max(0, regular - rules.thresholdSeconds),
+    };
+  },
+};
+const rollups = new PeriodRollupService(db, authorizedSubject, resolver,
+  { attendance: true, actorProfileId: authenticatedSupervisorProfileId });
+const card = await rollups.rollup(new Date());
+await rollups.confirm(card.id!);
+await rollups.adjust(card.id!, {
+  operationId: requestId, regularSeconds: 900, overtimeSeconds: 0,
+  reason: 'Approved correction after confirmation',
+});
+const effectiveSeconds = await rollups.totals(card.id!);
+```
+
+A timezone-aware resolver must compute each local boundary separately: a local
+day crossing DST is not necessarily 86400 seconds. Resolvers can use an app's
+existing calendar library; no new timezone dependency or implicit default is
+introduced here.
+
+## Evidence and immutability
+
+Only approved human `ServiceTimeEntry` rows for the subject count; corrected
+ancestors do not. Correction chains must remain within that subject/tenant and
+point to corrected parents. Multiple approved descendants of one root are
+rejected as ambiguous rather than double-counted. Entries with both `startedAt`
+and `endedAt` allocate their declared seconds
+proportionally across the period using exact integer prefix division, preserving
+seconds over adjacent periods. Unbounded entries count at `startedAt`, or, when
+absent, `approvedAt`; an end-only timestamp does not create an interval. Missing
+both attribution timestamps is an error. This is time attribution, not a
+claim that a manual entry has a continuous wall-clock duration.
+
+With `attendance: true`, closed punches without `reviewRequired` count, excluding
+unpaid breaks and retaining paid breaks. Open/review-required punches do not
+count. Linked attendance is authoritative: its evidence entry and any approved
+correction descendants are excluded, including when the punch is still under
+review or outside the requested period. Unlinked approved work entries and
+attendance both count; consumers must link overlapping evidence explicitly.
+Source snapshots preserve each paid attendance segment and entry identity.
+
+Repeated rollup updates one open card per tenant/person/start; a confirmed card
+cannot be recomputed. Confirmation is attributed and idempotent. Model save,
+collection create/update/upsert and object/collection delete cannot bypass the
+service. Model mutation capabilities are per-instance and not exported.
+Direct SQL is a trusted administrative boundary, not an exposed application API.
+Profile/card foreign keys restrict deletion to preserve history.
+
+Adjustments contain signed integer regular/overtime deltas, reason, operation
+key and actor attribution. A retry reuses its row only for the exact same
+payload and actor. Effective totals may never become negative or unsafe.
+Adjustments never alter the confirmed row or source snapshot. Undo an adjustment
+with a separately attributed compensating adjustment, never deletion.
+
+All service mutations use a root transaction, transaction-bound collections,
+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.

package/dist/attendance/models.d.ts

@@ -0,0 +1,59 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/** A tenant-scoped interval of attendance, independent of billable work. */
+export declare class AttendancePunch extends SmrtObject {
+    tenantId: string;
+    profileId: string;
+    startedAt: Date;
+    endedAt: Date | null;
+    durationSeconds: number;
+    unpaidBreakSeconds: number;
+    reviewRequired: boolean;
+    recordedOffline: boolean;
+    serviceTimeEntryId: string | null;
+    /** Unique while open; closed rows retain independent non-null slots on every dialect. */
+    openSlot: string;
+    save(): Promise<this>;
+    private saveConsistent;
+}
+/** A paid or unpaid break inside one attendance punch. */
+export declare class AttendanceBreak extends SmrtObject {
+    tenantId: string;
+    punchId: string;
+    startedAt: Date;
+    endedAt: Date | null;
+    paid: boolean;
+    openSlot: string;
+    save(): Promise<this>;
+    private saveConsistent;
+}
+/** Durable success or conflict; conflicts do not mutate attendance. */
+export interface AttendanceReplayOutcome {
+    clientId: string;
+    punchId?: string;
+    error?: string;
+}
+/** Durable offline-tap outcome; never exposed through generated operations. */
+export declare class AttendanceReplay extends SmrtObject {
+    tenantId: string;
+    replayKey: string;
+    content: string;
+    outcome: string;
+    /** Read a durable receipt, failing closed rather than re-executing a corrupt tap. */
+    getOutcome(): AttendanceReplayOutcome;
+    /** Store the JSON representation of a validated success or refusal. */
+    setOutcome(value: AttendanceReplayOutcome): void;
+    save(): Promise<this>;
+}
+/** Punches for attendance and period rollup. */
+export declare class AttendancePunchCollection extends SmrtCollection<AttendancePunch> {
+    static readonly _itemClass: typeof AttendancePunch;
+}
+/** Break intervals for net duration and period clipping. */
+export declare class AttendanceBreakCollection extends SmrtCollection<AttendanceBreak> {
+    static readonly _itemClass: typeof AttendanceBreak;
+}
+/** Internal durable replay ledger. */
+export declare class AttendanceReplayCollection extends SmrtCollection<AttendanceReplay> {
+    static readonly _itemClass: typeof AttendanceReplay;
+}
+//# sourceMappingURL=models.d.ts.map

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

@@ -0,0 +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"}

package/dist/attendance/service.d.ts

@@ -0,0 +1,64 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { AttendancePunch, type AttendanceReplayOutcome } from './models.js';
+export type { AttendanceReplayOutcome } 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. */
+export interface AttendanceWork {
+    workRefType: string;
+    workRefId: string;
+    description: string;
+}
+/** Offline command with a durable client-generated identifier and device timestamp. */
+export interface AttendanceTap {
+    clientId: string;
+    at: string;
+    action: 'punchIn' | 'punchOut' | 'startBreak' | 'endBreak';
+    paid?: boolean;
+    work?: AttendanceWork;
+}
+/** Expected state conflict, distinct from retryable database failures. */
+export declare class AttendanceConflict extends Error {
+}
+/**
+ * Attendance mutations bound to a trusted tenant/profile. Applications authorize
+ * the actor before constructing this service. Each transition is atomic; all
+ * participating collections use the transaction executor. PostgreSQL serializes
+ * this actor with an advisory lock; embedded adapters serialize writers.
+ */
+export declare class AttendanceService {
+    private readonly db;
+    private readonly actor;
+    constructor(db: DatabaseInterface, actor: AttendanceActor);
+    private identity;
+    private transact;
+    private date;
+    private open;
+    private chronological;
+    /** Open one punch; the database unique slot also protects direct model writers. */
+    punchIn(at?: Date): Promise<AttendancePunch>;
+    /** Close the punch and any active break; optionally create linked draft evidence. */
+    punchOut(at: Date, work?: AttendanceWork): Promise<AttendancePunch>;
+    /** Begin a break; paid defaults false and must be explicitly configured by the caller. */
+    startBreak(at: Date, paid?: boolean): Promise<AttendancePunch>;
+    /** End the current break. */
+    endBreak(at: Date): Promise<AttendancePunch>;
+    private transition;
+    private validateWork;
+    private link;
+    /** Idempotently link a closed, owned punch to draft service evidence. */
+    linkServiceTimeEntry(punchId: string, work: AttendanceWork): Promise<AttendancePunch>;
+    /** Close at startedAt + maxOpenSeconds once due, flagging the punch for review. */
+    autoClose(now: Date, maxOpenSeconds: number): Promise<AttendancePunch | null>;
+    /**
+     * Replay device timestamps in order (ties use clientId). Committed attendance
+     * wins: stale/state-conflicting taps get durable refusals; identical retries
+     * return the same outcome, changed payloads using a key are rejected. A
+     * database failure rolls back its tap and receipt and remains retryable.
+     */
+    replay(taps: readonly AttendanceTap[]): Promise<AttendanceReplayOutcome[]>;
+}
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/attendance/service.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EAEL,eAAe,EAGf,KAAK,uBAAuB,EAC7B,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AACD,uFAAuF;AACvF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED,0EAA0E;AAC1E,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAShD;;;;;GAKG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,EAAE,EAAE,iBAAiB,EACrB,KAAK,EAAE,eAAe;IAUzC,OAAO,CAAC,QAAQ;YAQF,QAAQ;IA0CtB,OAAO,CAAC,IAAI;YAQE,IAAI;YASJ,aAAa;IA+B3B,mFAAmF;IAC7E,OAAO,CAAC,EAAE,OAAa,GAAG,OAAO,CAAC,eAAe,CAAC;IAGxD,qFAAqF;IAC/E,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAKzE,0FAA0F;IACpF,UAAU,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,UAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAKlE,6BAA6B;IACvB,QAAQ,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC;YAMpC,UAAU;IAqFxB,OAAO,CAAC,YAAY;YAcN,IAAI;IA6ClB,yEAAyE;IACnE,oBAAoB,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,eAAe,CAAC;IAY3B,mFAAmF;IAC7E,SAAS,CACb,GAAG,EAAE,IAAI,EACT,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAwBlC;;;;;OAKG;IACG,MAAM,CACV,IAAI,EAAE,SAAS,aAAa,EAAE,GAC7B,OAAO,CAAC,uBAAuB,EAAE,CAAC;CAkGtC"}

package/dist/attendance.d.ts

@@ -0,0 +1,5 @@
+/** Tenant-scoped punches, breaks, automatic close and offline replay. */
+import './__smrt-register__.js';
+export * from './attendance/models.js';
+export * from './attendance/service.js';
+//# sourceMappingURL=attendance.d.ts.map

package/dist/attendance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attendance.d.ts","sourceRoot":"","sources":["../src/attendance.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,OAAO,wBAAwB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC"}