settld 0.1.0

package/src/core/log.js

@@ -0,0 +1,156 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const LEVELS = Object.freeze({
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+});
+
+const REDACTED = "[REDACTED]";
+const SENSITIVE_KEYWORDS = Object.freeze([
+  "secret",
+  "token",
+  "authorization",
+  "cookie",
+  "password",
+  "privatekey",
+  "accesskey",
+  "credentialref"
+]);
+
+function normalizeLevel(level) {
+  const raw = typeof level === "string" ? level.trim().toLowerCase() : "";
+  if (!raw) return "info";
+  if (raw === "warning") return "warn";
+  if (!Object.hasOwn(LEVELS, raw)) return "info";
+  return raw;
+}
+
+function minLevel() {
+  if (typeof process === "undefined") return "info";
+  return normalizeLevel(process.env.LOG_LEVEL ?? "info");
+}
+
+function shouldLog(level) {
+  const lvl = normalizeLevel(level);
+  return LEVELS[lvl] >= LEVELS[minLevel()];
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function errToJson(err) {
+  if (!err) return null;
+  if (err instanceof Error) {
+    return {
+      name: err.name,
+      message: err.message,
+      stack: err.stack
+    };
+  }
+  if (isPlainObject(err)) return err;
+  return { message: String(err) };
+}
+
+function isSensitiveKey(key) {
+  const k = typeof key === "string" ? key.trim().toLowerCase() : "";
+  if (!k) return false;
+  for (const needle of SENSITIVE_KEYWORDS) {
+    if (k.includes(needle)) return true;
+  }
+  return false;
+}
+
+function redactValue(value, seen) {
+  if (value === null || value === undefined) return value;
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") return value;
+  if (t !== "object") return String(value);
+
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.map((v) => redactValue(v, seen));
+  }
+
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (isSensitiveKey(k)) {
+      out[k] = REDACTED;
+      continue;
+    }
+    out[k] = redactValue(v, seen);
+  }
+  return out;
+}
+
+function redactPayload(payload) {
+  try {
+    return redactValue(payload, new WeakSet());
+  } catch {
+    return payload;
+  }
+}
+
+const ctx = new AsyncLocalStorage();
+
+export function withLogContext(context, fn) {
+  if (!isPlainObject(context)) throw new TypeError("context must be a plain object");
+  if (typeof fn !== "function") throw new TypeError("fn must be a function");
+  const existing = ctx.getStore();
+  const merged = existing ? { ...existing, ...context } : { ...context };
+  return ctx.run(merged, fn);
+}
+
+export function getLogContext() {
+  return ctx.getStore() ?? {};
+}
+
+export function log(level, msg, fields = {}) {
+  const normalizedLevel = normalizeLevel(level);
+  if (!shouldLog(normalizedLevel)) return;
+  if (typeof msg !== "string" || msg.trim() === "") throw new TypeError("msg must be a non-empty string");
+  if (!isPlainObject(fields)) throw new TypeError("fields must be a plain object");
+
+  const base = { ts: nowIso(), level: normalizedLevel, msg };
+  const context = getLogContext();
+
+  const payload = { ...base, ...context, ...fields };
+  if (payload.err !== undefined) payload.err = errToJson(payload.err);
+
+  // Drop undefined values to keep JSON compact and stable.
+  for (const [k, v] of Object.entries(payload)) {
+    if (v === undefined) delete payload[k];
+  }
+
+  try {
+    const safe = redactPayload(payload);
+    process.stdout.write(`${JSON.stringify(safe)}\n`);
+  } catch {
+    // Ignore logging failures.
+  }
+}
+
+export const logger = Object.freeze({
+  debug(msg, fields) {
+    log("debug", msg, fields);
+  },
+  info(msg, fields) {
+    log("info", msg, fields);
+  },
+  warn(msg, fields) {
+    log("warn", msg, fields);
+  },
+  error(msg, fields) {
+    log("error", msg, fields);
+  }
+});

package/src/core/maintenance-locks.js

@@ -0,0 +1,3 @@
+export const RETENTION_CLEANUP_ADVISORY_LOCK_KEY = "settld:maintenance:retention_cleanup:v1";
+export const FINANCE_RECONCILE_ADVISORY_LOCK_KEY = "settld:maintenance:finance_reconcile:v1";
+export const MIGRATIONS_ADVISORY_LOCK_KEY = "settld:migrations:v1";

package/src/core/marketplace-kernel.js

