@rubytech/create-maxy-code 0.1.570 → 0.1.572

package/payload/platform/lib/dispatch-read/src/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The dispatch config contract, and the row shapes every read returns.
+ *
+ * This mirrors `platform/plugins/dispatch/mcp/src/lib/types.ts`. It lives here
+ * because two callers now need it: the dispatch plugin's MCP tools and the
+ * office planner's UI route. One declaration, so a field added for the planner
+ * cannot silently diverge from what the tools return.
+ *
+ * Nothing an operator can name appears as a literal in this package. A taxi
+ * firm's fare/pickup/driver and a contractor's job/visit/engineer are both just
+ * `vocabulary`.
+ */
+export interface StatusDecl {
+    readonly name: string;
+    /** True when a job or visit that reaches this status is finished. */
+    readonly terminal: boolean;
+}
+/** One legal move, `[from, to]`. Absent from the list means refused. */
+export type Transition = readonly [string, string];
+export interface StatusConfig {
+    readonly job: readonly StatusDecl[];
+    readonly visit: readonly StatusDecl[];
+    readonly jobTransitions: readonly Transition[];
+    readonly visitTransitions: readonly Transition[];
+}
+export interface JobType {
+    readonly name: string;
+    /** A worker is offered for this type only if they hold this qualification. */
+    readonly requiredQualification: string;
+    readonly defaultDurationMin: number;
+    /**
+     * Hours from job creation to the SLA target. Omitted when the account sets no
+     * target for this type — omitted, never zero, because a zero would make every
+     * job of that type instantly overdue.
+     */
+    readonly slaTargetHours?: number;
+}
+/** `{ mon: ["08:00", "17:00"] }`. Absent day means not working that day. */
+export type WorkingHours = Readonly<Record<string, readonly [string, string]>>;
+export interface Worker {
+    readonly workerId: string;
+    readonly name: string;
+    readonly qualifications: readonly string[];
+    readonly workingHours: WorkingHours;
+}
+export interface RecordsConfig {
+    /** Checklist template per job type name. */
+    readonly checklists: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Field names a visit must carry before it may reach the keyed terminal visit
+     * status. Recognised names: `notes`, `media`, `parts`, `checklist`,
+     * `signature`.
+     */
+    readonly requiredBeforeTerminal: Readonly<Record<string, readonly string[]>>;
+}
+export interface Vocabulary {
+    readonly job: string;
+    readonly visit: string;
+    readonly worker: string;
+}
+export interface VehicleConfig {
+    readonly enabled: boolean;
+    readonly defaultGeofenceRadiusM?: number;
+}
+export interface DispatchConfig {
+    readonly statuses: StatusConfig;
+    readonly jobTypes: readonly JobType[];
+    readonly workers: readonly Worker[];
+    readonly records: RecordsConfig;
+    readonly vocabulary: Vocabulary;
+    readonly vehicles: VehicleConfig;
+}
+/**
+ * `loadDispatchConfig` result. Absence is a named state, never a throw: the
+ * plugin ships inert and most accounts never enable it, so "no config" is the
+ * common case rather than a fault. Module init reads this and must not throw,
+ * because plugin-system spawn enumerates tools with empty environment and one
+ * boot throw empties the whole registry.
+ */
+export type LoadResult = {
+    readonly present: true;
+    readonly value: DispatchConfig;
+} | {
+    readonly present: false;
+    readonly reason: "no-account-dir" | "no-file" | "unreadable" | "invalid";
+    readonly detail?: string;
+};
+export interface JobRow {
+    jobId: string;
+    status: string;
+    jobType: string | null;
+    slaTargetAt: string | null;
+    siteId: string | null;
+    siteName: string | null;
+    customerId: string | null;
+    createdAt: string | null;
+}
+export interface VisitRow {
+    visitId: string;
+    /** Null when the visit is not linked to a job. Log fields render `none`. */
+    jobId: string | null;
+    status: string;
+    startDate: string | null;
+    endDate: string | null;
+    purpose: string | null;
+    workerId: string | null;
+    /**
+     * What somebody said, and what was measured. Separate properties written by
+     * separate clauses: recording either never clears the other. A single
+     * `arrivedAt` cannot show a worker closing Monday's jobs on Tuesday; two that
+     * disagree can.
+     */
+    arrivedPressedAt: string | null;
+    arrivedObservedAt: string | null;
+    arrivedObservedDistanceM: number | null;
+}
+/** A visit with the fields a planner card needs beyond the plain visit row. */
+export interface PlannerVisit extends VisitRow {
+    siteName: string | null;
+    customerId: string | null;
+    customerName: string | null;
+    jobType: string | null;
+}
+/**
+ * Aggregates, not the length of a capped row list. `readJobList` caps at 500
+ * rows, so counting its result would under-report any account with more jobs
+ * than that — the reference account holds 2,869.
+ */
+export interface DispatchCounts {
+    total: number;
+    unallocated: number;
+    overdue: number;
+}
+export interface JobListFilter {
+    status?: string;
+    jobType?: string;
+    workerId?: string;
+    from?: string;
+    to?: string;
+    unallocatedOnly?: boolean;
+    limit?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/payload/platform/lib/dispatch-read/src/types.d.ts.map

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

package/payload/platform/lib/dispatch-read/src/types.ts

@@ -0,0 +1,188 @@
+/**
+ * The dispatch config contract, and the row shapes every read returns.
+ *
+ * This mirrors `platform/plugins/dispatch/mcp/src/lib/types.ts`. It lives here
+ * because two callers now need it: the dispatch plugin's MCP tools and the
+ * office planner's UI route. One declaration, so a field added for the planner
+ * cannot silently diverge from what the tools return.
+ *
+ * Nothing an operator can name appears as a literal in this package. A taxi
+ * firm's fare/pickup/driver and a contractor's job/visit/engineer are both just
+ * `vocabulary`.
+ */
+
+export interface StatusDecl {
+  readonly name: string;
+  /** True when a job or visit that reaches this status is finished. */
+  readonly terminal: boolean;
+}
+
+/** One legal move, `[from, to]`. Absent from the list means refused. */
+export type Transition = readonly [string, string];
+
+export interface StatusConfig {
+  readonly job: readonly StatusDecl[];
+  readonly visit: readonly StatusDecl[];
+  readonly jobTransitions: readonly Transition[];
+  readonly visitTransitions: readonly Transition[];
+}
+
+export interface JobType {
+  readonly name: string;
+  /** A worker is offered for this type only if they hold this qualification. */
+  readonly requiredQualification: string;
+  readonly defaultDurationMin: number;
+  /**
+   * Hours from job creation to the SLA target. Omitted when the account sets no
+   * target for this type — omitted, never zero, because a zero would make every
+   * job of that type instantly overdue.
+   */
+  readonly slaTargetHours?: number;
+}
+
+/** `{ mon: ["08:00", "17:00"] }`. Absent day means not working that day. */
+export type WorkingHours = Readonly<Record<string, readonly [string, string]>>;
+
+export interface Worker {
+  readonly workerId: string;
+  readonly name: string;
+  readonly qualifications: readonly string[];
+  readonly workingHours: WorkingHours;
+  /**
+   * The Telegram user id this worker signs in as, for the field job sheet
+   * (Task 2502). Absent means the worker has no field surface: an `initData`
+   * naming that Telegram user is refused as `unbound-user` rather than matched
+   * to somebody by name.
+   *
+   * It lives on the roster rather than in a bindings file of its own because a
+   * second roster is a second thing to keep in step, and nothing would.
+   */
+  readonly telegramUserId?: string;
+}
+
+export interface RecordsConfig {
+  /** Checklist template per job type name. */
+  readonly checklists: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Field names a visit must carry before it may reach the keyed terminal visit
+   * status. Recognised names: `notes`, `media`, `parts`, `checklist`,
+   * `signature`.
+   */
+  readonly requiredBeforeTerminal: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface Vocabulary {
+  readonly job: string;
+  readonly visit: string;
+  readonly worker: string;
+}
+
+export interface VehicleConfig {
+  readonly enabled: boolean;
+  readonly defaultGeofenceRadiusM?: number;
+}
+
+export interface DispatchConfig {
+  readonly statuses: StatusConfig;
+  readonly jobTypes: readonly JobType[];
+  readonly workers: readonly Worker[];
+  readonly records: RecordsConfig;
+  readonly vocabulary: Vocabulary;
+  readonly vehicles: VehicleConfig;
+}
+
+/**
+ * `loadDispatchConfig` result. Absence is a named state, never a throw: the
+ * plugin ships inert and most accounts never enable it, so "no config" is the
+ * common case rather than a fault. Module init reads this and must not throw,
+ * because plugin-system spawn enumerates tools with empty environment and one
+ * boot throw empties the whole registry.
+ */
+export type LoadResult =
+  | { readonly present: true; readonly value: DispatchConfig }
+  | {
+      readonly present: false;
+      readonly reason: "no-account-dir" | "no-file" | "unreadable" | "invalid";
+      readonly detail?: string;
+    };
+
+export interface JobRow {
+  jobId: string;
+  status: string;
+  jobType: string | null;
+  slaTargetAt: string | null;
+  siteId: string | null;
+  siteName: string | null;
+  customerId: string | null;
+  createdAt: string | null;
+}
+
+export interface VisitRow {
+  visitId: string;
+  /** Null when the visit is not linked to a job. Log fields render `none`. */
+  jobId: string | null;
+  status: string;
+  startDate: string | null;
+  endDate: string | null;
+  purpose: string | null;
+  workerId: string | null;
+  /**
+   * What somebody said, and what was measured. Separate properties written by
+   * separate clauses: recording either never clears the other. A single
+   * `arrivedAt` cannot show a worker closing Monday's jobs on Tuesday; two that
+   * disagree can.
+   */
+  arrivedPressedAt: string | null;
+  arrivedObservedAt: string | null;
+  arrivedObservedDistanceM: number | null;
+}
+
+/** A visit with the fields a planner card needs beyond the plain visit row. */
+export interface PlannerVisit extends VisitRow {
+  siteName: string | null;
+  customerId: string | null;
+  customerName: string | null;
+  jobType: string | null;
+}
+
+/**
+ * The field job sheet's card (Task 2502).
+ *
+ * Wider than `PlannerVisit` on contact detail, because a worker on a doorstep
+ * needs a name and a telephone and the office grid does not.
+ *
+ * It carries **no address and no postcode**, and that absence is the design.
+ * `:Site` declares neither, and the only `PostalAddress` edge in the ontology
+ * belongs to the logistics vertical. An always-null column would read as a
+ * site with no address rather than a product that does not store one. Task
+ * 2514 adds the edge; `sitesVisitedTodayWithoutAddress` on
+ * `[dispatch-field-census]` counts what it costs until then.
+ */
+export interface FieldVisit extends VisitRow {
+  siteId: string | null;
+  siteName: string | null;
+  customerName: string | null;
+  contactName: string | null;
+  contactTelephone: string | null;
+}
+
+/**
+ * Aggregates, not the length of a capped row list. `readJobList` caps at 500
+ * rows, so counting its result would under-report any account with more jobs
+ * than that — the reference account holds 2,869.
+ */
+export interface DispatchCounts {
+  total: number;
+  unallocated: number;
+  overdue: number;
+}
+
+export interface JobListFilter {
+  status?: string;
+  jobType?: string;
+  workerId?: string;
+  from?: string;
+  to?: string;
+  unallocatedOnly?: boolean;
+  limit?: number;
+}

package/payload/platform/lib/dispatch-read/src/window.ts

@@ -0,0 +1,131 @@
+/**
+ * Day boundaries in the account's zone, converted to UTC instants for the query.
+ *
+ * `dispatch-day` bounded its window with a literal `Z`
+ * (`${date}T00:00:00.000Z`), which places every Europe/London visit between
+ * local midnight and 01:00 on the previous day for the whole of British Summer
+ * Time. The zone here is always the account's, never the browser's and never
+ * the process's.
+ *
+ * No date library: `Intl.DateTimeFormat` carries the IANA rules already, and
+ * adding a dependency to compute an offset the platform ships would be a second
+ * source of zone truth.
+ */
+
+export const MAX_RANGE_DAYS = 31;
+
+/** Milliseconds the zone is ahead of UTC at this instant. */
+function zoneOffsetMs(instantMs: number, zone: string): number {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: zone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  }).formatToParts(new Date(instantMs));
+  const get = (type: string): number => Number(parts.find((p) => p.type === type)?.value ?? 0);
+  // `hour` formats local midnight as 24 under hour12:false in some ICU builds.
+  const asIfUtc = Date.UTC(
+    get("year"),
+    get("month") - 1,
+    get("day"),
+    get("hour") % 24,
+    get("minute"),
+    get("second"),
+  );
+  return asIfUtc - Math.floor(instantMs / 1000) * 1000;
+}
+
+function ymdParts(ymd: string): [number, number, number] {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(ymd);
+  if (!m) throw new Error(`bad-date reason=not-yyyy-mm-dd value=${ymd}`);
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * The UTC instant at which `dateYmd` begins in `zone`.
+ *
+ * Two passes: the offset at the naive guess can differ from the offset at the
+ * answer across a DST boundary, so the first pass finds an approximate instant
+ * and the second re-reads the offset there.
+ */
+export function zonedDayStartUtc(dateYmd: string, zone: string): string {
+  const [y, m, d] = ymdParts(dateYmd);
+  const guess = Date.UTC(y, m - 1, d, 0, 0, 0, 0);
+  const firstPass = guess - zoneOffsetMs(guess, zone);
+  const secondPass = guess - zoneOffsetMs(firstPass, zone);
+  return new Date(secondPass).toISOString();
+}
+
+export function addDaysYmd(ymd: string, days: number): string {
+  const [y, m, d] = ymdParts(ymd);
+  return new Date(Date.UTC(y, m - 1, d + days)).toISOString().slice(0, 10);
+}
+
+export function daysBetween(fromYmd: string, toYmd: string): number {
+  const [fy, fm, fd] = ymdParts(fromYmd);
+  const [ty, tm, td] = ymdParts(toYmd);
+  return Math.round((Date.UTC(ty, tm - 1, td) - Date.UTC(fy, fm - 1, fd)) / 86_400_000);
+}
+
+/**
+ * `[fromUtc, toUtc)` for an inclusive range of local dates. `toUtc` is the
+ * exclusive start of the day after `toYmd`, so the last day is whole.
+ *
+ * A range wider than the cap is refused rather than truncated: a silently
+ * shortened week renders as a quiet week.
+ */
+export function zonedRangeBounds(
+  fromYmd: string,
+  toYmd: string,
+  zone: string,
+): { fromUtc: string; toUtc: string } {
+  const span = daysBetween(fromYmd, toYmd);
+  if (span < 0) throw new Error(`range-inverted from=${fromYmd} to=${toYmd}`);
+  if (span + 1 > MAX_RANGE_DAYS) {
+    throw new Error(`range-too-wide days=${span + 1} max=${MAX_RANGE_DAYS}`);
+  }
+  return {
+    fromUtc: zonedDayStartUtc(fromYmd, zone),
+    toUtc: zonedDayStartUtc(addDaysYmd(toYmd, 1), zone),
+  };
+}
+
+/** The calendar date at `instantMs` as seen in `zone`. */
+export function ymdInZone(instantMs: number, zone: string): string {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: zone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(instantMs));
+  const get = (type: string): string => parts.find((p) => p.type === type)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+
+/**
+ * Minutes from local midnight. This is the grid's row offset, and it has to be
+ * computed in the account zone or a card lands in the wrong column.
+ */
+export function minutesIntoDay(instantMs: number, zone: string): number {
+  const dayStart = Date.parse(zonedDayStartUtc(ymdInZone(instantMs, zone), zone));
+  return Math.round((instantMs - dayStart) / 60_000);
+}
+
+/** Monday to Sunday containing `nowMs`, as local dates in `zone`. */
+export function currentWeekYmd(
+  nowMs: number,
+  zone: string,
+): { fromYmd: string; toYmd: string } {
+  const today = ymdInZone(nowMs, zone);
+  const [y, m, d] = ymdParts(today);
+  // A UTC-constructed date gives the weekday of the zone-local calendar date,
+  // because the date parts already came from the zone.
+  const weekday = new Date(Date.UTC(y, m - 1, d)).getUTCDay();
+  const backToMonday = weekday === 0 ? 6 : weekday - 1;
+  const fromYmd = addDaysYmd(today, -backToMonday);
+  return { fromYmd, toYmd: addDaysYmd(fromYmd, 6) };
+}

package/payload/platform/lib/dispatch-read/src/zone.ts

@@ -0,0 +1,43 @@
+import { withSession } from "./session.js";
+
+/**
+ * The account's IANA timezone, read from `:UserProfile`.
+ *
+ * Reimplemented here rather than imported from the UI server's `neo4j-store`
+ * because a route importing that would transitively pull in the neo4j driver,
+ * and the whole point of this package is that the planner route can be asserted
+ * to hold no graph access.
+ *
+ * Null on any failure, and the caller's policy is UTC. Falling back to the
+ * browser zone is the defect Task 2280 left on thirteen surfaces: it renders
+ * plausibly and is wrong, which is worse than rendering a zone you can see.
+ *
+ * `userId` omitted is the account-wide read: one UserProfile per account today,
+ * with the ORDER BY pinning the row so the answer stays deterministic if that
+ * ever stops being true.
+ */
+export async function resolveAccountZone(
+  accountId: string,
+  userId?: string,
+): Promise<string | null> {
+  try {
+    return await withSession(async (session) => {
+      const query = userId
+        ? `MATCH (up:UserProfile {accountId: $accountId, userId: $userId})
+           RETURN up.timezone AS timezone`
+        : `MATCH (up:UserProfile {accountId: $accountId})
+           RETURN up.timezone AS timezone ORDER BY up.createdAt LIMIT 1`;
+      const result = await session.run(query, { accountId, userId: userId ?? "" });
+      if (result.records.length === 0) return null;
+      const tz = result.records[0].get("timezone") as string | null;
+      return tz && tz.trim().length > 0 ? tz : null;
+    });
+  } catch (err) {
+    console.error(
+      `[dispatch-planner] op=zone-unresolved account=${accountId} error="${
+        err instanceof Error ? err.message : String(err)
+      }"`,
+    );
+    return null;
+  }
+}

package/payload/platform/lib/dispatch-read/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/lib/dispatch-read/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: false,
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});

