@databricks/appkit 0.45.0 → 0.47.0

package/dist/shared/src/schemas/metric-fqn.js

@@ -1,10 +1,9 @@
 //#region ../shared/src/schemas/metric-fqn.ts
 /**
-* Unity Catalog object-name grammar - the single source of truth for metric
-* view FQN naming validation.
+* Unity Catalog object-name grammar
+* the single source of truth for metric view FQN (Fully Qualified Name).
 *
-* This module is deliberately **zod-free**. A metric view's `source` FQN is
-* validated in two places that must agree:
+* A metric view's `source` FQN is validated in two places that must agree:
 *
 *  1. The canonical Zod schema (`./metric-source.ts`), which composes the
 *     three-part FQN regex from {@link UC_FQN_PATTERN} for IDE/CI and the
@@ -13,18 +12,8 @@
 *     which imports {@link UC_FQN_PATTERN} as a plain value to validate each
 *     dot-split segment.
 *
-* The type-generator's runtime path must NOT pull the shared Zod schema package
-* in (locked dependency-graph ruling - see the comment in
-* `packages/appkit/src/type-generator/cache.ts`). Keeping the pattern in this
-* zod-free module lets the runtime import the regex without dragging zod into
-* its bundle, while still single-sourcing the grammar.
 *
-* -- UC delimited (quoted) object-name rules ------------------------------
-* The metric view FQN is always backtick-quoted before interpolation into SQL
-* (see `quoteFqnForSql` in the type-generator), so the **delimited identifier**
-* grammar is the one that applies - not the narrower unquoted-identifier rule.
-*
-* Per the Databricks SQL names reference, a Unity Catalog object name:
+* A Unity Catalog object name:
 *  - cannot exceed 255 characters ({@link MAX_UC_OBJECT_NAME_LENGTH}); and
 *  - cannot contain any of these characters:
 *      - period (`.`)
@@ -35,41 +24,21 @@
 *
 * Every other character is permitted in a quoted name, including non-ASCII
 * letters (the docs demonstrate Chinese/Russian/Portuguese names) and hyphens.
-* This is intentionally broader than the old hand-rolled allowlist
-* (`[a-zA-Z0-9_-]`), which was flagged in PR #433 review (pkosiec: "more
-* restrictive than UC"): the goal is to accept what UC accepts as a quoted
-* name and reject only what UC rejects.
-*
-* Verified against the Databricks docs on 2026-06-19:
-*   https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-names
-* (the link cited in the PR #433 review). If the published rules change,
-* re-confirm against that page.
 *
-* @note The period is excluded here because it is the FQN segment separator -
-* a name containing a literal dot cannot be expressed in the dotted `source`
-* string at all. The dotted-source arity (exactly three segments) and the
-* 255-char-per-segment cap are enforced structurally by the callers; this
-* pattern only encodes the per-segment allowed character set.
+* @note the regex is the per-segment character set; structure (3 parts) and length are intentionally left to the callers.
 */
+const MAX_UC_OBJECT_NAME_LENGTH = 255;
 /**
-* Maximum length, in characters, of a single Unity Catalog object name
-* (catalog, schema, or metric view). UC rejects names longer than this.
+* Basename of the metric-view declarations file, resolved inside a
+* `config/metric-views/` folder. Single source of truth shared by the analytics
+* runtime (`plugins/analytics/mv`), the type-generator, its Vite watcher, and
+* the `generate-types` CLI. It lives in this zod-free module (rather than the
+* canonical `metric-source.ts` schema) so the type-generator can import it
+* without pulling zod into its locked dependency graph.
 */
-const MAX_UC_OBJECT_NAME_LENGTH = 255;
+const METRIC_CONFIG_FILE = "definitions.json";
 /**
-* Matches a single, non-empty Unity Catalog object name as it may appear in a
-* backtick-quoted (delimited) identifier - one segment of a metric view FQN.
-*
-* Accepts any non-empty run of characters EXCEPT the UC-prohibited set:
-* period, space, forward slash, ASCII control characters (U+0000-U+001F), and
-* DELETE (U+007F). Length is NOT bounded here - callers enforce
-* {@link MAX_UC_OBJECT_NAME_LENGTH} separately so they can emit a precise
-* "segment too long" message distinct from a charset violation.
-*
-* The negated character class encodes the prohibited set as one contiguous
-* range plus singletons: U+0000-U+0020 (every ASCII control character plus the
-* space, which sits at U+0020 immediately after the control range), U+007F
-* (DELETE), `.` (period - also the FQN segment separator), and `/` (slash).
+* Matches a single, non-empty Unity Catalog object name as it may appear in a backtick-quoted (delimited) identifier.
 *
 * @example
 * UC_FQN_PATTERN.test("revenue_metrics"); // true
@@ -79,7 +48,70 @@ const MAX_UC_OBJECT_NAME_LENGTH = 255;
 * UC_FQN_PATTERN.test("a/b");              // false (slash is prohibited)
 */
 const UC_FQN_PATTERN = /^[^\x00-\x20\x7f./]+$/;
+/** A metric view FQN is exactly three segments: catalog.schema.metric_view. */
+const FQN_SEGMENT_COUNT = 3;
+/**
+* Total predicate: is `fqn` a well-formed three-part UC metric view FQN?
+* Well-formed = exactly three non-empty, dot-separated segments, each a valid Unity Catalog object name per {@link UC_FQN_PATTERN}.
+* @example
+* isValidFqn("main.analytics.revenue");   // true
+* isValidFqn("prod-data.analytics.rev");   // true (hyphens are UC-legal)
+* isValidFqn("main.analytics");            // false (only two segments)
+*/
+function isValidFqn(fqn) {
+	const segments = fqn.split(".");
+	if (segments.length !== FQN_SEGMENT_COUNT) return false;
+	return segments.every((segment) => UC_FQN_PATTERN.test(segment));
+}
+/**
+* Quote a dot-separated FQN for safe interpolation into a Spark/Databricks SQL
+* statement.
+*
+* Each dot-split segment is wrapped in backtick-quoted-identifier syntax. The
+* one character that can break out of a backtick-quoted identifier is the
+* backtick itself, escaped by doubling (`` ` `` → `` `` ``) — so every backtick
+* inside a segment is doubled before the segment is wrapped. Control characters
+* and newlines have no valid escape inside a quoted identifier, so a segment
+* containing one is rejected outright.
+*
+* This is a pure, standalone escaper: it is intentionally independent of FQN
+* naming validation ({@link isValidFqn}). Naming validation decides whether an
+* FQN is an acceptable metric source; this function only guarantees that
+* whatever it is handed cannot break out of the quoted identifier it produces.
+* Grammar and quoting live together here so a metric source is validated and
+* escaped against one shared source of truth.
+*
+* An ordinary identifier is unchanged apart from the wrapping backticks:
+* `catalog.schema.view` → `` `catalog`.`schema`.`view` ``.
+*
+* @param fqn - Dot-separated identifier (e.g. `catalog.schema.view`).
+* @returns The backtick-quoted, escaped identifier ready for interpolation.
+* @throws If any segment contains a control character or newline.
+*/
+function quoteFqnForSql(fqn) {
+	return fqn.split(".").map(quoteIdentifier).join(".");
+}
+/**
+* The Unicode "control" category (`\p{Cc}`): C0 (incl. `\n`, `\r`, `\t`), DEL,
+* and C1 — every control character/newline. These have no valid escape inside
+* a backtick-quoted identifier, so a name containing one cannot be safely
+* quoted and is rejected.
+*/
+const CONTROL_OR_NEWLINE = /\p{Cc}/u;
+function isValidColumnName(name) {
+	return name.length > 0 && !CONTROL_OR_NEWLINE.test(name);
+}
+/**
+* Quote a single identifier (one column/measure/dimension name, or one FQN
+* segment) as a backtick-delimited identifier for safe SQL interpolation.
+*
+* @throws If `name` contains a control character or newline.
+*/
+function quoteIdentifier(name) {
+	if (CONTROL_OR_NEWLINE.test(name)) throw new Error(`Cannot quote identifier "${name}" for SQL: it contains a control character or newline, which has no valid escape inside a backtick-quoted identifier.`);
+	return `\`${name.replace(/`/g, "``")}\``;
+}
 
 //#endregion