@@ -0,0 +1,243 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const MARKETPLACE_OFFER_SCHEMA_VERSION = "MarketplaceOffer.v2";
+export const MARKETPLACE_ACCEPTANCE_SCHEMA_VERSION = "MarketplaceAcceptance.v2";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertIsoDate(value, name, { allowNull = false } = {}) {
+  if (value === null || value === undefined) {
+    if (allowNull) return;
+    throw new TypeError(`${name} must be an ISO date string`);
+  }
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function normalizeOptionalString(value) {
+  if (value === null || value === undefined) return null;
+  const text = String(value).trim();
+  return text === "" ? null : text;
+}
+
+function normalizeSafeInt(value, name, { min = 0, max = Number.MAX_SAFE_INTEGER, allowNull = false } = {}) {
+  if (value === null || value === undefined || value === "") {
+    if (allowNull) return null;
+    throw new TypeError(`${name} is required`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+    throw new TypeError(`${name} must be an integer in range ${min}..${max}`);
+  }
+  return parsed;
+}
+
+function normalizeSha256Hex(value, name, { allowNull = false } = {}) {
+  const normalized = normalizeOptionalString(value);
+  if (normalized === null) {
+    if (allowNull) return null;
+    throw new TypeError(`${name} is required`);
+  }
+  if (!/^[0-9a-f]{64}$/.test(normalized)) throw new TypeError(`${name} must be a 64-char lowercase hex sha256`);
+  return normalized;
+}
+
+function deriveProposalHash(proposal) {
+  const raw = proposal && typeof proposal === "object" && !Array.isArray(proposal) ? proposal : null;
+  if (!raw) return null;
+  try {
+    const withoutHash = { ...raw };
+    delete withoutHash.proposalHash;
+    return sha256Hex(canonicalJsonStringify(normalizeForCanonicalJson(withoutHash, { path: "$" })));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeCurrency(value, name) {
+  assertNonEmptyString(value, name);
+  return String(value).trim().toUpperCase();
+}
+
+export function buildMarketplaceOffer({
+  offerId = null,
+  tenantId,
+  rfqId,
+  runId = null,
+  bidId,
+  proposal,
+  offerChainHash,
+  proposalCount = null,
+  createdAt = null
+}) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(rfqId, "rfqId");
+  assertNonEmptyString(bidId, "bidId");
+
+  if (!proposal || typeof proposal !== "object" || Array.isArray(proposal)) {
+    throw new TypeError("proposal is required");
+  }
+
+  const proposalId = normalizeOptionalString(proposal.proposalId);
+  const revision = normalizeSafeInt(proposal.revision, "proposal.revision", { min: 1 });
+  const proposerAgentId = normalizeOptionalString(proposal.proposerAgentId);
+  const amountCents = normalizeSafeInt(proposal.amountCents, "proposal.amountCents", { min: 1 });
+  const currency = normalizeCurrency(proposal.currency, "proposal.currency");
+  const etaSeconds = normalizeSafeInt(proposal.etaSeconds, "proposal.etaSeconds", { min: 1, allowNull: true });
+  const proposalHash = normalizeSha256Hex(proposal.proposalHash ?? deriveProposalHash(proposal), "proposal.proposalHash");
+  const prevProposalHash = normalizeSha256Hex(proposal.prevProposalHash, "proposal.prevProposalHash", { allowNull: true });
+  const normalizedOfferChainHash = normalizeSha256Hex(offerChainHash, "offerChainHash", { allowNull: true });
+  const normalizedProposalCount = normalizeSafeInt(proposalCount, "proposalCount", { min: 1, allowNull: true });
+
+  const proposedAt =
+    typeof proposal.proposedAt === "string" && Number.isFinite(Date.parse(proposal.proposedAt))
+      ? new Date(Date.parse(proposal.proposedAt)).toISOString()
+      : new Date().toISOString();
+  const normalizedCreatedAt = createdAt ?? proposedAt;
+  assertIsoDate(normalizedCreatedAt, "createdAt");
+
+  const normalizedOfferId =
+    normalizeOptionalString(offerId) ??
+    `ofr_${rfqId}_${bidId}_${proposalId ?? `r${revision}`}`;
+
+  const body = normalizeForCanonicalJson(
+    {
+      schemaVersion: MARKETPLACE_OFFER_SCHEMA_VERSION,
+      offerId: normalizedOfferId,
+      tenantId: String(tenantId),
+      rfqId: String(rfqId),
+      runId: normalizeOptionalString(runId),
+      bidId: String(bidId),
+      proposalId,
+      revision,
+      proposerAgentId,
+      amountCents,
+      currency,
+      etaSeconds,
+      note: normalizeOptionalString(proposal.note),
+      verificationMethod:
+        proposal.verificationMethod && typeof proposal.verificationMethod === "object" && !Array.isArray(proposal.verificationMethod)
+          ? normalizeForCanonicalJson(proposal.verificationMethod, { path: "$" })
+          : null,
+      policy: proposal.policy && typeof proposal.policy === "object" && !Array.isArray(proposal.policy)
+        ? normalizeForCanonicalJson(proposal.policy, { path: "$" })
+        : null,
+      policyRef: proposal.policyRef && typeof proposal.policyRef === "object" && !Array.isArray(proposal.policyRef)
+        ? normalizeForCanonicalJson(proposal.policyRef, { path: "$" })
+        : null,
+      policyRefHash: normalizeSha256Hex(proposal.policyRefHash, "proposal.policyRefHash", { allowNull: true }),
+      prevProposalHash,
+      proposalHash,
+      offerChainHash: normalizedOfferChainHash,
+      proposalCount: normalizedProposalCount,
+      metadata:
+        proposal.metadata && typeof proposal.metadata === "object" && !Array.isArray(proposal.metadata)
+          ? normalizeForCanonicalJson(proposal.metadata, { path: "$" })
+          : null,
+      proposedAt,
+      createdAt: normalizedCreatedAt
+    },
+    { path: "$" }
+  );
+
+  return normalizeForCanonicalJson(
+    {
+      ...body,
+      offerHash: sha256Hex(canonicalJsonStringify(body))
+    },
+    { path: "$" }
+  );
+}
+
+export function buildMarketplaceAcceptance({
+  acceptanceId = null,
+  tenantId,
+  rfqId,
+  runId,
+  bidId,
+  agreementId = null,
+  acceptedAt = null,
+  acceptedByAgentId = null,
+  acceptedProposalId = null,
+  acceptedRevision = null,
+  acceptedProposalHash = null,
+  offerChainHash = null,
+  proposalCount = null,
+  offer = null,
+  createdAt = new Date().toISOString()
+}) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(rfqId, "rfqId");
+  assertNonEmptyString(runId, "runId");
+  assertNonEmptyString(bidId, "bidId");
+  assertIsoDate(acceptedAt, "acceptedAt", { allowNull: true });
+  assertIsoDate(createdAt, "createdAt");
+
+  const offerObj = offer && typeof offer === "object" && !Array.isArray(offer) ? offer : null;
+  const offerId = normalizeOptionalString(offerObj?.offerId);
+  const offerHash = normalizeSha256Hex(offerObj?.offerHash, "offer.offerHash", { allowNull: true });
+
+  const normalizedAcceptedProposalHash = normalizeSha256Hex(
+    acceptedProposalHash ?? offerObj?.proposalHash ?? null,
+    "acceptedProposalHash",
+    { allowNull: true }
+  );
+  const normalizedOfferChainHash = normalizeSha256Hex(
+    offerChainHash ?? offerObj?.offerChainHash ?? null,
+    "offerChainHash",
+    { allowNull: true }
+  );
+  const normalizedProposalCount = normalizeSafeInt(
+    proposalCount ?? offerObj?.proposalCount ?? null,
+    "proposalCount",
+    { min: 1, allowNull: true }
+  );
+
+  const normalizedAcceptedRevision =
+    acceptedRevision === null || acceptedRevision === undefined || acceptedRevision === ""
+      ? offerObj?.revision ?? null
+      : normalizeSafeInt(acceptedRevision, "acceptedRevision", { min: 1 });
+
+  const normalizedAcceptanceId =
+    normalizeOptionalString(acceptanceId) ??
+    `acc_${normalizeOptionalString(agreementId) ?? `${rfqId}_${bidId}`}`;
+
+  const body = normalizeForCanonicalJson(
+    {
+      schemaVersion: MARKETPLACE_ACCEPTANCE_SCHEMA_VERSION,
+      acceptanceId: normalizedAcceptanceId,
+      tenantId: String(tenantId),
+      rfqId: String(rfqId),
+      runId: String(runId),
+      bidId: String(bidId),
+      agreementId: normalizeOptionalString(agreementId),
+      acceptedAt: acceptedAt ?? null,
+      acceptedByAgentId: normalizeOptionalString(acceptedByAgentId),
+      acceptedProposalId: normalizeOptionalString(acceptedProposalId ?? offerObj?.proposalId ?? null),
+      acceptedRevision: normalizedAcceptedRevision,
+      acceptedProposalHash: normalizedAcceptedProposalHash,
+      offerChainHash: normalizedOfferChainHash,
+      proposalCount: normalizedProposalCount,
+      offerRef: normalizeForCanonicalJson(
+        {
+          offerId,
+          offerHash
+        },
+        { path: "$" }
+      ),
+      createdAt
+    },
+    { path: "$" }
+  );
+
+  return normalizeForCanonicalJson(
+    {
+      ...body,
+      acceptanceHash: sha256Hex(canonicalJsonStringify(body))
+    },
+    { path: "$" }
+  );
+}

package/src/core/metrics.js

@@ -0,0 +1,133 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function normalizeMetricName(name) {
+  assertNonEmptyString(name, "name");
+  const v = name.trim();
+  if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(v)) throw new TypeError("metric name must match /^[a-zA-Z_:][a-zA-Z0-9_:]*$/");
+  return v;
+}
+
+function normalizeLabels(labels) {
+  if (labels === null || labels === undefined) return [];
+  if (!labels || typeof labels !== "object" || Array.isArray(labels)) throw new TypeError("labels must be an object");
+  const out = [];
+  for (const [kRaw, vRaw] of Object.entries(labels)) {
+    if (vRaw === undefined) continue;
+    const k = String(kRaw);
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k)) throw new TypeError(`invalid label key: ${k}`);
+    const v = String(vRaw);
+    out.push([k, v]);
+  }
+  out.sort((a, b) => a[0].localeCompare(b[0]));
+  return out;
+}
+
+function escapeLabelValue(value) {
+  return String(value).replaceAll("\\", "\\\\").replaceAll("\n", "\\n").replaceAll("\"", "\\\"");
+}
+
+function labelsToKey(labels) {
+  if (!labels.length) return "";
+  return labels.map(([k, v]) => `${k}=${v}`).join("|");
+}
+
+function labelsToProm(labels) {
+  if (!labels.length) return "";
+  const parts = labels.map(([k, v]) => `${k}="${escapeLabelValue(v)}"`);
+  return `{${parts.join(",")}}`;
+}
+
+export function createMetrics() {
+  const counters = new Map(); // key -> number
+  const gauges = new Map(); // key -> number
+
+  function keyFor(name, labels) {
+    const metric = normalizeMetricName(name);
+    const pairs = normalizeLabels(labels);
+    const labelKey = labelsToKey(pairs);
+    return { metric, pairs, key: labelKey ? `${metric}|${labelKey}` : metric };
+  }
+
+  function declareCounter(name, labels) {
+    const { key } = keyFor(name, labels);
+    if (!counters.has(key)) counters.set(key, 0);
+  }
+
+  function declareGauge(name, labels) {
+    const { key } = keyFor(name, labels);
+    if (!gauges.has(key)) gauges.set(key, 0);
+  }
+
+  function incCounter(name, labels, inc = 1) {
+    const { key } = keyFor(name, labels);
+    const n = Number(inc);
+    if (!Number.isFinite(n) || n <= 0) throw new TypeError("inc must be a positive number");
+    counters.set(key, (counters.get(key) ?? 0) + n);
+  }
+
+  function setGauge(name, labels, value) {
+    const { key } = keyFor(name, labels);
+    const n = Number(value);
+    if (!Number.isFinite(n)) throw new TypeError("value must be a finite number");
+    gauges.set(key, n);
+  }
+
+  function getCounter(name, labels) {
+    const { key } = keyFor(name, labels);
+    return counters.get(key) ?? 0;
+  }
+
+  function getGauge(name, labels) {
+    const { key } = keyFor(name, labels);
+    return gauges.get(key) ?? 0;
+  }
+
+  function snapshot() {
+    const out = { counters: {}, gauges: {} };
+    for (const [k, v] of counters.entries()) out.counters[k] = v;
+    for (const [k, v] of gauges.entries()) out.gauges[k] = v;
+    return out;
+  }
+
+  function renderPrometheusText() {
+    const lines = [];
+
+    const rows = [];
+    for (const [key, value] of counters.entries()) rows.push({ key, value, type: "counter" });
+    for (const [key, value] of gauges.entries()) rows.push({ key, value, type: "gauge" });
+    rows.sort((a, b) => a.key.localeCompare(b.key));
+
+    let lastMetric = null;
+    for (const row of rows) {
+      const [metric, ...labelParts] = row.key.split("|");
+      const pairs = labelParts.length
+        ? labelParts.join("|").split("|").map((kv) => {
+            const idx = kv.indexOf("=");
+            return idx === -1 ? [kv, ""] : [kv.slice(0, idx), kv.slice(idx + 1)];
+          })
+        : [];
+
+      if (metric !== lastMetric) {
+        lines.push(`# TYPE ${metric} ${row.type}`);
+        lastMetric = metric;
+      }
+
+      lines.push(`${metric}${labelsToProm(pairs)} ${row.value}`);
+    }
+
+    return `${lines.join("\n")}\n`;
+  }
+
+  return {
+    declareCounter,
+    declareGauge,
+    incCounter,
+    setGauge,
+    getCounter,
+    getGauge,
+    snapshot,
+    renderPrometheusText
+  };
+}