settld 0.1.0

package/src/core/idempotency.js

@@ -0,0 +1,51 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertNoNewlines(value, name) {
+  if (value.includes("\n") || value.includes("\r")) throw new TypeError(`${name} must not contain newlines`);
+}
+
+export function normalizePrincipalId(headers, { headerName = "x-proxy-principal-id", defaultPrincipalId = "anon" } = {}) {
+  const raw = headers?.[headerName] ?? headers?.[headerName.toLowerCase()] ?? null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return defaultPrincipalId;
+  const principalId = String(raw);
+  assertNonEmptyString(principalId, "principalId");
+  assertNoNewlines(principalId, "principalId");
+  if (principalId.length > 200) throw new TypeError("principalId is too long");
+  return principalId;
+}
+
+export function makeIdempotencyEndpoint({ method, path }) {
+  assertNonEmptyString(method, "method");
+  assertNonEmptyString(path, "path");
+  const endpoint = `${method.toUpperCase()} ${path}`;
+  assertNoNewlines(endpoint, "endpoint");
+  if (endpoint.length > 500) throw new TypeError("endpoint is too long");
+  return endpoint;
+}
+
+export function makeIdempotencyStoreKey({ tenantId, principalId, endpoint, idempotencyKey }) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNoNewlines(tenantId, "tenantId");
+  assertNonEmptyString(principalId, "principalId");
+  assertNoNewlines(principalId, "principalId");
+  assertNonEmptyString(endpoint, "endpoint");
+  assertNoNewlines(endpoint, "endpoint");
+  assertNonEmptyString(idempotencyKey, "idempotencyKey");
+  assertNoNewlines(idempotencyKey, "idempotencyKey");
+  if (idempotencyKey.length > 500) throw new TypeError("idempotencyKey is too long");
+  return `${tenantId}\n${principalId}\n${endpoint}\n${idempotencyKey}`;
+}
+
+export function parseIdempotencyStoreKey(storeKey) {
+  assertNonEmptyString(storeKey, "storeKey");
+  const parts = storeKey.split("\n");
+  if (parts.length !== 4) throw new TypeError("invalid idempotency store key");
+  const [tenantId, principalId, endpoint, idempotencyKey] = parts;
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(principalId, "principalId");
+  assertNonEmptyString(endpoint, "endpoint");
+  assertNonEmptyString(idempotencyKey, "idempotencyKey");
+  return { tenantId, principalId, endpoint, idempotencyKey };
+}

package/src/core/ids.js

@@ -0,0 +1,21 @@
+import { randomUUID } from "node:crypto";
+
+let deterministicCounter = 0;
+function deterministicEnabled() {
+  if (typeof process === "undefined") return false;
+  if (process.env.NODE_ENV === "production") return false;
+  return process.env.PROXY_DETERMINISTIC_IDS === "1";
+}
+
+export function resetDeterministicIds() {
+  deterministicCounter = 0;
+}
+
+export function createId(prefix) {
+  if (deterministicEnabled()) {
+    const n = deterministicCounter;
+    deterministicCounter += 1;
+    return `${prefix}_det_${String(n).padStart(8, "0")}`;
+  }
+  return `${prefix}_${randomUUID()}`;
+}

package/src/core/incidents.js

