@happyvertical/smrt-human-resources 0.0.0-stage → 0.53.6

package/dist/qualifications/index.d.ts

@@ -0,0 +1,3 @@
+export * from './models.js';
+export * from './service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/qualifications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/qualifications/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/qualifications/internal.d.ts

@@ -0,0 +1,24 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import type { HrEventQueue } from '../service-base.js';
+import type { HrActor, IsoDate } from '../types.js';
+import { type HeldQualification } from './models.js';
+/** Reason recorded when an employment-scoped qualification ends with its employment. */
+export declare const EMPLOYMENT_ENDED_REASON = "employment-ended";
+/**
+ * End every qualification that belongs to an employment, from `effectiveOn`
+ * (the day after the last day employed). Called by EmploymentService inside
+ * the transaction that ends the employment, so the two never disagree.
+ * Person-scoped qualifications are untouched.
+ *
+ * The decision is made per renewal chain, from the chain's dated history and
+ * not from any stored status: the latest row of a chain gets the
+ * `employment-ended` revocation, and one event, unless a revocation effective
+ * on or before `effectiveOn` is already recorded anywhere in the chain. The
+ * rows that latest row renewed are not written: the dated replay cuts them
+ * off through the chain. A latest row whose stored status is already
+ * `revoked` (a later-dated revocation was recorded) is not saved again; only
+ * the change row is appended, and the replay treats the earliest revocation
+ * as in force. Returns the latest rows that were cut off.
+ */
+export declare function revokeEmploymentQualifications(db: DatabaseInterface, actor: Readonly<HrActor>, employmentId: string, effectiveOn: IsoDate, queue: HrEventQueue): Promise<HeldQualification[]>;
+//# sourceMappingURL=internal.d.ts.map

package/dist/qualifications/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/qualifications/internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EACL,KAAK,iBAAiB,EAIvB,MAAM,aAAa,CAAC;AAErB,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,8BAA8B,CAClD,EAAE,EAAE,iBAAiB,EACrB,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,EACxB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,OAAO,EACpB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA4D9B"}

package/dist/qualifications/models.d.ts