-export { MAX_UC_OBJECT_NAME_LENGTH, UC_FQN_PATTERN };
+export { MAX_UC_OBJECT_NAME_LENGTH, METRIC_CONFIG_FILE, UC_FQN_PATTERN, isValidColumnName, isValidFqn, quoteFqnForSql, quoteIdentifier };
 //# sourceMappingURL=metric-fqn.js.map

package/dist/shared/src/schemas/metric-fqn.js.map

@@ -1 +1 @@
-{"version":3,"file":"metric-fqn.js","names":[],"sources":["../../../../../shared/src/schemas/metric-fqn.ts"],"sourcesContent":["/**\n * Unity Catalog object-name grammar - the single source of truth for metric\n * view FQN naming validation.\n *\n * This module is deliberately **zod-free**. A metric view's `source` FQN is\n * validated in two places that must agree:\n *\n *  1. The canonical Zod schema (`./metric-source.ts`), which composes the\n *     three-part FQN regex from {@link UC_FQN_PATTERN} for IDE/CI and the\n *     generated JSON schema (`docs/static/schemas/metric-source.schema.json`).\n *  2. The type-generator runtime (`packages/appkit/src/type-generator/mv-registry/config.ts`),\n *     which imports {@link UC_FQN_PATTERN} as a plain value to validate each\n *     dot-split segment.\n *\n * The type-generator's runtime path must NOT pull the shared Zod schema package\n * in (locked dependency-graph ruling - see the comment in\n * `packages/appkit/src/type-generator/cache.ts`). Keeping the pattern in this\n * zod-free module lets the runtime import the regex without dragging zod into\n * its bundle, while still single-sourcing the grammar.\n *\n * -- UC delimited (quoted) object-name rules ------------------------------\n * The metric view FQN is always backtick-quoted before interpolation into SQL\n * (see `quoteFqnForSql` in the type-generator), so the **delimited identifier**\n * grammar is the one that applies - not the narrower unquoted-identifier rule.\n *\n * Per the Databricks SQL names reference, a Unity Catalog object name:\n *  - cannot exceed 255 characters ({@link MAX_UC_OBJECT_NAME_LENGTH}); and\n *  - cannot contain any of these characters:\n *      - period (`.`)\n *      - space (U+0020)\n *      - forward slash (`/`)\n *      - all ASCII control characters (U+0000-U+001F)\n *      - the DELETE character (U+007F)\n *\n * Every other character is permitted in a quoted name, including non-ASCII\n * letters (the docs demonstrate Chinese/Russian/Portuguese names) and hyphens.\n * This is intentionally broader than the old hand-rolled allowlist\n * (`[a-zA-Z0-9_-]`), which was flagged in PR #433 review (pkosiec: \"more\n * restrictive than UC\"): the goal is to accept what UC accepts as a quoted\n * name and reject only what UC rejects.\n *\n * Verified against the Databricks docs on 2026-06-19:\n *   https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-names\n * (the link cited in the PR #433 review). If the published rules change,\n * re-confirm against that page.\n *\n * @note The period is excluded here because it is the FQN segment separator -\n * a name containing a literal dot cannot be expressed in the dotted `source`\n * string at all. The dotted-source arity (exactly three segments) and the\n * 255-char-per-segment cap are enforced structurally by the callers; this\n * pattern only encodes the per-segment allowed character set.\n */\n\n/**\n * Maximum length, in characters, of a single Unity Catalog object name\n * (catalog, schema, or metric view). UC rejects names longer than this.\n */\nexport const MAX_UC_OBJECT_NAME_LENGTH = 255;\n\n/**\n * Matches a single, non-empty Unity Catalog object name as it may appear in a\n * backtick-quoted (delimited) identifier - one segment of a metric view FQN.\n *\n * Accepts any non-empty run of characters EXCEPT the UC-prohibited set:\n * period, space, forward slash, ASCII control characters (U+0000-U+001F), and\n * DELETE (U+007F). Length is NOT bounded here - callers enforce\n * {@link MAX_UC_OBJECT_NAME_LENGTH} separately so they can emit a precise\n * \"segment too long\" message distinct from a charset violation.\n *\n * The negated character class encodes the prohibited set as one contiguous\n * range plus singletons: U+0000-U+0020 (every ASCII control character plus the\n * space, which sits at U+0020 immediately after the control range), U+007F\n * (DELETE), `.` (period - also the FQN segment separator), and `/` (slash).\n *\n * @example\n * UC_FQN_PATTERN.test(\"revenue_metrics\"); // true\n * UC_FQN_PATTERN.test(\"prod-data\");        // true (hyphens are UC-legal)\n * UC_FQN_PATTERN.test(\"cafe\\u0301\");       // true (non-ASCII is UC-legal)\n * UC_FQN_PATTERN.test(\"bad name\");         // false (space is prohibited)\n * UC_FQN_PATTERN.test(\"a/b\");              // false (slash is prohibited)\n */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: UC explicitly prohibits ASCII control characters in object names; this negated class encodes that rule.\nexport const UC_FQN_PATTERN = /^[^\\x00-\\x20\\x7f./]+$/;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,MAAa,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;AAyBzC,MAAa,iBAAiB"}
+{"version":3,"file":"metric-fqn.js","names":[],"sources":["../../../../../shared/src/schemas/metric-fqn.ts"],"sourcesContent":["/**\n * Unity Catalog object-name grammar\n * the single source of truth for metric view FQN (Fully Qualified Name).\n *\n * A metric view's `source` FQN is validated in two places that must agree:\n *\n *  1. The canonical Zod schema (`./metric-source.ts`), which composes the\n *     three-part FQN regex from {@link UC_FQN_PATTERN} for IDE/CI and the\n *     generated JSON schema (`docs/static/schemas/metric-source.schema.json`).\n *  2. The type-generator runtime (`packages/appkit/src/type-generator/mv-registry/config.ts`),\n *     which imports {@link UC_FQN_PATTERN} as a plain value to validate each\n *     dot-split segment.\n *\n *\n * A Unity Catalog object name:\n *  - cannot exceed 255 characters ({@link MAX_UC_OBJECT_NAME_LENGTH}); and\n *  - cannot contain any of these characters:\n *      - period (`.`)\n *      - space (U+0020)\n *      - forward slash (`/`)\n *      - all ASCII control characters (U+0000-U+001F)\n *      - the DELETE character (U+007F)\n *\n * Every other character is permitted in a quoted name, including non-ASCII\n * letters (the docs demonstrate Chinese/Russian/Portuguese names) and hyphens.\n *\n * @note the regex is the per-segment character set; structure (3 parts) and length are intentionally left to the callers.\n */\n\nexport const MAX_UC_OBJECT_NAME_LENGTH = 255;\n\n/**\n * Basename of the metric-view declarations file, resolved inside a\n * `config/metric-views/` folder. Single source of truth shared by the analytics\n * runtime (`plugins/analytics/mv`), the type-generator, its Vite watcher, and\n * the `generate-types` CLI. It lives in this zod-free module (rather than the\n * canonical `metric-source.ts` schema) so the type-generator can import it\n * without pulling zod into its locked dependency graph.\n */\nexport const METRIC_CONFIG_FILE = \"definitions.json\";\n\n/**\n * Matches a single, non-empty Unity Catalog object name as it may appear in a backtick-quoted (delimited) identifier.\n *\n * @example\n * UC_FQN_PATTERN.test(\"revenue_metrics\"); // true\n * UC_FQN_PATTERN.test(\"prod-data\");        // true (hyphens are UC-legal)\n * UC_FQN_PATTERN.test(\"cafe\\u0301\");       // true (non-ASCII is UC-legal)\n * UC_FQN_PATTERN.test(\"bad name\");         // false (space is prohibited)\n * UC_FQN_PATTERN.test(\"a/b\");              // false (slash is prohibited)\n */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: UC explicitly prohibits ASCII control characters in object names; this negated class encodes that rule.\nexport const UC_FQN_PATTERN = /^[^\\x00-\\x20\\x7f./]+$/;\n\n/** A metric view FQN is exactly three segments: catalog.schema.metric_view. */\nconst FQN_SEGMENT_COUNT = 3;\n\n/**\n * Total predicate: is `fqn` a well-formed three-part UC metric view FQN?\n * Well-formed = exactly three non-empty, dot-separated segments, each a valid Unity Catalog object name per {@link UC_FQN_PATTERN}.\n * @example\n * isValidFqn(\"main.analytics.revenue\");   // true\n * isValidFqn(\"prod-data.analytics.rev\");   // true (hyphens are UC-legal)\n * isValidFqn(\"main.analytics\");            // false (only two segments)\n */\nexport function isValidFqn(fqn: string): boolean {\n  const segments = fqn.split(\".\");\n  if (segments.length !== FQN_SEGMENT_COUNT) {\n    return false;\n  }\n  return segments.every((segment) => UC_FQN_PATTERN.test(segment));\n}\n\n/**\n * Quote a dot-separated FQN for safe interpolation into a Spark/Databricks SQL\n * statement.\n *\n * Each dot-split segment is wrapped in backtick-quoted-identifier syntax. The\n * one character that can break out of a backtick-quoted identifier is the\n * backtick itself, escaped by doubling (`` ` `` → `` `` ``) — so every backtick\n * inside a segment is doubled before the segment is wrapped. Control characters\n * and newlines have no valid escape inside a quoted identifier, so a segment\n * containing one is rejected outright.\n *\n * This is a pure, standalone escaper: it is intentionally independent of FQN\n * naming validation ({@link isValidFqn}). Naming validation decides whether an\n * FQN is an acceptable metric source; this function only guarantees that\n * whatever it is handed cannot break out of the quoted identifier it produces.\n * Grammar and quoting live together here so a metric source is validated and\n * escaped against one shared source of truth.\n *\n * An ordinary identifier is unchanged apart from the wrapping backticks:\n * `catalog.schema.view` → `` `catalog`.`schema`.`view` ``.\n *\n * @param fqn - Dot-separated identifier (e.g. `catalog.schema.view`).\n * @returns The backtick-quoted, escaped identifier ready for interpolation.\n * @throws If any segment contains a control character or newline.\n */\nexport function quoteFqnForSql(fqn: string): string {\n  return fqn.split(\".\").map(quoteIdentifier).join(\".\");\n}\n\n/**\n * The Unicode \"control\" category (`\\p{Cc}`): C0 (incl. `\\n`, `\\r`, `\\t`), DEL,\n * and C1 — every control character/newline. These have no valid escape inside\n * a backtick-quoted identifier, so a name containing one cannot be safely\n * quoted and is rejected.\n */\nconst CONTROL_OR_NEWLINE = /\\p{Cc}/u;\n\nexport function isValidColumnName(name: string): boolean {\n  return name.length > 0 && !CONTROL_OR_NEWLINE.test(name);\n}\n\n/**\n * Quote a single identifier (one column/measure/dimension name, or one FQN\n * segment) as a backtick-delimited identifier for safe SQL interpolation.\n *\n * @throws If `name` contains a control character or newline.\n */\nexport function quoteIdentifier(name: string): string {\n  if (CONTROL_OR_NEWLINE.test(name)) {\n    throw new Error(\n      `Cannot quote identifier \"${name}\" for SQL: it contains a control character or newline, which has no valid escape inside a backtick-quoted identifier.`,\n    );\n  }\n  // Double every backtick, then wrap in backticks.\n  return `\\`${name.replace(/`/g, \"``\")}\\``;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,4BAA4B;;;;;;;;;AAUzC,MAAa,qBAAqB;;;;;;;;;;;AAalC,MAAa,iBAAiB;;AAG9B,MAAM,oBAAoB;;;;;;;;;AAU1B,SAAgB,WAAW,KAAsB;CAC/C,MAAM,WAAW,IAAI,MAAM,IAAI;AAC/B,KAAI,SAAS,WAAW,kBACtB,QAAO;AAET,QAAO,SAAS,OAAO,YAAY,eAAe,KAAK,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BlE,SAAgB,eAAe,KAAqB;AAClD,QAAO,IAAI,MAAM,IAAI,CAAC,IAAI,gBAAgB,CAAC,KAAK,IAAI;;;;;;;;AAStD,MAAM,qBAAqB;AAE3B,SAAgB,kBAAkB,MAAuB;AACvD,QAAO,KAAK,SAAS,KAAK,CAAC,mBAAmB,KAAK,KAAK;;;;;;;;AAS1D,SAAgB,gBAAgB,MAAsB;AACpD,KAAI,mBAAmB,KAAK,KAAK,CAC/B,OAAM,IAAI,MACR,4BAA4B,KAAK,uHAClC;AAGH,QAAO,KAAK,KAAK,QAAQ,MAAM,KAAK,CAAC"}

package/dist/shared/src/schemas/metric-source.js

@@ -0,0 +1,90 @@
+import { MAX_UC_OBJECT_NAME_LENGTH, UC_FQN_PATTERN } from "./metric-fqn.js";
+import { z } from "zod";
+
+//#region ../shared/src/schemas/metric-source.ts
+/**
+* AppKit metric-source schema.
+*
+* Single source of truth for `config/metric-views/definitions.json`
+* the config that activates the Analytics' metric-view path.
+*
+* `definitions.json` declares UC Metric Views under a single `metricViews` map.
+* Each entry binds a metric key to a UC metric view FQN plus the executor
+* the query runs as:
+* - `executor: "app_service_principal"` (default) — queried as the app service
+*   principal (cache scope shared across all users).
+* - `executor: "user"` — queried as the requesting user (on-behalf-of;
+*   cache scope per-user).
+*
+* A single map (rather than per-executor sections) makes metric keys unique
+* by construction — the same key cannot be declared twice with different
+* executors.
+*/
+/**
+* Safety cap on the number of declared metric views — a typo / DoS guard, NOT
+* a Unity Catalog limit. Mirrors the type-generator's `MAX_METRIC_VIEWS` so
+* runtime config validation and type generation accept exactly the same
+* configs (a config that fails generation must not silently pass at runtime).
+*/
+const MAX_METRIC_VIEWS = 200;
+/**
+* Whole-FQN length cap: three max-length UC object names plus the two dots.
+* The per-segment cap ({@link MAX_UC_OBJECT_NAME_LENGTH}) is enforced in the
+* `superRefine` below; this whole-string bound is the declarative half (it
+* serializes to a JSON-schema `maxLength`, whereas the per-segment check — like
+* the entry-count cap — cannot be expressed declaratively and lives in the
+* refinement, so it is a runtime/type-generator gate only).
+*/
+const MAX_FQN_LENGTH = MAX_UC_OBJECT_NAME_LENGTH * 3 + 2;
+/**
+* Three-part Unity Catalog FQN matcher, composed from the single-segment
+* {@link UC_FQN_PATTERN} so the per-segment grammar has exactly one source of
+* truth (shared by the type-generator runtime, which imports the zod-free
+* {@link UC_FQN_PATTERN} directly — see `./metric-fqn.ts`).
+*
+* `UC_FQN_PATTERN` is `^<segment>+$`; stripping its `^`/`$` anchors yields the
+* per-segment sub-pattern, which is joined with literal dots into
+* `^<segment>\.<segment>\.<segment>$`. Exactly three dot-separated segments,
+* each a valid UC object name. Arity (and the per-segment length cap) is also
+* enforced structurally by the type-generator's `resolveMetricConfig`.
+*/
+const UC_FQN_SEGMENT_SOURCE = UC_FQN_PATTERN.source.replace(/^\^/, "").replace(/\$$/, "");
+const UC_THREE_PART_FQN_PATTERN = new RegExp(`^${UC_FQN_SEGMENT_SOURCE}\\.${UC_FQN_SEGMENT_SOURCE}\\.${UC_FQN_SEGMENT_SOURCE}$`);
+const metricKeySchema = z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/).describe("Metric key. Must be a valid identifier (letters, digits, underscores; cannot start with a digit). Becomes the route key in POST /api/analytics/metric/:key, the hook argument in useMetricView('<key>', ...), and the MetricRegistry augmentation key.");
+const metricExecutorSchema = z.enum(["app_service_principal", "user"]).describe("Who the metric view is queried as. 'app_service_principal' (default) runs as the app service principal with a cache shared across all users; 'user' runs on-behalf-of the requesting user with a per-user cache.");
+/**
+* @note Entries are objects (rather than bare strings) at v1 so future per-entry
+* options (cacheTtl, defaultFilter, allowlists) can ship as additive
+* properties without a breaking change. `executor` is the first such option.
+*/
+const metricEntrySchema = z.object({
+	source: z.string().regex(UC_THREE_PART_FQN_PATTERN).max(MAX_FQN_LENGTH).describe("Three-part Unity Catalog FQN of the metric view: <catalog>.<schema>.<metric_view>").meta({ examples: ["appkit_demo.public.revenue_metrics", "main.analytics.customer_metrics"] }),
+	executor: metricExecutorSchema.default("app_service_principal")
+}).strict().describe("A single metric view source declaration: the UC FQN to query and the executor to query it as. Future per-entry options (cacheTtl, defaultFilter, allowlists) ship as additive properties.");
+const metricSourceSchema = z.object({
+	$schema: z.string().optional().describe("Reference to the JSON Schema for validation"),
+	metricViews: z.record(metricKeySchema, metricEntrySchema).optional().describe("Metric view declarations, keyed by metric key. Each entry names the UC metric view to query and the executor it runs as.")
+}).strict().describe("Schema for AppKit config/metric-views/definitions.json — declares Unity Catalog Metric View sources for the analytics plugin's metric-view path. Each entry under 'metricViews' binds a metric key to a UC metric view FQN and an executor ('app_service_principal' shared cache, or 'user' per-user cache). Object form (rather than bare string) at v1 enables future per-entry option growth without breaking changes.").superRefine((value, ctx) => {
+	const entries = value.metricViews ? Object.entries(value.metricViews) : [];
+	if (entries.length > MAX_METRIC_VIEWS) ctx.addIssue({
+		code: "custom",
+		message: `too many metric views: ${entries.length} declared, exceeding the maximum of ${MAX_METRIC_VIEWS}`,
+		path: ["metricViews"]
+	});
+	for (const [key, entry] of entries) {
+		const segments = entry.source.split(".");
+		for (let i = 0; i < segments.length; i++) if (segments[i].length > MAX_UC_OBJECT_NAME_LENGTH) ctx.addIssue({
+			code: "custom",
+			message: `metric source segment ${i + 1} is ${segments[i].length} characters, exceeding the per-segment maximum of ${MAX_UC_OBJECT_NAME_LENGTH}`,
+			path: [
+				"metricViews",
+				key,
+				"source"
+			]
+		});
+	}
+});
+
+//#endregion
+export { metricSourceSchema };
+//# sourceMappingURL=metric-source.js.map

package/dist/shared/src/schemas/metric-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-source.js","names":[],"sources":["../../../../../shared/src/schemas/metric-source.ts"],"sourcesContent":["/**\n * AppKit metric-source schema.\n *\n * Single source of truth for `config/metric-views/definitions.json`\n * the config that activates the Analytics' metric-view path.\n *\n * `definitions.json` declares UC Metric Views under a single `metricViews` map.\n * Each entry binds a metric key to a UC metric view FQN plus the executor\n * the query runs as:\n * - `executor: \"app_service_principal\"` (default) — queried as the app service\n *   principal (cache scope shared across all users).\n * - `executor: \"user\"` — queried as the requesting user (on-behalf-of;\n *   cache scope per-user).\n *\n * A single map (rather than per-executor sections) makes metric keys unique\n * by construction — the same key cannot be declared twice with different\n * executors.\n */\n\nimport { z } from \"zod\";\nimport { MAX_UC_OBJECT_NAME_LENGTH, UC_FQN_PATTERN } from \"./metric-fqn\";\n\n/**\n * Safety cap on the number of declared metric views — a typo / DoS guard, NOT\n * a Unity Catalog limit. Mirrors the type-generator's `MAX_METRIC_VIEWS` so\n * runtime config validation and type generation accept exactly the same\n * configs (a config that fails generation must not silently pass at runtime).\n */\nconst MAX_METRIC_VIEWS = 200;\n\n/**\n * Whole-FQN length cap: three max-length UC object names plus the two dots.\n * The per-segment cap ({@link MAX_UC_OBJECT_NAME_LENGTH}) is enforced in the\n * `superRefine` below; this whole-string bound is the declarative half (it\n * serializes to a JSON-schema `maxLength`, whereas the per-segment check — like\n * the entry-count cap — cannot be expressed declaratively and lives in the\n * refinement, so it is a runtime/type-generator gate only).\n */\nconst MAX_FQN_LENGTH = MAX_UC_OBJECT_NAME_LENGTH * 3 + 2;\n\n/**\n * Three-part Unity Catalog FQN matcher, composed from the single-segment\n * {@link UC_FQN_PATTERN} so the per-segment grammar has exactly one source of\n * truth (shared by the type-generator runtime, which imports the zod-free\n * {@link UC_FQN_PATTERN} directly — see `./metric-fqn.ts`).\n *\n * `UC_FQN_PATTERN` is `^<segment>+$`; stripping its `^`/`$` anchors yields the\n * per-segment sub-pattern, which is joined with literal dots into\n * `^<segment>\\.<segment>\\.<segment>$`. Exactly three dot-separated segments,\n * each a valid UC object name. Arity (and the per-segment length cap) is also\n * enforced structurally by the type-generator's `resolveMetricConfig`.\n */\nconst UC_FQN_SEGMENT_SOURCE = UC_FQN_PATTERN.source\n  .replace(/^\\^/, \"\")\n  .replace(/\\$$/, \"\");\nconst UC_THREE_PART_FQN_PATTERN = new RegExp(\n  `^${UC_FQN_SEGMENT_SOURCE}\\\\.${UC_FQN_SEGMENT_SOURCE}\\\\.${UC_FQN_SEGMENT_SOURCE}$`,\n);\n\nexport const metricKeySchema = z\n  .string()\n  .regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/)\n  .describe(\n    \"Metric key. Must be a valid identifier (letters, digits, underscores; cannot start with a digit). Becomes the route key in POST /api/analytics/metric/:key, the hook argument in useMetricView('<key>', ...), and the MetricRegistry augmentation key.\",\n  );\n\nexport const metricExecutorSchema = z\n  .enum([\"app_service_principal\", \"user\"])\n  .describe(\n    \"Who the metric view is queried as. 'app_service_principal' (default) runs as the app service principal with a cache shared across all users; 'user' runs on-behalf-of the requesting user with a per-user cache.\",\n  );\n\n/**\n * @note Entries are objects (rather than bare strings) at v1 so future per-entry\n * options (cacheTtl, defaultFilter, allowlists) can ship as additive\n * properties without a breaking change. `executor` is the first such option.\n */\nexport const metricEntrySchema = z\n  .object({\n    source: z\n      .string()\n      .regex(UC_THREE_PART_FQN_PATTERN)\n      .max(MAX_FQN_LENGTH)\n      .describe(\n        \"Three-part Unity Catalog FQN of the metric view: <catalog>.<schema>.<metric_view>\",\n      )\n      .meta({\n        examples: [\n          \"appkit_demo.public.revenue_metrics\",\n          \"main.analytics.customer_metrics\",\n        ],\n      }),\n    executor: metricExecutorSchema.default(\"app_service_principal\"),\n  })\n  .strict()\n  .describe(\n    \"A single metric view source declaration: the UC FQN to query and the executor to query it as. Future per-entry options (cacheTtl, defaultFilter, allowlists) ship as additive properties.\",\n  );\n\nexport const metricSourceSchema = z\n  .object({\n    $schema: z\n      .string()\n      .optional()\n      .describe(\"Reference to the JSON Schema for validation\"),\n    metricViews: z\n      .record(metricKeySchema, metricEntrySchema)\n      .optional()\n      .describe(\n        \"Metric view declarations, keyed by metric key. Each entry names the UC metric view to query and the executor it runs as.\",\n      ),\n  })\n  .strict()\n  .describe(\n    \"Schema for AppKit config/metric-views/definitions.json — declares Unity Catalog Metric View sources for the analytics plugin's metric-view path. Each entry under 'metricViews' binds a metric key to a UC metric view FQN and an executor ('app_service_principal' shared cache, or 'user' per-user cache). Object form (rather than bare string) at v1 enables future per-entry option growth without breaking changes.\",\n  )\n  // Caps that cannot be expressed declaratively (zod 4's `z.record` has no\n  // `.max`, and a per-dot-segment length bound isn't a whole-string\n  // `maxLength`). Enforced here so runtime config validation matches the\n  // type-generator's `resolveMetricConfig` exactly — a config that fails type\n  // generation must not silently pass at runtime. These refinements are\n  // invisible to `z.toJSONSchema`, so the generated JSON schema carries only\n  // the declarative `maxLength` on `source`; runtime + type-generator remain\n  // the authoritative gates for the entry-count and per-segment caps.\n  .superRefine((value, ctx) => {\n    const entries = value.metricViews ? Object.entries(value.metricViews) : [];\n\n    if (entries.length > MAX_METRIC_VIEWS) {\n      ctx.addIssue({\n        code: \"custom\",\n        message: `too many metric views: ${entries.length} declared, exceeding the maximum of ${MAX_METRIC_VIEWS}`,\n        path: [\"metricViews\"],\n      });\n    }\n\n    for (const [key, entry] of entries) {\n      const segments = entry.source.split(\".\");\n      for (let i = 0; i < segments.length; i++) {\n        if (segments[i].length > MAX_UC_OBJECT_NAME_LENGTH) {\n          ctx.addIssue({\n            code: \"custom\",\n            message: `metric source segment ${i + 1} is ${segments[i].length} characters, exceeding the per-segment maximum of ${MAX_UC_OBJECT_NAME_LENGTH}`,\n            path: [\"metricViews\", key, \"source\"],\n          });\n        }\n      }\n    }\n  });\n\nexport type MetricKey = z.infer<typeof metricKeySchema>;\nexport type MetricExecutor = z.infer<typeof metricExecutorSchema>;\nexport type MetricEntry = z.infer<typeof metricEntrySchema>;\nexport type MetricSource = z.infer<typeof metricSourceSchema>;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAM,mBAAmB;;;;;;;;;AAUzB,MAAM,iBAAiB,4BAA4B,IAAI;;;;;;;;;;;;;AAcvD,MAAM,wBAAwB,eAAe,OAC1C,QAAQ,OAAO,GAAG,CAClB,QAAQ,OAAO,GAAG;AACrB,MAAM,4BAA4B,IAAI,OACpC,IAAI,sBAAsB,KAAK,sBAAsB,KAAK,sBAAsB,GACjF;AAED,MAAa,kBAAkB,EAC5B,QAAQ,CACR,MAAM,2BAA2B,CACjC,SACC,yPACD;AAEH,MAAa,uBAAuB,EACjC,KAAK,CAAC,yBAAyB,OAAO,CAAC,CACvC,SACC,mNACD;;;;;;AAOH,MAAa,oBAAoB,EAC9B,OAAO;CACN,QAAQ,EACL,QAAQ,CACR,MAAM,0BAA0B,CAChC,IAAI,eAAe,CACnB,SACC,oFACD,CACA,KAAK,EACJ,UAAU,CACR,sCACA,kCACD,EACF,CAAC;CACJ,UAAU,qBAAqB,QAAQ,wBAAwB;CAChE,CAAC,CACD,QAAQ,CACR,SACC,4LACD;AAEH,MAAa,qBAAqB,EAC/B,OAAO;CACN,SAAS,EACN,QAAQ,CACR,UAAU,CACV,SAAS,8CAA8C;CAC1D,aAAa,EACV,OAAO,iBAAiB,kBAAkB,CAC1C,UAAU,CACV,SACC,2HACD;CACJ,CAAC,CACD,QAAQ,CACR,SACC,4ZACD,CASA,aAAa,OAAO,QAAQ;CAC3B,MAAM,UAAU,MAAM,cAAc,OAAO,QAAQ,MAAM,YAAY,GAAG,EAAE;AAE1E,KAAI,QAAQ,SAAS,iBACnB,KAAI,SAAS;EACX,MAAM;EACN,SAAS,0BAA0B,QAAQ,OAAO,sCAAsC;EACxF,MAAM,CAAC,cAAc;EACtB,CAAC;AAGJ,MAAK,MAAM,CAAC,KAAK,UAAU,SAAS;EAClC,MAAM,WAAW,MAAM,OAAO,MAAM,IAAI;AACxC,OAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,IACnC,KAAI,SAAS,GAAG,SAAS,0BACvB,KAAI,SAAS;GACX,MAAM;GACN,SAAS,yBAAyB,IAAI,EAAE,MAAM,SAAS,GAAG,OAAO,oDAAoD;GACrH,MAAM;IAAC;IAAe;IAAK;IAAS;GACrC,CAAC;;EAIR"}

