@happyvertical/smrt-timesheets 0.0.0-stage → 0.53.0

package/AGENTS.md

@@ -0,0 +1,105 @@
+# smrt-timesheets
+
+Shared time entries: who (a `smrt-profiles` Profile, or an agent) worked how
+long on what (a generic work reference), whether it was approved, and the
+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.
+
+## Models
+
+| Model | Table | Notes |
+|---|---|---|
+| `ServiceTimeEntry` | `service_time_entries` | `workRefType` + `workRefId`, `participantKind` (`human` \| `agent`), `participantProfileId` / `agentRef`, `source`, `startedAt` / `endedAt` / `durationSeconds`, status machine, `correctionOfId` |
+| `ServiceChargeSnapshot` | `service_charge_snapshots` | Client charge, integer minor units (#2401), one per entry |
+| `ServiceCompensationSnapshot` | `service_compensation_snapshots` | Provider earning, integer minor units, one per entry |
+
+`ServiceEvidenceService` records, submits, approves (writing both snapshots
+through a `ServiceCommercialResolver`), and corrects. `smrt-projects` supplies
+`SubscriptionServiceCommercialResolver` for #1925 pricing.
+
+## Invariants
+
+- **No domain foreign key on the base.** Work context is the generic
+  `workRefType` (qualified class name) + `workRefId`. A domain adds its own
+  context by subclassing over the same table — smrt-support's
+  `ServiceTimeEntry` adds `caseId` / `specialistId` and extends
+  `frozenFieldNames()` so they freeze on approval.
+- **Entries carry no rate.** Money lives only on the snapshots, `= 0`
+  integer initializers (INTEGER columns). Never `= 0.0`. Snapshot `save()`
+  rejects an `amount` that is not a safe integer (`VALIDATION_INVALID_VALUE`),
+  so SQLite cannot silently store `19.99`; fix a fractional resolver at its
+  source rather than rounding here.
+- **Approved evidence never changes.** `save()` enforces
+  `SERVICE_TIME_ENTRY_STATUS_TRANSITIONS` and compares the frozen fields with
+  the stored row. A correction is a new row (`correctionOfId`), the original
+  flips to `corrected`. Snapshots are immutable after their first save.
+- **Old qualified names are aliases.** Each model declares its pre-#3288
+  `@happyvertical/smrt-projects:*` name in `previousQualifiedNames` (#3338;
+  `packages/core/agents/model-moves.md`). smrt-projects must never list these
+  classes in its manifests again (`CONFIG_QUALIFIED_NAME_ALIAS_COLLISION`),
+  and no subtype (smrt-support's, or a consumer's closing subclass) may
+  redeclare an alias (two claimants). Known gap: a same-named subtype that
+  replaces a moved class drops that class's alias, and the replaced class's
+  own `@happyvertical/smrt-timesheets:*` name stops resolving too — guidance
+  for apps with smrt-support must name `@happyvertical/smrt-support:ServiceTimeEntry`.
+  Support's vitest environment keeps both classes registered, so verify this
+  against built packages, not package tests. `projects/src/__tests__/legacy-qualified-identity.test.ts` pins
+  the projects-only contract.
+- **Table names are a compatibility contract.** `service_time_entries` and the
+  two snapshot tables hold existing production rows from smrt-projects /
+  smrt-support; renaming any of them, or adding a discriminator, is a data
+  migration.
+
+## 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.
+
+Subclasses restate their fields: package-isolated manifest scanning does not
+read dependency sources, so an unrestated subclass manifest has no columns.
+
+## Svelte UI
+
+`./svelte` exports `TimeEntryCard`, `TimeEntryList`, `TimeSummary`,
+`DurationDisplay`, and `TimeEntryApprovalQueue` (props-driven, plain view
+objects, `smrt-ui` primitives, `smrtRawPrimitives: "strict"`). smrt-projects
+and smrt-support re-export them from their own `./svelte` subpaths.
+Card/list/summary message keys keep their `projects.*` namespace: tenant
+language overrides are stored by key, and renaming would orphan them. New
+keys use `timesheets.*`.
+
+## Validation
+
+```sh
+pnpm --filter @happyvertical/smrt-timesheets test
+pnpm --filter @happyvertical/smrt-timesheets test:postgres
+pnpm --filter @happyvertical/smrt-timesheets typecheck
+pnpm --filter @happyvertical/smrt-timesheets build
+pnpm --filter @happyvertical/smrt-projects test
+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.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,243 @@
-# Temporary Holding Version
+# @happyvertical/smrt-timesheets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared time entries for s-m-r-t: who worked how long on what, whether someone
+approved it, and what it was charged and paid at approval. One model for
+professional services, shop floors, and job sites, instead of one per vertical.
+
+- **Who** — a `smrt-profiles` Profile (`participantKind: 'human'`) or an agent
+  (`participantKind: 'agent'`, `agentRef`).
+- **What** — a generic work reference: `workRefType` (a qualified class name)
+  and `workRefId`. No domain-specific foreign key on the base entry.
+- **How long** — `startedAt`, `endedAt`, `durationSeconds`, and the `source`
+  (`timer`, `manual`, `import`, `agent`).
+- **Approval** — `draft → submitted → approved | rejected`; approved entries
+  never change. A correction is a new row whose `correctionOfId` points at the
+  entry it corrects, which flips to `corrected`.
+- **Money** — never on the entry. Approval writes one immutable
+  `ServiceChargeSnapshot` and one `ServiceCompensationSnapshot`, in integer
+  minor units (`$19.99` is `1999`), consistent with
+  [`smrt-commerce`](../commerce/README.md).
+
+See [AGENTS.md](./AGENTS.md) for invariants and extension rules.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-timesheets
+```
+
+Add `svelte` for the optional UI components. Application schemas are created
+by migrations (`smrt db:migrate`); the package never creates tables at
+runtime.
+
+## Record, approve, and correct time
+
+```ts
+import { ServiceEvidenceService } from '@happyvertical/smrt-timesheets';
+
+const timesheets = await ServiceEvidenceService.create({ db }, {
+  // Your pricing and pay rules; amounts are integer minor units.
+  priceClient: async (entry) => ({
+    amount: Math.round(entry.durationHours() * 9500),
+    version: 'rates-2026',
+    terms: { hourlyRate: 9500 },
+  }),
+  compensateProvider: async (entry) => ({
+    amount: Math.round(entry.durationHours() * 6000),
+    version: 'pay-2026',
+    terms: { hourlyRate: 6000 },
+  }),
+});
+
+const entry = await timesheets.record({
+  workRefType: '@acme/jobs:WorkPackage',
+  workRefId: 'wp-7',
+  participantKind: 'human',
+  participantProfileId: profile.id,
+  source: 'timer',
+  description: 'Framed the north wall',
+  startedAt: new Date('2026-07-01T08:00:00Z'),
+  endedAt: new Date('2026-07-01T10:30:00Z'),
+});
+
+await timesheets.submit(entry, profile.id);
+await timesheets.approve(entry, { approvalPath: 'operator' });
+```
+
+`record()` rejects a missing or half work reference, a human entry without a
+Profile, an agent entry without `agentRef`, a reversed period, and a
+non-positive duration. `correct(entry, input)` records the replacement and
+marks the approved entry `corrected`.
+
+## Svelte components
+
+```svelte
+<script lang="ts">
+  import { TimeEntryList, TimeSummary } from '@happyvertical/smrt-timesheets/svelte';
+</script>
+
+<TimeSummary totalHours={12.5} totalAmount={118750} currency="CAD" />
+<TimeEntryList {entries} selectable />
+```
+
+`TimeEntryCard`, `TimeEntryList`, `TimeSummary`, `DurationDisplay`, and
+`TimeEntryApprovalQueue` are props-driven: hosts load entries and pass plain
+view objects (`TimeEntry`, `TimeEntryApprovalView`).
+
+## 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 money through its own permission-gated services declares a same-named
+subclass over each table and closes it:
+
+```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
+}
+```
+
+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']`.
+
+## Migrating from smrt-projects / smrt-support
+
+`ServiceTimeEntry`, its collection, `ServiceChargeSnapshot`,
+`ServiceCompensationSnapshot`, their collections, and
+`ServiceEvidenceService` moved here in #3288.
+
+**Consumers already holding `service_time_entries` rows need no schema change
+and no data migration.** The table names, columns, indexes, and conflict keys
+are unchanged, and the tables carry no type discriminator, so existing rows
+load through every package's classes as they are. References stored under
+the old smrt-projects class names keep resolving as deprecated aliases (see
+"Stored and declared class names" below; one gap applies with smrt-support).
+
+> **pnpm: add a direct `@happyvertical/smrt-timesheets` dependency.** The
+> CLI's manifest discovery (`smrt db:migrate`, `db:status`, `db:diff`) reads
+> only packages installed at the top level of `node_modules`. Under pnpm a
+> transitive dependency is not there, so an application that depends on
+> smrt-projects or smrt-support but not on smrt-timesheets stops planning
+> `service_time_entries`, `service_charge_snapshots`, and
+> `service_compensation_snapshots`: a fresh database never gets them (and
+> `ServiceEvidenceService` then fails the runtime table check), and an
+> existing one reports them as orphan tables. Add
+> `pnpm add @happyvertical/smrt-timesheets`. npm and Yarn hoist the package
+> and are unaffected.
+
+| Before | After |
+|---|---|
+| `@happyvertical/smrt-projects` / `@happyvertical/smrt-support` in `dependencies` | Also add `@happyvertical/smrt-timesheets` under pnpm, or the CLI stops planning the three time tables (see the note above) |
+| `ServiceTimeEntry`, `ServiceEvidenceService`, snapshots from `@happyvertical/smrt-projects` | Same names, still exported from smrt-projects (re-exports); new code imports `@happyvertical/smrt-timesheets` |
+| `ServiceTimeEntry` from `@happyvertical/smrt-support` | Unchanged: support's subtype, now extending the timesheets entry |
+| `caseId` / `specialistId`, `forCase()` / `forSpecialist()` on the projects export | Support subtype only — import `ServiceTimeEntry` / `ServiceTimeEntryCollection` from smrt-support |
+| `ServiceEvidenceService.record({ caseId })` | Requires `workRefType` + `workRefId`; record case time through smrt-support's `ServiceTimeEntryService` |
+| `@happyvertical/smrt-projects:ServiceTimeEntry` (and the two snapshot names) stored in `meta_type` or declared in `@crossPackageRef` / playbook `model:` | Resolves as a deprecated alias of `@happyvertical/smrt-timesheets:*`; move declarations to the class that is registered in your app — `@happyvertical/smrt-timesheets:*`, except `@happyvertical/smrt-support:ServiceTimeEntry` when smrt-support is installed (or your own closing subclass) — and optionally backfill stored rows with `smrt db:migrate-qualified-names` (see below) |
+| `TimeEntryList`, `TimeEntryCard`, `TimeSummary`, `DurationDisplay` from `@happyvertical/smrt-projects/svelte`; `TimeEntryApprovalQueue` from `@happyvertical/smrt-support/svelte` | Still exported there; canonical home `@happyvertical/smrt-timesheets/svelte` |
+
+An application with smrt-projects but not smrt-support keeps its existing
+`case_id` / `specialist_id` columns: `db:migrate` reports them as orphan
+columns and never alters or drops them, and saves through the shared entry
+leave their values untouched.
+
+### Stored and declared class names
+
+The moved models' registered names changed from
+`@happyvertical/smrt-projects:*` to `@happyvertical/smrt-timesheets:*`. Each
+class declares its old name in `previousQualifiedNames` (#3338), so references
+that stored or declared it keep resolving as a **deprecated alias**:
+polymorphic association rows (`metaType`, including smrt-assets
+`AssetAssociation`), `ObjectRegistry.getClassByQualifiedName()`,
+`@crossPackageRef` and relationship targets, and playbook step `model:`
+names. The first resolution of each old name per process logs a deprecation
+warning; new association writes store the current name. Generated routes,
+MCP tool names, and permission slugs derive from simple and collection names
+and are unchanged.
+
+- `smrt doctor --db` counts stored references that still use an old name
+  ("Deprecated Qualified Names").
+- `smrt db:migrate-qualified-names` is an opt-in backfill that rewrites them
+  to the current names (`--dry-run` first); it is never run automatically.
+- Move source references — `@crossPackageRef(...)`, relationship targets,
+  playbook `model:` names — to the name of the class your application
+  actually registers, now. That is `@happyvertical/smrt-timesheets:*`, except
+  where a same-named subclass replaces the timesheets class: with smrt-support
+  installed, reference `@happyvertical/smrt-support:ServiceTimeEntry` (the
+  timesheets name is not registered there, so a `@crossPackageRef` to it
+  fails to load and an association stored under it hydrates to `null`); with
+  your own closing subclass, reference your subclass's qualified name. The
+  snapshots keep their timesheets names unless you subclass them. The aliases
+  will be removed in a later **breaking** release, once `smrt doctor --db`
+  reports no stored references.
+
+> **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") —
+> 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
+> (hydration returns `null`) and `smrt doctor --db` /
+> `db:migrate-qualified-names` do not see it; the snapshot aliases still work
+> unless the application subclasses the snapshots too. A subclass must not
+> redeclare the alias (two claimants of one old name collide). Until core
+> carries aliases across the replacement, rewrite affected stored references
+> (typically `meta_type` columns) to the replacing class's current name, e.g.
+> `@happyvertical/smrt-support:ServiceTimeEntry`.
+
+## Related packages
+
+- [`smrt-projects`](../projects/README.md) — delivery work and
+  `SubscriptionServiceCommercialResolver` pricing for these entries.
+- [`smrt-support`](../support/README.md) — support-case time on the same table.
+- [`smrt-profiles`](../profiles/README.md) — the participants.

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @happyvertical/smrt-timesheets
+ *
+ * Shared time entries: who (a smrt-profiles Profile or an agent) worked how
+ * long on what (a generic work reference), approval and correction, and the
+ * immutable charge / compensation snapshots taken at approval.
+ *
+ * `smrt-projects` re-exports all of these classes unchanged under their
+ * existing names. `smrt-support` subclasses only `ServiceTimeEntry` (adding
+ * `caseId` / `specialistId`) over the same table; the snapshots and
+ * `ServiceEvidenceService` are used from this package as they are.
+ *
+ * @packageDocumentation
+ */
+import './__smrt-register__.js';
+export * from './models/index.js';
+export * from './services/index.js';
+export { SERVICE_TIME_ENTRY_STATUS_TRANSITIONS, type ServiceEvidence, type ServiceParticipantKind, type ServiceTimeEntrySource, type ServiceTimeEntryStatus, } from './types.js';
+export { TIMESHEETS_MODULE_META, TIMESHEETS_UI_SLOTS } from './ui.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,wBAAwB,CAAC;AAEhC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EACL,qCAAqC,EACrC,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}