@@ -0,0 +1,77 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+import { type HeldQualificationChangeKind, type HeldQualificationStatus, type IsoDate, type QualificationKind, type QualificationScope } from '../types.js';
+/**
+ * A qualification definition: a managed list per tenant. Other packages gate
+ * work by referencing its id (`@happyvertical/smrt-human-resources:Qualification`).
+ * Not a permission: who may use the software stays with smrt-users.
+ */
+export declare class Qualification extends SmrtObject {
+    tenantId: string;
+    /** Lowercase kebab-case, unique per tenant: `first-aid`. */
+    key: string;
+    name: string;
+    kind: QualificationKind;
+    issuingBody: string;
+    /** Whether held qualifications of this kind expire. */
+    expires: boolean;
+    /** Default validity in months, applied when a grant gives no expiry. */
+    validityMonths: number | null;
+    /** Whether a held qualification belongs to the person or the employment. */
+    scope: QualificationScope;
+    isActive: boolean;
+    save(): Promise<this>;
+    delete(): Promise<void>;
+}
+/**
+ * A person holds a qualification. `employmentId` is set when the definition's
+ * scope is `employment`; such a row is revoked when that employment ends.
+ * A renewal is a new row pointing at the one it renews, so past dates still
+ * answer correctly. Expiry on a date is computed from `expiresOn`; the stored
+ * `expired` status is set by the service sweep. The stored status records the
+ * last change made, not standing on a date, and `revoked` is final: a row
+ * stored `revoked` is saved again only to record a verification.
+ */
+export declare class HeldQualification extends SmrtObject {
+    tenantId: string;
+    qualificationId: string;
+    profileId: string;
+    employmentId: string | null;
+    issuedOn: IsoDate;
+    expiresOn: IsoDate | null;
+    certificateNumber: string;
+    status: HeldQualificationStatus;
+    verifiedByProfileId: string | null;
+    verifiedAt: Date | null;
+    documentAssetId: string | null;
+    renewalOfId: string | null;
+    save(): Promise<this>;
+    delete(): Promise<void>;
+}
+/** Append-only dated change to a held qualification, attributed to an actor. */
+export declare class HeldQualificationChange extends SmrtObject {
+    tenantId: string;
+    heldQualificationId: string;
+    kind: HeldQualificationChangeKind;
+    effectiveOn: IsoDate;
+    reason: string;
+    actorProfileId: string;
+    save(): Promise<this>;
+    delete(): Promise<void>;
+}
+/**
+ * Scoped definition collection; mutations must use QualificationService.
+ * Collections are registered too, so each restates the closed surface: an
+ * undecorated one would publish its methods as generated tools.
+ */
+export declare class QualificationCollection extends SmrtCollection<Qualification> {
+    static readonly _itemClass: typeof Qualification;
+}
+/** Scoped held-qualification collection; closed like its model. */
+export declare class HeldQualificationCollection extends SmrtCollection<HeldQualification> {
+    static readonly _itemClass: typeof HeldQualification;
+}
+/** Scoped append-only change collection; closed like its model. */
+export declare class HeldQualificationChangeCollection extends SmrtCollection<HeldQualificationChange> {
+    static readonly _itemClass: typeof HeldQualificationChange;
+}
+//# sourceMappingURL=models.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/qualifications/models.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAE5B,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAGrB;;;;GAIG;AACH,qBASa,aAAc,SAAQ,UAAU;IAC/B,QAAQ,SAAM;IAC1B,4DAA4D;IAC5D,GAAG,SAAM;IACT,IAAI,SAAM;IACe,IAAI,EAAE,iBAAiB,CAAmB;IACnE,WAAW,SAAM;IACjB,uDAAuD;IACvD,OAAO,UAAS;IAChB,wEAAwE;IAExE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAQ;IACrC,4EAA4E;IACnD,KAAK,EAAE,kBAAkB,CAAY;IAC9D,QAAQ,UAAQ;IAED,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC;AAmBD;;;;;;;;GAQG;AACH,qBAkBa,iBAAkB,SAAQ,UAAU;IACnC,QAAQ,SAAM;IAC2B,eAAe,SAAM;IAI1E,SAAS,SAAM;IAEf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAQ;IACV,QAAQ,EAAE,OAAO,CAAM;IACP,SAAS,EAAE,OAAO,GAAG,IAAI,CAAQ;IAC1E,iBAAiB,SAAM;IACE,MAAM,EAAE,uBAAuB,CAAW;IAKnE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC1C,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEtC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BrB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC;AAED,gFAAgF;AAChF,qBAca,uBAAwB,SAAQ,UAAU;IACzC,QAAQ,SAAM;IAE1B,mBAAmB,SAAM;IACA,IAAI,EAAE,2BAA2B,CAAa;IAC9C,WAAW,EAAE,OAAO,CAAM;IACnD,MAAM,SAAM;IAIZ,cAAc,SAAM;IAEL,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAUrB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC;AAED;;;;GAIG;AACH,qBACa,uBAAwB,SAAQ,cAAc,CAAC,aAAa,CAAC;IACxE,MAAM,CAAC,QAAQ,CAAC,UAAU,uBAAiB;CAC5C;AACD,mEAAmE;AACnE,qBACa,2BAA4B,SAAQ,cAAc,CAAC,iBAAiB,CAAC;IAChF,MAAM,CAAC,QAAQ,CAAC,UAAU,2BAAqB;CAChD;AACD,mEAAmE;AACnE,qBACa,iCAAkC,SAAQ,cAAc,CAAC,uBAAuB,CAAC;IAC5F,MAAM,CAAC,QAAQ,CAAC,UAAU,iCAA2B;CACtD"}

package/dist/qualifications/service.d.ts

