settld 0.1.0

package/src/core/deterministic-zip.js

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertUint8Array(value, name) {
+  if (!(value instanceof Uint8Array)) throw new TypeError(`${name} must be a Uint8Array`);
+}
+
+function dosTimeDateFromDate(date) {
+  const d = new Date(date);
+  if (!Number.isFinite(d.getTime())) throw new TypeError("mtime must be a valid Date");
+  const year = d.getUTCFullYear();
+  const month = d.getUTCMonth() + 1;
+  const day = d.getUTCDate();
+  const hours = d.getUTCHours();
+  const minutes = d.getUTCMinutes();
+  const seconds = d.getUTCSeconds();
+
+  // DOS date starts at 1980.
+  const y = Math.max(1980, Math.min(2107, year)) - 1980;
+  const dosDate = (y << 9) | (month << 5) | day;
+  const dosTime = (hours << 11) | (minutes << 5) | Math.floor(seconds / 2);
+  return { dosTime, dosDate };
+}
+
+function crc32Table() {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < 256; i += 1) {
+    let c = i;
+    for (let k = 0; k < 8; k += 1) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[i] = c >>> 0;
+  }
+  return table;
+}
+
+const CRC32_TABLE = crc32Table();
+
+function crc32(bytes) {
+  assertUint8Array(bytes, "bytes");
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i += 1) {
+    c = CRC32_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function u16(n) {
+  const b = Buffer.allocUnsafe(2);
+  b.writeUInt16LE(n & 0xffff, 0);
+  return b;
+}
+
+function u32(n) {
+  const b = Buffer.allocUnsafe(4);
+  b.writeUInt32LE(n >>> 0, 0);
+  return b;
+}
+
+function concatBuffers(buffers) {
+  const total = buffers.reduce((sum, b) => sum + b.length, 0);
+  const out = Buffer.allocUnsafe(total);
+  let off = 0;
+  for (const b of buffers) {
+    b.copy(out, off);
+    off += b.length;
+  }
+  return out;
+}
+
+export function sha256HexBytes(bytes) {
+  assertUint8Array(bytes, "bytes");
+  return createHash("sha256").update(Buffer.from(bytes)).digest("hex");
+}
+
+/**
+ * Deterministic ZIP (STORE only).
+ * - Sorted entries
+ * - Fixed mtime
+ * - UTF-8 names
+ * - No compression (STORE) to avoid environment/library drift
+ */
+export function buildDeterministicZipStore({ files, mtime } = {}) {
+  if (!(files instanceof Map)) throw new TypeError("files must be a Map(name -> Uint8Array)");
+  const { dosTime, dosDate } = dosTimeDateFromDate(mtime ?? new Date("2000-01-01T00:00:00.000Z"));
+
+  const entries = Array.from(files.entries())
+    .map(([name, bytes]) => ({ name: String(name), bytes }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    assertNonEmptyString(entry.name, "zip entry name");
+    assertUint8Array(entry.bytes, `zip entry ${entry.name} bytes`);
+    const nameBytes = Buffer.from(entry.name, "utf8");
+    const data = Buffer.from(entry.bytes);
+    const crc = crc32(entry.bytes);
+    const size = data.length;
+    const flags = 0x0800; // UTF-8
+    const method = 0; // STORE
+
+    // Local file header
+    const localHeader = concatBuffers([
+      u32(0x04034b50),
+      u16(20), // version needed
+      u16(flags),
+      u16(method),
+      u16(dosTime),
+      u16(dosDate),
+      u32(crc),
+      u32(size),
+      u32(size),
+      u16(nameBytes.length),
+      u16(0) // extra len
+    ]);
+    localParts.push(localHeader, nameBytes, data);
+
+    // Central directory header
+    const centralHeader = concatBuffers([
+      u32(0x02014b50),
+      u16(20), // version made by
+      u16(20), // version needed
+      u16(flags),
+      u16(method),
+      u16(dosTime),
+      u16(dosDate),
+      u32(crc),
+      u32(size),
+      u32(size),
+      u16(nameBytes.length),
+      u16(0), // extra len
+      u16(0), // comment len
+      u16(0), // disk start
+      u16(0), // internal attrs
+      u32(0), // external attrs
+      u32(offset)
+    ]);
+    centralParts.push(centralHeader, nameBytes);
+
+    offset += localHeader.length + nameBytes.length + size;
+  }
+
+  const centralDir = concatBuffers(centralParts);
+  const centralOffset = offset;
+  const centralSize = centralDir.length;
+  offset += centralSize;
+
+  // End of central directory record
+  const eocd = concatBuffers([
+    u32(0x06054b50),
+    u16(0), // disk
+    u16(0), // disk start
+    u16(entries.length),
+    u16(entries.length),
+    u32(centralSize),
+    u32(centralOffset),
+    u16(0) // comment len
+  ]);
+
+  const zip = concatBuffers([...localParts, centralDir, eocd]);
+  return new Uint8Array(zip);
+}
+

package/src/core/dispatch-events.js

@@ -0,0 +1,113 @@
+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`);
+}
+
+const DISPATCH_FAILURE_REASONS = new Set(["NO_SUPPLY", "NO_ROBOTS", "NO_OPERATORS", "CONFLICT", "INVALID_STATE"]);
+
+export function validateDispatchRequestedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "requestedAt", "trigger"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertIsoDate(payload.requestedAt, "payload.requestedAt");
+  if (payload.trigger !== undefined && payload.trigger !== null) assertNonEmptyString(payload.trigger, "payload.trigger");
+  return payload;
+}
+
+export function validateDispatchEvaluatedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "evaluatedAt", "window", "zoneId", "requiresOperatorCoverage", "candidates", "selected"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertIsoDate(payload.evaluatedAt, "payload.evaluatedAt");
+
+  assertPlainObject(payload.window, "payload.window");
+  const winAllowed = new Set(["startAt", "endAt"]);
+  for (const key of Object.keys(payload.window)) {
+    if (!winAllowed.has(key)) throw new TypeError(`payload.window contains unknown field: ${key}`);
+  }
+  assertIsoDate(payload.window.startAt, "payload.window.startAt");
+  assertIsoDate(payload.window.endAt, "payload.window.endAt");
+  if (Date.parse(payload.window.startAt) >= Date.parse(payload.window.endAt)) throw new TypeError("payload.window.startAt must be before endAt");
+
+  if (payload.zoneId !== undefined && payload.zoneId !== null) assertNonEmptyString(payload.zoneId, "payload.zoneId");
+  if (payload.requiresOperatorCoverage !== undefined && typeof payload.requiresOperatorCoverage !== "boolean") {
+    throw new TypeError("payload.requiresOperatorCoverage must be a boolean");
+  }
+
+  if (payload.candidates !== undefined && payload.candidates !== null) {
+    if (!Array.isArray(payload.candidates)) throw new TypeError("payload.candidates must be an array");
+    for (let i = 0; i < payload.candidates.length; i += 1) {
+      const item = payload.candidates[i];
+      assertPlainObject(item, `payload.candidates[${i}]`);
+      const itemAllowed = new Set(["robotId", "score", "reasons", "rejected"]);
+      for (const key of Object.keys(item)) {
+        if (!itemAllowed.has(key)) throw new TypeError(`payload.candidates[${i}] contains unknown field: ${key}`);
+      }
+      assertNonEmptyString(item.robotId, `payload.candidates[${i}].robotId`);
+      if (typeof item.score !== "number" || !Number.isFinite(item.score)) throw new TypeError(`payload.candidates[${i}].score must be a finite number`);
+      if (item.rejected !== undefined && typeof item.rejected !== "boolean") throw new TypeError(`payload.candidates[${i}].rejected must be a boolean`);
+      if (item.reasons !== undefined && item.reasons !== null) {
+        if (!Array.isArray(item.reasons)) throw new TypeError(`payload.candidates[${i}].reasons must be an array`);
+        for (const r of item.reasons) assertNonEmptyString(r, `payload.candidates[${i}].reasons[]`);
+      }
+    }
+  }
+
+  if (payload.selected !== undefined && payload.selected !== null) {
+    assertPlainObject(payload.selected, "payload.selected");
+    const selAllowed = new Set(["robotId", "operatorId"]);
+    for (const key of Object.keys(payload.selected)) {
+      if (!selAllowed.has(key)) throw new TypeError(`payload.selected contains unknown field: ${key}`);
+    }
+    assertNonEmptyString(payload.selected.robotId, "payload.selected.robotId");
+    if (payload.selected.operatorId !== undefined && payload.selected.operatorId !== null) assertNonEmptyString(payload.selected.operatorId, "payload.selected.operatorId");
+  }
+
+  return payload;
+}
+
+export function validateDispatchConfirmedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "confirmedAt"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertIsoDate(payload.confirmedAt, "payload.confirmedAt");
+  return payload;
+}
+
+export function validateDispatchFailedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "failedAt", "reason", "details"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertIsoDate(payload.failedAt, "payload.failedAt");
+  assertNonEmptyString(payload.reason, "payload.reason");
+  if (!DISPATCH_FAILURE_REASONS.has(payload.reason)) throw new TypeError("payload.reason is not supported");
+  if (payload.details !== undefined && payload.details !== null) {
+    assertPlainObject(payload.details, "payload.details");
+  }
+  return payload;
+}
+

package/src/core/dispatch.js

@@ -0,0 +1,26 @@
+import { robotIsAvailableForWindow } from "./robots.js";
+
+export function selectRobotForJob({ robots, window, reservations, minTrustScore = 0 }) {
+  if (!Array.isArray(robots)) throw new TypeError("robots must be an array");
+  if (!window?.startAt || !window?.endAt) throw new TypeError("window must include startAt/endAt");
+  const isReservedOverlapping = typeof reservations === "function" ? reservations : () => false;
+
+  const candidates = [];
+  for (const robot of robots) {
+    if (!robot) continue;
+    if (robot.status && robot.status !== "active") continue;
+    const trustScore = typeof robot.trustScore === "number" ? robot.trustScore : 0;
+    if (trustScore < minTrustScore) continue;
+    if (!robotIsAvailableForWindow(robot, window)) continue;
+    if (isReservedOverlapping(robot.id, window)) continue;
+    candidates.push({ robotId: robot.id, score: trustScore });
+  }
+
+  candidates.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.robotId.localeCompare(b.robotId);
+  });
+
+  return { selected: candidates[0] ?? null, candidates };
+}
+

package/src/core/dispute-open-envelope.js

@@ -0,0 +1,163 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const DISPUTE_OPEN_ENVELOPE_SCHEMA_VERSION = "DisputeOpenEnvelope.v1";
+
+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 assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function normalizeId(value, name, { min = 1, max = 240 } = {}) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim();
+  if (out.length < min || out.length > max) throw new TypeError(`${name} must be length ${min}..${max}`);
+  if (!/^[A-Za-z0-9:_-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:_-]+$`);
+  return out;
+}
+
+function normalizeSha256(value, name) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be a 64-hex sha256`);
+  return out;
+}
+
+function normalizeIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const parsed = Date.parse(String(value));
+  if (!Number.isFinite(parsed)) throw new TypeError(`${name} must be an ISO date string`);
+  return new Date(parsed).toISOString();
+}
+
+function normalizeReasonCode(value, name) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim().toUpperCase();
+  if (!/^[A-Z0-9_]{2,64}$/.test(out)) throw new TypeError(`${name} must match ^[A-Z0-9_]{2,64}$`);
+  return out;
+}
+
+function normalizeSignature(value, name) {
+  assertNonEmptyString(value, name);
+  return String(value).trim();
+}
+
+export function buildDisputeOpenEnvelopeCoreV1({
+  envelopeId,
+  caseId,
+  tenantId,
+  agreementHash,
+  receiptHash,
+  holdHash,
+  openedByAgentId,
+  openedAt,
+  reasonCode,
+  nonce,
+  signerKeyId
+} = {}) {
+  const openedAtIso = normalizeIsoDate(openedAt ?? new Date().toISOString(), "openedAt");
+  const normalizedEnvelopeId = normalizeId(envelopeId, "envelopeId", { min: 3, max: 240 });
+  const normalizedCaseId = normalizeId(caseId, "caseId", { min: 3, max: 240 });
+  const normalized = normalizeForCanonicalJson(
+    {
+      schemaVersion: DISPUTE_OPEN_ENVELOPE_SCHEMA_VERSION,
+      artifactType: DISPUTE_OPEN_ENVELOPE_SCHEMA_VERSION,
+      artifactId: normalizedEnvelopeId,
+      envelopeId: normalizedEnvelopeId,
+      caseId: normalizedCaseId,
+      tenantId: normalizeId(tenantId, "tenantId", { min: 1, max: 128 }),
+      agreementHash: normalizeSha256(agreementHash, "agreementHash"),
+      receiptHash: normalizeSha256(receiptHash, "receiptHash"),
+      holdHash: normalizeSha256(holdHash, "holdHash"),
+      openedByAgentId: normalizeId(openedByAgentId, "openedByAgentId", { min: 3, max: 128 }),
+      openedAt: openedAtIso,
+      reasonCode: normalizeReasonCode(reasonCode, "reasonCode"),
+      nonce: normalizeId(nonce, "nonce", { min: 8, max: 240 }),
+      signerKeyId: normalizeId(signerKeyId, "signerKeyId", { min: 8, max: 240 })
+    },
+    { path: "$" }
+  );
+  return normalized;
+}
+
+export function computeDisputeOpenEnvelopeHashV1(envelopeCore) {
+  assertPlainObject(envelopeCore, "envelopeCore");
+  const copy = { ...envelopeCore };
+  delete copy.envelopeHash;
+  delete copy.signature;
+  delete copy.artifactHash;
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildDisputeOpenEnvelopeV1({
+  envelopeId,
+  caseId,
+  tenantId,
+  agreementHash,
+  receiptHash,
+  holdHash,
+  openedByAgentId,
+  openedAt,
+  reasonCode,
+  nonce,
+  signerKeyId,
+  signature
+} = {}) {
+  const core = buildDisputeOpenEnvelopeCoreV1({
+    envelopeId,
+    caseId,
+    tenantId,
+    agreementHash,
+    receiptHash,
+    holdHash,
+    openedByAgentId,
+    openedAt,
+    reasonCode,
+    nonce,
+    signerKeyId
+  });
+  const envelopeHash = computeDisputeOpenEnvelopeHashV1(core);
+  return normalizeForCanonicalJson(
+    {
+      ...core,
+      envelopeHash,
+      signature: normalizeSignature(signature, "signature")
+    },
+    { path: "$" }
+  );
+}
+
+export function validateDisputeOpenEnvelopeV1(envelope) {
+  assertPlainObject(envelope, "envelope");
+  if (envelope.schemaVersion !== DISPUTE_OPEN_ENVELOPE_SCHEMA_VERSION) {
+    throw new TypeError(`envelope.schemaVersion must be ${DISPUTE_OPEN_ENVELOPE_SCHEMA_VERSION}`);
+  }
+  if (envelope.artifactType !== DISPUTE_OPEN_ENVELOPE_SCHEMA_VERSION) {
+    throw new TypeError(`envelope.artifactType must be ${DISPUTE_OPEN_ENVELOPE_SCHEMA_VERSION}`);
+  }
+  const envelopeId = normalizeId(envelope.envelopeId, "envelope.envelopeId", { min: 3, max: 240 });
+  const artifactId = normalizeId(envelope.artifactId, "envelope.artifactId", { min: 3, max: 240 });
+  if (artifactId !== envelopeId) throw new TypeError("envelope.artifactId must equal envelope.envelopeId");
+  normalizeId(envelope.caseId, "envelope.caseId", { min: 3, max: 240 });
+  normalizeId(envelope.tenantId, "envelope.tenantId", { min: 1, max: 128 });
+  normalizeSha256(envelope.agreementHash, "envelope.agreementHash");
+  normalizeSha256(envelope.receiptHash, "envelope.receiptHash");
+  normalizeSha256(envelope.holdHash, "envelope.holdHash");
+  normalizeId(envelope.openedByAgentId, "envelope.openedByAgentId", { min: 3, max: 128 });
+  normalizeIsoDate(envelope.openedAt, "envelope.openedAt");
+  normalizeReasonCode(envelope.reasonCode, "envelope.reasonCode");
+  normalizeId(envelope.nonce, "envelope.nonce", { min: 8, max: 240 });
+  normalizeId(envelope.signerKeyId, "envelope.signerKeyId", { min: 8, max: 240 });
+  normalizeSignature(envelope.signature, "envelope.signature");
+  const envelopeHash = normalizeSha256(envelope.envelopeHash, "envelope.envelopeHash");
+  const computed = computeDisputeOpenEnvelopeHashV1(envelope);
+  if (computed !== envelopeHash) throw new TypeError("envelopeHash mismatch");
+  return true;
+}