@kindgi/bounds 0.0.0-stage → 0.1.8

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@kindgi/bounds",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.8",
+  "description": "The limits a Kindgi server puts on what a tenant sends it: pattern length and engine (V8, or linear-time RE2 when hosted), schema size and depth, template limits, and the size and idle time of bodies read from tenant-named endpoints. Set once at boot; read by the packages that compile or read tenant input.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/bounds"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/bounds#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "re2js": "^2.8.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }

package/src/bounds.ts

@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * The limits a Kindgi server puts on what a tenant sends it: one setting
+ * for the whole process, set once at boot (`configureTenantInputBounds`)
+ * and read where tenant input is compiled or read (`tenantInputBounds`).
+ *
+ * The runtime sets {@link HOSTED_BOUNDS} under the hosted profile, where
+ * one tenant's input must never stall the server for the others. Anywhere
+ * else (a self-hosted server, a pack's own process, a test) it's
+ * {@link SELF_HOSTED_BOUNDS}: today's behaviour, with generous limits on
+ * bodies, schemas and a render's memory.
+ *
+ * Why one setting rather than an argument: the places that compile tenant
+ * input are deep inside the SDK's packages (guardrails, schema, agents,
+ * flow, tools). One explicit call at boot is testable, and a second call
+ * throwing keeps it from changing while the server runs. Why not the
+ * environment: a library that reads `process.env` behaves differently in a
+ * test than in the server.
+ */
+export interface TenantInputBounds {
+  /**
+   * The engine a tenant's pattern runs on: V8's, or RE2's, which runs in
+   * linear time. On RE2, a tenant's JSON Schema checks its data in linear
+   * time too (`@kindgi/schema`): its patterns run on RE2, its formats are
+   * ajv-formats' `fast` ones, and `uniqueItems` compares items by a key.
+   */
+  readonly regex: 'v8' | 're2';
+  /** The longest a tenant's pattern may be: its source plus its flags, in characters. */
+  readonly patternMaxLength: number;
+  /**
+   * The most citations a `must-cite` guardrail may require (`minCitations`).
+   * It counts matches up to that many, and on RE2 each match can read the
+   * rest of the output, so this caps what one evaluation costs.
+   */
+  readonly mustCiteMaxCitations: number;
+  /** The largest schema compiled: its JSON, in bytes, before it's compiled. */
+  readonly schemaMaxBytes: number;
+  /** The deepest a schema may nest, objects and arrays. */
+  readonly schemaMaxDepth: number;
+  /** Compiled schemas kept, by their JSON, the least recently used dropped first. */
+  readonly schemaCacheEntries: number;
+  /**
+   * The most schema JSON those compiled schemas may add up to, in bytes: a
+   * compiled schema takes 4 to 15 times its JSON in memory for real API
+   * schemas, and up to about 20 times for the worst shapes measured.
+   */
+  readonly schemaCacheMaxBytes: number;
+  /**
+   * The time a tenant's schemas may spend compiling in any 60 seconds, in
+   * milliseconds: the compiles that count (`runAsTenant` says whose work
+   * it is, and which count). Past it, the tenant's next compile that
+   * counts is refused until the window moves on; schemas already compiled
+   * keep working.
+   */
+  readonly schemaCompileBudgetMs: number;
+  /**
+   * The time a tenant's templates may spend rendering in any 60 seconds,
+   * in milliseconds, for renders done as its work (`runAsTenant`). Past it,
+   * the tenant's next render is refused until the window moves on. A
+   * render holds the event loop while it runs.
+   */
+  readonly templateRenderBudgetMs: number;
+  /** A template's limits (liquidjs's own). */
+  readonly liquid: {
+    /** The longest template parsed, in characters. */
+    readonly parseLimit: number;
+    /** The longest one render may take, in milliseconds. */
+    readonly renderLimitMs: number;
+    /**
+     * The most one render may allocate, in liquidjs's own units (roughly
+     * characters of strings and arrays it builds), not bytes: 8,388,608 is
+     * not 8 MiB, and isn't meant to be.
+     */
+    readonly memoryLimit: number;
+  };
+  /** The largest body read from a tenant-named endpoint, decompressed, in bytes. */
+  readonly responseMaxBytes: number;
+  /** The longest wait between two chunks of such a body, in milliseconds. */
+  readonly responseIdleMs: number;
+  /** The largest one event of a `text/event-stream` may be; the stream itself has no total. */
+  readonly sseEventMaxBytes: number;
+  /** The largest request body the API reads, in bytes (routes that take more set their own). */
+  readonly requestMaxBytes: number;
+  /**
+   * The deepest a request's JSON may nest, in levels of objects and arrays,
+   * the body's own being 1. It leaves room for a schema as deep as
+   * `schemaMaxDepth` inside the body that carries it.
+   */
+  readonly requestJsonMaxDepth: number;
+}
+
+const KiB = 1024;
+const MiB = 1024 * KiB;
+
+/*
+ * The numbers: fitted to limits the code already enforces (a pack
+ * service's body and an HTTP tool's response 10 MiB, a webhook body
+ * 256 KiB, MCP sign-in 64 KiB), until hosted usage tunes them. The
+ * compile cache's bytes and the compile budget are measured: a 256 KiB
+ * schema compiles to 4–5 MiB of heap in up to 0.75 s, and a 100 KiB one
+ * derived from a public OpenAPI document in 0.1–0.2 s.
+ */
+
+/**
+ * Anywhere but the hosted profile: today's behaviour. A pattern on V8's
+ * engine, a template's length and render time, and idle time without
+ * limits; caps where today has none that a self-hoster could still hurt
+ * itself without (bodies, schemas, the compile cache, a render's memory).
+ */
+export const SELF_HOSTED_BOUNDS: TenantInputBounds = deepFreeze({
+  regex: 'v8',
+  patternMaxLength: 8_192,
+  mustCiteMaxCitations: Number.POSITIVE_INFINITY,
+  schemaMaxBytes: 1 * MiB,
+  schemaMaxDepth: 64,
+  schemaCacheEntries: 1_000,
+  schemaCacheMaxBytes: Number.POSITIVE_INFINITY,
+  schemaCompileBudgetMs: Number.POSITIVE_INFINITY,
+  templateRenderBudgetMs: Number.POSITIVE_INFINITY,
+  liquid: {
+    parseLimit: Number.POSITIVE_INFINITY,
+    renderLimitMs: Number.POSITIVE_INFINITY,
+    memoryLimit: 16_777_216,
+  },
+  responseMaxBytes: 10 * MiB,
+  responseIdleMs: Number.POSITIVE_INFINITY,
+  sseEventMaxBytes: 10 * MiB,
+  requestMaxBytes: 10 * MiB,
+  requestJsonMaxDepth: 128,
+});
+
+/** The hosted profile: patterns on RE2 (linear time), and tight limits. */
+export const HOSTED_BOUNDS: TenantInputBounds = deepFreeze({
+  regex: 're2',
+  patternMaxLength: 1_024,
+  mustCiteMaxCitations: 100,
+  schemaMaxBytes: 256 * KiB,
+  schemaMaxDepth: 64,
+  schemaCacheEntries: 512,
+  schemaCacheMaxBytes: 8 * MiB,
+  schemaCompileBudgetMs: 2_000,
+  templateRenderBudgetMs: 5_000,
+  liquid: {
+    parseLimit: 262_144,
+    renderLimitMs: 1_000,
+    memoryLimit: 8_388_608,
+  },
+  responseMaxBytes: 10 * MiB,
+  responseIdleMs: 60_000,
+  sseEventMaxBytes: 10 * MiB,
+  requestMaxBytes: 2 * MiB,
+  requestJsonMaxDepth: 128,
+});
+
+let configured: TenantInputBounds | undefined;
+
+/**
+ * Sets the process's bounds, once, at boot. A second call throws: they
+ * never change while the server runs.
+ */
+export function configureTenantInputBounds(bounds: TenantInputBounds): void {
+  if (configured !== undefined) {
+    throw new Error('Tenant input bounds are already set: they are set once, at boot.');
+  }
+  configured = deepFreeze(structuredClone(bounds));
+}
+
+/** The process's bounds: what boot set, or {@link SELF_HOSTED_BOUNDS}. */
+export function tenantInputBounds(): TenantInputBounds {
+  return configured ?? SELF_HOSTED_BOUNDS;
+}
+
+/**
+ * For tests (`@kindgi/bounds/testing`): runs with other bounds, and puts
+ * back what was set.
+ */
+export function overrideTenantInputBounds(bounds: TenantInputBounds): () => void {
+  const before = configured;
+  configured = deepFreeze(structuredClone(bounds));
+  return () => {
+    configured = before;
+  };
+}
+
+function deepFreeze<T extends object>(value: T): T {
+  for (const inner of Object.values(value)) {
+    if (inner !== null && typeof inner === 'object') deepFreeze(inner);
+  }
+  return Object.freeze(value);
+}