@@ -0,0 +1,75 @@
+export const INCIDENT_TYPE = Object.freeze({
+  DAMAGE_PROPERTY: "DAMAGE_PROPERTY",
+  PRIVACY_VIOLATION: "PRIVACY_VIOLATION",
+  SAFETY_NEAR_MISS: "SAFETY_NEAR_MISS",
+  FAILURE_TO_COMPLETE: "FAILURE_TO_COMPLETE",
+  BLOCKED_ZONE: "BLOCKED_ZONE",
+  ACCESS_FAILURE: "ACCESS_FAILURE",
+  THEFT_ALLEGATION: "THEFT_ALLEGATION",
+  ROBOT_STUCK: "ROBOT_STUCK",
+  UNEXPECTED_HUMAN_CONTACT: "UNEXPECTED_HUMAN_CONTACT"
+});
+
+const INCIDENT_TYPES = new Set(Object.values(INCIDENT_TYPE));
+
+const REPORTED_BY = new Set(["customer", "operator", "ops", "system"]);
+
+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 assertSeverity(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 5) {
+    throw new TypeError(`${name} must be an integer in range 1..5`);
+  }
+}
+
+export function validateIncidentReportedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "incidentId", "type", "severity", "summary", "description", "reportedBy", "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.incidentId, "payload.incidentId");
+  assertNonEmptyString(payload.type, "payload.type");
+  if (!INCIDENT_TYPES.has(payload.type)) throw new TypeError("payload.type is not a supported incident type");
+  assertSeverity(payload.severity, "payload.severity");
+  assertNonEmptyString(payload.summary, "payload.summary");
+  if (payload.description !== undefined) assertNonEmptyString(payload.description, "payload.description");
+  if (payload.zoneId !== undefined && payload.zoneId !== null) assertNonEmptyString(payload.zoneId, "payload.zoneId");
+  if (payload.reportedBy !== undefined) {
+    assertNonEmptyString(payload.reportedBy, "payload.reportedBy");
+    if (!REPORTED_BY.has(payload.reportedBy)) throw new TypeError("payload.reportedBy is not supported");
+  }
+
+  return payload;
+}
+
+export function validateIncidentDetectedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "incidentId", "type", "severity", "summary", "description", "signals", "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.incidentId, "payload.incidentId");
+  assertNonEmptyString(payload.type, "payload.type");
+  if (!INCIDENT_TYPES.has(payload.type)) throw new TypeError("payload.type is not a supported incident type");
+  assertSeverity(payload.severity, "payload.severity");
+  assertNonEmptyString(payload.summary, "payload.summary");
+  if (payload.description !== undefined) assertNonEmptyString(payload.description, "payload.description");
+  if (payload.zoneId !== undefined && payload.zoneId !== null) assertNonEmptyString(payload.zoneId, "payload.zoneId");
+  if (payload.signals !== undefined) assertPlainObject(payload.signals, "payload.signals");
+
+  return payload;
+}

package/src/core/insurer-reimbursements.js

@@ -0,0 +1,58 @@
+import { parseYearMonth } from "./statements.js";
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "./tenancy.js";
+
+export const FINANCE_STREAM_ID = "finance";
+
+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`);
+  return value;
+}
+
+function assertSafeCents(value, name) {
+  if (!Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer (cents)`);
+}
+
+export function validateInsurerReimbursementRecordedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["tenantId", "reimbursementId", "insurerId", "amountCents", "currency", "month", "recordedAt", "reference"]);
+  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.reimbursementId, "payload.reimbursementId");
+  assertNonEmptyString(payload.insurerId, "payload.insurerId");
+  assertSafeCents(payload.amountCents, "payload.amountCents");
+  if (payload.amountCents <= 0) throw new TypeError("payload.amountCents must be positive");
+  assertNonEmptyString(payload.currency, "payload.currency");
+  if (payload.currency !== "USD") throw new TypeError("payload.currency is not supported");
+
+  assertNonEmptyString(payload.month, "payload.month");
+  const period = parseYearMonth(payload.month);
+
+  const recordedAt = assertIsoDate(payload.recordedAt, "payload.recordedAt");
+  const t = Date.parse(recordedAt);
+  const startMs = Date.parse(period.startAt);
+  const endMs = Date.parse(period.endAt);
+  if (Number.isFinite(t) && Number.isFinite(startMs) && Number.isFinite(endMs) && (t < startMs || t >= endMs)) {
+    throw new TypeError("payload.recordedAt must fall within payload.month");
+  }
+
+  if (payload.reference !== undefined && payload.reference !== null) assertNonEmptyString(payload.reference, "payload.reference");
+
+  return { ...payload, tenantId, recordedAt };
+}
+

package/src/core/interaction-directions.js

