settld 0.1.0

package/src/core/escrow-ledger.js

@@ -0,0 +1,329 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { addAccount, applyJournalEntry, createAccount, createJournalEntry, createLedger } from "./ledger.js";
+
+export const ESCROW_OPERATION_TYPE = Object.freeze({
+  HOLD: "hold",
+  RELEASE: "release",
+  FORFEIT: "forfeit"
+});
+
+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 normalizeIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date-time`);
+  return value;
+}
+
+function normalizeAmountCents(value, { name = "amountCents", allowZero = false } = {}) {
+  const amountCents = Number(value);
+  if (!Number.isSafeInteger(amountCents)) throw new TypeError(`${name} must be a safe integer`);
+  if (allowZero ? amountCents < 0 : amountCents <= 0) throw new TypeError(`${name} must be ${allowZero ? ">= 0" : "> 0"}`);
+  return amountCents;
+}
+
+function normalizeOperationType(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!Object.values(ESCROW_OPERATION_TYPE).includes(normalized)) {
+    throw new TypeError(`type must be one of: ${Object.values(ESCROW_OPERATION_TYPE).join("|")}`);
+  }
+  return normalized;
+}
+
+function normalizeCurrency(value) {
+  assertNonEmptyString(value, "currency");
+  const normalized = value.trim().toUpperCase();
+  if (!/^[A-Z][A-Z0-9_]{2,11}$/.test(normalized)) throw new TypeError("currency must match ^[A-Z][A-Z0-9_]{2,11}$");
+  return normalized;
+}
+
+function clone(value) {
+  if (value === null || value === undefined) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function conflictError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+export function walletAvailableAccountId({ tenantId, walletId }) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(walletId, "walletId");
+  return `wallet:${tenantId}:${walletId}:available`;
+}
+
+export function walletEscrowAccountId({ tenantId, walletId }) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(walletId, "walletId");
+  return `wallet:${tenantId}:${walletId}:escrow_locked`;
+}
+
+function ensureWalletAccounts({ state, tenantId, walletId }) {
+  const availableAccountId = walletAvailableAccountId({ tenantId, walletId });
+  const escrowAccountId = walletEscrowAccountId({ tenantId, walletId });
+  if (!state.ledger.accounts.has(availableAccountId)) {
+    addAccount(
+      state.ledger,
+      createAccount({
+        id: availableAccountId,
+        name: `Wallet ${walletId} Available`,
+        currency: state.currency,
+        type: "asset"
+      })
+    );
+  }
+  if (!state.ledger.accounts.has(escrowAccountId)) {
+    addAccount(
+      state.ledger,
+      createAccount({
+        id: escrowAccountId,
+        name: `Wallet ${walletId} Escrow Locked`,
+        currency: state.currency,
+        type: "liability"
+      })
+    );
+  }
+}
+
+function getBalance(ledger, accountId) {
+  return Number(ledger.balances.get(accountId) ?? 0);
+}
+
+function normalizeOperationInput(input, { now, currency }) {
+  assertPlainObject(input, "input");
+  const operationId = String(input.operationId ?? "").trim();
+  const tenantId = String(input.tenantId ?? "").trim();
+  const payerWalletId = String(input.payerWalletId ?? "").trim();
+  const payeeWalletIdRaw = input.payeeWalletId === null || input.payeeWalletId === undefined ? null : String(input.payeeWalletId).trim();
+  const type = normalizeOperationType(input.type);
+  const amountCents = normalizeAmountCents(input.amountCents);
+  const at = normalizeIsoDate(input.at ?? now(), "at");
+
+  if (!operationId) throw new TypeError("operationId is required");
+  if (!tenantId) throw new TypeError("tenantId is required");
+  if (!payerWalletId) throw new TypeError("payerWalletId is required");
+  if (type === ESCROW_OPERATION_TYPE.RELEASE && !payeeWalletIdRaw) {
+    throw new TypeError("payeeWalletId is required for release operations");
+  }
+  if ((type === ESCROW_OPERATION_TYPE.HOLD || type === ESCROW_OPERATION_TYPE.FORFEIT) && payeeWalletIdRaw) {
+    throw new TypeError("payeeWalletId is only valid for release operations");
+  }
+
+  const memoRaw = input.memo === null || input.memo === undefined ? null : String(input.memo).trim();
+  const memo = memoRaw === "" ? null : memoRaw;
+
+  return {
+    operationId,
+    tenantId,
+    payerWalletId,
+    payeeWalletId: payeeWalletIdRaw || null,
+    type,
+    amountCents,
+    at,
+    memo,
+    currency
+  };
+}
+
+function operationRequestHash(normalizedInput) {
+  const normalized = normalizeForCanonicalJson(
+    {
+      operationId: normalizedInput.operationId,
+      tenantId: normalizedInput.tenantId,
+      payerWalletId: normalizedInput.payerWalletId,
+      payeeWalletId: normalizedInput.payeeWalletId,
+      type: normalizedInput.type,
+      amountCents: normalizedInput.amountCents,
+      currency: normalizedInput.currency
+    },
+    { path: "$" }
+  );
+  return canonicalJsonStringify(normalized);
+}
+
+function operationStoreKey({ tenantId, operationId }) {
+  return canonicalJsonStringify(
+    normalizeForCanonicalJson(
+      {
+        tenantId,
+        operationId
+      },
+      { path: "$" }
+    )
+  );
+}
+
+function buildPostingsForOperation({ input }) {
+  const payerAvailable = walletAvailableAccountId({ tenantId: input.tenantId, walletId: input.payerWalletId });
+  const payerEscrow = walletEscrowAccountId({ tenantId: input.tenantId, walletId: input.payerWalletId });
+  if (input.type === ESCROW_OPERATION_TYPE.HOLD) {
+    return {
+      fromAccountId: payerAvailable,
+      toAccountId: payerEscrow,
+      postings: [
+        { accountId: payerAvailable, amountCents: -input.amountCents },
+        { accountId: payerEscrow, amountCents: input.amountCents }
+      ]
+    };
+  }
+  if (input.type === ESCROW_OPERATION_TYPE.RELEASE) {
+    const payeeAvailable = walletAvailableAccountId({ tenantId: input.tenantId, walletId: input.payeeWalletId });
+    return {
+      fromAccountId: payerEscrow,
+      toAccountId: payeeAvailable,
+      postings: [
+        { accountId: payerEscrow, amountCents: -input.amountCents },
+        { accountId: payeeAvailable, amountCents: input.amountCents }
+      ]
+    };
+  }
+  if (input.type === ESCROW_OPERATION_TYPE.FORFEIT) {
+    return {
+      fromAccountId: payerEscrow,
+      toAccountId: payerAvailable,
+      postings: [
+        { accountId: payerEscrow, amountCents: -input.amountCents },
+        { accountId: payerAvailable, amountCents: input.amountCents }
+      ]
+    };
+  }
+  throw new TypeError(`unsupported escrow operation type: ${String(input.type ?? "")}`);
+}
+
+function ensureSufficientBalance({ state, input, fromAccountId }) {
+  const currentBalance = getBalance(state.ledger, fromAccountId);
+  if (currentBalance < input.amountCents) {
+    if (input.type === ESCROW_OPERATION_TYPE.HOLD) {
+      throw conflictError("INSUFFICIENT_WALLET_AVAILABLE", "insufficient available wallet balance for hold");
+    }
+    throw conflictError("INSUFFICIENT_ESCROW_LOCKED", "insufficient escrow balance for release/forfeit");
+  }
+}
+
+export function createEscrowLedger({
+  now = () => new Date().toISOString(),
+  currency = "USD",
+  initialWalletBalances = []
+} = {}) {
+  if (typeof now !== "function") throw new TypeError("now must be a function");
+  if (!Array.isArray(initialWalletBalances)) throw new TypeError("initialWalletBalances must be an array");
+
+  const normalizedCurrency = normalizeCurrency(currency);
+  const ledger = createLedger();
+  const state = {
+    schemaVersion: "EscrowLedger.v1",
+    currency: normalizedCurrency,
+    ledger,
+    operations: new Map(),
+    now
+  };
+
+  for (const row of initialWalletBalances) {
+    assertPlainObject(row, "initialWalletBalances[]");
+    const tenantId = String(row.tenantId ?? "").trim();
+    const walletId = String(row.walletId ?? "").trim();
+    if (!tenantId) throw new TypeError("initialWalletBalances[].tenantId is required");
+    if (!walletId) throw new TypeError("initialWalletBalances[].walletId is required");
+    const availableCents = normalizeAmountCents(row.availableCents ?? 0, { name: "initialWalletBalances[].availableCents", allowZero: true });
+    const escrowLockedCents = normalizeAmountCents(row.escrowLockedCents ?? 0, { name: "initialWalletBalances[].escrowLockedCents", allowZero: true });
+    ensureWalletAccounts({ state, tenantId, walletId });
+    state.ledger.balances.set(walletAvailableAccountId({ tenantId, walletId }), availableCents);
+    state.ledger.balances.set(walletEscrowAccountId({ tenantId, walletId }), escrowLockedCents);
+  }
+
+  return state;
+}
+
+export function getEscrowLedgerBalance({ state, accountId }) {
+  assertPlainObject(state, "state");
+  assertNonEmptyString(accountId, "accountId");
+  return getBalance(state.ledger, accountId);
+}
+
+export function upsertEscrowLedgerWalletBalances({
+  state,
+  tenantId,
+  walletId,
+  availableCents,
+  escrowLockedCents
+}) {
+  assertPlainObject(state, "state");
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(walletId, "walletId");
+  const nextAvailable = normalizeAmountCents(availableCents, { name: "availableCents", allowZero: true });
+  const nextEscrow = normalizeAmountCents(escrowLockedCents, { name: "escrowLockedCents", allowZero: true });
+  ensureWalletAccounts({ state, tenantId: tenantId.trim(), walletId: walletId.trim() });
+  state.ledger.balances.set(walletAvailableAccountId({ tenantId: tenantId.trim(), walletId: walletId.trim() }), nextAvailable);
+  state.ledger.balances.set(walletEscrowAccountId({ tenantId: tenantId.trim(), walletId: walletId.trim() }), nextEscrow);
+  return {
+    availableCents: nextAvailable,
+    escrowLockedCents: nextEscrow
+  };
+}
+
+export function applyEscrowOperation({ state, input }) {
+  assertPlainObject(state, "state");
+  if (!state.ledger || !state.operations) throw new TypeError("state is not an escrow ledger state");
+
+  const normalizedInput = normalizeOperationInput(input, { now: state.now, currency: state.currency });
+  const requestHash = operationRequestHash(normalizedInput);
+  const opStoreKey = operationStoreKey({ tenantId: normalizedInput.tenantId, operationId: normalizedInput.operationId });
+  const existing = state.operations.get(opStoreKey) ?? null;
+  if (existing) {
+    if (existing.requestHash !== requestHash) {
+      throw conflictError("ESCROW_OPERATION_CONFLICT", "operationId was already used with a different request");
+    }
+    return { state, operation: clone(existing.operation), applied: false };
+  }
+
+  ensureWalletAccounts({ state, tenantId: normalizedInput.tenantId, walletId: normalizedInput.payerWalletId });
+  if (normalizedInput.payeeWalletId) {
+    ensureWalletAccounts({ state, tenantId: normalizedInput.tenantId, walletId: normalizedInput.payeeWalletId });
+  }
+
+  const postingPlan = buildPostingsForOperation({ input: normalizedInput });
+  ensureSufficientBalance({ state, input: normalizedInput, fromAccountId: postingPlan.fromAccountId });
+
+  const entryId = `escrow:${normalizedInput.tenantId}:${normalizedInput.operationId}`;
+  const entry = createJournalEntry({
+    id: entryId,
+    at: normalizedInput.at,
+    memo: normalizedInput.memo ?? `escrow:${normalizedInput.type}:${normalizedInput.operationId}`,
+    postings: postingPlan.postings
+  });
+  const inserted = applyJournalEntry(state.ledger, entry);
+  if (!inserted) throw conflictError("ESCROW_ENTRY_DUPLICATE", "ledger entry id already exists");
+
+  const operation = {
+    schemaVersion: "EscrowOperation.v1",
+    operationId: normalizedInput.operationId,
+    tenantId: normalizedInput.tenantId,
+    type: normalizedInput.type,
+    amountCents: normalizedInput.amountCents,
+    currency: state.currency,
+    payerWalletId: normalizedInput.payerWalletId,
+    payeeWalletId: normalizedInput.payeeWalletId,
+    entryId,
+    fromAccountId: postingPlan.fromAccountId,
+    toAccountId: postingPlan.toAccountId,
+    at: normalizedInput.at,
+    balancesAfter: {
+      [postingPlan.fromAccountId]: getBalance(state.ledger, postingPlan.fromAccountId),
+      [postingPlan.toAccountId]: getBalance(state.ledger, postingPlan.toAccountId)
+    }
+  };
+
+  state.operations.set(opStoreKey, { requestHash, operation });
+  return { state, operation: clone(operation), applied: true };
+}

package/src/core/event-chain.js

@@ -0,0 +1,114 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex, signHashHexEd25519, verifyHashHexEd25519 } from "./crypto.js";
+import { createId } from "./ids.js";
+
+export const EVENT_ENVELOPE_VERSION = 1;
+
+function payloadMaterialForEvent({ v, id, at, streamId, type, actor, payload }) {
+  return canonicalJsonStringify({ v, id, at, streamId, type, actor, payload });
+}
+
+function chainMaterialForEvent({ v, prevChainHash, payloadHash }) {
+  return canonicalJsonStringify({ v, prevChainHash, payloadHash });
+}
+
+export function createChainedEvent({ streamId, type, actor, payload = null, at = new Date().toISOString(), id = null } = {}) {
+  return {
+    v: EVENT_ENVELOPE_VERSION,
+    id: id ?? createId("evt"),
+    at,
+    streamId,
+    type,
+    actor,
+    payload,
+    payloadHash: null,
+    prevChainHash: null,
+    chainHash: null,
+    signature: null,
+    signerKeyId: null
+  };
+}
+
+export function finalizeChainedEvent({ event, prevChainHash, signer }) {
+  if (!event || typeof event !== "object") throw new TypeError("event must be an object");
+  if (event.v !== EVENT_ENVELOPE_VERSION) throw new TypeError(`event.v must be ${EVENT_ENVELOPE_VERSION}`);
+
+  const normalizedActor = normalizeForCanonicalJson(event.actor ?? null, { path: "$.actor" });
+  const normalizedPayload = normalizeForCanonicalJson(event.payload ?? null, { path: "$.payload" });
+
+  const base = {
+    ...event,
+    actor: normalizedActor,
+    payload: normalizedPayload,
+    prevChainHash
+  };
+
+  const payloadHash = sha256Hex(payloadMaterialForEvent(base));
+  const chainHash = sha256Hex(chainMaterialForEvent({ v: EVENT_ENVELOPE_VERSION, prevChainHash, payloadHash }));
+
+  let signature = null;
+  let signerKeyId = null;
+  if (signer?.privateKeyPem && signer?.keyId) {
+    signature = signHashHexEd25519(payloadHash, signer.privateKeyPem);
+    signerKeyId = signer.keyId;
+  }
+
+  return {
+    ...base,
+    payloadHash,
+    chainHash,
+    signature,
+    signerKeyId
+  };
+}
+
+export function appendChainedEvent({ events, event, signer }) {
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+  const prev = events.length ? events[events.length - 1] : null;
+  const prevChainHash = prev?.chainHash ?? null;
+  const finalized = finalizeChainedEvent({ event, prevChainHash, signer });
+  return [...events, finalized];
+}
+
+export function verifyChainedEvents(events, { publicKeyByKeyId = new Map() } = {}) {
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+
+  for (let i = 0; i < events.length; i += 1) {
+    const event = events[i];
+    const prev = i === 0 ? null : events[i - 1];
+
+    if (!event || typeof event !== "object") return { ok: false, error: `invalid event at index ${i}` };
+    if (event.v !== EVENT_ENVELOPE_VERSION) return { ok: false, error: `unsupported event.v at index ${i}` };
+
+    const expectedPrevChainHash = prev?.chainHash ?? null;
+    if (event.prevChainHash !== expectedPrevChainHash) {
+      return { ok: false, error: `prevChainHash mismatch at index ${i}` };
+    }
+
+    const expectedPayloadHash = sha256Hex(payloadMaterialForEvent(event));
+    if (event.payloadHash !== expectedPayloadHash) {
+      return { ok: false, error: `payloadHash mismatch at index ${i}` };
+    }
+
+    const expectedChainHash = sha256Hex(
+      chainMaterialForEvent({ v: EVENT_ENVELOPE_VERSION, prevChainHash: event.prevChainHash, payloadHash: event.payloadHash })
+    );
+    if (event.chainHash !== expectedChainHash) {
+      return { ok: false, error: `chainHash mismatch at index ${i}` };
+    }
+
+    if (event.signature) {
+      if (!event.signerKeyId) return { ok: false, error: `missing signerKeyId at index ${i}` };
+      const publicKeyPem = publicKeyByKeyId.get(event.signerKeyId);
+      if (!publicKeyPem) return { ok: false, error: `unknown signerKeyId at index ${i}` };
+      const ok = verifyHashHexEd25519({
+        hashHex: event.payloadHash,
+        signatureBase64: event.signature,
+        publicKeyPem
+      });
+      if (!ok) return { ok: false, error: `signature invalid at index ${i}` };
+    }
+  }
+
+  return { ok: true };
+}

package/src/core/event-policy.js

@@ -0,0 +1,120 @@
+export const SIGNER_KIND = Object.freeze({
+  SERVER: "server",
+  ROBOT: "robot",
+  OPERATOR: "operator",
+  ROBOT_OR_OPERATOR: "robot_or_operator",
+  SERVER_OR_OPERATOR: "server_or_operator",
+  SERVER_OR_ROBOT: "server_or_robot",
+  NONE: "none"
+});
+
+const ROBOT_SIGNED_TYPES = new Set([
+  "TELEMETRY_HEARTBEAT",
+  "CHECKPOINT_REACHED",
+  "EN_ROUTE",
+  "ASSIST_REQUESTED",
+  "EXECUTION_STARTED",
+  "JOB_EXECUTION_STARTED",
+  "JOB_HEARTBEAT",
+  "EXECUTION_COMPLETED",
+  "JOB_EXECUTION_COMPLETED",
+  "EXECUTION_ABORTED",
+  "INCIDENT_DETECTED",
+  "SKILL_METER_REPORTED",
+  "ROBOT_HEARTBEAT"
+]);
+
+const OPERATOR_SIGNED_TYPES = new Set([
+  "ASSIST_STARTED",
+  "ASSIST_ENDED",
+  "ASSIST_ACCEPTED",
+  "ASSIST_DECLINED",
+  "OPERATOR_SHIFT_OPENED",
+  "OPERATOR_SHIFT_CLOSED"
+]);
+
+const ROBOT_OR_OPERATOR_SIGNED_TYPES = new Set(["ACCESS_GRANTED", "ACCESS_DENIED", "SKILL_USED", "ZONE_COVERAGE_REPORTED"]);
+
+const SERVER_OR_OPERATOR_SIGNED_TYPES = new Set(["INCIDENT_REPORTED", "CLAIM_TRIAGED"]);
+
+const SERVER_OR_ROBOT_SIGNED_TYPES = new Set(["EVIDENCE_CAPTURED", "JOB_EXECUTION_ABORTED", "JOB_EXECUTION_RESUMED", "ROBOT_UNHEALTHY"]);
+
+  const SERVER_SIGNED_TYPES = new Set([
+  "JOB_CREATED",
+  "QUOTE_PROPOSED",
+  "RISK_SCORED",
+  "BOOKED",
+  "DISPATCH_REQUESTED",
+  "DISPATCH_EVALUATED",
+  "DISPATCH_CONFIRMED",
+  "DISPATCH_FAILED",
+  "OPERATOR_COVERAGE_RESERVED",
+  "OPERATOR_COVERAGE_RELEASED",
+  "ASSIST_QUEUED",
+  "ASSIST_ASSIGNED",
+  "ASSIST_TIMEOUT",
+  "MATCHED",
+  "RESERVED",
+  "SETTLED",
+  "JOB_EXECUTION_STALLED",
+  "JOB_RESCHEDULED",
+  "JOB_CANCELLED",
+  "ACCESS_PLAN_ISSUED",
+  "ACCESS_REVOKED",
+  "ACCESS_EXPIRED",
+  "SKILL_LICENSED",
+  "CLAIM_OPENED",
+  "CLAIM_APPROVED",
+  "CLAIM_DENIED",
+  "CLAIM_PAID",
+  "JOB_ADJUSTED",
+  "ROBOT_REGISTERED",
+  "ROBOT_AVAILABILITY_SET",
+  "ROBOT_QUARANTINED",
+  "ROBOT_QUARANTINE_CLEARED",
+  "MAINTENANCE_REQUESTED",
+  "MAINTENANCE_COMPLETED",
+  "ROBOT_STATUS_CHANGED",
+  "OPERATOR_REGISTERED",
+  "OPERATOR_COST_RECORDED",
+  "SLA_BREACH_DETECTED",
+  "SLA_CREDIT_ISSUED",
+  "PROOF_EVALUATED",
+  "PROOF_OVERRIDDEN",
+  "SETTLEMENT_HELD",
+  "SETTLEMENT_RELEASED",
+  "SETTLEMENT_FORFEITED",
+  "DISPUTE_OPENED",
+  "DISPUTE_CLOSED",
+  "EVIDENCE_VIEWED",
+  "EVIDENCE_EXPIRED",
+  "CORRELATION_LINKED",
+  "CORRELATION_RELINKED",
+  "MONTH_CLOSE_REQUESTED",
+  "MONTH_CLOSED",
+  "MONTH_CLOSE_REOPENED",
+  "INSURER_REIMBURSEMENT_RECORDED",
+  "DECISION_RECORDED",
+  "TENANT_POLICY_UPDATED",
+  "SERVER_SIGNER_KEY_REGISTERED",
+  "SERVER_SIGNER_KEY_ROTATED",
+  "SERVER_SIGNER_KEY_REVOKED"
+]);
+
+export function requiredSignerKindForEventType(eventType) {
+  if (ROBOT_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.ROBOT;
+  if (OPERATOR_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.OPERATOR;
+  if (ROBOT_OR_OPERATOR_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.ROBOT_OR_OPERATOR;
+  if (SERVER_OR_OPERATOR_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.SERVER_OR_OPERATOR;
+  if (SERVER_OR_ROBOT_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.SERVER_OR_ROBOT;
+  if (SERVER_SIGNED_TYPES.has(eventType)) return SIGNER_KIND.SERVER;
+  return SIGNER_KIND.NONE;
+}
+
+export function listKnownEventTypes() {
+  const all = new Set();
+  for (const s of [ROBOT_SIGNED_TYPES, OPERATOR_SIGNED_TYPES, ROBOT_OR_OPERATOR_SIGNED_TYPES, SERVER_OR_OPERATOR_SIGNED_TYPES, SERVER_OR_ROBOT_SIGNED_TYPES, SERVER_SIGNED_TYPES]) {
+    for (const t of s) all.add(t);
+  }
+  return Array.from(all).sort();
+}

package/src/core/evidence-linker.js

@@ -0,0 +1,93 @@
+import { sha256Hex } from "./crypto.js";
+
+function isPlainObject(v) {
+  return Boolean(v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null));
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function cmpString(a, b) {
+  const aa = String(a ?? "");
+  const bb = String(b ?? "");
+  if (aa < bb) return -1;
+  if (aa > bb) return 1;
+  return 0;
+}
+
+function evidenceRefHash(evidenceRef) {
+  const s = typeof evidenceRef === "string" ? evidenceRef : null;
+  if (!s || !s.trim()) return null;
+  return sha256Hex(s);
+}
+
+export function buildEvidenceIndexV1({ generatedAt, jobProof, jobEvents, meteringReport } = {}) {
+  assertNonEmptyString(generatedAt, "generatedAt");
+  if (!isPlainObject(jobProof)) throw new TypeError("jobProof must be an object");
+  assertNonEmptyString(jobProof.embeddedPath, "jobProof.embeddedPath");
+  assertNonEmptyString(jobProof.manifestHash, "jobProof.manifestHash");
+  assertNonEmptyString(jobProof.headAttestationHash, "jobProof.headAttestationHash");
+  if (!Array.isArray(jobEvents)) throw new TypeError("jobEvents must be an array");
+  if (!isPlainObject(meteringReport)) throw new TypeError("meteringReport must be an object");
+
+  const items = [];
+
+  // Metering evidenceRefs (file paths + hashes bound to JobProof manifest).
+  for (const ref of Array.isArray(meteringReport.evidenceRefs) ? meteringReport.evidenceRefs : []) {
+    if (!ref || typeof ref !== "object") continue;
+    const p = typeof ref.path === "string" ? ref.path.replaceAll("\\", "/") : null;
+    const sha256 = typeof ref.sha256 === "string" ? ref.sha256 : null;
+    if (!p || !sha256) continue;
+    items.push({
+      key: `metering:${p}`,
+      source: "metering_evidence_ref",
+      path: p,
+      sha256,
+      eventId: null,
+      at: null,
+      evidenceId: null,
+      kind: null,
+      contentType: null,
+      sizeBytes: null,
+      evidenceRefHash: null
+    });
+  }
+
+  // JobProof evidence capture events (do not include raw evidenceRef; include hash).
+  for (const e of jobEvents) {
+    if (!e || typeof e !== "object") continue;
+    if (e.type !== "EVIDENCE_CAPTURED") continue;
+    const p = e.payload ?? null;
+    if (!p || typeof p !== "object") continue;
+    const evidenceId = typeof p.evidenceId === "string" && p.evidenceId.trim() ? p.evidenceId.trim() : null;
+    if (!evidenceId) continue;
+    items.push({
+      key: `evidence:${evidenceId}`,
+      source: "job_evidence_event",
+      path: null,
+      sha256: null,
+      eventId: typeof e.id === "string" ? e.id : null,
+      at: typeof e.at === "string" ? e.at : null,
+      evidenceId,
+      kind: typeof p.kind === "string" ? p.kind : null,
+      contentType: typeof p.contentType === "string" ? p.contentType : null,
+      sizeBytes: Number.isSafeInteger(p.sizeBytes) ? p.sizeBytes : null,
+      evidenceRefHash: evidenceRefHash(p.evidenceRef ?? null)
+    });
+  }
+
+  items.sort((a, b) => cmpString(a.key, b.key));
+
+  return {
+    schemaVersion: "EvidenceIndex.v1",
+    generatedAt,
+    jobProof: {
+      embeddedPath: jobProof.embeddedPath,
+      manifestHash: jobProof.manifestHash,
+      headAttestationHash: jobProof.headAttestationHash
+    },
+    items
+  };
+}
+