package/dist/stream/buffers.js

@@ -94,5 +94,5 @@ var EventRingBuffer = class {
 };
 
 //#endregion
-export { EventRingBuffer, RingBuffer };
+export { EventRingBuffer };
 //# sourceMappingURL=buffers.js.map

package/dist/stream/buffers.js.map

@@ -1 +1 @@
-{"version":3,"file":"buffers.js","names":[],"sources":["../../src/stream/buffers.ts"],"sourcesContent":["import { ValidationError } from \"../errors\";\nimport type { BufferedEvent } from \"./types\";\n\n// generic ring buffer implementation\nexport class RingBuffer<T> {\n  public buffer: (T | null)[];\n  public capacity: number;\n  private writeIndex: number;\n  private size: number;\n  private keyExtractor: (item: T) => string;\n  private keyIndex: Map<string, number>;\n\n  constructor(capacity: number, keyExtractor: (item: T) => string) {\n    if (capacity <= 0) {\n      throw ValidationError.invalidValue(\n        \"capacity\",\n        capacity,\n        \"greater than 0\",\n      );\n    }\n\n    this.capacity = capacity;\n    this.buffer = new Array(capacity).fill(null);\n    this.writeIndex = 0;\n    this.size = 0;\n    this.keyExtractor = keyExtractor;\n    this.keyIndex = new Map();\n  }\n\n  // add an item to the buffer\n  add(item: T): void {\n    const key = this.keyExtractor(item);\n\n    // check if item already exists\n    const existingIndex = this.keyIndex.get(key);\n    if (existingIndex !== undefined) {\n      // update existing item\n      this.buffer[existingIndex] = item;\n      return;\n    }\n\n    // evict least recently used item if at capacity\n    const evicted = this.buffer[this.writeIndex];\n    if (evicted !== null) {\n      const evictedKey = this.keyExtractor(evicted);\n      this.keyIndex.delete(evictedKey);\n    }\n\n    // add new item\n    this.buffer[this.writeIndex] = item;\n    this.keyIndex.set(key, this.writeIndex);\n\n    // update write index and size\n    this.writeIndex = (this.writeIndex + 1) % this.capacity;\n    this.size = Math.min(this.size + 1, this.capacity);\n  }\n\n  // get an item from the buffer\n  get(key: string): T | null {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return null;\n\n    return this.buffer[index];\n  }\n\n  // check if an item exists in the buffer\n  has(key: string): boolean {\n    return this.keyIndex.has(key);\n  }\n\n  // remove an item from the buffer\n  remove(key: string): void {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return;\n\n    // remove item from buffer\n    this.buffer[index] = null;\n    this.keyIndex.delete(key);\n\n    // update size\n    this.size = Math.max(this.size - 1, 0);\n  }\n\n  // get all items from the buffer\n  getAll(): T[] {\n    const result: T[] = [];\n\n    // iterate over buffer in order of insertion\n    for (let i = 0; i < this.size; i++) {\n      // calculate index of item in buffer\n      const index =\n        (this.writeIndex - this.size + i + this.capacity) % this.capacity;\n      // add item to result if not null\n      const item = this.buffer[index];\n      if (item !== null) {\n        result.push(item);\n      }\n    }\n    return result;\n  }\n\n  // get the size of the buffer\n  getSize(): number {\n    return this.size;\n  }\n\n  // clear the buffer\n  clear(): void {\n    this.buffer = new Array(this.capacity).fill(null);\n    this.keyIndex.clear();\n    this.writeIndex = 0;\n    this.size = 0;\n  }\n}\n\n// event ring buffer implementation\nexport class EventRingBuffer {\n  private buffer: RingBuffer<BufferedEvent>;\n\n  constructor(capacity: number = 100) {\n    this.buffer = new RingBuffer<BufferedEvent>(capacity, (event) => event.id);\n  }\n\n  // add an event to the buffer\n  add(event: BufferedEvent): void {\n    this.buffer.add(event);\n  }\n\n  // check if an event exists in the buffer\n  has(eventId: string): boolean {\n    return this.buffer.has(eventId);\n  }\n\n  // get all events since a given event id\n  getEventsSince(lastEventId: string): BufferedEvent[] {\n    const allEvents = this.buffer.getAll();\n    const result: BufferedEvent[] = [];\n    // flag to track if we've found the last event\n    let foundLastEvent = false;\n\n    // iterate over all events\n    for (const event of allEvents) {\n      // if found, add to result\n      if (foundLastEvent) {\n        result.push(event);\n        // if not found, check if it's the last event\n      } else if (event.id === lastEventId) {\n        foundLastEvent = true;\n      }\n    }\n    return result;\n  }\n\n  clear(): void {\n    this.buffer.clear();\n  }\n}\n"],"mappings":";;;;AAIA,IAAa,aAAb,MAA2B;CACzB,AAAO;CACP,AAAO;CACP,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CAER,YAAY,UAAkB,cAAmC;AAC/D,MAAI,YAAY,EACd,OAAM,gBAAgB,aACpB,YACA,UACA,iBACD;AAGH,OAAK,WAAW;AAChB,OAAK,SAAS,IAAI,MAAM,SAAS,CAAC,KAAK,KAAK;AAC5C,OAAK,aAAa;AAClB,OAAK,OAAO;AACZ,OAAK,eAAe;AACpB,OAAK,2BAAW,IAAI,KAAK;;CAI3B,IAAI,MAAe;EACjB,MAAM,MAAM,KAAK,aAAa,KAAK;EAGnC,MAAM,gBAAgB,KAAK,SAAS,IAAI,IAAI;AAC5C,MAAI,kBAAkB,QAAW;AAE/B,QAAK,OAAO,iBAAiB;AAC7B;;EAIF,MAAM,UAAU,KAAK,OAAO,KAAK;AACjC,MAAI,YAAY,MAAM;GACpB,MAAM,aAAa,KAAK,aAAa,QAAQ;AAC7C,QAAK,SAAS,OAAO,WAAW;;AAIlC,OAAK,OAAO,KAAK,cAAc;AAC/B,OAAK,SAAS,IAAI,KAAK,KAAK,WAAW;AAGvC,OAAK,cAAc,KAAK,aAAa,KAAK,KAAK;AAC/C,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,KAAK,SAAS;;CAIpD,IAAI,KAAuB;EACzB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW,QAAO;AAEhC,SAAO,KAAK,OAAO;;CAIrB,IAAI,KAAsB;AACxB,SAAO,KAAK,SAAS,IAAI,IAAI;;CAI/B,OAAO,KAAmB;EACxB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW;AAGzB,OAAK,OAAO,SAAS;AACrB,OAAK,SAAS,OAAO,IAAI;AAGzB,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,EAAE;;CAIxC,SAAc;EACZ,MAAM,SAAc,EAAE;AAGtB,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,MAAM,KAAK;GAElC,MAAM,SACH,KAAK,aAAa,KAAK,OAAO,IAAI,KAAK,YAAY,KAAK;GAE3D,MAAM,OAAO,KAAK,OAAO;AACzB,OAAI,SAAS,KACX,QAAO,KAAK,KAAK;;AAGrB,SAAO;;CAIT,UAAkB;AAChB,SAAO,KAAK;;CAId,QAAc;AACZ,OAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC,KAAK,KAAK;AACjD,OAAK,SAAS,OAAO;AACrB,OAAK,aAAa;AAClB,OAAK,OAAO;;;AAKhB,IAAa,kBAAb,MAA6B;CAC3B,AAAQ;CAER,YAAY,WAAmB,KAAK;AAClC,OAAK,SAAS,IAAI,WAA0B,WAAW,UAAU,MAAM,GAAG;;CAI5E,IAAI,OAA4B;AAC9B,OAAK,OAAO,IAAI,MAAM;;CAIxB,IAAI,SAA0B;AAC5B,SAAO,KAAK,OAAO,IAAI,QAAQ;;CAIjC,eAAe,aAAsC;EACnD,MAAM,YAAY,KAAK,OAAO,QAAQ;EACtC,MAAM,SAA0B,EAAE;EAElC,IAAI,iBAAiB;AAGrB,OAAK,MAAM,SAAS,UAElB,KAAI,eACF,QAAO,KAAK,MAAM;WAET,MAAM,OAAO,YACtB,kBAAiB;AAGrB,SAAO;;CAGT,QAAc;AACZ,OAAK,OAAO,OAAO"}
+{"version":3,"file":"buffers.js","names":[],"sources":["../../src/stream/buffers.ts"],"sourcesContent":["import { ValidationError } from \"../errors\";\nimport type { BufferedEvent } from \"./types\";\n\n// generic ring buffer implementation\nclass RingBuffer<T> {\n  public buffer: (T | null)[];\n  public capacity: number;\n  private writeIndex: number;\n  private size: number;\n  private keyExtractor: (item: T) => string;\n  private keyIndex: Map<string, number>;\n\n  constructor(capacity: number, keyExtractor: (item: T) => string) {\n    if (capacity <= 0) {\n      throw ValidationError.invalidValue(\n        \"capacity\",\n        capacity,\n        \"greater than 0\",\n      );\n    }\n\n    this.capacity = capacity;\n    this.buffer = new Array(capacity).fill(null);\n    this.writeIndex = 0;\n    this.size = 0;\n    this.keyExtractor = keyExtractor;\n    this.keyIndex = new Map();\n  }\n\n  // add an item to the buffer\n  add(item: T): void {\n    const key = this.keyExtractor(item);\n\n    // check if item already exists\n    const existingIndex = this.keyIndex.get(key);\n    if (existingIndex !== undefined) {\n      // update existing item\n      this.buffer[existingIndex] = item;\n      return;\n    }\n\n    // evict least recently used item if at capacity\n    const evicted = this.buffer[this.writeIndex];\n    if (evicted !== null) {\n      const evictedKey = this.keyExtractor(evicted);\n      this.keyIndex.delete(evictedKey);\n    }\n\n    // add new item\n    this.buffer[this.writeIndex] = item;\n    this.keyIndex.set(key, this.writeIndex);\n\n    // update write index and size\n    this.writeIndex = (this.writeIndex + 1) % this.capacity;\n    this.size = Math.min(this.size + 1, this.capacity);\n  }\n\n  // get an item from the buffer\n  get(key: string): T | null {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return null;\n\n    return this.buffer[index];\n  }\n\n  // check if an item exists in the buffer\n  has(key: string): boolean {\n    return this.keyIndex.has(key);\n  }\n\n  // remove an item from the buffer\n  remove(key: string): void {\n    const index = this.keyIndex.get(key);\n    if (index === undefined) return;\n\n    // remove item from buffer\n    this.buffer[index] = null;\n    this.keyIndex.delete(key);\n\n    // update size\n    this.size = Math.max(this.size - 1, 0);\n  }\n\n  // get all items from the buffer\n  getAll(): T[] {\n    const result: T[] = [];\n\n    // iterate over buffer in order of insertion\n    for (let i = 0; i < this.size; i++) {\n      // calculate index of item in buffer\n      const index =\n        (this.writeIndex - this.size + i + this.capacity) % this.capacity;\n      // add item to result if not null\n      const item = this.buffer[index];\n      if (item !== null) {\n        result.push(item);\n      }\n    }\n    return result;\n  }\n\n  // get the size of the buffer\n  getSize(): number {\n    return this.size;\n  }\n\n  // clear the buffer\n  clear(): void {\n    this.buffer = new Array(this.capacity).fill(null);\n    this.keyIndex.clear();\n    this.writeIndex = 0;\n    this.size = 0;\n  }\n}\n\n// event ring buffer implementation\nexport class EventRingBuffer {\n  private buffer: RingBuffer<BufferedEvent>;\n\n  constructor(capacity: number = 100) {\n    this.buffer = new RingBuffer<BufferedEvent>(capacity, (event) => event.id);\n  }\n\n  // add an event to the buffer\n  add(event: BufferedEvent): void {\n    this.buffer.add(event);\n  }\n\n  // check if an event exists in the buffer\n  has(eventId: string): boolean {\n    return this.buffer.has(eventId);\n  }\n\n  // get all events since a given event id\n  getEventsSince(lastEventId: string): BufferedEvent[] {\n    const allEvents = this.buffer.getAll();\n    const result: BufferedEvent[] = [];\n    // flag to track if we've found the last event\n    let foundLastEvent = false;\n\n    // iterate over all events\n    for (const event of allEvents) {\n      // if found, add to result\n      if (foundLastEvent) {\n        result.push(event);\n        // if not found, check if it's the last event\n      } else if (event.id === lastEventId) {\n        foundLastEvent = true;\n      }\n    }\n    return result;\n  }\n\n  clear(): void {\n    this.buffer.clear();\n  }\n}\n"],"mappings":";;;;AAIA,IAAM,aAAN,MAAoB;CAClB,AAAO;CACP,AAAO;CACP,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CAER,YAAY,UAAkB,cAAmC;AAC/D,MAAI,YAAY,EACd,OAAM,gBAAgB,aACpB,YACA,UACA,iBACD;AAGH,OAAK,WAAW;AAChB,OAAK,SAAS,IAAI,MAAM,SAAS,CAAC,KAAK,KAAK;AAC5C,OAAK,aAAa;AAClB,OAAK,OAAO;AACZ,OAAK,eAAe;AACpB,OAAK,2BAAW,IAAI,KAAK;;CAI3B,IAAI,MAAe;EACjB,MAAM,MAAM,KAAK,aAAa,KAAK;EAGnC,MAAM,gBAAgB,KAAK,SAAS,IAAI,IAAI;AAC5C,MAAI,kBAAkB,QAAW;AAE/B,QAAK,OAAO,iBAAiB;AAC7B;;EAIF,MAAM,UAAU,KAAK,OAAO,KAAK;AACjC,MAAI,YAAY,MAAM;GACpB,MAAM,aAAa,KAAK,aAAa,QAAQ;AAC7C,QAAK,SAAS,OAAO,WAAW;;AAIlC,OAAK,OAAO,KAAK,cAAc;AAC/B,OAAK,SAAS,IAAI,KAAK,KAAK,WAAW;AAGvC,OAAK,cAAc,KAAK,aAAa,KAAK,KAAK;AAC/C,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,KAAK,SAAS;;CAIpD,IAAI,KAAuB;EACzB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW,QAAO;AAEhC,SAAO,KAAK,OAAO;;CAIrB,IAAI,KAAsB;AACxB,SAAO,KAAK,SAAS,IAAI,IAAI;;CAI/B,OAAO,KAAmB;EACxB,MAAM,QAAQ,KAAK,SAAS,IAAI,IAAI;AACpC,MAAI,UAAU,OAAW;AAGzB,OAAK,OAAO,SAAS;AACrB,OAAK,SAAS,OAAO,IAAI;AAGzB,OAAK,OAAO,KAAK,IAAI,KAAK,OAAO,GAAG,EAAE;;CAIxC,SAAc;EACZ,MAAM,SAAc,EAAE;AAGtB,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,MAAM,KAAK;GAElC,MAAM,SACH,KAAK,aAAa,KAAK,OAAO,IAAI,KAAK,YAAY,KAAK;GAE3D,MAAM,OAAO,KAAK,OAAO;AACzB,OAAI,SAAS,KACX,QAAO,KAAK,KAAK;;AAGrB,SAAO;;CAIT,UAAkB;AAChB,SAAO,KAAK;;CAId,QAAc;AACZ,OAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC,KAAK,KAAK;AACjD,OAAK,SAAS,OAAO;AACrB,OAAK,aAAa;AAClB,OAAK,OAAO;;;AAKhB,IAAa,kBAAb,MAA6B;CAC3B,AAAQ;CAER,YAAY,WAAmB,KAAK;AAClC,OAAK,SAAS,IAAI,WAA0B,WAAW,UAAU,MAAM,GAAG;;CAI5E,IAAI,OAA4B;AAC9B,OAAK,OAAO,IAAI,MAAM;;CAIxB,IAAI,SAA0B;AAC5B,SAAO,KAAK,OAAO,IAAI,QAAQ;;CAIjC,eAAe,aAAsC;EACnD,MAAM,YAAY,KAAK,OAAO,QAAQ;EACtC,MAAM,SAA0B,EAAE;EAElC,IAAI,iBAAiB;AAGrB,OAAK,MAAM,SAAS,UAElB,KAAI,eACF,QAAO,KAAK,MAAM;WAET,MAAM,OAAO,YACtB,kBAAiB;AAGrB,SAAO;;CAGT,QAAc;AACZ,OAAK,OAAO,OAAO"}