@@ -0,0 +1,381 @@
+import { HrService } from '../service-base.js';
+import { type HeldQualificationStatus, type IsoDate, type QualificationCheck, type QualificationKind, type QualificationScope } from '../types.js';
+import { HeldQualification, HeldQualificationChange, Qualification } from './models.js';
+/** Input for {@link QualificationService.define} and {@link QualificationService.seed}. */
+export interface DefineQualificationInput {
+    /** Lowercase kebab-case, unique per tenant: `first-aid`. */
+    key: string;
+    /** Display name. */
+    name: string;
+    /** What the qualification is. */
+    kind: QualificationKind;
+    /** Who issues it; free text. */
+    issuingBody?: string;
+    /** Whether held qualifications of this kind expire. Defaults to false. */
+    expires?: boolean;
+    /** Default validity in months; only meaningful when `expires` is true. */
+    validityMonths?: number | null;
+    /** Defaults to `employment` for kind `authorization`, else `person`. */
+    scope?: QualificationScope;
+}
+/** Input for {@link QualificationService.update}. Key and scope never change. */
+export interface UpdateQualificationInput {
+    /** New display name. */
+    name?: string;
+    /** New issuing body. */
+    issuingBody?: string;
+    /** Whether new grants expire; turning it off clears `validityMonths`. */
+    expires?: boolean;
+    /** New default validity in months, or null for none. */
+    validityMonths?: number | null;
+    /** Deactivate (or reactivate) the definition; inactive ones cannot be granted. */
+    isActive?: boolean;
+}
+/** Options for {@link QualificationService.list}. */
+export interface ListQualificationsOptions {
+    /** Include deactivated definitions. Defaults to false. */
+    includeInactive?: boolean;
+}
+/** Input for {@link QualificationService.grant}. */
+export interface GrantQualificationInput {
+    /** The definition being granted. */
+    qualificationId: string;
+    /** The person receiving it. */
+    profileId: string;
+    /** First day it is valid. */
+    issuedOn: IsoDate;
+    /** Last day it is valid (inclusive). Defaults from the definition's validity. */
+    expiresOn?: IsoDate | null;
+    /** Certificate or ticket number; free text. */
+    certificateNumber?: string;
+    /** Optional `smrt-assets:Asset` id of the scanned document. */
+    documentAssetId?: string | null;
+    /** Record the actor as having verified the document, now. */
+    verified?: boolean;
+    /** For an employment-scoped definition; resolved from the profile when omitted. */
+    employmentId?: string | null;
+}
+/** Input for {@link QualificationService.renew}. */
+export interface RenewQualificationInput {
+    /** First day the renewal is valid. */
+    issuedOn: IsoDate;
+    /** Last day it is valid (inclusive). Defaults from the definition's validity. */
+    expiresOn?: IsoDate | null;
+    /** Certificate or ticket number of the renewal. */
+    certificateNumber?: string;
+    /** Optional `smrt-assets:Asset` id of the renewal's document. */
+    documentAssetId?: string | null;
+    /** Record the actor as having verified the document, now. */
+    verified?: boolean;
+}
+/** Input for suspending or revoking a held qualification. */
+export interface HeldQualificationReasonInput {
+    /** The calendar date the change takes effect (that day included). */
+    effectiveOn: IsoDate;
+    /** Why; required. */
+    reason: string;
+}
+/** Input for {@link QualificationService.reinstate}. */
+export interface ReinstateQualificationInput {
+    /** The calendar date the qualification is good again (that day included). */
+    effectiveOn: IsoDate;
+    /** Optional note. */
+    reason?: string;
+}
+/** Input for {@link QualificationService.verify}. */
+export interface VerifyQualificationInput {
+    /**
+     * `smrt-assets:Asset` id of the document to attach or replace; null removes
+     * it, and omitting it keeps the current one.
+     */
+    documentAssetId?: string | null;
+}
+/** Options for {@link QualificationService.holders}. */
+export interface QualificationHoldersOptions {
+    /** Only people with an employment term covering the date. */
+    employedOnly?: boolean;
+}
+/** Options for {@link QualificationService.sweepExpired}. */
+export interface SweepExpiredOptions {
+    /**
+     * Only look at qualifications whose last day is on or after this date.
+     * Bounds the work of a scheduled sweep; omit it to look at all history.
+     */
+    since?: IsoDate | null;
+}
+/** Options for {@link QualificationService.expiringWithin}. */
+export interface ExpiringQualificationsOptions {
+    /** Only people with an employment term covering `today`. */
+    employedOnly?: boolean;
+}
+/** Status of a held qualification computed for one calendar date. */
+export type HeldQualificationStatusOn = HeldQualificationStatus | 'not-yet-issued';
+/** One row of {@link QualificationService.listForProfile}. */
+export interface ProfileQualification {
+    /** What the person holds. */
+    held: HeldQualification;
+    /** Its definition. */
+    qualification: Qualification;
+    /** Status computed for the requested date. */
+    status: HeldQualificationStatusOn;
+}
+/**
+ * A small, generic starter list an application may pass to
+ * {@link QualificationService.seed}. Illustrative only: validity periods and
+ * what a restriction means are the application's and its jurisdiction's call.
+ */
+export declare const SUGGESTED_QUALIFICATIONS: readonly DefineQualificationInput[];
+/**
+ * The only writer of qualification definitions and held qualifications, and
+ * the gate ({@link QualificationService.check}) applications call before
+ * letting a person do qualified work. Constructed from a trusted
+ * tenant/profile actor the application has already authorized.
+ *
+ * Whether a qualification is good on a date is computed from `issuedOn`,
+ * `expiresOn` and the dated change history, so past dates keep answering
+ * correctly and expiry needs no scheduler. The stored status records the
+ * last change made (a revocation or suspension stores at once, even when it
+ * takes effect later), so every rule that asks about standing replays the
+ * dated history instead, including the rules that decide whether a
+ * qualification may be suspended, reinstated, revoked or renewed. A stored
+ * `revoked` is final: later changes to such a row are change rows only. The
+ * stored `expired` status is written by
+ * {@link QualificationService.sweepExpired}, and by a reinstatement of a row
+ * whose lapse the sweep has recorded.
+ */
+export declare class QualificationService extends HrService {
+    /** Add a qualification definition; its key is unique per tenant. */
+    define(input: DefineQualificationInput): Promise<Qualification>;
+    /** Change a definition's descriptive fields; key and scope are immutable. */
+    update(qualificationId: string, input: UpdateQualificationInput): Promise<Qualification>;
+    /**
+     * Create the definitions whose key is missing and leave existing rows
+     * untouched. Returns one definition per input, in input order.
+     */
+    seed(definitions: readonly DefineQualificationInput[]): Promise<Qualification[]>;
+    /** The tenant's definitions ordered by key; active ones unless asked. */
+    list(options?: ListQualificationsOptions): Promise<Qualification[]>;
+    /**
+     * One definition by id.
+     *
+     * @throws HrError `HR_NOT_FOUND` outside the actor's tenant, `HR_INVALID` for a blank id
+     */
+    get(qualificationId: string): Promise<Qualification>;
+    /** One definition by key, or null. */
+    findByKey(key: string): Promise<Qualification | null>;
+    /**
+     * Record that a person holds a qualification from `issuedOn`.
+     *
+     * A person has one live grant of a qualification at a time, decided by
+     * date: the grant is refused unless everything they already hold of it is
+     * revoked effective on or before `issuedOn`. A lapsed ticket (swept or not)
+     * is renewed, not granted again, and a revocation scheduled for a later
+     * date does not free an earlier issue date.
+     *
+     * An employment-scoped grant dated inside a term whose end is already
+     * recorded ends with that employment: the `employment-ended` revocation,
+     * effective the day after the term's last day, is recorded in the same
+     * transaction and the row is stored `revoked`.
+     *
+     * @throws HrError `HR_ALREADY_HELD` unless every earlier grant is revoked effective on or before `issuedOn` (renew the existing one instead), `HR_QUALIFICATION_SCOPE`, `HR_INVALID`, `HR_NOT_FOUND`
+     */
+    grant(input: GrantQualificationInput): Promise<HeldQualification>;
+    /**
+     * Renew a held qualification: a new row pointing at the old one. The old row
+     * is not modified, so checks on past dates still answer from it. Only the
+     * latest row of a chain can be renewed.
+     *
+     * The renewal is validated against the old row's dated history, not its
+     * stored status: `issuedOn` cannot be earlier than the row's latest
+     * suspension or reinstatement (the renewal would otherwise answer for dates
+     * the history says were suspended), the row must not be suspended on
+     * `issuedOn`, and it must not be revoked on or before `issuedOn`.
+     *
+     * A revocation recorded for a later date (a scheduled one, or the end of an
+     * employment whose last day is ahead) does not stop a renewal: the
+     * qualification is still in force, so a ticket that lapses first can be
+     * renewed. The renewal carries the cutoff forward. It is stored `revoked`
+     * with a revocation at the earlier of the old row's pending revocation
+     * (with its reason) and, for an employment-scoped one inside a term whose
+     * end is recorded, the day after the last day employed
+     * (`employment-ended`); `held-qualification.renewed` and
+     * `held-qualification.revoked` are both raised.
+     *
+     * @throws HrError `HR_STATUS_TRANSITION` when suspended on `issuedOn` (reinstate it first); `HR_ALREADY_HELD` when the person holds another grant outside this chain that is not revoked on or before `issuedOn` and starts before the day this renewal is cut off; `HR_INVALID` for a row revoked on or before `issuedOn`, an already renewed row, an `issuedOn` before the row's own or before its latest suspension or reinstatement, or an expiry earlier than the row's own (revoke it and grant a new one instead); `HR_NOT_FOUND`
+     */
+    renew(heldQualificationId: string, input: RenewQualificationInput): Promise<HeldQualification>;
+    /**
+     * Suspend a qualification from `effectiveOn` until it is reinstated. Act on
+     * the latest row of a renewal chain: the whole chain shares its standing,
+     * so the rows it renewed stop passing checks too.
+     *
+     * Whether it can be suspended is decided from the chain's dated history as
+     * of `effectiveOn`, never from the stored status: it must be neither
+     * suspended nor revoked on that day. A revocation recorded for a later date
+     * (scheduled, or the end of an employment whose last day is ahead) does not
+     * prevent it, and neither does a stored `expired`.
+     *
+     * `effectiveOn` may be any date from the chain's first issue date onward,
+     * not before the chain's latest suspension or reinstatement. It may precede
+     * the latest row's own issue date: with a renewal recorded ahead of time,
+     * that is how the ticket in force today is suspended, and the renewal is
+     * then suspended from its issue date until reinstated.
+     *
+     * The stored status becomes `suspended`, except on a row already stored
+     * `revoked`, which keeps it: only the change row is added.
+     *
+     * @throws HrError `HR_INVALID` for a row that was renewed, a date outside that range or a bad input; `HR_STATUS_TRANSITION` when suspended or revoked on `effectiveOn`; `HR_NOT_FOUND`
+     */
+    suspend(heldQualificationId: string, input: HeldQualificationReasonInput): Promise<HeldQualification>;
+    /**
+     * Lift a suspension from `effectiveOn`, which follows the same date rule as
+     * {@link suspend}. The chain must be suspended on that day by its dated
+     * history, and not yet revoked. The stored status becomes `valid`, or
+     * `expired` when the sweep has recorded the row's lapse; a stored `revoked`
+     * stays.
+     *
+     * @throws HrError `HR_INVALID` for a row that was renewed, a date before the suspension or a bad input; `HR_STATUS_TRANSITION` unless suspended on `effectiveOn`; `HR_NOT_FOUND`
+     */
+    reinstate(heldQualificationId: string, input: ReinstateQualificationInput): Promise<HeldQualification>;
+    /**
+     * Revoke a qualification from `effectiveOn`. Terminal: grant a new one
+     * dated on or after it. Act on the latest row of a renewal chain: the rows
+     * it renewed stop passing checks from the same date; dated before a renewal
+     * recorded ahead of time, the renewal is revoked from its issue date.
+     *
+     * `effectiveOn` may be any date from the chain's first issue date onward,
+     * whatever else is recorded: an urgent revocation may be dated before a
+     * suspension recorded ahead of time, or before a revocation that has not
+     * taken effect yet (a scheduled one, or the end of an employment whose last
+     * day is ahead). The earliest revocation is the one in force. It is refused
+     * only when the chain is already revoked on or before `effectiveOn`.
+     *
+     * The stored status becomes `revoked` at once, meaning a revocation has
+     * been recorded; until `effectiveOn` the qualification still passes
+     * {@link check}. A row already stored `revoked` is not saved again: the
+     * earlier revocation is one more change row, and the event carries its
+     * date.
+     *
+     * @throws HrError `HR_INVALID` for a row that was renewed, a date before the chain was issued or a bad input; `HR_STATUS_TRANSITION` when already revoked on or before `effectiveOn`; `HR_NOT_FOUND`
+     */
+    revoke(heldQualificationId: string, input: HeldQualificationReasonInput): Promise<HeldQualification>;
+    /**
+     * Record that the actor has verified a held qualification's document, now.
+     * Optionally attaches, replaces or removes the document. The status and the
+     * dated history do not change, and no event is raised. Verification is not
+     * a status, so it works whatever the standing, including on a row stored
+     * `revoked` (which may still be in force until its revocation takes effect).
+     *
+     * @throws HrError `HR_INVALID`, `HR_NOT_FOUND`
+     */
+    verify(heldQualificationId: string, input?: VerifyQualificationInput): Promise<HeldQualification>;
+    /**
+     * Record the lapse of every qualification whose last day is before `today`
+     * and that was still in force on it: an `expired` change dated the day
+     * after `expiresOn`. The application calls this from its own scheduler;
+     * checks never depend on it. Idempotent: a row is recorded once.
+     *
+     * Which rows lapsed is decided by date, not by the stored status, so a
+     * ticket that runs out while a suspension is in force, or while a
+     * revocation is recorded for a later day (a notice period), is recorded
+     * too. A row revoked on or before the day after `expiresOn` did not lapse:
+     * it was revoked. The stored status becomes `expired` only on a row stored
+     * `valid`; a stored `suspended` or `revoked` stays as it is.
+     *
+     * Every run re-reads the lapsed rows stored `suspended` or `revoked`, a set
+     * that only grows with a tenant's history. Pass `since` (a day on or before
+     * the last day the previous run covered) to look only at rows whose last
+     * day is on or after it.
+     *
+     * Emits `held-qualification.expired`, and returns the row, only for
+     * qualifications that were not renewed.
+     *
+     * @throws HrError `HR_INVALID` for a bad `today` or `since`
+     */
+    sweepExpired(today: IsoDate, options?: SweepExpiredOptions): Promise<HeldQualification[]>;
+    /**
+     * Whether a person holds a qualification on a calendar date. Computed from
+     * issue and expiry dates and the dated change history, never from the stored
+     * status alone, so it is correct for past dates and without the sweep. A
+     * renewal chain shares its standing: while a renewal is revoked or
+     * suspended, the row it renewed does not pass either. A blank profile or
+     * qualification id is `not-held`.
+     */
+    check(profileId: string, qualificationId: string, on: IsoDate): Promise<QualificationCheck>;
+    /**
+     * One held qualification per person who passes {@link check} on `on`,
+     * ordered by profile id.
+     */
+    holders(qualificationId: string, on: IsoDate, options?: QualificationHoldersOptions): Promise<HeldQualification[]>;
+    /**
+     * Qualifications good on `today` (issued, and not suspended or revoked by
+     * the dated history, exactly as {@link check} decides) whose last day falls
+     * in `[today, today + days]`, soonest first. The stored status plays no
+     * part. A qualification that was already renewed is left out, and
+     * `employedOnly` keeps only people with an employment term covering `today`.
+     */
+    expiringWithin(days: number, today: IsoDate, options?: ExpiringQualificationsOptions): Promise<HeldQualification[]>;
+    /**
+     * Everything a person holds (renewed rows are replaced by their renewal),
+     * each with its definition and its status computed for `on`. The status
+     * agrees with {@link check}: it is `valid` when the row, or a row it renews,
+     * is good on `on`, and otherwise the status of the latest row of the chain
+     * issued by `on`. Ordered by qualification key, then issue date.
+     *
+     * @throws HrError `HR_INVALID` for a blank profile id or a bad date
+     */
+    listForProfile(profileId: string, on: IsoDate): Promise<ProfileQualification[]>;
+    /**
+     * The dated changes of one held qualification, oldest first.
+     *
+     * @throws HrError `HR_NOT_FOUND` outside the actor's tenant, `HR_INVALID` for a blank id
+     */
+    history(heldQualificationId: string): Promise<HeldQualificationChange[]>;
+    private byKey;
+    private definition;
+    private grantable;
+    private insertDefinition;
+    private held;
+    /** Held rows in the actor's tenant matching `where`. */
+    private rows;
+    private rowsById;
+    /**
+     * The chains among `rows` (everything one person holds of one
+     * qualification) that are not revoked effective on or before `on`, each
+     * represented by its latest row and the date its revocation takes effect,
+     * if one is recorded. The chain whose latest row is `exceptId` is skipped.
+     * Decided from the dated history: a revocation stored now but effective
+     * later still counts as held.
+     */
+    private liveChains;
+    /** Ids, among `rows`, that a later row renews. */
+    private supersededIds;
+    /** Change rows per held qualification, oldest first. */
+    private changesByHeld;
+    /**
+     * The employment an employment-scoped grant belongs to (null for a
+     * person-scoped one) and, when the term covering `issuedOn` already has its
+     * end recorded, that term's last day. The person must be employed on
+     * `issuedOn`.
+     */
+    private employmentFor;
+    /**
+     * Insert a granted or renewed row with its change and event. With a
+     * `revocation` (the end of an employment term that is already closed, or a
+     * pending revocation a renewal carries forward) the row starts out cut off,
+     * exactly as `EmploymentService.end()` leaves the rows that existed when
+     * the end was recorded: stored `revoked`, a revocation on that date, and
+     * the revoked event.
+     */
+    private insertHeld;
+    /**
+     * Suspend, reinstate or revoke the latest row of a chain. The change is
+     * validated against the chain's dated history as of `effectiveOn`; the
+     * stored status is not consulted, except that a row stored `revoked` is
+     * never saved again and gets the change row only.
+     */
+    private transition;
+    private recordChange;
+    private announce;
+}
+//# sourceMappingURL=service.d.ts.map

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

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

