@firedrill-tools/unified 0.1.1

package/firedrill/tools/unified/lib/store.mjs

@@ -0,0 +1,75 @@
+// State access: row ids, the shared id counter, bounded prefix scans and per-request indexes.
+import { MAX_SCAN_BOUND, fail, scanBoundExceeded } from "./errors.mjs";
+import { pad } from "./util.mjs";
+
+const CHUNK = 512;
+
+/** Data rows are keyed `{connection_id}/{id}` so one connection's rows form one contiguous row-id range. */
+export const rowId = (connectionId, id) => `${connectionId}/${id}`;
+
+/** The scan bound for the caller's workspace: `limits.max_rows_per_namespace`, never above the hard ceiling. */
+export function scanBound(workspace) {
+  const configured = workspace?.limits?.max_rows_per_namespace;
+  return Number.isInteger(configured) && configured >= 1 ? Math.min(configured, MAX_SCAN_BOUND) : MAX_SCAN_BOUND;
+}
+
+/**
+ * Reads every row of `namespace` under one connection, in row-id (creation) order. A connection holding more than
+ * `bound` rows fails FAILED_PRECONDITION instead of answering from an incomplete scan.
+ */
+export function scanConnection(context, namespace, connectionId, bound) {
+  const prefix = `${connectionId}/`;
+  const out = [];
+  let after = prefix;
+  for (;;) {
+    const rows = context.state.scan(namespace, { afterRowId: after, limit: CHUNK });
+    for (const row of rows) {
+      if (!row.rowId.startsWith(prefix)) return out;
+      out.push(row.value);
+      if (out.length > bound) scanBoundExceeded(context, namespace, bound);
+    }
+    if (rows.length < CHUNK) return out;
+    after = rows[rows.length - 1].rowId;
+  }
+}
+
+/** Reads a whole namespace (used for the small `workspaces` and `connections` namespaces). */
+export function scanAll(context, namespace, bound = MAX_SCAN_BOUND) {
+  const out = [];
+  let after;
+  for (;;) {
+    const rows = context.state.scan(namespace, after === undefined ? { limit: CHUNK } : { afterRowId: after, limit: CHUNK });
+    for (const row of rows) {
+      out.push(row.value);
+      if (out.length > bound) scanBoundExceeded(context, namespace, bound);
+    }
+    if (rows.length < CHUNK) return out;
+    after = rows[rows.length - 1].rowId;
+  }
+}
+
+/** Indexes rows by id for the duration of one request (no per-row rescans). */
+export function indexById(rows) {
+  const map = new Map();
+  for (const row of rows) map.set(row.id, row);
+  return map;
+}
+
+export const getRow = (context, namespace, connectionId, id) => context.state.get(namespace, rowId(connectionId, id));
+
+export const putRow = (context, namespace, row) => context.state.put(namespace, rowId(row.connection_id, row.id), row);
+
+export const deleteRow = (context, namespace, connectionId, id) => context.state.delete(namespace, rowId(connectionId, id));
+
+/** Ids issued at runtime: `68c8` + 14 zeros + a 6-hex-digit counter, so they sort in creation order and never collide. */
+export const idFor = (n) => `68c8${"0".repeat(14)}${pad(n.toString(16), 6)}`;
+
+/** Draws the next object id from the counter row (created lazily), writing the counter back. */
+export function nextId(context) {
+  const row = context.state.get("meta", "counters");
+  const next = Number.isInteger(row?.next_id) && row.next_id >= 1 ? row.next_id : 1;
+  // Six hex digits hold 16,777,215 ids; past that the id would no longer be 24 characters.
+  if (next > 0xffffff) fail(context, "FAILED_PRECONDITION", "The simulated workspace has exhausted its id space");
+  context.state.put("meta", "counters", { next_id: next + 1 });
+  return idFor(next);
+}

package/firedrill/tools/unified/lib/time.mjs