package/dist/stream/defaults.js

@@ -3,8 +3,6 @@ const streamDefaults = {
 	bufferSize: 100,
 	maxEventSize: 1 * 1024 * 1024,
 	bufferTTL: 600 * 1e3,
-	cleanupInterval: 300 * 1e3,
-	maxPersistentBuffers: 1e4,
 	heartbeatInterval: 10 * 1e3,
 	maxActiveStreams: 1e3,
 	disconnectGraceMs: 15e3

package/dist/stream/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","names":[],"sources":["../../src/stream/defaults.ts"],"sourcesContent":["export const streamDefaults = {\n  bufferSize: 100,\n  // 1 MiB. SSE carries only short JSON control messages — JSON_ARRAY result\n  // rows (already row-size-bounded by the warehouse) plus warehouse-readiness\n  // and error events. ARROW_STREAM never uses SSE: the raw Arrow IPC bytes\n  // stream back on the query response body (`_handleArrowStreamQuery`).\n  maxEventSize: 1 * 1024 * 1024,\n  bufferTTL: 10 * 60 * 1000, // 10 minutes\n  cleanupInterval: 5 * 60 * 1000, // 5 minutes\n  maxPersistentBuffers: 10000, // 10000 buffers\n  heartbeatInterval: 10 * 1000, // 10 seconds\n  maxActiveStreams: 1000, // 1000 streams\n  disconnectGraceMs: 15_000, // 15 seconds\n} as const;\n"],"mappings":";AAAA,MAAa,iBAAiB;CAC5B,YAAY;CAKZ,cAAc,IAAI,OAAO;CACzB,WAAW,MAAU;CACrB,iBAAiB,MAAS;CAC1B,sBAAsB;CACtB,mBAAmB,KAAK;CACxB,kBAAkB;CAClB,mBAAmB;CACpB"}
+{"version":3,"file":"defaults.js","names":[],"sources":["../../src/stream/defaults.ts"],"sourcesContent":["export const streamDefaults = {\n  bufferSize: 100,\n  // 1 MiB. SSE carries only short JSON control messages — JSON_ARRAY result\n  // rows (already row-size-bounded by the warehouse) plus warehouse-readiness\n  // and error events. ARROW_STREAM never uses SSE: the raw Arrow IPC bytes\n  // stream back on the query response body (`_handleArrowStreamQuery`).\n  maxEventSize: 1 * 1024 * 1024,\n  bufferTTL: 10 * 60 * 1000, // 10 minutes\n  heartbeatInterval: 10 * 1000, // 10 seconds\n  maxActiveStreams: 1000, // 1000 streams\n  disconnectGraceMs: 15_000, // 15 seconds\n} as const;\n"],"mappings":";AAAA,MAAa,iBAAiB;CAC5B,YAAY;CAKZ,cAAc,IAAI,OAAO;CACzB,WAAW,MAAU;CACrB,mBAAmB,KAAK;CACxB,kBAAkB;CAClB,mBAAmB;CACpB"}

package/dist/stream/stream-manager.d.ts

@@ -20,10 +20,10 @@ declare class StreamManager {
   private _combineSignals;
   private _broadcastEventsToClients;
   private _broadcastErrorToClients;
+  private _finalizeStream;
   private _closeAllClients;
   private _scheduleGraceAbort;
-  private _clearGraceTimer;
-  private _cleanupStream;
+  private _scheduleRemovalAfterTTL;
   private _categorizeError;
 }
 //#endregion

package/dist/stream/stream-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-manager.d.ts","names":[],"sources":["../../src/stream/stream-manager.ts"],"mappings":";;;;;cAgBa,aAAA;EAAA,QACH,gBAAA;EAAA,QACA,cAAA;EAAA,QACA,SAAA;EAAA,QACA,YAAA;EAAA,QACA,SAAA;EAAA,QACA,iBAAA;cAEI,OAAA,GAAU,YAAA;EAahB,MAAA,CACJ,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,MAAA,EAAQ,WAAA,KAAgB,cAAA,sBAClC,OAAA,GAAU,YAAA,EACV,QAAA,YACC,OAAA;EAsCH,QAAA,CAAA;EAaA,cAAA,CAAA;EAAA,QAKc,uBAAA;EAAA,QA4EA,gBAAA;EAAA,QA4EA,6BAAA;EAAA,QAkHN,eAAA;EAAA,QA6BA,yBAAA;EAAA,QAaA,wBAAA;EAAA,QAyBA,gBAAA;EAAA,QASA,mBAAA;EAAA,QAmBA,gBAAA;EAAA,QAQA,cAAA;EAAA,QAUA,gBAAA;AAAA"}
+{"version":3,"file":"stream-manager.d.ts","names":[],"sources":["../../src/stream/stream-manager.ts"],"mappings":";;;;;cAiBa,aAAA;EAAA,QACH,gBAAA;EAAA,QACA,cAAA;EAAA,QACA,SAAA;EAAA,QACA,YAAA;EAAA,QACA,SAAA;EAAA,QACA,iBAAA;cAEI,OAAA,GAAU,YAAA;EAahB,MAAA,CACJ,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,MAAA,EAAQ,WAAA,KAAgB,cAAA,sBAClC,OAAA,GAAU,YAAA,EACV,QAAA,YACC,OAAA;EAsCH,QAAA,CAAA;EAaA,cAAA,CAAA;EAAA,QAKc,uBAAA;EAAA,QA+EA,gBAAA;EAAA,QAiFA,6BAAA;EAAA,QAwGN,eAAA;EAAA,QA6BA,yBAAA;EAAA,QAaA,wBAAA;EAAA,QAwBA,eAAA;EAAA,QAYA,gBAAA;EAAA,QAUA,mBAAA;EAAA,QAuBA,wBAAA;EAAA,QA8BA,gBAAA;AAAA"}

package/dist/stream/stream-manager.js

@@ -6,6 +6,7 @@ import { streamDefaults } from "./defaults.js";
 import { SSEErrorCode } from "./types.js";
 import { StreamValidator } from "./validator.js";
 import { SSEWriter } from "./sse-writer.js";
+import { clearGraceTimer, clearRemovalTimer } from "./timers.js";
 import { StreamRegistry } from "./stream-registry.js";
 import { randomUUID } from "node:crypto";
 import { context } from "@opentelemetry/api";
@@ -67,7 +68,8 @@ var StreamManager = class {
 				}
 			} else this.sseWriter.writeBufferOverflowWarning(res, validEventId);
 		}
