settld 0.1.0

package/src/core/month-close-hold-policy.js

@@ -0,0 +1,19 @@
+export const MONTH_CLOSE_HOLD_POLICY = Object.freeze({
+  BLOCK_ANY_OPEN_HOLDS: "BLOCK_ANY_OPEN_HOLDS",
+  BLOCK_HOLDS_ORIGINATED_IN_PERIOD: "BLOCK_HOLDS_ORIGINATED_IN_PERIOD",
+  ALLOW_WITH_DISCLOSURE: "ALLOW_WITH_DISCLOSURE"
+});
+
+export function normalizeMonthCloseHoldPolicy(value) {
+  if (value === null || value === undefined || String(value).trim() === "") {
+    return MONTH_CLOSE_HOLD_POLICY.BLOCK_HOLDS_ORIGINATED_IN_PERIOD;
+  }
+  const raw = String(value).trim().toUpperCase();
+  for (const v of Object.values(MONTH_CLOSE_HOLD_POLICY)) {
+    if (raw === v) return v;
+  }
+  throw new TypeError(
+    `invalid month close hold policy: ${String(value)} (expected one of ${Object.values(MONTH_CLOSE_HOLD_POLICY).join(", ")})`
+  );
+}
+

package/src/core/month-close.js

@@ -0,0 +1,159 @@
+import { parseYearMonth } from "./statements.js";
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "./tenancy.js";
+
+export const MONTH_CLOSE_BASIS = Object.freeze({
+  SETTLED_AT: "settledAt"
+});
+
+const BASES = new Set(Object.values(MONTH_CLOSE_BASIS));
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+export function makeMonthCloseStreamId({ month, basis = MONTH_CLOSE_BASIS.SETTLED_AT } = {}) {
+  assertNonEmptyString(month, "month");
+  parseYearMonth(month);
+  assertNonEmptyString(basis, "basis");
+  if (!BASES.has(basis)) throw new TypeError("unsupported basis");
+  return `month_close_${month}_${basis}`;
+}
+
+export function validateMonthCloseRequestedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["tenantId", "month", "basis", "requestedAt"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  const tenantId = normalizeTenantId(payload.tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(payload.month, "payload.month");
+  parseYearMonth(payload.month);
+  assertNonEmptyString(payload.basis, "payload.basis");
+  if (!BASES.has(payload.basis)) throw new TypeError("payload.basis is not supported");
+  assertIsoDate(payload.requestedAt, "payload.requestedAt");
+  return { ...payload, tenantId };
+}
+
+export function validateMonthClosedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["tenantId", "month", "basis", "closedAt", "statementArtifactId", "statementArtifactHash"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  const tenantId = normalizeTenantId(payload.tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(payload.month, "payload.month");
+  parseYearMonth(payload.month);
+  assertNonEmptyString(payload.basis, "payload.basis");
+  if (!BASES.has(payload.basis)) throw new TypeError("payload.basis is not supported");
+  assertIsoDate(payload.closedAt, "payload.closedAt");
+  assertNonEmptyString(payload.statementArtifactId, "payload.statementArtifactId");
+  assertNonEmptyString(payload.statementArtifactHash, "payload.statementArtifactHash");
+  return { ...payload, tenantId };
+}
+
+export function validateMonthCloseReopenedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["tenantId", "month", "basis", "reopenedAt", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  const tenantId = normalizeTenantId(payload.tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(payload.month, "payload.month");
+  parseYearMonth(payload.month);
+  assertNonEmptyString(payload.basis, "payload.basis");
+  if (!BASES.has(payload.basis)) throw new TypeError("payload.basis is not supported");
+  assertIsoDate(payload.reopenedAt, "payload.reopenedAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  return { ...payload, tenantId };
+}
+
+export function reduceMonthClose(events) {
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+  if (events.length === 0) return null;
+
+  const head = events[events.length - 1];
+  const streamId = head?.streamId ?? null;
+  if (typeof streamId !== "string" || streamId.trim() === "") throw new TypeError("month streamId is required");
+
+  let state = {
+    id: streamId,
+    tenantId: DEFAULT_TENANT_ID,
+    month: null,
+    basis: MONTH_CLOSE_BASIS.SETTLED_AT,
+    status: "OPEN", // OPEN|CLOSED
+    requestedAt: null,
+    closedAt: null,
+    reopenedAt: null,
+    statementArtifactId: null,
+    statementArtifactHash: null,
+    lastChainHash: null,
+    lastEventId: null,
+    updatedAt: head?.at ?? null
+  };
+
+  for (const e of events) {
+    if (!e || typeof e !== "object") continue;
+    if (e.type === "MONTH_CLOSE_REQUESTED") {
+      const p = e.payload ?? {};
+      state = {
+        ...state,
+        tenantId: normalizeTenantId(p.tenantId ?? state.tenantId),
+        month: p.month ?? state.month,
+        basis: p.basis ?? state.basis,
+        requestedAt: p.requestedAt ?? e.at ?? state.requestedAt,
+        updatedAt: e.at ?? state.updatedAt
+      };
+    }
+    if (e.type === "MONTH_CLOSED") {
+      const p = e.payload ?? {};
+      state = {
+        ...state,
+        tenantId: normalizeTenantId(p.tenantId ?? state.tenantId),
+        month: p.month ?? state.month,
+        basis: p.basis ?? state.basis,
+        status: "CLOSED",
+        closedAt: p.closedAt ?? e.at ?? state.closedAt,
+        statementArtifactId: p.statementArtifactId ?? state.statementArtifactId,
+        statementArtifactHash: p.statementArtifactHash ?? state.statementArtifactHash,
+        updatedAt: e.at ?? state.updatedAt
+      };
+    }
+    if (e.type === "MONTH_CLOSE_REOPENED") {
+      const p = e.payload ?? {};
+      state = {
+        ...state,
+        tenantId: normalizeTenantId(p.tenantId ?? state.tenantId),
+        month: p.month ?? state.month,
+        basis: p.basis ?? state.basis,
+        status: "OPEN",
+        reopenedAt: p.reopenedAt ?? e.at ?? state.reopenedAt,
+        closedAt: null,
+        statementArtifactId: null,
+        statementArtifactHash: null,
+        updatedAt: e.at ?? state.updatedAt
+      };
+    }
+  }
+
+  state = {
+    ...state,
+    lastChainHash: head?.chainHash ?? null,
+    lastEventId: head?.id ?? null
+  };
+
+  return state;
+}
+

package/src/core/operator-cost.js

@@ -0,0 +1,79 @@
+export const OPERATOR_COST_BASIS = Object.freeze({
+  SHIFT_RATE: "SHIFT_RATE",
+  CONTRACT_RATE: "CONTRACT_RATE",
+  BLENDED: "BLENDED"
+});
+
+const COST_BASIS = new Set(Object.values(OPERATOR_COST_BASIS));
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertSafeInt(value, name) {
+  if (!Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer`);
+}
+
+export function computeOperatorCostCents({ assistSeconds, rateCentsPerMinute }) {
+  assertSafeInt(assistSeconds, "assistSeconds");
+  if (assistSeconds < 0) throw new TypeError("assistSeconds must be >= 0");
+  assertSafeInt(rateCentsPerMinute, "rateCentsPerMinute");
+  if (rateCentsPerMinute < 0) throw new TypeError("rateCentsPerMinute must be >= 0");
+
+  const billableMinutes = Math.ceil(assistSeconds / 60);
+  return billableMinutes * rateCentsPerMinute;
+}
+
+export function validateOperatorCostRecordedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set([
+    "jobId",
+    "zoneId",
+    "operatorId",
+    "assistSeconds",
+    "rateCentsPerMinute",
+    "costCents",
+    "currency",
+    "basis",
+    "settledEventId"
+  ]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  if (payload.zoneId !== undefined && payload.zoneId !== null) assertNonEmptyString(payload.zoneId, "payload.zoneId");
+  if (payload.operatorId !== undefined && payload.operatorId !== null) assertNonEmptyString(payload.operatorId, "payload.operatorId");
+
+  assertSafeInt(payload.assistSeconds, "payload.assistSeconds");
+  if (payload.assistSeconds < 0) throw new TypeError("payload.assistSeconds must be >= 0");
+  assertSafeInt(payload.rateCentsPerMinute, "payload.rateCentsPerMinute");
+  if (payload.rateCentsPerMinute < 0) throw new TypeError("payload.rateCentsPerMinute must be >= 0");
+  assertSafeInt(payload.costCents, "payload.costCents");
+  if (payload.costCents < 0) throw new TypeError("payload.costCents must be >= 0");
+
+  assertNonEmptyString(payload.currency, "payload.currency");
+  if (payload.currency !== "USD") throw new TypeError("payload.currency is not supported");
+  assertNonEmptyString(payload.basis, "payload.basis");
+  if (!COST_BASIS.has(payload.basis)) throw new TypeError("payload.basis is not supported");
+
+  if (payload.settledEventId !== undefined && payload.settledEventId !== null) {
+    assertNonEmptyString(payload.settledEventId, "payload.settledEventId");
+  }
+
+  const expected = computeOperatorCostCents({
+    assistSeconds: payload.assistSeconds,
+    rateCentsPerMinute: payload.rateCentsPerMinute
+  });
+  if (payload.costCents !== expected) throw new TypeError("payload.costCents must match deterministic operator cost formula");
+
+  return payload;
+}
+

package/src/core/operator-coverage.js

@@ -0,0 +1,46 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+export function validateOperatorCoverageReservedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "operatorId", "startAt", "endAt", "reservationId", "zoneId"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.operatorId, "payload.operatorId");
+  assertIsoDate(payload.startAt, "payload.startAt");
+  assertIsoDate(payload.endAt, "payload.endAt");
+  if (Date.parse(payload.startAt) >= Date.parse(payload.endAt)) throw new TypeError("payload.startAt must be before payload.endAt");
+  assertNonEmptyString(payload.reservationId, "payload.reservationId");
+  if (payload.zoneId !== undefined && payload.zoneId !== null) assertNonEmptyString(payload.zoneId, "payload.zoneId");
+  return payload;
+}
+
+export function validateOperatorCoverageReleasedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "reservationId", "releasedAt", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.reservationId, "payload.reservationId");
+  assertIsoDate(payload.releasedAt, "payload.releasedAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  return payload;
+}
+

package/src/core/operator-reducer.js

@@ -0,0 +1,73 @@
+import { validateOperatorRegisteredPayload, validateOperatorShiftClosedPayload, validateOperatorShiftOpenedPayload } from "./operators.js";
+import { DEFAULT_TENANT_ID } from "./tenancy.js";
+
+export function reduceOperator(events) {
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+  if (events.length === 0) return null;
+
+  let operator = null;
+
+  for (const event of events) {
+    if (!event || typeof event !== "object") throw new TypeError("event must be an object");
+
+    if (event.type === "OPERATOR_REGISTERED") {
+      const payload = event.payload ?? {};
+      validateOperatorRegisteredPayload(payload);
+      if (payload.operatorId !== event.streamId) throw new TypeError("operatorId must match streamId");
+      operator = {
+        id: event.streamId,
+        tenantId: payload.tenantId ?? DEFAULT_TENANT_ID,
+        name: payload.name ?? null,
+        signerKeyId: payload.signerKeyId ?? null,
+        shift: { status: "closed", shiftId: null, openedAt: null, closedAt: null, zoneId: null, maxConcurrentJobs: 1 },
+        revision: 0,
+        registeredAt: event.at,
+        createdAt: event.at,
+        updatedAt: event.at
+      };
+      continue;
+    }
+
+    if (!operator) throw new TypeError("operator stream is missing OPERATOR_REGISTERED");
+
+    const now = event.at ?? new Date().toISOString();
+    operator = { ...operator, revision: operator.revision + 1, updatedAt: now };
+
+    if (event.type === "OPERATOR_SHIFT_OPENED") {
+      const payload = event.payload ?? {};
+      validateOperatorShiftOpenedPayload(payload);
+      if (payload.operatorId !== operator.id) throw new TypeError("payload.operatorId must match operator id");
+      operator = {
+        ...operator,
+        shift: {
+          status: "open",
+          shiftId: payload.shiftId ?? null,
+          openedAt: now,
+          closedAt: null,
+          zoneId: payload.zoneId ?? operator.shift?.zoneId ?? null,
+          maxConcurrentJobs: payload.maxConcurrentJobs ?? operator.shift?.maxConcurrentJobs ?? 1
+        }
+      };
+    }
+
+    if (event.type === "OPERATOR_SHIFT_CLOSED") {
+      const payload = event.payload ?? {};
+      validateOperatorShiftClosedPayload(payload);
+      if (payload.operatorId !== operator.id) throw new TypeError("payload.operatorId must match operator id");
+      operator = {
+        ...operator,
+        shift: {
+          status: "closed",
+          shiftId: payload.shiftId ?? operator.shift?.shiftId ?? null,
+          openedAt: operator.shift?.openedAt ?? null,
+          closedAt: now,
+          zoneId: operator.shift?.zoneId ?? null,
+          maxConcurrentJobs: operator.shift?.maxConcurrentJobs ?? 1
+        }
+      };
+    }
+  }
+
+  const head = events[events.length - 1];
+  return { ...operator, lastChainHash: head?.chainHash ?? null, lastEventId: head?.id ?? null };
+}

package/src/core/operators.js

@@ -0,0 +1,52 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+export function validateOperatorRegisteredPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["operatorId", "tenantId", "name", "signerKeyId"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.operatorId, "payload.operatorId");
+  if (payload.tenantId !== undefined && payload.tenantId !== null) assertNonEmptyString(payload.tenantId, "payload.tenantId");
+  if (payload.name !== undefined && payload.name !== null) assertNonEmptyString(payload.name, "payload.name");
+  if (payload.signerKeyId !== undefined && payload.signerKeyId !== null) assertNonEmptyString(payload.signerKeyId, "payload.signerKeyId");
+  return payload;
+}
+
+export function validateOperatorShiftOpenedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["operatorId", "shiftId", "zoneId", "maxConcurrentJobs"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.operatorId, "payload.operatorId");
+  if (payload.shiftId !== undefined && payload.shiftId !== null) assertNonEmptyString(payload.shiftId, "payload.shiftId");
+  if (payload.zoneId !== undefined && payload.zoneId !== null) assertNonEmptyString(payload.zoneId, "payload.zoneId");
+  if (payload.maxConcurrentJobs !== undefined && payload.maxConcurrentJobs !== null) {
+    if (!Number.isSafeInteger(payload.maxConcurrentJobs) || payload.maxConcurrentJobs <= 0) {
+      throw new TypeError("payload.maxConcurrentJobs must be a positive safe integer");
+    }
+  }
+  return payload;
+}
+
+export function validateOperatorShiftClosedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["operatorId", "shiftId", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.operatorId, "payload.operatorId");
+  if (payload.shiftId !== undefined && payload.shiftId !== null) assertNonEmptyString(payload.shiftId, "payload.shiftId");
+  if (payload.reason !== undefined) assertNonEmptyString(payload.reason, "payload.reason");
+  return payload;
+}

package/src/core/ops-audit.js

@@ -0,0 +1,45 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "./tenancy.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+export function makeOpsAuditRecord({
+  tenantId = DEFAULT_TENANT_ID,
+  actorKeyId = null,
+  actorPrincipalId = null,
+  requestId = null,
+  action,
+  targetType = null,
+  targetId = null,
+  at = null,
+  details = null
+} = {}) {
+  tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(action, "action");
+
+  let normalizedDetails;
+  try {
+    normalizedDetails = normalizeForCanonicalJson(details === undefined ? null : details);
+  } catch {
+    normalizedDetails = { error: "DETAILS_UNSERIALIZABLE" };
+  }
+
+  const detailsHash = sha256Hex(canonicalJsonStringify(normalizedDetails));
+
+  return {
+    tenantId,
+    actorKeyId: actorKeyId === null || actorKeyId === undefined ? null : String(actorKeyId),
+    actorPrincipalId: actorPrincipalId === null || actorPrincipalId === undefined ? null : String(actorPrincipalId),
+    requestId: requestId === null || requestId === undefined ? null : String(requestId),
+    action: String(action),
+    targetType: targetType === null || targetType === undefined ? null : String(targetType),
+    targetId: targetId === null || targetId === undefined ? null : String(targetId),
+    at: at ? new Date(String(at)).toISOString() : new Date().toISOString(),
+    detailsHash,
+    details: normalizedDetails
+  };
+}
+

package/src/core/party-statements.js

@@ -0,0 +1,145 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+export function jobIdFromLedgerMemo(memo) {
+  if (typeof memo !== "string" || memo.trim() === "") return null;
+  const m = /^job:([^\s]+)\s/.exec(memo);
+  if (!m) return null;
+  return String(m[1]);
+}
+
+function postingIndexFromPostingId(postingId) {
+  if (typeof postingId !== "string" || postingId.trim() === "") return null;
+  const m = /^p(\d+)$/.exec(String(postingId));
+  if (!m) return null;
+  const idx = Number(m[1]);
+  return Number.isSafeInteger(idx) && idx >= 0 ? idx : null;
+}
+
+export function accountIdFromEntryPostingId({ entry, postingId }) {
+  if (!entry || typeof entry !== "object") return null;
+  if (!Array.isArray(entry.postings)) return null;
+  const idx = postingIndexFromPostingId(postingId);
+  if (idx === null) return null;
+  const p = entry.postings[idx];
+  const accountId = p?.accountId ?? null;
+  if (typeof accountId !== "string" || accountId.trim() === "") return null;
+  return String(accountId);
+}
+
+export function computeAllocationDigest({ allocations }) {
+  if (!Array.isArray(allocations)) throw new TypeError("allocations must be an array");
+  const rows = allocations
+    .map((a) => ({
+      entryId: a?.entryId ?? null,
+      postingId: a?.postingId ?? null,
+      accountId: a?.accountId ?? null,
+      partyId: a?.partyId ?? null,
+      partyRole: a?.partyRole ?? null,
+      currency: a?.currency ?? null,
+      amountCents: Number.isSafeInteger(a?.amountCents) ? a.amountCents : null
+    }))
+    .filter((r) => r.entryId && r.postingId && r.partyId && r.partyRole && r.currency && Number.isSafeInteger(r.amountCents));
+
+  rows.sort(
+    (a, b) =>
+      String(a.entryId).localeCompare(String(b.entryId)) ||
+      String(a.postingId).localeCompare(String(b.postingId)) ||
+      String(a.partyId).localeCompare(String(b.partyId))
+  );
+
+  return sha256Hex(canonicalJsonStringify(rows));
+}
+
+export function computePartyStatement({ tenantId, partyId, partyRole, period, basis, allocations, entriesById = null, currency = "USD" } = {}) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(partyId, "partyId");
+  assertNonEmptyString(partyRole, "partyRole");
+  assertNonEmptyString(period, "period");
+  assertNonEmptyString(basis, "basis");
+  if (!Array.isArray(allocations)) throw new TypeError("allocations must be an array");
+  assertNonEmptyString(currency, "currency");
+
+  const totalsByAccountId = Object.create(null);
+  let balanceDeltaCents = 0;
+  let feesCents = 0;
+  let payoutCents = 0;
+  let creditsCents = 0;
+  const includedEntryIds = new Set();
+  const includedAllocations = [];
+
+  for (const a of allocations) {
+    if (!a || typeof a !== "object") continue;
+    if (String(a.partyId ?? "") !== partyId) continue;
+    if (String(a.partyRole ?? "") !== partyRole) continue;
+    if (!Number.isSafeInteger(a.amountCents)) continue;
+    if (typeof a.entryId !== "string" || a.entryId.trim() === "") continue;
+    if (typeof a.postingId !== "string" || a.postingId.trim() === "") continue;
+    includedEntryIds.add(String(a.entryId));
+    includedAllocations.push(a);
+
+    balanceDeltaCents += a.amountCents;
+
+    let accountId = typeof a.accountId === "string" && a.accountId.trim() ? String(a.accountId) : null;
+    if (!accountId && entriesById && typeof entriesById.get === "function") {
+      const entry = entriesById.get(String(a.entryId)) ?? null;
+      accountId = accountIdFromEntryPostingId({ entry, postingId: a.postingId });
+    }
+    if (!accountId) accountId = "acct_unknown";
+
+    totalsByAccountId[accountId] = (Number.isSafeInteger(totalsByAccountId[accountId]) ? totalsByAccountId[accountId] : 0) + a.amountCents;
+
+    // Party-facing rollup semantics (match SettlementStatement partyRollups):
+    // - platform revenue credits are negative amounts -> feesCents increases by -amt
+    // - operator payable credits are negative amounts -> payoutCents increases by -amt
+    // - customer credits payable credits are negative amounts -> creditsCents increases by -amt
+    const amt = a.amountCents;
+    if (accountId === "acct_platform_revenue") feesCents += -amt;
+    if (accountId === "acct_owner_payable" || accountId === "acct_operator_payable") payoutCents += -amt;
+    if (accountId === "acct_customer_credits_payable") creditsCents += -amt;
+  }
+
+  const allocationDigest = computeAllocationDigest({ allocations: includedAllocations });
+  const entryIds = Array.from(includedEntryIds).sort();
+
+  const netCents = feesCents + payoutCents + creditsCents;
+  return {
+    type: "PartyStatementBody.v1",
+    v: 1,
+    currency,
+    tenantId,
+    partyId,
+    partyRole,
+    period,
+    basis,
+    allocationDigest,
+    allocationCount: includedAllocations.length,
+    includedEntryIds: entryIds,
+    totalsByAccountId,
+    balanceDeltaCents,
+    feesCents,
+    payoutCents,
+    creditsCents,
+    netCents
+  };
+}
+
+export function computePayoutAmountCentsForStatement({ partyRole, statement }) {
+  assertNonEmptyString(partyRole, "partyRole");
+  if (!statement || typeof statement !== "object") throw new TypeError("statement is required");
+  const payoutCents = Number.isSafeInteger(statement.payoutCents) ? statement.payoutCents : 0;
+  if (partyRole !== "operator" && partyRole !== "subcontractor") return 0;
+  return payoutCents > 0 ? payoutCents : 0;
+}
+
+export function payoutKeyFor({ tenantId, partyId, period, statementHash }) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(partyId, "partyId");
+  assertNonEmptyString(period, "period");
+  assertNonEmptyString(statementHash, "statementHash");
+  return `${tenantId}:party:${partyId}:period:${period}:statement:${statementHash}`;
+}

package/src/core/pilot-templates.js

@@ -0,0 +1,26 @@
+import { ENV_TIER } from "./booking.js";
+import { DEFAULT_ZONE_ID } from "./zones.js";
+
+export const PILOT_TEMPLATES = Object.freeze({
+  managed_common_area_reset_l1: {
+    id: "managed_common_area_reset_l1",
+    name: "Managed Common Area Reset L1",
+    jobTemplateId: "reset_lite",
+    environmentTier: ENV_TIER.ENV_MANAGED_BUILDING,
+    requiresOperatorCoverage: false,
+    windowMinutes: 60,
+    defaultZoneId: DEFAULT_ZONE_ID,
+    allowedAccessMethods: ["BUILDING_CONCIERGE", "DOCKED_IN_BUILDING"],
+    skillBundle: ["reset_lite_v1"]
+  }
+});
+
+export function listPilotTemplates() {
+  return Object.values(PILOT_TEMPLATES);
+}
+
+export function getPilotTemplate(pilotTemplateId) {
+  if (typeof pilotTemplateId !== "string" || pilotTemplateId.trim() === "") return null;
+  return PILOT_TEMPLATES[pilotTemplateId.trim()] ?? null;
+}
+