package/payload/platform/lib/dispatch-write/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Dispatch writes, shared by the MCP tools and the field job sheet.
+ *
+ * One implementation of the visit-write semantics and the transition contract.
+ * Before this package existed both lived inside the dispatch plugin, where a
+ * UI route cannot reach them, so the field job sheet's only options were a
+ * second implementation or a process spawn per checklist tick.
+ *
+ * Two consumption shapes, matching `dispatch-read`: `platform/ui` imports from
+ * `src` (tsup bundles the TypeScript), plugins import from `dist` (built by the
+ * platform `build:lib` chain, which runs before the plugin glob).
+ */
+export { checkTransition, firstMissingRequiredField, formatTransitionRefused, initialStatus, isTerminal, } from "./lifecycle.js";
+export type { TransitionCheck, TransitionKind, VisitRecordState, } from "./lifecycle.js";
+export { visitRecord, visitStatusSet } from "./write.js";
+export type { StatusSource, VisitRecordParams, VisitRecordResult, VisitStatusResult, VisitStatusSetParams, WriteOutcome, } from "./write.js";
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/dispatch-write/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,uBAAuB,EACvB,aAAa,EACb,UAAU,GACX,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzD,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/payload/platform/lib/dispatch-write/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visitStatusSet = exports.visitRecord = exports.isTerminal = exports.initialStatus = exports.formatTransitionRefused = exports.firstMissingRequiredField = exports.checkTransition = void 0;
+/**
+ * Dispatch writes, shared by the MCP tools and the field job sheet.
+ *
+ * One implementation of the visit-write semantics and the transition contract.
+ * Before this package existed both lived inside the dispatch plugin, where a
+ * UI route cannot reach them, so the field job sheet's only options were a
+ * second implementation or a process spawn per checklist tick.
+ *
+ * Two consumption shapes, matching `dispatch-read`: `platform/ui` imports from
+ * `src` (tsup bundles the TypeScript), plugins import from `dist` (built by the
+ * platform `build:lib` chain, which runs before the plugin glob).
+ */
+var lifecycle_js_1 = require("./lifecycle.js");
+Object.defineProperty(exports, "checkTransition", { enumerable: true, get: function () { return lifecycle_js_1.checkTransition; } });
+Object.defineProperty(exports, "firstMissingRequiredField", { enumerable: true, get: function () { return lifecycle_js_1.firstMissingRequiredField; } });
+Object.defineProperty(exports, "formatTransitionRefused", { enumerable: true, get: function () { return lifecycle_js_1.formatTransitionRefused; } });
+Object.defineProperty(exports, "initialStatus", { enumerable: true, get: function () { return lifecycle_js_1.initialStatus; } });
+Object.defineProperty(exports, "isTerminal", { enumerable: true, get: function () { return lifecycle_js_1.isTerminal; } });
+// Session-taking writes: the plugin's, which owns its own driver.
+var write_js_1 = require("./write.js");
+Object.defineProperty(exports, "visitRecord", { enumerable: true, get: function () { return write_js_1.visitRecord; } });
+Object.defineProperty(exports, "visitStatusSet", { enumerable: true, get: function () { return write_js_1.visitStatusSet; } });
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/dispatch-write/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,+CAMwB;AALtB,+GAAA,eAAe,OAAA;AACf,yHAAA,yBAAyB,OAAA;AACzB,uHAAA,uBAAuB,OAAA;AACvB,6GAAA,aAAa,OAAA;AACb,0GAAA,UAAU,OAAA;AASZ,kEAAkE;AAClE,uCAAyD;AAAhD,uGAAA,WAAW,OAAA;AAAE,0GAAA,cAAc,OAAA"}