-		this._clearGraceTimer(streamEntry);
+		clearGraceTimer(streamEntry);
+		clearRemovalTimer(streamEntry);
 		streamEntry.clients.add(res);
 		streamEntry.lastAccess = Date.now();
 		const combinedSignal = this._combineSignals(streamEntry.abortController.signal, options?.userSignal);
@@ -83,14 +85,14 @@ var StreamManager = class {
 			streamEntry.clients.delete(res);
 			this.activeOperations.delete(streamOperation);
 			if (streamEntry.clients.size === 0 && !streamEntry.isCompleted) this._scheduleGraceAbort(streamEntry);
-			if (streamEntry.isCompleted && streamEntry.clients.size === 0) setTimeout(() => {
-				if (streamEntry.clients.size === 0) this.streamRegistry.remove(streamEntry.streamId);
-			}, this.bufferTTL);
+			this._scheduleRemovalAfterTTL(streamEntry);
 		});
 		if (streamEntry.isCompleted) {
 			res.end();
 			this.activeOperations.delete(streamOperation);
 			clearInterval(heartbeat);
+			streamEntry.clients.delete(res);
+			this._scheduleRemovalAfterTTL(streamEntry);
 		}
 	}
 	async _createNewStream(res, handler, options, ownerKey) {
@@ -128,6 +130,7 @@ var StreamManager = class {
 			this.activeOperations.delete(streamOperation);
 			streamEntry.clients.delete(res);
 			if (streamEntry.clients.size === 0 && !streamEntry.isCompleted) this._scheduleGraceAbort(streamEntry);
+			this._scheduleRemovalAfterTTL(streamEntry);
 		});
 		await this._processGeneratorInBackground(streamEntry);
 		clearInterval(heartbeat);