@@ -0,0 +1,59 @@
+// Host-independent time handling: ISO-8601 UTC strings from virtual microseconds and strict parsing of caller dates.
+// Zone-less input is UTC (the provider's documented default); nothing here consults the host clock or time zone.
+import { pad } from "./util.mjs";
+
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+const isLeap = (year) => (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+
+/** Formats virtual microseconds as `YYYY-MM-DDTHH:MM:SS.sssZ`. */
+export function isoFromUs(us) {
+  const ms = Math.floor(Number(us) / 1000);
+  const date = new Date(ms);
+  return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}T${pad(
+    date.getUTCHours(),
+    2,
+  )}:${pad(date.getUTCMinutes(), 2)}:${pad(date.getUTCSeconds(), 2)}.${pad(date.getUTCMilliseconds(), 3)}Z`;
+}
+
+export const nowIso = (context) => isoFromUs(context.clock.nowUs());
+
+const ISO =
+  /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,6}))?)?)?(Z|[+-]\d{2}:?\d{2})?$/;
+
+/**
+ * Parses an ISO-8601 date or date-time into microseconds since the epoch, or returns null when the text is not a
+ * real instant. Time and zone are optional; a missing zone means UTC. A U+FFFD (mangled percent-encoding) is invalid.
+ */
+export function parseIsoUs(text) {
+  if (typeof text !== "string" || text.length > 40 || text.includes("�")) return null;
+  const match = ISO.exec(text.trim());
+  if (match === null) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const hour = match[4] === undefined ? 0 : Number(match[4]);
+  const minute = match[5] === undefined ? 0 : Number(match[5]);
+  const second = match[6] === undefined ? 0 : Number(match[6]);
+  const fraction = match[7] === undefined ? 0 : Number(match[7].padEnd(6, "0"));
+  if (year < 1970 || year > 9999 || month < 1 || month > 12 || day < 1) return null;
+  const maxDay = DAYS_IN_MONTH[month - 1] + (month === 2 && isLeap(year) ? 1 : 0);
+  if (day > maxDay || hour > 23 || minute > 59 || second > 60) return null;
+  let offsetMinutes = 0;
+  if (match[8] !== undefined && match[8] !== "Z") {
+    const sign = match[8][0] === "-" ? -1 : 1;
+    const digits = match[8].slice(1).replace(":", "");
+    const offsetHours = Number(digits.slice(0, 2));
+    const offsetMins = Number(digits.slice(2, 4));
+    if (offsetHours > 14 || offsetMins > 59) return null;
+    offsetMinutes = sign * (offsetHours * 60 + offsetMins);
+  }
+  const ms = Date.UTC(year, month - 1, day, hour, minute, Math.min(second, 59)) - offsetMinutes * 60000;
+  return ms * 1000 + fraction;
+}
+
+/** Normalises caller date text to the canonical ISO string, or null when invalid. */
+export function normaliseIso(text) {
+  const us = parseIsoUs(text);
+  return us === null ? null : isoFromUs(us);
+}

package/firedrill/tools/unified/lib/util.mjs

@@ -0,0 +1,92 @@
+// Small deterministic helpers shared by every module. No clock, no randomness, no Node built-ins.
+
+export const HEX24 = /^[0-9a-f]{24}$/;
+
+export const isHex24 = (value) => typeof value === "string" && HEX24.test(value);
+
+export const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Clips caller text quoted into messages so no error message ever approaches the framework's 4,000-character cap. */
+export function clip(value, max = 200) {
+  const text = String(value);
+  return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+
+export const pad = (value, width, fill = "0") => String(value).padStart(width, fill);
+
+/** UTF-8 byte length of a string, computed from code points (a behavior module has no Buffer). */
+export function utf8Bytes(text) {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      // High surrogate: a well-formed pair is one 4-byte code point; a lone surrogate serialises as 3 bytes.
+      const next = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        i += 1;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** UTF-8 byte size of the JSON encoding of a value. */
+export const jsonBytes = (value) => utf8Bytes(JSON.stringify(value));
+
+/** Case fold for search: lower-case plus a full-width/upper-case normalisation that never depends on the host locale. */
+export const fold = (text) => text.toLowerCase();
+
+/** Linear-time substring test on folded text (String.prototype.includes is linear in V8; the needle is literal). */
+export const containsFolded = (haystack, needle) => typeof haystack === "string" && fold(haystack).includes(needle);
+
+export function titleCase(slug) {
+  return slug
+    .split(/[-_]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+/** Deterministic string comparison by UTF-16 code units (no locale). */
+export function compareText(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+export function hasOwn(object, key) {
+  return isPlainObject(object) && Object.hasOwn(object, key);
+}
+
+/** Returns a copy of `value` without the listed keys. */
+export function omit(value, keys) {
+  const out = {};
+  for (const key of Object.keys(value)) {
+    if (!keys.includes(key)) out[key] = value[key];
+  }
+  return out;
+}
+
+/** Structural equality for JSON values (used to compute changed fields on update). */
+export function jsonEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) if (!jsonEqual(a[i], b[i])) return false;
+    return true;
+  }
+  if (typeof a === "object") {
+    if (Array.isArray(b)) return false;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    for (const key of keysA) {
+      if (!Object.hasOwn(b, key) || !jsonEqual(a[key], b[key])) return false;
+    }
+    return true;
+  }
+  return false;
+}

package/firedrill/tools/unified/lib/validate.mjs

@@ -0,0 +1,114 @@
+// Body validation against the state schema bounds. Every problem is BAD_REQUEST naming the field and the bound, with
+// caller text clipped. Read-only fields are ignored (as the provider ignores them); unknown fields are refused.
+import { badRequest, invalidField } from "./errors.mjs";
+import { normaliseIso } from "./time.mjs";
+import { clip, isHex24, isPlainObject } from "./util.mjs";
+import { SHAPES } from "./shapes.mjs";
+
+export const READ_ONLY = new Set(["id", "created_at", "updated_at", "connection_id", "workspace_id"]);
+
+// Field spec constructors -----------------------------------------------------------------------
+export const str = (max, opts = {}) => ({ kind: "str", max, min: opts.min ?? 0, nullable: opts.nullable !== false, pattern: opts.pattern ?? null });
+export const bool = () => ({ kind: "bool" });
+export const num = (opts = {}) => ({ kind: "num", min: opts.min ?? null, max: opts.max ?? null, integer: opts.integer === true, nullable: opts.nullable !== false });
+export const strArray = (maxItems, maxLen) => ({ kind: "strArray", maxItems, maxLen });
+export const idArray = (maxItems) => ({ kind: "idArray", maxItems });
+export const enumOf = (values, nullable = true) => ({ kind: "enum", values, nullable });
+export const iso = () => ({ kind: "iso" });
+export const shape = (name) => ({ kind: "shape", name });
+
+const isNullish = (value) => value === undefined || value === null;
+
+/** Validates one value against a spec, returning the normalised value. */
+export function checkValue(context, field, spec, value) {
+  switch (spec.kind) {
+    case "str": {
+      if (isNullish(value)) {
+        if (!spec.nullable) invalidField(context, field, "a string is required");
+        return null;
+      }
+      if (typeof value !== "string") invalidField(context, field, "must be a string");
+      if (value.length < spec.min) invalidField(context, field, `must be at least ${spec.min} characters`);
+      if (value.length > spec.max) invalidField(context, field, `must be at most ${spec.max} characters`);
+      if (spec.pattern !== null && !spec.pattern.test(value)) invalidField(context, field, "has an invalid format");
+      return value;
+    }
+    case "bool":
+      if (isNullish(value)) return null;
+      if (typeof value !== "boolean") invalidField(context, field, "must be a boolean");
+      return value;
+    case "num": {
+      if (isNullish(value)) {
+        if (!spec.nullable) invalidField(context, field, "a number is required");
+        return null;
+      }
+      if (typeof value !== "number" || !Number.isFinite(value)) invalidField(context, field, "must be a finite number");
+      if (spec.integer && !Number.isInteger(value)) invalidField(context, field, "must be an integer");
+      if (spec.min !== null && value < spec.min) invalidField(context, field, `must be at least ${spec.min}`);
+      if (spec.max !== null && value > spec.max) invalidField(context, field, `must be at most ${spec.max}`);
+      return value;
+    }
+    case "strArray": {
+      if (isNullish(value)) return [];
+      if (!Array.isArray(value)) invalidField(context, field, "must be an array of strings");
+      if (value.length > spec.maxItems) invalidField(context, field, `must have at most ${spec.maxItems} entries`);
+      for (const entry of value) {
+        if (typeof entry !== "string" || entry.length > spec.maxLen) invalidField(context, field, `entries must be strings of at most ${spec.maxLen} characters`);
+      }
+      return value.slice();
+    }
+    case "idArray": {
+      if (isNullish(value)) return [];
+      if (!Array.isArray(value)) invalidField(context, field, "must be an array of ids");
+      if (value.length > spec.maxItems) invalidField(context, field, `must have at most ${spec.maxItems} entries`);
+      const out = [];
+      for (const entry of value) {
+        if (!isHex24(entry)) invalidField(context, field, `contains an invalid id ${clip(String(entry), 40)}`);
+        if (!out.includes(entry)) out.push(entry);
+      }
+      return out;
+    }
+    case "enum":
+      if (isNullish(value)) {
+        if (!spec.nullable) invalidField(context, field, `must be one of ${spec.values.join(", ")}`);
+        return null;
+      }
+      if (typeof value !== "string" || !spec.values.includes(value)) invalidField(context, field, `must be one of ${spec.values.join(", ")}`);
+      return value;
+    case "iso": {
+      if (isNullish(value)) return null;
+      const normalised = typeof value === "string" ? normaliseIso(value) : null;
+      if (normalised === null) invalidField(context, field, "must be an ISO-8601 date-time");
+      return normalised;
+    }
+    case "shape": {
+      const validator = SHAPES.get(spec.name);
+      return validator(context, field, value);
+    }
+    default:
+      invalidField(context, field, "unsupported");
+  }
+  return null;
+}
+
+/**
+ * Validates a request body against `specs` (field -> spec). Returns the normalised present fields only, so the
+ * caller can merge them (update) or fill defaults (create). Read-only names are dropped; unknown names fail.
+ */
+export function validateBody(context, body, specs) {
+  if (!isPlainObject(body)) badRequest(context, "Request body must be a JSON object");
+  const out = {};
+  for (const key of Object.keys(body)) {
+    if (READ_ONLY.has(key) || key === "__request_error") continue;
+    if (!Object.hasOwn(specs, key)) badRequest(context, `Unknown field "${clip(key, 80)}"`);
+    out[key] = checkValue(context, key, specs[key], body[key]);
+  }
+  return out;
+}
+
+/** Splits an operation input into the addressing part and the resource body (everything that is not addressing). */
+export function bodyOf(input, addressing) {
+  const body = {};
+  for (const key of Object.keys(input)) if (!addressing.includes(key)) body[key] = input[key];
+  return body;
+}

package/firedrill/tools/unified/lib/wire.mjs

@@ -0,0 +1,120 @@
+// Pure HTTP codecs for the provider-shaped routes. `decode` maps path, query and JSON body into the canonical
+// snake_case arguments; a request that cannot be mapped travels as `__request_error`, which every handler checks
+// first so the caller receives the provider envelope and status instead of a framework message. `encode` passes
+// success bodies through and renders `{ statusCode, message, error }` for every failure.
+import { ERRORS } from "./errors.mjs";
+import { clip } from "./util.mjs";
+
+const MAX_DEPTH = 512;
+const MAX_REPEATS = 16;
+const MAX_MEMBERS = 20000;
+const BANNED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const RESERVED = "__request_error";
+
+/** Iterative shape check (explicit stack): depth, member count and prototype-poisoning keys. */
+function shapeProblem(value) {
+  const stack = [[value, 1]];
+  let visited = 0;
+  while (stack.length > 0) {
+    const [node, depth] = stack.pop();
+    if (depth > MAX_DEPTH) return "Request body is nested too deeply";
+    if (node === null || typeof node !== "object") continue;
+    visited += 1;
+    if (visited > MAX_MEMBERS) return "Request body has too many members";
+    if (Array.isArray(node)) {
+      if (node.length > MAX_MEMBERS) return "Request body has too many array entries";
+      for (const child of node) if (child !== null && typeof child === "object") stack.push([child, depth + 1]);
+    } else {
+      for (const key of Object.keys(node)) {
+        if (BANNED_KEYS.has(key)) return `Invalid key "${clip(key, 60)}"`;
+        const child = node[key];
+        if (child !== null && typeof child === "object") stack.push([child, depth + 1]);
+      }
+    }
+  }
+  return null;
+}
+
+const intOrRaw = (value) => (typeof value === "string" && /^-?[0-9]{1,15}$/.test(value) ? Number(value) : value);
+
+export const Q = {
+  str: (value) => value,
+  int: intOrRaw,
+  list: null, // marker: collect every repetition into an array
+};
+
+/**
+ * Builds a decoder. `path` lists path parameter names copied verbatim; `query` maps query names to converters
+ * (Q.list collects repetitions); `body` is "json" or "none"; `idem` reads the Idempotency-Key header.
+ */
+export function decoder({ path = [], query = {}, body = "none", idem = false }) {
+  return (request) => {
+    const args = {};
+    for (const name of path) args[name] = typeof request.path[name] === "string" ? request.path[name] : "";
+    const refuse = (message) => ({ arguments: { ...args, [RESERVED]: clip(message, 300) } });
+
+    for (const [name, convert] of Object.entries(query)) {
+      const values = request.query[name];
+      if (!Array.isArray(values) || values.length === 0) continue;
+      if (values.length > MAX_REPEATS) return refuse(`Query parameter ${name} is repeated more than ${MAX_REPEATS} times`);
+      if (convert === null) args[name] = values.slice();
+      else args[name] = convert(values[values.length - 1]);
+    }
+
+    if (body === "json") {
+      if (request.body.kind === "json") {
+        const value = request.body.value;
+        if (value === null || typeof value !== "object" || Array.isArray(value)) return refuse("Request body must be a JSON object");
+        const problem = shapeProblem(value);
+        if (problem !== null) return refuse(problem);
+        for (const key of Object.keys(value)) {
+          if (key === RESERVED || Object.hasOwn(args, key)) continue;
+          args[key] = value[key];
+        }
+      } else if (request.body.kind === "text" && request.body.value.trim().length > 0) {
+        return refuse("Request body must be JSON");
+      } else if (request.body.kind === "form") {
+        return refuse("Request body must be JSON");
+      }
+    }
+
+    const out = { arguments: args };
+    if (idem) {
+      const keys = request.headers["idempotency-key"];
+      const key = Array.isArray(keys) && keys.length > 0 ? keys[keys.length - 1] : undefined;
+      if (typeof key === "string" && key.length > 0 && key.length <= 255) out.idempotencyKey = key;
+    }
+    return out;
+  };
+}
+
+function envelope(status, message, reason) {
+  return { statusCode: status, message: clip(message, 2000), error: reason };
+}
+
+/** Renders the failure envelope; framework outcomes keep the framework's fixed statuses (400/403/404). */
+export function encodeError({ invocation, outcome }) {
+  const error = outcome.error ?? {};
+  const refusal = invocation?.arguments?.[RESERVED];
+  if (outcome.status === "invalid") {
+    let message = "Required parameters are missing or in the wrong format";
+    if (typeof refusal === "string") message = refusal;
+    else if (Array.isArray(error.issues) && error.issues.length > 0) {
+      const issue = error.issues[0];
+      const where = Array.isArray(issue.path) && issue.path.length > 0 ? clip(issue.path.join("."), 80) : "request";
+      message = `${message}: ${where} ${clip(String(issue.message ?? "is invalid"), 200)}`;
+    }
+    return { body: { kind: "json", value: envelope(400, message, "Bad Request") } };
+  }
+  if (outcome.status === "denied") return { body: { kind: "json", value: envelope(403, "Forbidden", "Forbidden") } };
+  if (outcome.status === "unsupported") return { body: { kind: "json", value: envelope(404, "Not Found", "Not Found") } };
+  const code = String(error.code ?? "").replace(/^tool\./, "");
+  const [status, reason] = ERRORS.get(code) ?? [500, "Internal Server Error"];
+  const message = typeof error.message === "string" && error.message.length > 0 ? error.message : reason;
+  const response = { body: { kind: "json", value: envelope(status, message, reason) } };
+  if (code === "RATE_LIMITED") response.headers = { "retry-after": "1" };
+  return response;
+}
+
+/** Success -> the canonical value verbatim; failure -> the envelope. */
+export const encoder = (result) => (result.outcome.status === "ok" ? { body: { kind: "json", value: result.outcome.value } } : encodeError(result));

package/firedrill/tools/unified/ops/channels.mjs

@@ -0,0 +1,45 @@
+// Messaging channels: read-only list and get. `has_subchannels` is computed from the connection's `parent_id` rows
+// at read time; the internal `alias` field (INBOX/SENT/DRAFT resolution for messages) is never returned.
+import { enumFilter, finishPage, idFilter, matchesQuery, parseFields, parseListParams, project, sortRows, updatedSince } from "../lib/query.mjs";
+import { open, requireId, rowsOf } from "./resource.mjs";
+
+const SPEC = { namespace: "channels", label: "Channel", category: "messaging", permission: "messaging_channel" };
+const HIDDEN = ["alias"];
+
+const parentsOf = (rows) => {
+  const parents = new Set();
+  for (const row of rows) if (typeof row.parent_id === "string") parents.add(row.parent_id);
+  return parents;
+};
+
+const withSubchannels = (row, parents) => ({ ...row, has_subchannels: parents.has(row.id) });
+
+export const channels = {
+  list(input, context) {
+    const { workspace, connection } = open(input, context, SPEC, "read");
+    const params = parseListParams(input, context);
+    const fields = parseFields(input, context);
+    const parentId = idFilter(input, context, "parent_id");
+    const type = enumFilter(input, context, "type", ["PUBLIC", "PRIVATE"]);
+    const all = rowsOf(context, workspace, SPEC, connection.id);
+    const parents = parentsOf(all);
+    const rows = all
+      .filter(
+        (row) =>
+          updatedSince(row, params.updatedGteUs) &&
+          matchesQuery(row, params.query, ["name", "description"]) &&
+          (parentId === null || row.parent_id === parentId) &&
+          (type === null || row.is_private === (type === "PRIVATE")),
+      )
+      .map((row) => withSubchannels(row, parents));
+    sortRows(rows, params.sort, params.order, "name");
+    return finishPage(context, rows, params, fields, HIDDEN);
+  },
+  get(input, context) {
+    const { workspace, connection } = open(input, context, SPEC, "read");
+    const fields = parseFields(input, context);
+    const row = requireId(context, SPEC, connection.id, input.id);
+    const parents = parentsOf(rowsOf(context, workspace, SPEC, connection.id));
+    return project(withSubchannels(row, parents), fields, HIDDEN);
+  },
+};

package/firedrill/tools/unified/ops/connections.mjs

@@ -0,0 +1,151 @@
+// Workspace connections: list with env/categories/external_xref filters, get, create (a synthetic, already-authorised
+// connection), merge update and remove with a cascade over every data namespace of the connection.
+import { badRequest, forbidden, notFound, scanBoundExceeded } from "../lib/errors.mjs";
+import { emitDeleted } from "../lib/events.mjs";
+import { connectionScope, inScope, loadConnection, resolveWorkspace } from "../lib/identity.mjs";
+import { finishPage, parseListParams, project, sortRows, textFilter, updatedSince } from "../lib/query.mjs";
+import { deleteRow, nextId, scanAll, scanBound, scanConnection } from "../lib/store.mjs";
+import { nowIso } from "../lib/time.mjs";
+import { bodyOf, checkValue, enumOf, str, strArray, validateBody } from "../lib/validate.mjs";
+import { CATEGORIES, PERMISSIONS } from "../lib/enums.mjs";
+import { isPlainObject, titleCase } from "../lib/util.mjs";
+
+const ENVIRONMENTS = ["Production", "Sandbox"];
+const DATA_NAMESPACES = { contacts: "crm_contact", companies: "crm_company", deals: "crm_deal", pipelines: null, channels: null, messages: "messaging_message" };
+const AUTH_SPECS = { name: str(256), emails: strArray(8, 320), user_id: str(256) };
+
+const CREATE_SPECS = {
+  integration_type: str(64, { nullable: false, min: 1, pattern: /^[a-z][a-z0-9_-]*$/ }),
+  permissions: strArray(64, 64),
+  categories: strArray(35, 32),
+  external_xref: str(256),
+  environment: enumOf(ENVIRONMENTS),
+  auth: { kind: "auth" },
+  // Read-only members of the Connection schema are accepted and ignored, as the provider ignores them.
+  integration_name: str(256),
+  is_paused: { kind: "ignored" },
+  last_healthy_at: { kind: "ignored" },
+  last_unhealthy_at: { kind: "ignored" },
+  last_unhealthy_code: { kind: "ignored" },
+};
+
+const IGNORED = new Set(["integration_name", "is_paused", "last_healthy_at", "last_unhealthy_at", "last_unhealthy_code"]);
+
+function checkAuth(context, value) {
+  if (value === undefined || value === null) return { name: null, emails: [], user_id: null };
+  if (!isPlainObject(value)) badRequest(context, "Invalid value for auth: must be an object");
+  const out = validateBody(context, value, AUTH_SPECS);
+  for (const email of out.emails ?? []) if (!email.includes("@")) badRequest(context, "Invalid value for auth.emails: entries must be e-mail addresses");
+  return { name: out.name ?? null, emails: out.emails ?? [], user_id: out.user_id ?? null };
+}
+
+function checkEnums(context, fields) {
+  for (const category of fields.categories ?? []) if (!CATEGORIES.includes(category)) badRequest(context, `Invalid value for categories: ${category.slice(0, 60)} is not a supported category`);
+  for (const permission of fields.permissions ?? []) if (!PERMISSIONS.includes(permission)) badRequest(context, `Invalid value for permissions: ${permission.slice(0, 60)} is not a supported permission`);
+}
+
+/** Every permission's category prefix (crm_ -> crm, messaging_ -> messaging) must be one of the connection's categories. */
+function checkPermissionCategories(context, permissions, categories) {
+  for (const permission of permissions) {
+    const category = permission.split("_")[0];
+    if (!categories.includes(category)) badRequest(context, `Permission ${permission} requires the ${category} category`);
+  }
+}
+
+function validateConnectionBody(context, body) {
+  const fields = {};
+  for (const key of Object.keys(body)) {
+    if (["id", "workspace_id", "created_at", "updated_at", "__request_error"].includes(key)) continue;
+    if (!Object.hasOwn(CREATE_SPECS, key)) badRequest(context, `Unknown field "${key.slice(0, 80)}"`);
+    if (IGNORED.has(key)) continue;
+    fields[key] = key === "auth" ? checkAuth(context, body[key]) : checkValue(context, key, CREATE_SPECS[key], body[key]);
+  }
+  checkEnums(context, fields);
+  return fields;
+}
+
+const listFilter = (input, context) => {
+  const env = input.env === undefined || input.env === null ? "Production" : input.env;
+  if (!ENVIRONMENTS.includes(env)) badRequest(context, "env must be Production or Sandbox");
+  const external = textFilter(input, context, "external_xref");
+  let categories = [];
+  if (input.categories !== undefined && input.categories !== null) {
+    const parts = Array.isArray(input.categories) ? input.categories : typeof input.categories === "string" ? [input.categories] : null;
+    if (parts === null) badRequest(context, "categories must be a comma-separated list");
+    for (const part of parts) {
+      if (typeof part !== "string") badRequest(context, "categories must be a comma-separated list");
+      for (const name of part.split(",")) if (name.trim().length > 0) categories.push(name.trim());
+    }
+    if (categories.length > 35) badRequest(context, "categories lists too many values");
+    for (const category of categories) if (!CATEGORIES.includes(category)) badRequest(context, `categories: ${category.slice(0, 60)} is not a supported category`);
+  }
+  return (row) => row.environment === env && (external === null || row.external_xref === external) && categories.every((category) => row.categories.includes(category));
+};
+
+export const connections = {
+  list(input, context) {
+    const workspace = resolveWorkspace(input, context);
+    const params = parseListParams(input, context);
+    const filter = listFilter(input, context);
+    const scope = connectionScope(context);
+    const rows = scanAll(context, "connections", scanBound(workspace)).filter(
+      (row) => row.workspace_id === workspace.id && inScope(scope, row.id) && updatedSince(row, params.updatedGteUs) && filter(row),
+    );
+    sortRows(rows, params.sort, params.order, "integration_name");
+    return finishPage(context, rows, params, null);
+  },
+  get(input, context) {
+    const workspace = resolveWorkspace(input, context);
+    return project(loadConnection(context, workspace, input.id), null);
+  },
+  create(input, context) {
+    const workspace = resolveWorkspace(input, context);
+    if (connectionScope(context) !== null) forbidden(context, "Connection-scoped tokens cannot create connections");
+    const fields = validateConnectionBody(context, bodyOf(input, ["__request_error"]));
+    if (typeof fields.integration_type !== "string") badRequest(context, "integration_type is required");
+    const categories = fields.categories ?? [];
+    if (categories.length === 0) badRequest(context, "categories must list at least one category");
+    const permissions = fields.permissions ?? [];
+    checkPermissionCategories(context, permissions, categories);
+    const existing = scanAll(context, "connections", scanBound(workspace)).filter((row) => row.workspace_id === workspace.id);
+    const bound = scanBound(workspace);
+    if (existing.length >= bound) scanBoundExceeded(context, "connections", bound);
+    const now = nowIso(context);
+    const row = {
+      id: nextId(context), workspace_id: workspace.id, integration_type: fields.integration_type, integration_name: titleCase(fields.integration_type),
+      external_xref: fields.external_xref ?? null, permissions, categories, auth: fields.auth ?? { name: null, emails: [], user_id: null },
+      is_paused: false, environment: fields.environment ?? "Production", last_healthy_at: now, last_unhealthy_at: null, last_unhealthy_code: null,
+      created_at: now, updated_at: now,
+    };
+    context.state.put("connections", row.id, row);
+    return row;
+  },
+  update(input, context) {
+    const workspace = resolveWorkspace(input, context);
+    const existing = loadConnection(context, workspace, input.id);
+    const fields = validateConnectionBody(context, bodyOf(input, ["id", "__request_error"]));
+    const merged = { ...existing };
+    for (const key of ["permissions", "external_xref", "environment", "auth"]) if (Object.hasOwn(fields, key) && fields[key] !== null) merged[key] = fields[key];
+    if (Object.hasOwn(fields, "external_xref") && fields.external_xref === null) merged.external_xref = null;
+    if (Object.hasOwn(fields, "integration_type") || Object.hasOwn(fields, "categories")) badRequest(context, "integration_type and categories cannot be changed after creation");
+    checkPermissionCategories(context, merged.permissions, merged.categories);
+    merged.updated_at = nowIso(context);
+    context.state.put("connections", merged.id, merged);
+    return merged;
+  },
+  remove(input, context) {
+    const workspace = resolveWorkspace(input, context);
+    const existing = loadConnection(context, workspace, input.id);
+    const bound = scanBound(workspace);
+    // Read every namespace first so the cascade either completes or refuses without half-deleting.
+    const cascade = Object.keys(DATA_NAMESPACES).map((namespace) => [namespace, scanConnection(context, namespace, existing.id, bound)]);
+    for (const [namespace, rows] of cascade) {
+      for (const row of rows) {
+        deleteRow(context, namespace, existing.id, row.id);
+        if (DATA_NAMESPACES[namespace] !== null) emitDeleted(context, existing, DATA_NAMESPACES[namespace], row.id);
+      }
+    }
+    context.state.delete("connections", existing.id);
+    return {};
+  },
+};