@happyvertical/smrt-support 0.51.32 → 0.51.35

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-support",
-  "packageVersion": "0.51.32",
+  "packageVersion": "0.51.35",
   "objects": {
     "@happyvertical/smrt-support:ServiceTimeEntry": {
       "name": "servicetimeentry",

package/dist/migrations/moneyMinorUnits.d.ts

@@ -1,4 +1,33 @@
-import { DatabaseInterface, MinorUnitsPreflightResult, MinorUnitsRescaleResult, MoneyColumnTarget } from '@happyvertical/smrt-core/migrations';
+/**
+ * Support money columns: floating-point major units → integer minor units.
+ *
+ * Ships as an explicit, opt-in migration rather than a schema-differ upgrade
+ * because REAL→INTEGER is not information-preserving: an automatic
+ * `ALTER … TYPE integer` would truncate `19.99` to `19`. The values have to be
+ * rescaled by the currency's minor-unit factor during the type change (#2401).
+ *
+ * ```ts
+ * console.log((await preflightSupportMoneyMinorUnits(db)).summary);
+ * await migrateSupportMoneyToMinorUnits(db);
+ * ```
+ *
+ * **Rate columns are deliberately absent.** `SupportPlan.overageHourlyRate`,
+ * `SupportPlan.onCallHourlyRate` and `SupportCompensationPlan.hourlyRate` stay
+ * DECIMAL — a rate is inherently fractional — but their *unit* changes from
+ * major units per hour to **minor units per hour**, so existing rows must be
+ * multiplied by the same scale. That is a value change with no type change, and
+ * the column list below cannot express it; rescale them in the same deploy
+ * step, e.g. `UPDATE support_plans SET overage_hourly_rate = overage_hourly_rate * 100`.
+ *
+ * Frozen `rateSnapshot` JSON on already-settled charges is history and is left
+ * alone: it records what the rate was when the charge was priced, and the
+ * amount beside it is rescaled by this migration.
+ *
+ * On SQLite the values are rescaled but the declared type cannot change in
+ * place; those columns come back in `declaredTypeChangePending` and need the
+ * table-rebuild path (#2370).
+ */
+import { type DatabaseInterface, type MinorUnitsPreflightResult, type MinorUnitsRescaleResult, type MoneyColumnTarget } from '@happyvertical/smrt-core/migrations';
 /** Marker recorded in `_smrt_backfills` once the rescale has run. */
 export declare const SUPPORT_MONEY_MINOR_UNITS_BACKFILL = "@happyvertical/smrt-support:money-minor-units:v1";
 /** Every support money column that held major units before #2401. */

package/dist/models/service-time-entry.d.ts

@@ -1,5 +1,6 @@
+/** Compatibility mapping for issue #1955. */
 import { SmrtCollection } from '@happyvertical/smrt-core';
-import { ServiceParticipantKind, ServiceTimeEntrySource, ServiceTimeEntryStatus, ServiceTimeEntry as SharedServiceTimeEntry } from '@happyvertical/smrt-projects';
+import { type ServiceParticipantKind, type ServiceTimeEntrySource, type ServiceTimeEntryStatus, ServiceTimeEntry as SharedServiceTimeEntry } from '@happyvertical/smrt-projects';
 /**
  * Source-compatible support subtype over the shared canonical table. The
  * fields are restated because package-isolated manifest scanning deliberately

package/dist/models/support-ai-run.d.ts

@@ -1,5 +1,15 @@
+/**
+ * SupportAiRun — the auditable record of one Automated Support Response phase
+ * (FR-28a): what the AI attempted (acknowledge / classify / answer /
+ * troubleshoot / resolve), with confidence, classification output, knowledge
+ * references, attempted tool calls, and outcome. This is the "prior automated
+ * work" a Human Handoff transfers losslessly (FR-28b).
+ *
+ * Append-only: generated surface is `list`/`get`; the workflow writes each
+ * run once and never rewrites history.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportAiRunOutcome, SupportAiRunPhase } from '../types.js';
+import { type SupportAiRunOutcome, type SupportAiRunPhase } from '../types.js';
 export declare class SupportAiRun extends SmrtObject {
     tenantId: string | null;
     caseId: string;

package/dist/models/support-case-event.d.ts

@@ -1,5 +1,15 @@
+/**
+ * SupportCaseEvent — append-only audit trail for a Support Case: creations,
+ * transitions, assignments, AI runs, handoffs, escalations, target state
+ * changes, work links, and reopens. Together with interactions this is the
+ * "complete Case context" a Human Handoff transfers (FR-28b) and the reopen
+ * history FR-29b preserves.
+ *
+ * Events are immutable: the generated surface is `list`/`get` only and the
+ * service never updates an event after writing it.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportActorKind, SupportCaseEventType } from '../types.js';
+import { type SupportActorKind, type SupportCaseEventType } from '../types.js';
 export declare class SupportCaseEvent extends SmrtObject {
     tenantId: string | null;
     caseId: string;

package/dist/models/support-case.d.ts

@@ -1,5 +1,16 @@
-import { DecisionRequest, DecisionResult, SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportCaseStatus } from '../types.js';
+/**
+ * SupportCase — the canonical, tenant-scoped record of a client support
+ * request (FR-28/FR-29): one Case per request across every channel, carrying
+ * priority, severity, plan snapshot, lifecycle state, assignment, resolution,
+ * and reopen history.
+ *
+ * Internal model — writes go through {@link SupportCaseService} (closed-facade
+ * idiom, mirroring `smrt-chat`'s `ChatService`). The generated CRUD surface is
+ * read-only (`list`/`get`); the save-time transition guard below additionally
+ * rejects illegal status flips done via raw field assignment.
+ */
+import { type DecisionRequest, type DecisionResult, SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+import { type SupportCaseStatus } from '../types.js';
 /** Generate a short human-facing case number (unique enough per tenant). */
 export declare function generateCaseNumber(now?: Date): string;
 export declare class SupportCase extends SmrtObject {

package/dist/models/support-channel-binding.d.ts

@@ -1,5 +1,15 @@
+/**
+ * SupportChannelBinding — marks a transport container (a chat room, an email
+ * account) as a Managed Support intake channel. Inbound activity on a bound
+ * container creates-or-joins Support Cases; unbound containers are never
+ * touched, so ordinary chat rooms and mailboxes stay out of the support
+ * system.
+ *
+ * Bindings are configuration (operator-managed), so unlike the case-side
+ * models they expose full generated CRUD.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportBindingKind, SupportChannelKind } from '../types.js';
+import { type SupportBindingKind, type SupportChannelKind } from '../types.js';
 export declare class SupportChannelBinding extends SmrtObject {
     tenantId: string | null;
     /** Operator-facing binding name (inherited `name` is the display label). */

package/dist/models/support-compensation-plan.d.ts

@@ -1,3 +1,14 @@
+/**
+ * SupportCompensationPlan — the provider-facing **Support Compensation Plan**
+ * (FR-32/FR-35): the effective-dated terms under which a Support Specialist
+ * earns for delivered support time. Deliberately separate from
+ * {@link SupportPlan} (client pricing) so margin stays measurable and client
+ * terms never leak provider terms.
+ *
+ * Resolution: the specialist-specific plan effective at the work instant
+ * wins; otherwise the tenant default (`specialistId` null) effective at that
+ * instant applies.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
 export declare class SupportCompensationPlan extends SmrtObject {
     tenantId: string | null;

package/dist/models/support-interaction.d.ts

@@ -1,5 +1,16 @@
+/**
+ * SupportInteraction — a channel-neutral transport record attached to a
+ * Support Case (FR-28/FR-29): one row per message/chat/email/voice exchange,
+ * preserving chronology and transport metadata. The channel row (a
+ * `ChatMessage`, an `Email`, …) stays in its own package; this row links it
+ * via a qualified `sourceType`/`sourceId` pair and a globally unique
+ * `sourceKey` so re-ingesting the same transport record is idempotent.
+ *
+ * Internal model — writes go through {@link SupportCaseService}. Generated
+ * surface is read-only.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportActorKind, SupportChannelKind, SupportInteractionDirection } from '../types.js';
+import { type SupportActorKind, type SupportChannelKind, type SupportInteractionDirection } from '../types.js';
 export declare class SupportInteraction extends SmrtObject {
     tenantId: string | null;
     caseId: string;

package/dist/models/support-plan.d.ts

@@ -1,5 +1,23 @@
+/**
+ * SupportPlan — the client-facing **Managed Support Plan** (FR-31): coverage
+ * hours and channels, severity definitions, acknowledgement / response /
+ * update / resolution Service Targets, pause rules, escalation policy, an
+ * availability fee, included support time, and metered overage pricing.
+ *
+ * Pure hourly support is a plan with zero availability fee and zero included
+ * minutes. A Service Target here is an operational objective — it becomes a
+ * contractual Service Level Agreement only in the governing agreement, which
+ * is out of this package's scope.
+ *
+ * Client pricing lives here; Support Specialist earnings live in the separate
+ * {@link SupportCompensationPlan} — the two are never merged (FR-32/FR-35).
+ *
+ * `subscriptionPlanKey` optionally binds the plan to a
+ * `@happyvertical/smrt-subscriptions` plan by its natural key for entitlement
+ * checks — a string reference, deliberately not a package dependency.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { CoverageWindow, EscalationStep, ServiceTargetMinutes, SeverityDefinition, TimeApprovalPolicy } from '../types.js';
+import { type CoverageWindow, type EscalationStep, type ServiceTargetMinutes, type SeverityDefinition, type TimeApprovalPolicy } from '../types.js';
 /** Default target minutes applied when a plan omits a severity's targets. */
 export declare const DEFAULT_TARGET_MINUTES: ServiceTargetMinutes;
 export declare class SupportPlan extends SmrtObject {

package/dist/models/support-policy.d.ts

@@ -1,3 +1,14 @@
+/**
+ * SupportPolicy — governs what the AI support workflow may do without a human
+ * (FR-28a/FR-28b): which phases run automatically, whether low-risk
+ * resolutions may complete autonomously, the confidence floor, sensitive
+ * categories, and the tool whitelist for troubleshooting.
+ *
+ * Resolution is most-specific-wins per case: `(planId, projectId)` exact →
+ * `planId` → `projectId` → tenant default (both null) → the package's
+ * conservative built-in defaults (see `DEFAULT_SUPPORT_POLICY`). Policies are
+ * operator configuration, so they expose full generated CRUD.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
 /**
  * Conservative defaults applied when no SupportPolicy row matches: the AI

package/dist/models/support-service-target.d.ts

@@ -1,5 +1,19 @@
+/**
+ * Service Target clocks and escalations (FR-30/FR-31).
+ *
+ * - **SupportServiceTarget** — one acknowledgement/response/update/resolution
+ *   clock on a case, derived from the applicable plan's targets, coverage
+ *   calendar, and pause rules. `escalationJobId` holds the one-shot
+ *   `_smrt_jobs` row scheduled at `dueAt` so satisfying the target can cancel
+ *   the pending escalation.
+ * - **SupportEscalation** — the auditable record of one escalation firing
+ *   (target breach, target risk, manual, or AI-triggered).
+ *
+ * Both are written by the target engine / case service only; generated
+ * surfaces are read-only.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { ServiceTargetStatus, ServiceTargetType, SupportEscalationReason } from '../types.js';
+import { type ServiceTargetStatus, type ServiceTargetType, type SupportEscalationReason } from '../types.js';
 /** Outcome of one {@link SupportServiceTarget.checkAndEscalate} delivery. */
 export interface CheckAndEscalateResult {
     outcome: 'breached' | 'escalated' | 'rescheduled' | 'noop' | 'missing';

package/dist/models/support-settlement.d.ts

@@ -1,5 +1,24 @@
+/**
+ * Derived commercial snapshots for approved Service Time Entries
+ * (FR-32/FR-35, issue #1930). Two deliberately separate rows per entry:
+ *
+ * - **SupportCharge** — what the Client owes, derived from the Managed
+ *   Support Plan (included-time consumption, then metered overage).
+ * - **SupportCompensation** — what the delivering Participant earns, derived
+ *   from the Support Compensation Plan.
+ *
+ * Margin = charge − compensation, computed by readers; the two records are
+ * never merged so client pricing can't leak provider terms. Rows snapshot the
+ * rate terms at derivation time (`rateSnapshot`) — later plan edits never
+ * rewrite them; corrections void/supersede and re-derive from the correcting
+ * entry. Settlement (invoicing, ledger posting) is out of scope here and
+ * composes at the app/accounting boundary (#1925).
+ *
+ * Append-only surfaces: `list`/`get` generated routes only; writes go through
+ * `TimeEntryApprovalService`.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportSettlementStatus } from '../types.js';
+import { type SupportSettlementStatus } from '../types.js';
 export declare class SupportCharge extends SmrtObject {
     tenantId: string | null;
     timeEntryId: string;

package/dist/models/support-specialist.d.ts

@@ -1,5 +1,19 @@
+/**
+ * Support Specialist models (FR-30): the specialist role record layered on a
+ * Profile (the `commerce Customer` role-record idiom), per-project
+ * qualifications, and availability/on-call windows.
+ *
+ * - **SupportSpecialist** — a Participant qualified to handle first-tier
+ *   support; workload cap, languages, and timezone drive routing.
+ * - **SupportQualification** — recognition that a specialist is trained and
+ *   approved for a specific app-defined project (effective-dated).
+ * - **SupportAvailability** — weekly working windows, on-call spans, and
+ *   time-off exceptions used by routing and coverage checks.
+ *
+ * These are operator configuration surfaces, so they expose generated CRUD.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportAvailabilityKind, SupportQualificationLevel, SupportSpecialistStatus } from '../types.js';
+import { type SupportAvailabilityKind, type SupportQualificationLevel, type SupportSpecialistStatus } from '../types.js';
 export declare class SupportSpecialist extends SmrtObject {
     tenantId: string | null;
     /** The Participant (Person profile) this specialist role belongs to. */

package/dist/models/support-work-link.d.ts

@@ -1,5 +1,17 @@
+/**
+ * SupportWorkLink — links a Support Case to separately tracked internal work
+ * (FR-29/FR-29a): a **Support Work Item** on the operational board, or a
+ * **Development Work Item** created through a Delivery Handoff.
+ *
+ * Boundary: Support owns the Case and this link; Delivery Operations owns the
+ * linked work's execution (agents, previews, merges, deployments). The
+ * `status` field here is a read-only echo the delivery side reports back —
+ * this package never drives the linked item's lifecycle. Targets are
+ * addressed by qualified type + id (e.g. `@happyvertical/smrt-projects:Issue`)
+ * so no runtime dependency on the owning package is needed.
+ */
 import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
-import { SupportWorkLinkKind } from '../types.js';
+import { type SupportWorkLinkKind } from '../types.js';
 export declare class SupportWorkLink extends SmrtObject {
     tenantId: string | null;
     caseId: string;

package/dist/permissions.d.ts

@@ -1,4 +1,15 @@
-import { PermissionDefinition } from '@happyvertical/smrt-users';
+/**
+ * Custom permission slugs contributed by `@happyvertical/smrt-support` to the
+ * runtime permission catalog (the `personas.activate-directive` pattern).
+ *
+ * The privileged operations are permission splits, not bespoke checks:
+ * - `support.reassign-case` — manual reassignment despite routing (FR-30).
+ * - `support.approve-time-entry` — accept a Service Time Entry and derive its
+ *   commercial snapshots (FR-36) via the operator path.
+ * - `support.manage-plans` — administer Managed Support Plans and Support
+ *   Compensation Plans.
+ */
+import { type PermissionDefinition } from '@happyvertical/smrt-users';
 /** Authorizes manual case reassignment overriding automatic routing. */
 export declare const REASSIGN_CASE_PERMISSION = "support.reassign-case";
 /** Authorizes operator approval/rejection of Service Time Entries. */

package/dist/services/coverage-calendar.d.ts

@@ -1,4 +1,25 @@
-import { CoverageWindow } from '../types.js';
+/**
+ * Coverage-calendar math for Service Target clocks (FR-30/FR-31): pure,
+ * deterministic business-time arithmetic over a Managed Support Plan's
+ * coverage windows, holidays, and IANA timezone.
+ *
+ * Semantics:
+ * - An empty `windows` array means 24×7 coverage; with no holidays either,
+ *   covered time is plain wall-clock time (the fast path).
+ * - Holidays (`YYYY-MM-DD` in the calendar's timezone) exclude whole days
+ *   from coverage, including under 24×7 coverage.
+ * - All functions take explicit instants — no `Date.now()` inside — so the
+ *   engine and its tests stay deterministic.
+ *
+ * Timezone handling uses `Intl.DateTimeFormat#formatToParts` only (no date
+ * library): {@link zonedParts} projects a UTC instant onto the calendar
+ * timezone's wall clock, and an iterative inverse converts wall-clock day
+ * positions back to UTC instants. DST transition days therefore keep exact
+ * window boundaries; a window boundary falling inside a nonexistent
+ * spring-forward hour lands on the later real instant so clocks never gain
+ * time.
+ */
+import type { CoverageWindow } from '../types.js';
 /** The coverage terms a Service Target clock runs against. */
 export interface CoverageCalendar {
     /** Weekly coverage windows; empty means 24×7 coverage. */

package/dist/services/human-handoff-service.d.ts

@@ -1,7 +1,22 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * HumanHandoffService — the lossless Human Handoff (FR-28b, issue #1928).
+ * Whatever pulls the trigger (an explicit client request, low answer
+ * confidence, a sensitive classification, high severity, failed automation,
+ * a policy cap, or a manual escalation), the handoff transfers the FULL case
+ * context — current state, the merged interaction/event timeline, and every
+ * prior {@link SupportAiRun} — so the Client never repeats themselves and the
+ * Support Specialist starts with the complete history.
+ *
+ * A no-repeat guarantee keeps at most one handoff active per case
+ * (`metadata.activeHandoff`): repeat triggers while one is pending only
+ * append a deduped audit event. Routing is a seam — the #1929 routing
+ * service plugs in via `assignSpecialist`; without it the case is queued for
+ * manual pickup (`new` → `triaged`).
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
 import { SupportAiRunCollection } from '../models/support-ai-run.js';
-import { SupportCase } from '../models/support-case.js';
-import { HumanHandoffTrigger } from '../types.js';
+import type { SupportCase } from '../models/support-case.js';
+import type { HumanHandoffTrigger } from '../types.js';
 import { SupportCaseService } from './support-case-service.js';
 /** One compact timeline entry inside a {@link HandoffContextPackage}. */
 export interface HandoffTimelineItem {

package/dist/services/project-assistance-adapter.d.ts

@@ -1,5 +1,5 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { AssistanceSupportPort } from '@happyvertical/smrt-projects';
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { AssistanceSupportPort } from '@happyvertical/smrt-projects';
 import { SupportCaseService } from './support-case-service.js';
 /** Concrete lossless bridge from smrt-projects Assistance Requests to Support. */
 export declare class ProjectAssistanceSupportAdapter implements AssistanceSupportPort {

package/dist/services/service-target-engine.d.ts

@@ -1,10 +1,37 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * ServiceTargetEngine — Service Target clocks with timed escalation
+ * (FR-30/FR-31).
+ *
+ * Owns the full clock lifecycle on a case:
+ * - **start** — one clock per configured target type from the case's plan
+ *   terms (the frozen `planSnapshot` wins over the live plan; sensible
+ *   defaults with no plan), `dueAt` computed in *covered* time through the
+ *   plan's coverage calendar, plus a one-shot `_smrt_jobs` row
+ *   (`SupportServiceTarget.checkAndEscalate`) scheduled at `dueAt`;
+ * - **satisfy** — outbound specialist/agent interactions satisfy the
+ *   acknowledgement/response clocks and roll the recurring update clock to
+ *   its next cycle; satisfied clocks cancel their escalation job;
+ * - **pause/resume** — case statuses listed in the plan's `pauseStatuses`
+ *   freeze clocks (FR-29b: waiting periods pause clocks *only when the plan
+ *   says so*); resume recomputes `dueAt` from the remaining covered minutes
+ *   and enqueues a fresh job;
+ * - **resolve/reopen** — resolution satisfies the resolution clock and
+ *   cancels the rest; reopening starts fresh clocks on a new cycle;
+ * - **breach** — an overdue clock is marked breached and escalated through
+ *   the plan's escalation policy (notify or reassign via
+ *   {@link SupportRoutingService}), with optional delayed follow-up steps.
+ *
+ * The engine is invoked by the application around
+ * {@link SupportCaseService} calls; it deliberately takes explicit `at`
+ * instants so behavior is deterministic and testable.
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
 import { SmrtJobCollection } from '@happyvertical/smrt-jobs';
-import { SupportCase } from '../models/support-case.js';
-import { SupportInteraction } from '../models/support-interaction.js';
-import { SupportEscalationCollection, SupportServiceTarget, SupportServiceTargetCollection } from '../models/support-service-target.js';
-import { EscalationStep, ServiceTargetMinutes, SupportCaseStatus } from '../types.js';
-import { CoverageCalendar } from './coverage-calendar.js';
+import type { SupportCase } from '../models/support-case.js';
+import type { SupportInteraction } from '../models/support-interaction.js';
+import { SupportEscalationCollection, type SupportServiceTarget, SupportServiceTargetCollection } from '../models/support-service-target.js';
+import { type EscalationStep, type ServiceTargetMinutes, type SupportCaseStatus } from '../types.js';
+import { type CoverageCalendar } from './coverage-calendar.js';
 import { SupportCaseService } from './support-case-service.js';
 /** Queue name for support escalation jobs. */
 export declare const SUPPORT_JOB_QUEUE = "support";

package/dist/services/service-time-entry-service.d.ts

@@ -1,6 +1,18 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { ServiceTimeEntry, ServiceTimeEntryCollection } from '../models/service-time-entry.js';
-import { ServiceTimeEntrySource, SupportParticipantKind, TimeEntryEvidence } from '../types.js';
+/**
+ * ServiceTimeEntryService — the shared recording contract for Service Time
+ * Entries (FR-40, issue #1930): timer, manual, imported, and automatic agent
+ * entries all pass ONE validation and audit gate, so no source can smuggle in
+ * an incoherent duration, participant, or work context.
+ *
+ * Recording is deliberately money-free: entries capture the work (duration,
+ * period, evidence, participant, context) and land as `draft`; pricing and
+ * earnings derive later, at approval time, in `TimeEntryApprovalService`.
+ * Case-attached entries append a `time_recorded` audit event so the case
+ * timeline shows the work as it happens.
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { type ServiceTimeEntry, ServiceTimeEntryCollection } from '../models/service-time-entry.js';
+import type { ServiceTimeEntrySource, SupportParticipantKind, TimeEntryEvidence } from '../types.js';
 import { SupportCaseService } from './support-case-service.js';
 /** Options for {@link ServiceTimeEntryService.create}. */
 export interface ServiceTimeEntryServiceOptions extends SmrtObjectOptions {

package/dist/services/support-ai-workflow.d.ts

@@ -1,12 +1,29 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { SupportAiRun, SupportAiRunCollection } from '../models/support-ai-run.js';
-import { SupportCase } from '../models/support-case.js';
+/**
+ * SupportAiWorkflow — the Automated Support Response pipeline (FR-28a, issue
+ * #1928): on intake a case is immediately acknowledged, classified, and
+ * answered from scoped knowledge; only when the resolved {@link SupportPolicy}
+ * explicitly allows it may the workflow resolve a low-risk case autonomously.
+ * Every phase — run or skipped — writes an append-only {@link SupportAiRun}
+ * audit row, and every risk signal (client request, low confidence,
+ * sensitivity, high severity, boundary failure, attempt cap) routes through
+ * {@link HumanHandoffService} so a Support Specialist takes over with the
+ * complete context (FR-28b).
+ *
+ * The AI call is an injected {@link SupportAiBoundary} and knowledge
+ * retrieval an injected {@link SupportKnowledgeProvider} (the `smrt-personas`
+ * `ReflectionRunner` injected-boundary idiom) — tests mock only these seams,
+ * and the package stays dependency-free: apps plug `smrt-facts` /
+ * `smrt-content`-backed providers.
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { type SupportAiRun, SupportAiRunCollection } from '../models/support-ai-run.js';
+import type { SupportCase } from '../models/support-case.js';
 import { SupportInteractionCollection } from '../models/support-interaction.js';
 import { SupportPolicyCollection } from '../models/support-policy.js';
-import { HumanHandoffTrigger, SeverityDefinition } from '../types.js';
+import { type HumanHandoffTrigger, type SeverityDefinition } from '../types.js';
 import { HumanHandoffService } from './human-handoff-service.js';
 import { SupportCaseService } from './support-case-service.js';
-import { IntakeResult } from './support-intake-service.js';
+import type { IntakeResult } from './support-intake-service.js';
 /** One knowledge source consulted while drafting an automated answer. */
 export interface KnowledgeSnippet {
     /** Source kind, e.g. `fact`, `article`, `document`. */

package/dist/services/support-case-service.d.ts

@@ -1,10 +1,18 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { SupportCase, SupportCaseCollection } from '../models/support-case.js';
-import { SupportCaseEvent, SupportCaseEventCollection } from '../models/support-case-event.js';
-import { SupportInteraction, SupportInteractionCollection } from '../models/support-interaction.js';
-import { SupportPlan, SupportPlanCollection } from '../models/support-plan.js';
-import { SupportWorkLink, SupportWorkLinkCollection } from '../models/support-work-link.js';
-import { SupportActorKind, SupportCaseEventType, SupportCaseStatus, SupportChannelKind, SupportInteractionDirection, SupportWorkLinkKind } from '../types.js';
+/**
+ * SupportCaseService — the closed write facade for Support Cases (the
+ * `smrt-chat` `ChatService` idiom): case creation, interaction recording,
+ * lifecycle transitions, assignment, resolution, reopening, human requests,
+ * and work links all flow through here so the audit trail
+ * ({@link SupportCaseEvent}) and the lifecycle guard stay coherent. The
+ * generated CRUD surface on the case-side models is read-only.
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { type SupportCase, SupportCaseCollection } from '../models/support-case.js';
+import { type SupportCaseEvent, SupportCaseEventCollection } from '../models/support-case-event.js';
+import { type SupportInteraction, SupportInteractionCollection } from '../models/support-interaction.js';
+import { type SupportPlan, SupportPlanCollection } from '../models/support-plan.js';
+import { type SupportWorkLink, SupportWorkLinkCollection } from '../models/support-work-link.js';
+import type { SupportActorKind, SupportCaseEventType, SupportCaseStatus, SupportChannelKind, SupportInteractionDirection, SupportWorkLinkKind } from '../types.js';
 export interface OpenCaseInput {
     tenantId?: string | null;
     subject: string;

package/dist/services/support-intake-service.d.ts

@@ -1,7 +1,28 @@
-import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { SupportCase } from '../models/support-case.js';
-import { SupportChannelBinding, SupportChannelBindingCollection } from '../models/support-channel-binding.js';
-import { SupportInteraction } from '../models/support-interaction.js';
+/**
+ * SupportIntakeService — channel intake: every inbound interaction on a bound
+ * transport container deterministically creates or joins one canonical
+ * Support Case (FR-28, issue #1926).
+ *
+ * Channels are transports, not systems of record: the ChatMessage / Email row
+ * stays canonical in its package; intake links it as a
+ * {@link SupportInteraction} (idempotent on `sourceKey`) and drives the
+ * create-or-join decision by conversation key:
+ *
+ * - chat: `chat:<roomId>[:<threadId>]` — a bound room is one client
+ *   conversation; threads open distinct cases.
+ * - email: the RFC thread — a reply (`inReplyTo`) joins the case holding the
+ *   referenced message; otherwise the message id starts a new thread key.
+ *
+ * Join semantics: open case → join; resolved case → reopen + join (the client
+ * replied to a "resolved" conversation); closed case → a fresh case.
+ *
+ * Intake never throws into the source package's save path — the opt-in
+ * interceptor (`registerSupportIntake`) swallows and logs intake errors.
+ */
+import type { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { SupportCase } from '../models/support-case.js';
+import { type SupportChannelBinding, SupportChannelBindingCollection } from '../models/support-channel-binding.js';
+import type { SupportInteraction } from '../models/support-interaction.js';
 import { SupportCaseService } from './support-case-service.js';
 /** Qualified source types intake understands. */
 export declare const CHAT_MESSAGE_SOURCE_TYPE = "@happyvertical/smrt-chat:ChatMessage";

package/dist/services/support-plan-admin-service.d.ts

@@ -1,7 +1,20 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { SupportCompensationPlan, SupportCompensationPlanCollection } from '../models/support-compensation-plan.js';
-import { SupportPlan, SupportPlanCollection } from '../models/support-plan.js';
-import { SupportPrincipal } from '../permissions.js';
+/**
+ * SupportPlanAdminService — the permission-gated write surface for
+ * commercial terms: Managed Support Plans (client pricing/service terms) and
+ * Support Compensation Plans (provider earning terms).
+ *
+ * The `support.manage-plans` split is the gate (the
+ * `personas.activate-directive` idiom): the generated CRUD routes on both
+ * models are read-only, so every plan write flows through here, carries an
+ * accountable principal, and refuses cross-tenant acts. Plan history stays
+ * safe regardless — cases snapshot plan terms at apply time and settlements
+ * snapshot rates at approval time — but only holders of the split may shape
+ * future terms.
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { type SupportCompensationPlan, SupportCompensationPlanCollection } from '../models/support-compensation-plan.js';
+import { type SupportPlan, SupportPlanCollection } from '../models/support-plan.js';
+import { type SupportPrincipal } from '../permissions.js';
 /** Thrown when a plan write is attempted without the manage-plans split. */
 export declare class PlanAdminDeniedError extends Error {
     constructor(message: string);

package/dist/services/support-routing-service.d.ts

@@ -1,8 +1,23 @@
-import { SmrtObjectOptions } from '@happyvertical/smrt-core';
-import { SupportCase } from '../models/support-case.js';
+/**
+ * SupportRoutingService — Project-qualified Support Case routing (FR-30).
+ *
+ * Ranks Support Specialists for a case with an **explainable** score: every
+ * hard eligibility check (active status, effective Project Support
+ * Qualification, workload cap, availability) is recorded as a factor on the
+ * ranked entry, so the queue UI can show *why* someone was or wasn't chosen.
+ * Ineligible specialists stay in the returned ranking (`eligible: false`)
+ * for that rationale display.
+ *
+ * `autoAssign` writes the assignment through {@link SupportCaseService} with
+ * the ranking rationale in the audit event; `reassign` is the manual
+ * override, gated by the `support.reassign-case` permission split and a
+ * cross-tenant guard.
+ */
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import type { SupportCase } from '../models/support-case.js';
 import { SupportAvailabilityCollection, SupportQualificationCollection, SupportSpecialistCollection } from '../models/support-specialist.js';
-import { SupportPrincipal } from '../permissions.js';
-import { SupportActorKind } from '../types.js';
+import { type SupportPrincipal } from '../permissions.js';
+import type { SupportActorKind } from '../types.js';
 import { SupportCaseService } from './support-case-service.js';
 /**
  * Named scoring weights, so the ranking is auditable against the code.