@@ -155,10 +158,7 @@ var StreamManager = class {
 					this._broadcastEventsToClients(streamEntry, eventId, event);
 					streamEntry.lastAccess = Date.now();
 				}
-				streamEntry.isCompleted = true;
-				this._clearGraceTimer(streamEntry);
-				this._closeAllClients(streamEntry);
-				this._cleanupStream(streamEntry);
+				this._finalizeStream(streamEntry);
 			} catch (error) {
 				const rawMsg = error instanceof Error ? error.message : "Internal server error";
 				const clientMsg = error instanceof AppKitError ? error.clientMessage : "Internal server error";
@@ -167,10 +167,7 @@ var StreamManager = class {
 				const errorCode = this._categorizeError(error);
 				if (errorCode === SSEErrorCode.STREAM_ABORTED) {
 					logger.info("Stream aborted by client (code=%s)", errorCode);
-					streamEntry.isCompleted = true;
-					this._clearGraceTimer(streamEntry);
-					this._closeAllClients(streamEntry);
-					this._cleanupStream(streamEntry);
+					this._finalizeStream(streamEntry);
 					return;
 				}
 				logger.error("Stream execution failed: %s (code=%s upstreamCode=%s)", rawMsg, errorCode, upstreamCode ?? "n/a");
@@ -186,8 +183,7 @@ var StreamManager = class {
 					timestamp: Date.now()
 				});
 				this._broadcastErrorToClients(streamEntry, errorEventId, clientMsg, errorCode, true, upstreamCode);
-				streamEntry.isCompleted = true;
-				this._clearGraceTimer(streamEntry);
+				this._finalizeStream(streamEntry);
 			}
 		});
 	}