package/dist/service-base.d.ts

@@ -0,0 +1,47 @@
+import { type DatabaseInterface } from '@happyvertical/sql';
+import { type HrActor, type HrEvent, type HrServiceOptions } from './types.js';
+/** Collects events inside a transaction; they are delivered after it commits. */
+export type HrEventQueue = (event: HrEvent) => void;
+/**
+ * Shared plumbing for the HR services: a trusted tenant/profile actor, scoped
+ * reads, serialized transactional writes, and after-commit event delivery.
+ * Applications authorize the actor before constructing a service. Reads and
+ * writes reject conflicting ambient tenancy.
+ *
+ * Construct a service with the root database handle. A mutation begins and
+ * commits its own transaction with `beginTransaction()` and then delivers its
+ * events; on a handle that is already inside a transaction (the `tx` of
+ * `db.transaction()`, or a `beginTransaction()` handle) the commit would
+ * belong to the caller, so a mutation is refused with
+ * `HR_TRANSACTION_UNSUPPORTED` before anything is written. Such a handle
+ * either has no `beginTransaction` or refuses it with the SDK's
+ * `NestedTransactionError`; the service never opens a nested (savepoint)
+ * transaction. Reads work on any handle.
+ */
+export declare abstract class HrService {
+    protected readonly db: DatabaseInterface;
+    protected readonly actor: Readonly<HrActor>;
+    private readonly onEvent;
+    constructor(db: DatabaseInterface, actor: HrActor, options?: HrServiceOptions);
+    /** Normalize an id; PostgreSQL stores identities as UUIDs. */
+    protected identity(value: string): string;
+    /**
+     * A required id from caller input, trimmed and normalized.
+     *
+     * @throws HrError `HR_INVALID` when it is not text or is blank
+     */
+    protected id(fieldName: string, value: unknown): string;
+    /** An optional id from caller input: null or undefined is null. */
+    protected optionalId(fieldName: string, value: unknown): string | null;
+    /** Run a read inside the actor's tenant. */
+    protected scope<T>(run: () => Promise<T>): Promise<T>;
+    /**
+     * Run a mutation in one transaction, serialized per tenant, then deliver the
+     * events it queued. Nothing is delivered when the transaction fails.
+     *
+     * @throws HrError `HR_TRANSACTION_UNSUPPORTED` when the service was constructed with a handle that is already inside a transaction
+     */
+    protected transact<T>(run: (db: DatabaseInterface, queue: HrEventQueue) => Promise<T>): Promise<T>;
+    private emit;
+}
+//# sourceMappingURL=service-base.d.ts.map

package/dist/service-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-base.d.ts","sourceRoot":"","sources":["../src/service-base.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAIpB,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,8BAAsB,SAAS;IAK3B,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,iBAAiB;IAJ1C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;gBAGjC,EAAE,EAAE,iBAAiB,EACxC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gBAAqB;IAchC,8DAA8D;IAC9D,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAWzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM;IAMvD,mEAAmE;IACnE,SAAS,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAMtE,4CAA4C;IAC5C,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAUrD;;;;;OAKG;cACa,QAAQ,CAAC,CAAC,EACxB,GAAG,EAAE,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9D,OAAO,CAAC,CAAC,CAAC;YAgDC,IAAI;CAWnB"}