@secondlayer/shared 11.20.0 → 11.21.0

package/dist/src/archive/range-digest.d.ts

@@ -847,6 +847,8 @@ interface Database {
 	sentinel_accounts: SentinelAccountsTable;
 	waitlists: WaitlistsTable;
 	waitlist_signups: WaitlistSignupsTable;
+	api_failed_requests: ApiFailedRequestsTable;
+	feedback_tickets: FeedbackTicketsTable;
 }
 interface ServiceHeartbeatsTable {
 	name: string;
@@ -1055,6 +1057,43 @@ interface WaitlistSignupsTable {
 	created_at: Generated<Date>;
 }
 /**
+* 24h hosted record of a failed API request, keyed by `request_id` and
+* scoped to the account that made it. `query` is redacted before insert.
+*/
+interface ApiFailedRequestsTable {
+	request_id: string;
+	account_id: string;
+	method: string;
+	path: string;
+	status: number;
+	code: string;
+	message: Generated<string>;
+	query: Record<string, unknown>;
+	origin: string | null;
+	created_at: Generated<Date>;
+}
+/**
+* Hosted problem report. `attempted` is the server's own copy of the failed
+* request (never caller-supplied); `status` starts `new` until classified.
+*/
+interface FeedbackTicketsTable {
+	id: Generated<string>;
+	account_id: string;
+	idempotency_key: string | null;
+	request_id: string | null;
+	intent: string;
+	expected: Record<string, unknown> | null;
+	kind_hint: string | null;
+	evidence: Record<string, unknown> | null;
+	attempted: Record<string, unknown> | null;
+	origin: string;
+	status: Generated<"new" | "classified">;
+	route: string | null;
+	classification: Record<string, unknown> | null;
+	classified_at: Date | null;
+	created_at: Generated<Date>;
+}
+/**
 * Cheap, SQL-computed digests over a height range — the basis of a verify that
 * runs in seconds instead of hours.
 *

package/dist/src/archive/semantic-digest-builder.d.ts

@@ -847,6 +847,8 @@ interface Database {
 	sentinel_accounts: SentinelAccountsTable;
 	waitlists: WaitlistsTable;
 	waitlist_signups: WaitlistSignupsTable;
+	api_failed_requests: ApiFailedRequestsTable;
+	feedback_tickets: FeedbackTicketsTable;
 }
 interface ServiceHeartbeatsTable {
 	name: string;
@@ -1055,6 +1057,43 @@ interface WaitlistSignupsTable {
 	created_at: Generated<Date>;
 }
 /**
+* 24h hosted record of a failed API request, keyed by `request_id` and
+* scoped to the account that made it. `query` is redacted before insert.
+*/
+interface ApiFailedRequestsTable {
+	request_id: string;
+	account_id: string;
+	method: string;
+	path: string;
+	status: number;
+	code: string;
+	message: Generated<string>;
+	query: Record<string, unknown>;
+	origin: string | null;
+	created_at: Generated<Date>;
+}
+/**
+* Hosted problem report. `attempted` is the server's own copy of the failed
+* request (never caller-supplied); `status` starts `new` until classified.
+*/
+interface FeedbackTicketsTable {
+	id: Generated<string>;
+	account_id: string;
+	idempotency_key: string | null;
+	request_id: string | null;
+	intent: string;
+	expected: Record<string, unknown> | null;
+	kind_hint: string | null;
+	evidence: Record<string, unknown> | null;
+	attempted: Record<string, unknown> | null;
+	origin: string;
+	status: Generated<"new" | "classified">;
+	route: string | null;
+	classification: Record<string, unknown> | null;
+	classified_at: Date | null;
+	created_at: Generated<Date>;
+}
+/**
 * v1 canonical byte encoding for chain identity — the shape that lets
 * independently-run runtimes agree on the same block.
 *

package/dist/src/classify/index.d.ts

@@ -0,0 +1,83 @@
+type ClassifierName = "jev" | "kev" | "clef" | "rules";
+type Question = {
+	type: "choice"
+	instructions: string
+	criteria: Record<string, string>
+} | {
+	type: "score"
+	instructions: string
+	criteria: readonly string[]
+} | {
+	type: "boolean"
+	instructions: string
+	criteria: {
+		true: string
+		false: string
+	}
+};
+type Answer = {
+	type: "choice"
+	choice: string
+	probabilities: Record<string, number>
+	confidence: number
+} | {
+	type: "score"
+	score: number
+	probabilities: Record<string, number>
+	confidence: number
+} | {
+	type: "boolean"
+	probability: number
+	confidence: number
+} | {
+	type: "refusal"
+};
+type Answers<Q extends Record<string, Question>> = { [K in keyof Q] : Answer };
+type ClassifyResult<Q extends Record<string, Question>> = {
+	provider: ClassifierName
+	/** response.modelId when the backend reports one. */
+	modelId: string
+	answers: Answers<Q>
+};
+/** Deterministic answers for the offline provider. Return a value per question
+*  it can decide; omitted questions come back as `{ type: "refusal" }`. */
+type RuleValue = string | number | boolean;
+type RulesFn<Q extends Record<string, Question>> = (state: string | Record<string, unknown>) => { [K in keyof Q]? : RuleValue } | null;
+declare class ClassifierInputError extends Error {
+	constructor(message: string);
+}
+/**
+* One classifier call over jev, kev, clef or offline rules.
+* Returns null on any provider failure (fail-open: callers decide what null
+* means). Only ClassifierInputError, a bad question definition, escapes.
+* Never logs state or response bodies.
+*/
+declare function classify<const Q extends Record<string, Question>>(input: {
+	state: string | Record<string, unknown>
+	questions: Q
+	rules?: RulesFn<Q>
+	/** Overrides resolveProvider(); used by classifier-compare. */
+	provider?: ClassifierName
+	/** Overrides CLASSIFIER_MODEL / the provider default. */
+	modelId?: string
+	/** Default 5000. */
+	timeoutMs?: number
+	env?: Record<string, string | undefined>
+	/** Tests only (kev/clef). */
+	fetchImpl?: typeof fetch
+}): Promise<ClassifyResult<Q> | null>;
+type Env = Record<string, string | undefined>;
+/** CLASSIFIER picks the backend; unset means jev when the gateway key is set,
+*  else offline rules. A backend missing credentials falls back to rules. */
+declare function resolveProvider(env?: Env): {
+	name: ClassifierName
+	modelId: string
+};
+/** (p_max - 1/K) / (1 - 1/K). One option gives 1. */
+declare function choiceConfidence(probabilities: Record<string, number>): number;
+/** max(0, 1 - E|level - mode| / D); D = mean distance of a uniform
+*  distribution over the levels from the middle level. */
+declare function scoreConfidence(probabilities: Record<string, number>, levels: number): number;
+/** Host-defined: |2p - 1|. Not comparable with choice/score confidence. */
+declare function booleanConfidence(p: number): number;
+export { Answer, Answers, ClassifierInputError, ClassifierName, ClassifyResult, Question, RuleValue, RulesFn, booleanConfidence, choiceConfidence, classify, resolveProvider, scoreConfidence };