@@ -215,11 +211,18 @@ var StreamManager = class {
 			if (closeClients) client.end();
 		}
 	}
+	_finalizeStream(streamEntry) {
+		streamEntry.isCompleted = true;
+		clearGraceTimer(streamEntry);
+		this._closeAllClients(streamEntry);
+		this._scheduleRemovalAfterTTL(streamEntry);
+	}
 	_closeAllClients(streamEntry) {
 		for (const client of streamEntry.clients) if (!client.writableEnded) client.end();
+		streamEntry.clients.clear();
 	}
 	_scheduleGraceAbort(streamEntry) {
-		this._clearGraceTimer(streamEntry);
+		clearGraceTimer(streamEntry);
 		const timer = setTimeout(() => {
 			streamEntry.disconnectGraceTimer = void 0;
 			if (streamEntry.clients.size === 0 && !streamEntry.isCompleted) streamEntry.abortController.abort(new DOMException("Client disconnected (grace expired)", "AbortError"));
@@ -227,16 +230,15 @@ var StreamManager = class {
 		timer.unref?.();
 		streamEntry.disconnectGraceTimer = timer;
 	}
-	_clearGraceTimer(streamEntry) {
-		if (streamEntry.disconnectGraceTimer) {
-			clearTimeout(streamEntry.disconnectGraceTimer);
-			streamEntry.disconnectGraceTimer = void 0;
-		}
-	}
-	_cleanupStream(streamEntry) {
-		if (streamEntry.clients.size === 0) setTimeout(() => {
-			if (streamEntry.clients.size === 0) this.streamRegistry.remove(streamEntry.streamId);
+	_scheduleRemovalAfterTTL(streamEntry) {
+		if (!streamEntry.isCompleted || streamEntry.clients.size > 0) return;
+		clearRemovalTimer(streamEntry);
+		streamEntry.lastAccess = Date.now();
+		streamEntry.removalTimer = setTimeout(() => {
+			streamEntry.removalTimer = void 0;
+			if (streamEntry.clients.size === 0 && Date.now() - streamEntry.lastAccess >= this.bufferTTL) this.streamRegistry.remove(streamEntry.streamId);
 		}, this.bufferTTL);
+		streamEntry.removalTimer.unref?.();
 	}
 	_categorizeError(error) {
 		if (error instanceof Error) {