package/src/budget.ts

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Budgets kept per tenant: the time a tenant's work of one kind (its
+ * schema compiles, its template renders) takes in any 60 seconds. That
+ * work holds the event loop while it runs, so a tenant past its budget
+ * waits instead of the others: its next piece of that work is refused
+ * until the window moves on, and may be retried then. The budget doesn't
+ * stop a piece it let start, so a tenant's minute can run past the budget
+ * by one piece.
+ */
+
+/** The window a budget kept per tenant counts over, in milliseconds. */
+export const BUDGET_WINDOW_MS = 60_000;
+
+/** Which budget refused: what the API's refusal names in `details.limit`. */
+export type TenantBudgetLimit = 'schema-compile-time' | 'template-render-time';
+
+/**
+ * A tenant's work refused: it spent its budget of `budgetMs` (`limit`) in
+ * the last 60 seconds, and is under it again after `retryAfterMs`. Every
+ * budget's refusal is one of these, so what answers for one (the API, an
+ * agent's turn, a run's step) answers for them all.
+ */
+export class TenantBudgetError extends Error {
+  constructor(
+    message: string,
+    readonly limit: TenantBudgetLimit,
+    readonly budgetMs: number,
+    readonly retryAfterMs: number,
+  ) {
+    super(message);
+    this.name = 'TenantBudgetError';
+  }
+}
+
+/** Where a budget reads the time. */
+export interface BudgetClock {
+  /** The wall time, in milliseconds: where a piece of work sits in the window. */
+  now(): number;
+  /** A monotonic time, in milliseconds: how long a piece of work took. */
+  monotonic(): number;
+}
+
+/** The system's clock, read when asked: `Date.now` and `performance.now`. */
+export const SYSTEM_CLOCK: BudgetClock = {
+  now: () => Date.now(),
+  monotonic: () => performance.now(),
+};
+
+interface Spent {
+  /** When the piece of work started, by the wall clock. */
+  readonly at: number;
+  /** How long it took, in whole microseconds. */
+  readonly us: number;
+}
+
+/**
+ * One tenant's work in the window: its pieces in the order they started,
+ * from `head` on, and their total. Whole microseconds, so adding pieces
+ * and dropping them never drifts from what they add up to.
+ */
+interface Ledger {
+  pieces: Spent[];
+  head: number;
+  spentUs: number;
+  /**
+   * Once refused: when the tenant is under its budget again. Read only
+   * while it's over the budget; a piece charged clears it.
+   */
+  refusedUntil: number;
+}
+
+/**
+ * The time each tenant spent on one kind of work in the last 60 seconds,
+ * against `budgetMs`; `refuse` makes the error for a tenant past it. An
+ * infinite budget keeps no count. Charging a piece costs the same however
+ * many pieces the window holds.
+ */
+export class TenantTimeBudget {
+  private readonly ledgers = new Map<string, Ledger>();
+  private readonly budgetUs: number;
+  private sweptAt = 0;
+
+  constructor(
+    private readonly budgetMs: number,
+    private readonly refuse: (budgetMs: number, retryAfterMs: number) => TenantBudgetError,
+    private readonly clock: BudgetClock = SYSTEM_CLOCK,
+  ) {
+    this.budgetUs = budgetMs * 1_000;
+  }
+
+  /**
+   * Runs `work` as `tenant`'s, and returns what it returns: refused with
+   * `refuse`'s error, before it starts, once the tenant has spent its
+   * budget. Its time is charged, a failed piece's too.
+   */
+  charge<T>(tenant: string, work: () => T): T {
+    if (this.budgetMs === Number.POSITIVE_INFINITY) return work();
+    const now = this.clock.now();
+    this.sweep(now);
+    this.check(tenant, now);
+    const started = this.clock.monotonic();
+    try {
+      return work();
+    } finally {
+      this.spend(tenant, now, this.clock.monotonic() - started);
+    }
+  }
+
+  /** Once a window: drops the work that left it, and the tenants with none left. */
+  private sweep(now: number): void {
+    if (now - this.sweptAt <= BUDGET_WINDOW_MS) return;
+    this.sweptAt = now;
+    for (const [tenant, ledger] of this.ledgers) {
+      if (this.inWindow(ledger, now) === 0) this.ledgers.delete(tenant);
+    }
+  }
+
+  /** Throws `refuse`'s error when `tenant` has spent its budget. */
+  private check(tenant: string, now: number): void {
+    const ledger = this.ledgerOf(tenant);
+    this.inWindow(ledger, now);
+    if (ledger.spentUs < this.budgetUs) return;
+    // Read after the count, so a wall clock set back never refuses a tenant under its budget.
+    if (now < ledger.refusedUntil) throw this.refuse(this.budgetMs, ledger.refusedUntil - now);
+    // Under the budget again once enough of the oldest work leaves the window.
+    let left = ledger.spentUs;
+    let under = now;
+    for (let i = ledger.head; i < ledger.pieces.length; i += 1) {
+      const spent = ledger.pieces[i] as Spent;
+      left -= spent.us;
+      under = spent.at + BUDGET_WINDOW_MS;
+      if (left < this.budgetUs) break;
+    }
+    // It holds until a piece is charged: what the tenant starts now is refused.
+    ledger.refusedUntil = under;
+    throw this.refuse(this.budgetMs, under - now);
+  }
+
+  /** Charges `tenant` for work started `at` that took `ms`. */
+  private spend(tenant: string, at: number, ms: number): void {
+    const ledger = this.ledgerOf(tenant);
+    const us = Math.round(ms * 1_000);
+    ledger.spentUs += us;
+    // A piece that started before a refusal can end after it, and move the wait.
+    ledger.refusedUntil = 0;
+    // Work ends in the order it started, but for a piece inside another one.
+    let i = ledger.pieces.length;
+    while (i > ledger.head && (ledger.pieces[i - 1] as Spent).at > at) i -= 1;
+    ledger.pieces.splice(i, 0, { at, us });
+  }
+
+  /** Drops `ledger`'s work that left the window ending `now`; returns how many pieces are left. */
+  private inWindow(ledger: Ledger, now: number): number {
+    const { pieces } = ledger;
+    while (
+      ledger.head < pieces.length &&
+      (pieces[ledger.head] as Spent).at <= now - BUDGET_WINDOW_MS
+    ) {
+      ledger.spentUs -= (pieces[ledger.head] as Spent).us;
+      ledger.head += 1;
+    }
+    // Copied down once as many were dropped as are kept: each piece is copied about once.
+    if (ledger.head > 0 && ledger.head * 2 >= pieces.length) {
+      ledger.pieces = pieces.slice(ledger.head);
+      ledger.head = 0;
+    }
+    return ledger.pieces.length - ledger.head;
+  }
+
+  private ledgerOf(tenant: string): Ledger {
+    let ledger = this.ledgers.get(tenant);
+    if (ledger === undefined) {
+      ledger = { pieces: [], head: 0, spentUs: 0, refusedUntil: 0 };
+      this.ledgers.set(tenant, ledger);
+    }
+    return ledger;
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export {
+  HOSTED_BOUNDS,
+  SELF_HOSTED_BOUNDS,
+  type TenantInputBounds,
+  configureTenantInputBounds,
+  tenantInputBounds,
+} from './bounds.js';
+export {
+  BUDGET_WINDOW_MS,
+  type BudgetClock,
+  SYSTEM_CLOCK,
+  TenantBudgetError,
+  type TenantBudgetLimit,
+  TenantTimeBudget,
+} from './budget.js';
+export {
+  type CompiledTenantPattern,
+  type TenantPattern,
+  compileTenantPattern,
+  tenantPatternSyntaxProblem,
+} from './pattern.js';
+export {
+  type RunAsTenantOptions,
+  type TenantCompiles,
+  type TenantScope,
+  currentTenant,
+  runAsTenant,
+  runOutsideTenant,
+} from './tenant.js';