package/dist/src/classify/index.js

@@ -0,0 +1,464 @@
+// src/env.ts
+import { z } from "zod";
+var networksSchema = z.string().transform((val) => {
+  const networks = val.split(",").map((n) => n.trim()).filter(Boolean);
+  const valid = ["mainnet", "testnet"];
+  for (const n of networks) {
+    if (!valid.includes(n)) {
+      throw new Error(`Invalid network: ${n}. Must be one of: ${valid.join(", ")}`);
+    }
+  }
+  return networks;
+});
+var envSchema = z.object({
+  DATABASE_URL: z.preprocess((val) => typeof val === "string" && val.length === 0 ? undefined : val, z.string().url().optional()),
+  SOURCE_DATABASE_URL: z.preprocess((val) => typeof val === "string" && val.length === 0 ? undefined : val, z.string().url().optional()),
+  TARGET_DATABASE_URL: z.preprocess((val) => typeof val === "string" && val.length === 0 ? undefined : val, z.string().url().optional()),
+  NETWORK: z.enum(["mainnet", "testnet"]).optional(),
+  NETWORKS: networksSchema.optional(),
+  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development")
+});
+var cachedEnv = null;
+function getEnv() {
+  if (cachedEnv) {
+    return cachedEnv;
+  }
+  const result = envSchema.safeParse(process.env);
+  if (!result.success) {
+    console.error("❌ Invalid environment configuration:");
+    console.error(z.treeifyError(result.error));
+    throw new Error("Invalid environment configuration");
+  }
+  let enabledNetworks;
+  if (result.data.NETWORKS && result.data.NETWORKS.length > 0) {
+    enabledNetworks = result.data.NETWORKS;
+  } else if (result.data.NETWORK) {
+    enabledNetworks = [result.data.NETWORK];
+  } else {
+    enabledNetworks = ["mainnet"];
+  }
+  cachedEnv = { ...result.data, enabledNetworks };
+  return cachedEnv;
+}
+function isProductionEnv() {
+  return process.env["NODE_ENV"] === "production";
+}
+function isPox4DecoderEnabled(env = process.env) {
+  return env.POX4_DECODER_ENABLED !== "false";
+}
+function isPox5DecoderEnabled(env = process.env) {
+  return env.POX5_DECODER_ENABLED !== "false";
+}
+function isSbtcDecoderEnabled(env = process.env) {
+  return env.SBTC_DECODER_ENABLED !== "false";
+}
+function isBnsDecoderEnabled(env = process.env) {
+  return env.BNS_DECODER_ENABLED === "true";
+}
+// src/logger.ts
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+
+class Logger {
+  _level;
+  _isProduction;
+  _initialized = false;
+  init() {
+    if (this._initialized)
+      return;
+    this._initialized = true;
+    try {
+      const env = getEnv();
+      this._level = env.LOG_LEVEL;
+      this._isProduction = env.NODE_ENV === "production";
+    } catch {
+      this._level = "info";
+      this._isProduction = false;
+    }
+  }
+  get level() {
+    this.init();
+    return this._level;
+  }
+  get isProduction() {
+    this.init();
+    return this._isProduction;
+  }
+  shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+  }
+  formatMessage(level, message, meta) {
+    const timestamp = new Date().toISOString();
+    if (this.isProduction) {
+      return JSON.stringify({
+        timestamp,
+        level,
+        message,
+        ...meta
+      });
+    }
+    const metaStr = meta ? ` ${JSON.stringify(meta)}` : "";
+    return `[${timestamp}] ${level.toUpperCase()}: ${message}${metaStr}`;
+  }
+  debug(message, meta) {
+    if (this.shouldLog("debug")) {
+      console.debug(this.formatMessage("debug", message, meta));
+    }
+  }
+  info(message, meta) {
+    if (this.shouldLog("info")) {
+      console.info(this.formatMessage("info", message, meta));
+    }
+  }
+  warn(message, meta) {
+    if (this.shouldLog("warn")) {
+      console.warn(this.formatMessage("warn", message, meta));
+    }
+  }
+  error(message, meta) {
+    if (this.shouldLog("error")) {
+      console.error(this.formatMessage("error", message, meta));
+    }
+  }
+}
+var logger = new Logger;
+
+// src/classify/confidence.ts
+var clamp01 = (n) => Math.min(1, Math.max(0, n));
+function choiceConfidence(probabilities) {
+  const ps = Object.values(probabilities);
+  const k = ps.length;
+  if (k <= 1)
+    return 1;
+  const pmax = Math.max(...ps);
+  return clamp01((pmax - 1 / k) / (1 - 1 / k));
+}
+function scoreConfidence(probabilities, levels) {
+  if (levels <= 1)
+    return 1;
+  let mode = 0;
+  let best = -1;
+  for (let i = 0;i < levels; i++) {
+    const p = probabilities[String(i)] ?? 0;
+    if (p > best) {
+      best = p;
+      mode = i;
+    }
+  }
+  let e = 0;
+  let d = 0;
+  for (let i = 0;i < levels; i++) {
+    e += (probabilities[String(i)] ?? 0) * Math.abs(i - mode);
+    d += Math.abs(i - (levels - 1) / 2);
+  }
+  d /= levels;
+  return clamp01(1 - e / d);
+}
+function booleanConfidence(p) {
+  return Math.abs(2 * p - 1);
+}
+function normalizeAnswer(question, raw) {
+  if (raw.type === "refusal")
+    return { type: "refusal" };
+  if (raw.type === "boolean" && question.type === "boolean") {
+    return {
+      type: "boolean",
+      probability: raw.probability,
+      confidence: booleanConfidence(raw.probability)
+    };
+  }
+  if (raw.type === "choice" && question.type === "choice") {
+    const probabilities = raw.probabilities ?? {};
+    return {
+      type: "choice",
+      choice: raw.choice,
+      probabilities,
+      confidence: raw.probabilities ? choiceConfidence(probabilities) : 0
+    };
+  }
+  if (raw.type === "score" && question.type === "score") {
+    const probabilities = raw.probabilities ?? {};
+    return {
+      type: "score",
+      score: raw.score,
+      probabilities,
+      confidence: raw.probabilities ? scoreConfidence(probabilities, question.criteria.length) : 0
+    };
+  }
+  return { type: "refusal" };
+}
+
+// src/classify/types.ts
+class ClassifierInputError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ClassifierInputError";
+  }
+}
+
+// src/classify/limits.ts
+var MAX_QUESTIONS = 64;
+var MIN_CHOICE = 2;
+var MAX_CHOICE = 255;
+var MIN_SCORE = 2;
+var MAX_SCORE = 10;
+var QUESTION_ID = /^[A-Za-z0-9_.-]{1,100}$/;
+var MAX_STATE_CHARS = 24000;
+function validateQuestions(questions) {
+  const ids = Object.keys(questions);
+  if (ids.length === 0)
+    throw new ClassifierInputError("no questions");
+  if (ids.length > MAX_QUESTIONS) {
+    throw new ClassifierInputError(`more than ${MAX_QUESTIONS} questions`);
+  }
+  for (const id of ids) {
+    if (!QUESTION_ID.test(id)) {
+      throw new ClassifierInputError(`invalid question id: ${id}`);
+    }
+    const q = questions[id];
+    if (q.type === "choice") {
+      const n = Object.keys(q.criteria).length;
+      if (n < MIN_CHOICE || n > MAX_CHOICE) {
+        throw new ClassifierInputError(`question ${id}: choice needs ${MIN_CHOICE}-${MAX_CHOICE} options`);
+      }
+    } else if (q.type === "score") {
+      const n = q.criteria.length;
+      if (n < MIN_SCORE || n > MAX_SCORE) {
+        throw new ClassifierInputError(`question ${id}: score needs ${MIN_SCORE}-${MAX_SCORE} levels`);
+      }
+    } else if (q.type !== "boolean") {
+      throw new ClassifierInputError(`question ${id}: unknown type`);
+    }
+  }
+}
+function stateSize(state) {
+  return typeof state === "string" ? state.length : JSON.stringify(state).length;
+}
+
+// src/classify/system-one.ts
+function toWireState(state) {
+  const parts = state.map((p) => {
+    if (p.type === "text")
+      return p.text;
+    if (p.type === "json")
+      return p.value;
+    throw new Error("file state unsupported");
+  });
+  return parts.length === 1 ? parts[0] : parts;
+}
+function renormalize(p) {
+  const sum = Object.values(p).reduce((a, b) => a + b, 0);
+  if (!(sum > 0))
+    return p;
+  return Object.fromEntries(Object.entries(p).map(([k, v]) => [k, v / sum]));
+}
+function mapAnswer(a) {
+  if (a.type === "noul" && typeof a.noul === "number") {
+    return { type: "boolean", probability: a.noul };
+  }
+  if (a.type === "choice" && typeof a.choice === "string") {
+    return {
+      type: "choice",
+      choice: a.choice,
+      ...a.probabilities && { probabilities: renormalize(a.probabilities) }
+    };
+  }
+  if (a.type === "score" && typeof a.score === "number") {
+    if (!a.probabilities)
+      return { type: "score", score: a.score };
+    const probabilities = renormalize(a.probabilities);
+    const score = Object.entries(probabilities).reduce((s, [level, p]) => s + Number(level) * p, 0);
+    return { type: "score", score, probabilities };
+  }
+  return { type: "refusal" };
+}
+function systemOneModel(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  return {
+    specificationVersion: "v4",
+    provider: `secondlayer.${opts.provider}`,
+    modelId: opts.modelId,
+    supportedQuestionTypes: ["choice", "score", "boolean"],
+    async doDecide({ state, questions, abortSignal }) {
+      const wireQuestions = Object.fromEntries(Object.entries(questions).map(([id, q]) => [
+        id,
+        q.type === "boolean" ? { ...q, type: "noul" } : q
+      ]));
+      const res = await doFetch(opts.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...opts.apiKey && { authorization: `Bearer ${opts.apiKey}` }
+        },
+        body: JSON.stringify({
+          model: opts.modelId,
+          state: toWireState(state),
+          questions: wireQuestions
+        }),
+        signal: abortSignal
+      });
+      if (!res.ok)
+        throw new Error(`${opts.provider} ${res.status}`);
+      const json = await res.json();
+      const body = json.result ?? json;
+      const answers = Object.fromEntries(Object.entries(body.answers ?? {}).map(([id, a]) => [id, mapAnswer(a)]));
+      return {
+        answers,
+        warnings: [],
+        usage: {
+          inputTokens: body.usage?.input_tokens,
+          outputTokens: body.usage?.output_tokens
+        },
+        response: { modelId: body.model ?? opts.modelId }
+      };
+    }
+  };
+}
+
+// src/classify/providers.ts
+var DEFAULT_MODEL = {
+  jev: "typesafe-ai/jev",
+  kev: "kev-latest",
+  clef: "clef"
+};
+var REQUIRED_ENV = {
+  jev: ["AI_GATEWAY_API_KEY"],
+  kev: ["KEV_URL"],
+  clef: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"]
+};
+var envModel = (env) => env.CLASSIFIER_MODEL?.trim() || undefined;
+function resolveProvider(env = process.env) {
+  const rules = { name: "rules", modelId: "rules" };
+  const requested = env.CLASSIFIER?.trim();
+  let name;
+  if (!requested) {
+    name = env.AI_GATEWAY_API_KEY ? "jev" : "rules";
+  } else if (requested === "jev" || requested === "kev" || requested === "clef" || requested === "rules") {
+    name = requested;
+  } else {
+    logger.warn(`classifier: unknown CLASSIFIER=${requested}; using rules`);
+    return rules;
+  }
+  if (name === "rules")
+    return rules;
+  const missing = REQUIRED_ENV[name].find((v) => !env[v]);
+  if (missing) {
+    logger.warn(`classifier: CLASSIFIER=${name} missing ${missing}; using rules`);
+    return rules;
+  }
+  return { name, modelId: envModel(env) ?? DEFAULT_MODEL[name] };
+}
+function buildModel(name, modelId, env = process.env, fetchImpl) {
+  if (name === "jev")
+    return modelId;
+  if (name === "kev") {
+    return systemOneModel({
+      provider: "kev",
+      url: `${(env.KEV_URL ?? "").replace(/\/$/, "")}/v1/systemone`,
+      modelId,
+      apiKey: env.KEV_API_KEY,
+      fetchImpl
+    });
+  }
+  return systemOneModel({
+    provider: "clef",
+    url: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/run/@cf/cloudflare/${modelId}`,
+    modelId,
+    apiKey: env.CLOUDFLARE_API_TOKEN,
+    fetchImpl
+  });
+}
+
+// src/classify/rules.ts
+function answerFor(question, value) {
+  if (value === undefined)
+    return { type: "refusal" };
+  if (question.type === "choice") {
+    if (typeof value !== "string" || !(value in question.criteria)) {
+      return { type: "refusal" };
+    }
+    const probabilities = Object.fromEntries(Object.keys(question.criteria).map((k) => [k, k === value ? 1 : 0]));
+    return { type: "choice", choice: value, probabilities, confidence: 1 };
+  }
+  if (question.type === "score") {
+    const n = question.criteria.length;
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+      return { type: "refusal" };
+    }
+    if (value < 0 || value >= n)
+      return { type: "refusal" };
+    const probabilities = Object.fromEntries(Array.from({ length: n }, (_, i) => [String(i), i === value ? 1 : 0]));
+    return { type: "score", score: value, probabilities, confidence: 1 };
+  }
+  if (typeof value !== "boolean")
+    return { type: "refusal" };
+  return { type: "boolean", probability: value ? 1 : 0, confidence: 1 };
+}
+function runRules(questions, fn, state) {
+  const values = fn(state) ?? {};
+  const out = {};
+  for (const id of Object.keys(questions)) {
+    out[id] = answerFor(questions[id], values[id]);
+  }
+  return out;
+}
+
+// src/classify/classify.ts
+async function classify(input) {
+  validateQuestions(input.questions);
+  const env = input.env ?? process.env;
+  const resolved = resolveProvider(env);
+  const name = input.provider ?? resolved.name;
+  if (name === "rules") {
+    if (!input.rules)
+      return null;
+    return {
+      provider: "rules",
+      modelId: "rules",
+      answers: runRules(input.questions, input.rules, input.state)
+    };
+  }
+  const modelId = input.modelId ?? (input.provider ? undefined : envModel(env)) ?? DEFAULT_MODEL[name];
+  if (stateSize(input.state) > MAX_STATE_CHARS) {
+    logger.warn(`classifier: state over ${MAX_STATE_CHARS} chars; skipped`);
+    return null;
+  }
+  try {
+    const { experimental_decide: decide } = await import("ai");
+    const r = await decide({
+      model: buildModel(name, modelId, env, input.fetchImpl),
+      state: input.state,
+      questions: input.questions,
+      maxRetries: 1,
+      abortSignal: AbortSignal.timeout(input.timeoutMs ?? 5000)
+    });
+    const answers = {};
+    for (const id of Object.keys(input.questions)) {
+      answers[id] = normalizeAnswer(input.questions[id], r.answers[id] ?? { type: "refusal" });
+    }
+    return {
+      provider: name,
+      modelId: r.response.modelId ?? modelId,
+      answers
+    };
+  } catch (err) {
+    logger.warn(`classifier: ${name} failed: ${err instanceof Error ? err.name : "error"}`);
+    return null;
+  }
+}
+export {
+  ClassifierInputError,
+  booleanConfidence,
+  choiceConfidence,
+  classify,
+  resolveProvider,
+  scoreConfidence
+};
+
+//# debugId=6AA8B48DE6A7F1DB64756E2164756E21
+//# sourceMappingURL=index.js.map