settld 0.1.0

package/src/core/job-state-machine.js

@@ -0,0 +1,266 @@
+export const JOB_STATUS = Object.freeze({
+  CREATED: "CREATED",
+  QUOTED: "QUOTED",
+  BOOKED: "BOOKED",
+  MATCHED: "MATCHED",
+  RESERVED: "RESERVED",
+  EN_ROUTE: "EN_ROUTE",
+  ACCESS_GRANTED: "ACCESS_GRANTED",
+  EXECUTING: "EXECUTING",
+  ASSISTED: "ASSISTED",
+  STALLED: "STALLED",
+  ABORTING_SAFE_EXIT: "ABORTING_SAFE_EXIT",
+  COMPLETED: "COMPLETED",
+  ABORTED: "ABORTED",
+  SETTLED: "SETTLED"
+});
+
+export const JOB_EVENT_TYPE = Object.freeze({
+  QUOTE_PROPOSED: "QUOTE_PROPOSED",
+  BOOKED: "BOOKED",
+  MATCHED: "MATCHED",
+  RESERVED: "RESERVED",
+  EN_ROUTE: "EN_ROUTE",
+  ACCESS_GRANTED: "ACCESS_GRANTED",
+  ACCESS_REVOKED: "ACCESS_REVOKED",
+  ACCESS_EXPIRED: "ACCESS_EXPIRED",
+  EXECUTION_STARTED: "EXECUTION_STARTED",
+  JOB_EXECUTION_STARTED: "JOB_EXECUTION_STARTED",
+  JOB_EXECUTION_STALLED: "JOB_EXECUTION_STALLED",
+  JOB_EXECUTION_RESUMED: "JOB_EXECUTION_RESUMED",
+  ASSIST_STARTED: "ASSIST_STARTED",
+  ASSIST_ENDED: "ASSIST_ENDED",
+  EXECUTION_COMPLETED: "EXECUTION_COMPLETED",
+  JOB_EXECUTION_COMPLETED: "JOB_EXECUTION_COMPLETED",
+  EXECUTION_ABORTED: "EXECUTION_ABORTED",
+  JOB_EXECUTION_ABORTED: "JOB_EXECUTION_ABORTED",
+  JOB_RESCHEDULED: "JOB_RESCHEDULED",
+  JOB_CANCELLED: "JOB_CANCELLED",
+  SETTLED: "SETTLED",
+  INCIDENT_REPORTED: "INCIDENT_REPORTED"
+});
+
+export class InvalidJobTransitionError extends Error {
+  constructor(message, { jobId, fromStatus, eventType } = {}) {
+    super(message);
+    this.name = "InvalidJobTransitionError";
+    this.jobId = jobId;
+    this.fromStatus = fromStatus;
+    this.eventType = eventType;
+  }
+}
+
+const TRANSITIONS = new Map([
+  [`${JOB_STATUS.CREATED}:${JOB_EVENT_TYPE.QUOTE_PROPOSED}`, JOB_STATUS.QUOTED],
+  [`${JOB_STATUS.QUOTED}:${JOB_EVENT_TYPE.BOOKED}`, JOB_STATUS.BOOKED],
+  [`${JOB_STATUS.BOOKED}:${JOB_EVENT_TYPE.MATCHED}`, JOB_STATUS.MATCHED],
+  [`${JOB_STATUS.MATCHED}:${JOB_EVENT_TYPE.RESERVED}`, JOB_STATUS.RESERVED],
+  [`${JOB_STATUS.RESERVED}:${JOB_EVENT_TYPE.EN_ROUTE}`, JOB_STATUS.EN_ROUTE],
+  [`${JOB_STATUS.EN_ROUTE}:${JOB_EVENT_TYPE.ACCESS_GRANTED}`, JOB_STATUS.ACCESS_GRANTED],
+  [`${JOB_STATUS.ACCESS_GRANTED}:${JOB_EVENT_TYPE.EXECUTION_STARTED}`, JOB_STATUS.EXECUTING],
+  [`${JOB_STATUS.ACCESS_GRANTED}:${JOB_EVENT_TYPE.JOB_EXECUTION_STARTED}`, JOB_STATUS.EXECUTING],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.ASSIST_STARTED}`, JOB_STATUS.ASSISTED],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.ASSIST_ENDED}`, JOB_STATUS.EXECUTING],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.EXECUTION_COMPLETED}`, JOB_STATUS.COMPLETED],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.EXECUTION_COMPLETED}`, JOB_STATUS.COMPLETED],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.JOB_EXECUTION_COMPLETED}`, JOB_STATUS.COMPLETED],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.JOB_EXECUTION_COMPLETED}`, JOB_STATUS.COMPLETED],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.ABORTING_SAFE_EXIT}:${JOB_EVENT_TYPE.EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.JOB_EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.JOB_EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.ABORTING_SAFE_EXIT}:${JOB_EVENT_TYPE.JOB_EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.JOB_EXECUTION_STALLED}`, JOB_STATUS.STALLED],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.JOB_EXECUTION_STALLED}`, JOB_STATUS.STALLED],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.JOB_EXECUTION_RESUMED}`, JOB_STATUS.EXECUTING],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.JOB_EXECUTION_ABORTED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.EXECUTION_COMPLETED}`, JOB_STATUS.COMPLETED],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.JOB_EXECUTION_COMPLETED}`, JOB_STATUS.COMPLETED],
+
+  // Rescheduling resets dispatch.
+  [`${JOB_STATUS.BOOKED}:${JOB_EVENT_TYPE.JOB_RESCHEDULED}`, JOB_STATUS.BOOKED],
+  [`${JOB_STATUS.MATCHED}:${JOB_EVENT_TYPE.JOB_RESCHEDULED}`, JOB_STATUS.BOOKED],
+  [`${JOB_STATUS.RESERVED}:${JOB_EVENT_TYPE.JOB_RESCHEDULED}`, JOB_STATUS.BOOKED],
+
+  // Cancellation: aborts the job or forces safe exit if already active.
+  [`${JOB_STATUS.CREATED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.QUOTED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.BOOKED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.MATCHED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.RESERVED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.EN_ROUTE}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.ACCESS_GRANTED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.ABORTING_SAFE_EXIT}:${JOB_EVENT_TYPE.JOB_CANCELLED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+
+  // Access revocation/expiry forces safe exit when active; otherwise cancels.
+  [`${JOB_STATUS.CREATED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.QUOTED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.BOOKED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.MATCHED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.RESERVED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.EN_ROUTE}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.ACCESS_GRANTED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.ACCESS_REVOKED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+
+  [`${JOB_STATUS.CREATED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.QUOTED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.BOOKED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.MATCHED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.RESERVED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTED],
+  [`${JOB_STATUS.EN_ROUTE}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.ACCESS_GRANTED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.EXECUTING}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.ASSISTED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+  [`${JOB_STATUS.STALLED}:${JOB_EVENT_TYPE.ACCESS_EXPIRED}`, JOB_STATUS.ABORTING_SAFE_EXIT],
+
+  [`${JOB_STATUS.COMPLETED}:${JOB_EVENT_TYPE.SETTLED}`, JOB_STATUS.SETTLED],
+  [`${JOB_STATUS.ABORTED}:${JOB_EVENT_TYPE.SETTLED}`, JOB_STATUS.SETTLED]
+]);
+
+const TRANSITION_EVENT_TYPES = new Set([
+  JOB_EVENT_TYPE.QUOTE_PROPOSED,
+  JOB_EVENT_TYPE.BOOKED,
+  JOB_EVENT_TYPE.MATCHED,
+  JOB_EVENT_TYPE.RESERVED,
+  JOB_EVENT_TYPE.EN_ROUTE,
+  JOB_EVENT_TYPE.ACCESS_GRANTED,
+  JOB_EVENT_TYPE.ACCESS_REVOKED,
+  JOB_EVENT_TYPE.ACCESS_EXPIRED,
+  JOB_EVENT_TYPE.EXECUTION_STARTED,
+  JOB_EVENT_TYPE.JOB_EXECUTION_STARTED,
+  JOB_EVENT_TYPE.JOB_EXECUTION_STALLED,
+  JOB_EVENT_TYPE.JOB_EXECUTION_RESUMED,
+  JOB_EVENT_TYPE.ASSIST_STARTED,
+  JOB_EVENT_TYPE.ASSIST_ENDED,
+  JOB_EVENT_TYPE.EXECUTION_COMPLETED,
+  JOB_EVENT_TYPE.EXECUTION_ABORTED,
+  JOB_EVENT_TYPE.JOB_EXECUTION_COMPLETED,
+  JOB_EVENT_TYPE.JOB_EXECUTION_ABORTED,
+  JOB_EVENT_TYPE.JOB_RESCHEDULED,
+  JOB_EVENT_TYPE.JOB_CANCELLED,
+  JOB_EVENT_TYPE.SETTLED
+]);
+
+export function createJob({
+  id,
+  templateId,
+  constraints = {},
+  createdAt = new Date().toISOString(),
+  tenantId = null,
+  customerId = null,
+  siteId = null,
+  contractId = null
+}) {
+  return {
+    id,
+    tenantId,
+    customerId,
+    siteId,
+    contractId,
+    customerContractHash: null,
+    customerPolicyHash: null,
+    customerCompilerId: null,
+    operatorContractHash: null,
+    operatorPolicyHash: null,
+    operatorCompilerId: null,
+    templateId,
+    constraints,
+    status: JOB_STATUS.CREATED,
+    revision: 0,
+    createdAt,
+    updatedAt: createdAt,
+    lastChainHash: null,
+    lastEventId: null,
+    quote: null,
+    booking: null,
+    cancellation: null,
+    match: null,
+    reservation: null,
+    accessPlan: null,
+    access: {
+      status: "none",
+      accessPlanId: null,
+      grantedAt: null,
+      deniedAt: null,
+      revokedAt: null,
+      expiredAt: null
+    },
+    execution: {
+      startedAt: null,
+      robotId: null,
+      stage: null,
+      lastHeartbeatAt: null,
+      lastHeartbeatStage: null,
+      lastHeartbeatProgress: null,
+      lastHeartbeatAssistRequested: null,
+      stalledAt: null,
+      stallReason: null,
+      resumedAt: null,
+      completedAt: null,
+      abortedAt: null
+    },
+    operatorCoverage: {
+      status: "none",
+      reservationId: null,
+      operatorId: null,
+      startAt: null,
+      endAt: null,
+      reservedAt: null,
+      releasedAt: null
+    },
+    assist: {
+      status: "none",
+      queueId: null,
+      operatorId: null,
+      queuedAt: null,
+      assignedAt: null,
+      acceptedAt: null,
+      declinedAt: null
+    },
+    skillLicenses: [],
+    skillUses: []
+  };
+}
+
+export function applyJobEvent(job, event) {
+  if (!job || typeof job !== "object") throw new TypeError("job must be an object");
+  if (!event || typeof event !== "object") throw new TypeError("event must be an object");
+  if (event.streamId && event.streamId !== job.id) {
+    throw new Error(`event.streamId (${event.streamId}) does not match job.id (${job.id})`);
+  }
+
+  const now = event.at ?? new Date().toISOString();
+
+  if (event.type === JOB_EVENT_TYPE.INCIDENT_REPORTED || !TRANSITION_EVENT_TYPES.has(event.type)) {
+    return { ...job, revision: job.revision + 1, updatedAt: now };
+  }
+
+  const key = `${job.status}:${event.type}`;
+  const next = TRANSITIONS.get(key);
+  if (!next) {
+    throw new InvalidJobTransitionError(`Invalid transition from ${job.status} via ${event.type}`, {
+      jobId: job.id,
+      fromStatus: job.status,
+      eventType: event.type
+    });
+  }
+
+  const nextJob = { ...job, status: next, revision: job.revision + 1, updatedAt: now };
+
+  if (event.type === JOB_EVENT_TYPE.QUOTE_PROPOSED) {
+    nextJob.quote = event.payload ?? null;
+  }
+  if (event.type === JOB_EVENT_TYPE.MATCHED) {
+    nextJob.match = event.payload ?? null;
+  }
+
+  return nextJob;
+}

package/src/core/journal-csv.js

@@ -0,0 +1,94 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+import { resolveExternalAccountFor } from "./finance-account-map.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function csvEscape(value) {
+  if (value === null || value === undefined) return "";
+  const s = String(value);
+  if (s.includes('"') || s.includes(",") || s.includes("\n") || s.includes("\r")) return `"${s.replace(/\"/g, '""')}"`;
+  return s;
+}
+
+export const JOURNAL_CSV_SCHEMA_VERSION_V1 = "JournalCsv.v1";
+
+export function renderJournalCsvV1({ glBatchArtifact, accountMap, columns = null } = {}) {
+  if (!glBatchArtifact || typeof glBatchArtifact !== "object") throw new TypeError("glBatchArtifact is required");
+  if (!accountMap || typeof accountMap !== "object") throw new TypeError("accountMap is required");
+
+  const artifactType = glBatchArtifact.artifactType ?? null;
+  if (artifactType !== "GLBatch.v1") throw new TypeError("glBatchArtifact.artifactType must be GLBatch.v1");
+  assertNonEmptyString(glBatchArtifact.tenantId, "glBatchArtifact.tenantId");
+  assertNonEmptyString(glBatchArtifact.period, "glBatchArtifact.period");
+
+  const batch = glBatchArtifact.batch ?? null;
+  if (!batch || typeof batch !== "object") throw new TypeError("glBatchArtifact.batch is required");
+  const lines = Array.isArray(batch.lines) ? batch.lines : [];
+
+  const header =
+    columns ??
+    [
+      "schemaVersion",
+      "tenantId",
+      "period",
+      "basis",
+      "glBatchArtifactHash",
+      "entryId",
+      "postingId",
+      "at",
+      "partyId",
+      "partyRole",
+      "accountId",
+      "externalAccount",
+      "debitCents",
+      "creditCents",
+      "currency",
+      "jobId",
+      "memo"
+    ];
+
+  const rows = [];
+  rows.push(header.map(csvEscape).join(","));
+
+  const artifactHash = glBatchArtifact.artifactHash ?? null;
+  const basis = glBatchArtifact.basis ?? null;
+
+  for (const l of lines) {
+    if (!l || typeof l !== "object") continue;
+    const amountCents = Number.isSafeInteger(l.amountCents) ? l.amountCents : null;
+    if (amountCents === null) continue;
+    const debitCents = amountCents > 0 ? amountCents : 0;
+    const creditCents = amountCents < 0 ? -amountCents : 0;
+    const externalAccount = resolveExternalAccountFor({ map: accountMap, accountId: String(l.accountId ?? "") });
+
+    const record = {
+      schemaVersion: JOURNAL_CSV_SCHEMA_VERSION_V1,
+      tenantId: glBatchArtifact.tenantId,
+      period: glBatchArtifact.period,
+      basis,
+      glBatchArtifactHash: artifactHash ?? "",
+      entryId: l.entryId ?? "",
+      postingId: l.postingId ?? "",
+      at: l.at ?? "",
+      partyId: l.partyId ?? "",
+      partyRole: l.partyRole ?? "",
+      accountId: l.accountId ?? "",
+      externalAccount,
+      debitCents,
+      creditCents,
+      currency: l.currency ?? "USD",
+      jobId: l.jobId ?? "",
+      memo: l.memo ?? ""
+    };
+
+    rows.push(header.map((c) => csvEscape(record[c])).join(","));
+  }
+
+  const csv = `${rows.join("\n")}\n`;
+  const csvHash = sha256Hex(canonicalJsonStringify({ csv }));
+  return { csv, csvHash, rowCount: Math.max(0, rows.length - 1) };
+}
+

package/src/core/ledger-postings-finance.js

@@ -0,0 +1,31 @@
+import { createJournalEntry } from "./ledger.js";
+
+function assertSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer`);
+}
+
+export function ledgerEntriesForFinanceEvent({ event }) {
+  if (!event || typeof event !== "object") throw new TypeError("event is required");
+  const entries = [];
+
+  if (event.type === "INSURER_REIMBURSEMENT_RECORDED") {
+    const amountCents = event.payload?.amountCents ?? null;
+    assertSafeInteger(amountCents, "payload.amountCents");
+    if (amountCents <= 0) throw new TypeError("payload.amountCents must be positive");
+
+    entries.push(
+      createJournalEntry({
+        id: `jnl_${event.id}`,
+        at: event.at,
+        memo: `finance reimbursement:${event.payload?.insurerId ?? "unknown"}`,
+        postings: [
+          { accountId: "acct_cash", amountCents },
+          { accountId: "acct_insurer_receivable", amountCents: -amountCents }
+        ]
+      })
+    );
+  }
+
+  return entries;
+}
+