package/payload/platform/lib/dispatch-write/dist/lifecycle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Dispatch writes, shared by the MCP tools and the field job sheet.
+ *
+ * The sibling of `dispatch-read`, and for the same reason: the field Mini App's
+ * route must be assertable as holding no graph access while still writing to
+ * the graph. Two consumption shapes, matching that package — session-taking
+ * functions for the plugin, which owns its driver, and session-owning wrappers
+ * for the UI route, which must not.
+ */
+/**
+ * Transition legality, read from the account's own edge list.
+ *
+ * Legality is data. No status string appears in this file: the caller passes
+ * the config and the pair, and the answer is membership in that config's
+ * transition list for the matching kind. A taxi firm's Booked → Dispatched and
+ * a contractor's New → Allocated run this same function against different data.
+ *
+ * A refusal is never swallowed. `op=transition-refused` carries both ends and
+ * the reason, because "the status did not change" with no line is
+ * indistinguishable from a request nobody made.
+ */
+import type { DispatchConfig, RecordableField } from "../../dispatch-read/dist/index.js";
+export type TransitionKind = "job" | "visit";
+export type TransitionCheck = {
+    readonly legal: true;
+} | {
+    readonly legal: false;
+    readonly reason: "not-in-config";
+};
+export declare function checkTransition(kind: TransitionKind, from: string, to: string, cfg: DispatchConfig): TransitionCheck;
+/** Is this a declared terminal status of the given kind? */
+export declare function isTerminal(kind: TransitionKind, status: string, cfg: DispatchConfig): boolean;
+/** The status a newly created job or visit starts in: the first declared. */
+export declare function initialStatus(kind: TransitionKind, cfg: DispatchConfig): string;
+/** What a visit currently carries, for the required-before-terminal check. */
+export interface VisitRecordState {
+    readonly notes: number;
+    readonly media: number;
+    readonly parts: number;
+    readonly checklistDone: number;
+    readonly checklistTotal: number;
+    readonly signatures: number;
+}
+/**
+ * The first `records.requiredBeforeTerminal` field this visit does not carry,
+ * or null when it carries them all. Returns the FIRST rather than all of them
+ * so the refusal names one concrete thing to go and do.
+ */
+export declare function firstMissingRequiredField(toStatus: string, cfg: DispatchConfig, state: VisitRecordState): RecordableField | null;
+export declare function formatTransitionRefused(p: {
+    jobId: string;
+    visitId: string | null;
+    from: string;
+    to: string;
+    reason: string;
+}): string;
+//# sourceMappingURL=lifecycle.d.ts.map

package/payload/platform/lib/dispatch-write/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAGzF,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,OAAO,CAAC;AAE7C,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAEhE,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,cAAc,GAClB,eAAe,CAKjB;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CACxB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,cAAc,GAClB,OAAO,CAGT;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,cAAc,GAAG,MAAM,CAG/E;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAyBD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,gBAAgB,GACtB,eAAe,GAAG,IAAI,CAUxB;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAKT"}