@@ -0,0 +1,170 @@
+export const INTERACTION_DIRECTION_SCHEMA_VERSION = "InteractionDirectionMatrix.v1";
+
+export const INTERACTION_ENTITY_TYPE = Object.freeze({
+  AGENT: "agent",
+  HUMAN: "human",
+  ROBOT: "robot",
+  MACHINE: "machine"
+});
+
+export const INTERACTION_ENTITY_TYPES = Object.freeze([
+  INTERACTION_ENTITY_TYPE.AGENT,
+  INTERACTION_ENTITY_TYPE.HUMAN,
+  INTERACTION_ENTITY_TYPE.ROBOT,
+  INTERACTION_ENTITY_TYPE.MACHINE
+]);
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object") return value;
+  for (const key of Object.keys(value)) deepFreeze(value[key]);
+  return Object.freeze(value);
+}
+
+const MATRIX = deepFreeze({
+  [INTERACTION_ENTITY_TYPE.AGENT]: {
+    [INTERACTION_ENTITY_TYPE.AGENT]: true,
+    [INTERACTION_ENTITY_TYPE.HUMAN]: true,
+    [INTERACTION_ENTITY_TYPE.ROBOT]: true,
+    [INTERACTION_ENTITY_TYPE.MACHINE]: true
+  },
+  [INTERACTION_ENTITY_TYPE.HUMAN]: {
+    [INTERACTION_ENTITY_TYPE.AGENT]: true,
+    [INTERACTION_ENTITY_TYPE.HUMAN]: true,
+    [INTERACTION_ENTITY_TYPE.ROBOT]: true,
+    [INTERACTION_ENTITY_TYPE.MACHINE]: true
+  },
+  [INTERACTION_ENTITY_TYPE.ROBOT]: {
+    [INTERACTION_ENTITY_TYPE.AGENT]: true,
+    [INTERACTION_ENTITY_TYPE.HUMAN]: true,
+    [INTERACTION_ENTITY_TYPE.ROBOT]: true,
+    [INTERACTION_ENTITY_TYPE.MACHINE]: true
+  },
+  [INTERACTION_ENTITY_TYPE.MACHINE]: {
+    [INTERACTION_ENTITY_TYPE.AGENT]: true,
+    [INTERACTION_ENTITY_TYPE.HUMAN]: true,
+    [INTERACTION_ENTITY_TYPE.ROBOT]: true,
+    [INTERACTION_ENTITY_TYPE.MACHINE]: true
+  }
+});
+
+export const INTERACTION_DIRECTION_MATRIX = MATRIX;
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) throw new TypeError(`${name} must be a plain object`);
+}
+
+function normalizeEntityType(value, name) {
+  const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (!INTERACTION_ENTITY_TYPES.includes(raw)) {
+    throw new TypeError(`${name} must be one of ${INTERACTION_ENTITY_TYPES.join("|")}`);
+  }
+  return raw;
+}
+
+function cloneMatrix() {
+  const out = {};
+  for (const from of INTERACTION_ENTITY_TYPES) {
+    out[from] = {};
+    for (const to of INTERACTION_ENTITY_TYPES) out[from][to] = true;
+  }
+  return out;
+}
+
+export function buildInteractionDirectionMatrixV1() {
+  return {
+    schemaVersion: INTERACTION_DIRECTION_SCHEMA_VERSION,
+    entityTypes: [...INTERACTION_ENTITY_TYPES],
+    directions: cloneMatrix(),
+    directionalCount: INTERACTION_ENTITY_TYPES.length * INTERACTION_ENTITY_TYPES.length
+  };
+}
+
+export function isInteractionDirectionAllowed(fromType, toType) {
+  const from = normalizeEntityType(fromType, "fromType");
+  const to = normalizeEntityType(toType, "toType");
+  return MATRIX[from][to] === true;
+}
+
+export function assertInteractionDirectionAllowed(fromType, toType) {
+  const from = normalizeEntityType(fromType, "fromType");
+  const to = normalizeEntityType(toType, "toType");
+  if (MATRIX[from][to] !== true) {
+    throw new TypeError(`interaction direction not allowed: ${from}->${to}`);
+  }
+  return true;
+}
+
+export function normalizeInteractionDirection({
+  fromType = null,
+  toType = null,
+  defaultFromType = INTERACTION_ENTITY_TYPE.AGENT,
+  defaultToType = INTERACTION_ENTITY_TYPE.AGENT,
+  onInvalid = "throw"
+} = {}) {
+  const normalizeWithDefault = (value, fallback, valueName) => {
+    if (value === null || value === undefined || String(value).trim() === "") {
+      return normalizeEntityType(fallback, `default${valueName[0].toUpperCase()}${valueName.slice(1)}`);
+    }
+    return normalizeEntityType(value, valueName);
+  };
+  const fallback = {
+    fromType: normalizeEntityType(defaultFromType, "defaultFromType"),
+    toType: normalizeEntityType(defaultToType, "defaultToType")
+  };
+  try {
+    const normalized = {
+      fromType: normalizeWithDefault(fromType, fallback.fromType, "fromType"),
+      toType: normalizeWithDefault(toType, fallback.toType, "toType")
+    };
+    assertInteractionDirectionAllowed(normalized.fromType, normalized.toType);
+    return normalized;
+  } catch (err) {
+    if (onInvalid === "fallback") {
+      assertInteractionDirectionAllowed(fallback.fromType, fallback.toType);
+      return fallback;
+    }
+    throw err;
+  }
+}
+
+export function validateInteractionDirectionMatrixV1(value) {
+  assertPlainObject(value, "value");
+  if (value.schemaVersion !== INTERACTION_DIRECTION_SCHEMA_VERSION) {
+    throw new TypeError(`value.schemaVersion must be ${INTERACTION_DIRECTION_SCHEMA_VERSION}`);
+  }
+  if (!Array.isArray(value.entityTypes)) throw new TypeError("value.entityTypes must be an array");
+  if (value.entityTypes.length !== INTERACTION_ENTITY_TYPES.length) {
+    throw new TypeError(`value.entityTypes must include ${INTERACTION_ENTITY_TYPES.length} entity types`);
+  }
+  for (let index = 0; index < INTERACTION_ENTITY_TYPES.length; index += 1) {
+    if (value.entityTypes[index] !== INTERACTION_ENTITY_TYPES[index]) {
+      throw new TypeError(`value.entityTypes[${index}] must be ${INTERACTION_ENTITY_TYPES[index]}`);
+    }
+  }
+
+  assertPlainObject(value.directions, "value.directions");
+  const expectedCount = INTERACTION_ENTITY_TYPES.length * INTERACTION_ENTITY_TYPES.length;
+  if (value.directionalCount !== expectedCount) throw new TypeError(`value.directionalCount must be ${expectedCount}`);
+
+  const fromKeys = Object.keys(value.directions).sort();
+  const expectedKeys = [...INTERACTION_ENTITY_TYPES].sort();
+  if (fromKeys.length !== expectedKeys.length || fromKeys.some((key, index) => key !== expectedKeys[index])) {
+    throw new TypeError(`value.directions keys must be ${INTERACTION_ENTITY_TYPES.join(", ")}`);
+  }
+
+  for (const from of INTERACTION_ENTITY_TYPES) {
+    const row = value.directions[from];
+    assertPlainObject(row, `value.directions.${from}`);
+    const toKeys = Object.keys(row).sort();
+    if (toKeys.length !== expectedKeys.length || toKeys.some((key, index) => key !== expectedKeys[index])) {
+      throw new TypeError(`value.directions.${from} keys must be ${INTERACTION_ENTITY_TYPES.join(", ")}`);
+    }
+    for (const to of INTERACTION_ENTITY_TYPES) {
+      if (row[to] !== true) throw new TypeError(`value.directions.${from}.${to} must be true`);
+    }
+  }
+
+  return true;
+}