@rocicorp/zero 1.11.0-canary.2 → 1.11.0-canary.20

package/out/zero-cache/src/services/plannerz.d.ts

@@ -0,0 +1,163 @@
+import type { LogContext } from '@rocicorp/logger';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { Database } from '../../../zqlite/src/db.ts';
+import { type SampleValueKind } from '../../../zqlite/src/sqlite-stat4-sample.ts';
+import type { NormalizedZeroConfig as ZeroConfig } from '../config/normalize.ts';
+/**
+ * A fixed glossary, sent with every bundle. The audience is a language model
+ * that has the user's codebase but has never seen these statistics, and would
+ * otherwise read a sampled estimate as an exact count.
+ */
+declare const ABOUT: {
+    readonly whatThisIs: string;
+    readonly stat1Format: string;
+    readonly stat4Format: string;
+    readonly howThePlannerUsesThis: readonly [string, string, string];
+    readonly whatYouCanChange: readonly [string, 'A `limit`, which lets the planner stop early.', string, 'The planner flags in `server.planner`.'];
+    readonly caveats: readonly [string, string, string];
+};
+export type Stat1 = {
+    /** The raw `sqlite_stat1.stat` text, in case a flag is not parsed here. */
+    raw: string;
+    /** Estimated rows in the table. */
+    rows: number;
+    /**
+     * Average rows per distinct key prefix: the first entry is for a 1-column
+     * prefix, the second for 2 columns, and so on.
+     */
+    avgRowsPerPrefix: number[];
+    /** Non-numeric tokens, e.g. `unordered`, `noskipscan`, `sz=N`. */
+    flags: string[];
+};
+/** A `sqlite_stat4` sample with its values replaced by their types. */
+export type Stat4Sample = {
+    nEq: number[];
+    nLt: number[];
+    nDLt: number[];
+    /** One entry per key column, plus the trailing rowid. */
+    sample: SampleValueKind[];
+};
+/**
+ * A digest of an index's `sqlite_stat4` histogram, one entry per key prefix
+ * depth. This is what the default response carries: a full histogram runs to
+ * hundreds of samples per index, which is a lot of context to spend on data an
+ * LLM would only summarize anyway.
+ */
+export type Stat4PrefixSummary = {
+    /** Rows equal to the most common sampled key at this depth. */
+    maxRowsPerKey: number;
+    /** Median rows per sampled key at this depth. */
+    medianRowsPerKey: number;
+    /**
+     * Lower bound on distinct keys at this depth, from the last sample's count of
+     * distinct values less than it.
+     */
+    estimatedDistinctKeys: number;
+};
+export type Stat4Summary = {
+    samples: number;
+    /** The type of each key column, and of the trailing rowid. */
+    sampleKinds: SampleValueKind[];
+    /** One entry per key prefix depth: 1 column, then 2, and so on. */
+    perPrefix: Stat4PrefixSummary[];
+};
+export type IndexStats = {
+    name: string;
+    columns: {
+        name: string;
+        dir: 'ASC' | 'DESC';
+    }[];
+    unique: boolean;
+    partial: boolean;
+    stat1?: Stat1 | undefined;
+    stat4?: Stat4Summary | undefined;
+    /** The full histogram, only with `?stat4=full`. */
+    stat4Samples?: Stat4Sample[] | undefined;
+};
+export type ColumnStats = {
+    name: string;
+    dataType: string;
+    nullable: boolean;
+    /** The ZQL type, or `null` for a column clients cannot see. */
+    zqlType: string | null;
+    backfilling?: true | undefined;
+};
+export type TableStats = {
+    name: string;
+    columns: ColumnStats[];
+    primaryKey: string[] | undefined;
+    estimatedRows: number | undefined;
+    syncable: boolean;
+    indexes: IndexStats[];
+};
+export type PlannerzBundle = {
+    about: typeof ABOUT;
+    server: {
+        zeroVersion: string;
+        sqliteVersion: string;
+        replicaWatermark: string | undefined;
+        generatedAt: string;
+        planner: {
+            enableQueryPlanner: boolean;
+            enableCorrelatedPredicatePushdown: boolean;
+            enablePlannerAwarePushdown: boolean;
+        };
+    };
+    statsQuality: {
+        stat1Present: boolean;
+        stat4Rows: number;
+        method: string;
+        tablesWithoutStats: string[];
+    };
+    tables: TableStats[];
+};
+/**
+ * Parses a `sqlite_stat1.stat` value.
+ *
+ * @visibleForTesting
+ */
+export declare function parseStat1(raw: string): Stat1;
+/**
+ * Builds the `/plannerz` bundle from the replica's catalog, `sqlite_stat*`
+ * tables and the server config. No user table is read, so the cost does not
+ * depend on how much data the replica holds.
+ *
+ * @visibleForTesting
+ */
+export declare function buildPlannerzBundle(lc: LogContext, config: ZeroConfig, opts?: BundleOptions): PlannerzBundle;
+export type BundleOptions = {
+    /** Include the full `sqlite_stat4` histogram, not just the digest. */
+    fullStat4?: boolean | undefined;
+};
+/** @visibleForTesting */
+export declare function buildPlannerzBundleFromDB(lc: LogContext, db: Database, config: ZeroConfig, opts?: BundleOptions): PlannerzBundle;
+/**
+ * Digests an index's stat4 samples.
+ *
+ * Note that `nLt` and `nDLt` are stored as text, so SQL cannot order the
+ * samples by them numerically. This works off the whole set rather than
+ * relying on the samples' order: the highest `nDLt` is a lower bound on the
+ * distinct keys, since the sample holding it has that many distinct keys below
+ * it plus itself.
+ *
+ * @visibleForTesting
+ */
+export declare function summarizeStat4(samples: Stat4Sample[]): Stat4Summary;
+/**
+ * Serves the replica's schema, indexes and SQLite statistics for consumption by
+ * a language model, so that it can advise on query rewrites and indexes.
+ *
+ * Row data is never returned. See `designs/003_replica_stats_endpoint.md`.
+ *
+ * This is available to the operator password as well as the admin password
+ * (see `--operator-password`). That does not extend to `/plannerz/analyze`,
+ * which runs caller-supplied queries against the replica and so must require
+ * the admin password (`isAdminPasswordValid`).
+ *
+ * HTTP query parameters:
+ * * `pretty`: indents the JSON
+ * * `stat4=full`: includes the full sqlite_stat4 histogram, which is large
+ */
+export declare function handlePlannerzRequest(lc: LogContext, config: ZeroConfig, req: FastifyRequest, res: FastifyReply): Promise<void>;
+export {};
+//# sourceMappingURL=plannerz.d.ts.map

package/out/zero-cache/src/services/plannerz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plannerz.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/services/plannerz.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAC,QAAQ,EAAC,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,4CAA4C,CAAC;AACpD,OAAO,KAAK,EAAC,oBAAoB,IAAI,UAAU,EAAC,MAAM,wBAAwB,CAAC;AAuB/E;;;;GAIG;AACH,QAAA,MAAM,KAAK;aACT,UAAU;aAIV,WAAW;aAMX,WAAW;aAOX,qBAAqB;aAUrB,gBAAgB,oBAGd,+CAA+C,UAG/C,wCAAwC;aAE1C,OAAO;CASC,CAAC;AAEX,MAAM,MAAM,KAAK,GAAG;IAClB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,kEAAkE;IAClE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,yDAAyD;IACzD,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,mEAAmE;IACnE,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAAA;KAAC,EAAE,CAAC;IAC/C,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACjC,mDAAmD;IACnD,YAAY,CAAC,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;QACrC,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE;YACP,kBAAkB,EAAE,OAAO,CAAC;YAC5B,iCAAiC,EAAE,OAAO,CAAC;YAC3C,0BAA0B,EAAE,OAAO,CAAC;SACrC,CAAC;KACH,CAAC;IACF,YAAY,EAAE;QACZ,YAAY,EAAE,OAAO,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,kBAAkB,EAAE,MAAM,EAAE,CAAC;KAC9B,CAAC;IACF,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAmB7C;AAmCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,aAAkB,GACvB,cAAc,CAGhB;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC,CAAC;AAEF,yBAAyB;AACzB,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,aAAkB,GACvB,cAAc,CAsHhB;AAiBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,YAAY,CAuBnE;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,YAAY,iBA0BlB"}

package/out/zero-cache/src/services/plannerz.js

@@ -0,0 +1,267 @@
+import { getOperatorAccess, getServerVersion } from "../config/zero-config.js";
+import { Database } from "../../../zqlite/src/db.js";
+import { computeZqlSpecsFromLiteSpecs, listIndexes, listTables } from "../db/lite-tables.js";
+import { decodeSampleKinds } from "../../../zqlite/src/sqlite-stat4-sample.js";
+import { getReplicationState } from "./replicator/schema/replication-state.js";
+import { StatementRunner } from "../db/statements.js";
+import { _usingCtx } from "../../../_virtual/_@oxc-project_runtime@0.130.0/helpers/usingCtx.js";
+import auth from "basic-auth";
+//#region ../zero-cache/src/services/plannerz.ts
+/**
+* How the statistics in the replica were gathered. zero-cache only ever runs
+* `PRAGMA optimize`, and always under an `analysis_limit`, which samples rather
+* than scanning. A replica that someone ran `ANALYZE` on by hand has better
+* statistics, which is visible in `sqlite_stat4` having rows at all.
+*/
+var APPROXIMATE_METHOD = "PRAGMA optimize under an analysis_limit. Row counts and per-key averages are sampled estimates, and sqlite_stat4 is not collected.";
+var FULL_METHOD = "ANALYZE, with no analysis limit. sqlite_stat4 has rows, so a full ANALYZE ran against this replica at some point.";
+/**
+* A fixed glossary, sent with every bundle. The audience is a language model
+* that has the user's codebase but has never seen these statistics, and would
+* otherwise read a sampled estimate as an exact count.
+*/
+var ABOUT = {
+	whatThisIs: "Schema, indexes and SQLite statistics for the SQLite replica that zero-cache queries. Use it to decide how to rewrite ZQL queries and which indexes to add. It contains no row data.",
+	stat1Format: "sqlite_stat1.stat is \"<rows> <avg rows per distinct 1-column prefix> <... per 2-column prefix> ...\", parsed here into `rows` and `avgRowsPerPrefix`. NULLs count as ordinary values, so a sparse column looks less selective than it is. Trailing flags such as \"unordered\", \"noskipscan\" and \"sz=N\" are kept in `flags`.",
+	stat4Format: "sqlite_stat4 is a per-index histogram. For each sample, `nEq` is the rows equal to it, `nLt` the rows less than it, and `nDLt` the distinct values less than it, one entry per key column. A large `nEq` next to a small `nDLt` means a skewed column, where the average in stat1 hides the common values. Sample values are never returned: `sample` reports only each key column’s type.",
+	howThePlannerUsesThis: [
+		"Cost comes from SQLite scanstatus estimates for the SQL each source connection would run, so the statistics here are what the planner sees.",
+		"Join fanout comes from sqlite_stat4, else sqlite_stat1, else a default of 3. With no stat4 (the usual case) fanout on a nullable foreign key is overestimated, because stat1 counts NULLs.",
+		"The planner chooses per join whether to run it as a semi-join or to flip it so the child drives. An index that matches the child’s constraint plus ordering is what makes a flip cheap."
+	],
+	whatYouCanChange: [
+		"The ZQL query: `whereExists` vs `related`, the order of conditions, and ordering that matches an existing index.",
+		"A `limit`, which lets the planner stop early.",
+		"Indexes: add them in Postgres, not on the replica. The replica copies upstream indexes, so a new index reaches it through replication.",
+		"The planner flags in `server.planner`."
+	],
+	caveats: [
+		"Row counts are estimates from the statistics, not COUNT(*). This endpoint never scans a table.",
+		"Statistics are as of the last time they were gathered, which SQLite does not record. A table whose size changed a lot since then can be far off.",
+		"Tables in `tables` with `syncable: false` cannot be queried by clients: they lack a primary key or unique index, or every column has a type ZQL does not support."
+	]
+};
+/**
+* Parses a `sqlite_stat1.stat` value.
+*
+* @visibleForTesting
+*/
+function parseStat1(raw) {
+	const tokens = raw.trim().split(SEPARATOR).filter(Boolean);
+	const numbers = [];
+	const flags = [];
+	for (const token of tokens) if (flags.length === 0 && COUNT.test(token)) numbers.push(parseInt(token, 10));
+	else flags.push(token);
+	return {
+		raw,
+		rows: numbers[0] ?? 0,
+		avgRowsPerPrefix: numbers.slice(1),
+		flags
+	};
+}
+/** Whitespace between the counts in a `sqlite_stat1` or `sqlite_stat4` value. */
+var SEPARATOR = /\s+/;
+/** A count, as opposed to a trailing flag such as `unordered` or `sz=N`. */
+var COUNT = /^\d+$/;
+function tableExists(db, name) {
+	return db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`).all(name).length > 0;
+}
+function parseCounts(raw) {
+	return raw.trim().split(SEPARATOR).filter(Boolean).map((n) => parseInt(n, 10));
+}
+/**
+* Builds the `/plannerz` bundle from the replica's catalog, `sqlite_stat*`
+* tables and the server config. No user table is read, so the cost does not
+* depend on how much data the replica holds.
+*
+* @visibleForTesting
+*/
+function buildPlannerzBundle(lc, config, opts = {}) {
+	try {
+		var _usingCtx$1 = _usingCtx();
+		return buildPlannerzBundleFromDB(lc, _usingCtx$1.u(new Database(lc, config.replica.file, { readonly: true })), config, opts);
+	} catch (_) {
+		_usingCtx$1.e = _;
+	} finally {
+		_usingCtx$1.d();
+	}
+}
+/** @visibleForTesting */
+function buildPlannerzBundleFromDB(lc, db, config, opts = {}) {
+	const tables = listReplicaTables(lc, db);
+	const indexes = listIndexes(db);
+	const zqlSpecs = computeZqlSpecsFromLiteSpecs(tables, indexes, { includeBackfillingColumns: false }, void 0, void 0, lc);
+	const stat1Present = tableExists(db, "sqlite_stat1");
+	const stat1ByTableAndIndex = /* @__PURE__ */ new Map();
+	const statsByTable = /* @__PURE__ */ new Map();
+	if (stat1Present) for (const { tbl, idx, stat } of db.prepare(`SELECT tbl, idx, stat FROM sqlite_stat1`).all()) {
+		const parsed = parseStat1(stat);
+		if (idx !== null) stat1ByTableAndIndex.set(`${tbl}.${idx}`, parsed);
+		if (idx === null || !statsByTable.has(tbl)) statsByTable.set(tbl, parsed);
+	}
+	const stat4Present = tableExists(db, "sqlite_stat4");
+	const stat4ByTableAndIndex = /* @__PURE__ */ new Map();
+	let stat4Rows = 0;
+	if (stat4Present) for (const { tbl, idx, neq, nlt, ndlt, sample } of db.prepare(`SELECT tbl, idx, neq, nlt, ndlt, sample FROM sqlite_stat4`).all()) {
+		stat4Rows++;
+		const samples = stat4ByTableAndIndex.get(`${tbl}.${idx}`) ?? [];
+		samples.push({
+			nEq: parseCounts(neq),
+			nLt: parseCounts(nlt),
+			nDLt: parseCounts(ndlt),
+			sample: decodeSampleKinds(sample)
+		});
+		stat4ByTableAndIndex.set(`${tbl}.${idx}`, samples);
+	}
+	const indexesByTable = /* @__PURE__ */ new Map();
+	for (const index of indexes) {
+		const key = `${index.tableName}.${index.name}`;
+		const stat4 = stat4ByTableAndIndex.get(key);
+		const forTable = indexesByTable.get(index.tableName) ?? [];
+		forTable.push({
+			name: index.name,
+			columns: Object.entries(index.columns).map(([name, dir]) => ({
+				name,
+				dir
+			})),
+			unique: index.unique,
+			partial: index.partial === true,
+			stat1: stat1ByTableAndIndex.get(key),
+			stat4: stat4?.length ? summarizeStat4(stat4) : void 0,
+			stat4Samples: opts.fullStat4 && stat4?.length ? stat4 : void 0
+		});
+		indexesByTable.set(index.tableName, forTable);
+	}
+	const tablesWithoutStats = [];
+	const tableStats = tables.map((table) => {
+		const zqlSpec = zqlSpecs.get(table.name)?.zqlSpec;
+		if (!statsByTable.has(table.name)) tablesWithoutStats.push(table.name);
+		const backfilling = new Set(table.backfilling ?? []);
+		return {
+			name: table.name,
+			columns: Object.entries(table.columns).map(([name, spec]) => ({
+				name,
+				dataType: spec.dataType,
+				nullable: !spec.notNull,
+				zqlType: zqlSpec?.[name]?.type ?? null,
+				...backfilling.has(name) ? { backfilling: true } : {}
+			})),
+			primaryKey: table.primaryKey ? [...table.primaryKey] : void 0,
+			estimatedRows: statsByTable.get(table.name)?.rows,
+			syncable: zqlSpec !== void 0,
+			indexes: indexesByTable.get(table.name) ?? []
+		};
+	});
+	return {
+		about: ABOUT,
+		server: {
+			zeroVersion: getServerVersion(config),
+			sqliteVersion: sqliteVersion(db),
+			replicaWatermark: replicaWatermark(lc, db),
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			planner: {
+				enableQueryPlanner: config.enableQueryPlanner,
+				enableCorrelatedPredicatePushdown: config.enableCorrelatedPredicatePushdown !== false,
+				enablePlannerAwarePushdown: config.enablePlannerAwarePushdown !== false
+			}
+		},
+		statsQuality: {
+			stat1Present,
+			stat4Rows,
+			method: stat4Rows > 0 ? FULL_METHOD : APPROXIMATE_METHOD,
+			tablesWithoutStats
+		},
+		tables: tableStats
+	};
+}
+/**
+* Lists the replica's tables, tolerating a replica that has no metadata tables
+* yet. `listTables` reads `_zero.tableMetadata` for backfill status, which does
+* not exist until initial sync has created it. Reporting the schema without
+* backfill status beats failing the whole request.
+*/
+function listReplicaTables(lc, db) {
+	try {
+		return listTables(db);
+	} catch (e) {
+		lc.debug?.("reading table metadata failed; listing tables without it", e);
+		return listTables(db, true, false);
+	}
+}
+/**
+* Digests an index's stat4 samples.
+*
+* Note that `nLt` and `nDLt` are stored as text, so SQL cannot order the
+* samples by them numerically. This works off the whole set rather than
+* relying on the samples' order: the highest `nDLt` is a lower bound on the
+* distinct keys, since the sample holding it has that many distinct keys below
+* it plus itself.
+*
+* @visibleForTesting
+*/
+function summarizeStat4(samples) {
+	const depth = Math.max(...samples.map((s) => s.nEq.length));
+	const perPrefix = [];
+	for (let d = 0; d < depth; d++) {
+		const counts = samples.map((s) => s.nEq[d]).filter((n) => n !== void 0).sort((a, b) => a - b);
+		const maxDistinctBelow = Math.max(...samples.map((s) => s.nDLt[d]).filter((n) => n !== void 0));
+		perPrefix.push({
+			maxRowsPerKey: counts.at(-1),
+			medianRowsPerKey: counts[Math.floor((counts.length - 1) / 2)],
+			estimatedDistinctKeys: maxDistinctBelow + 1
+		});
+	}
+	return {
+		samples: samples.length,
+		sampleKinds: samples[0].sample,
+		perPrefix
+	};
+}
+function sqliteVersion(db) {
+	const [{ version }] = db.prepare(`SELECT sqlite_version() AS version`).all();
+	return version;
+}
+function replicaWatermark(lc, db) {
+	try {
+		return getReplicationState(new StatementRunner(db)).stateVersion;
+	} catch (e) {
+		lc.debug?.("could not read replication state", e);
+		return;
+	}
+}
+/**
+* Serves the replica's schema, indexes and SQLite statistics for consumption by
+* a language model, so that it can advise on query rewrites and indexes.
+*
+* Row data is never returned. See `designs/003_replica_stats_endpoint.md`.
+*
+* This is available to the operator password as well as the admin password
+* (see `--operator-password`). That does not extend to `/plannerz/analyze`,
+* which runs caller-supplied queries against the replica and so must require
+* the admin password (`isAdminPasswordValid`).
+*
+* HTTP query parameters:
+* * `pretty`: indents the JSON
+* * `stat4=full`: includes the full sqlite_stat4 histogram, which is large
+*/
+async function handlePlannerzRequest(lc, config, req, res) {
+	if (getOperatorAccess(lc, config, auth(req)?.pass) === void 0) {
+		res.code(401).header("WWW-Authenticate", "Basic realm=\"Plannerz Protected Area\"").send("Unauthorized");
+		return;
+	}
+	const query = req.query;
+	const indent = query.pretty !== void 0 ? 2 : void 0;
+	let bundle;
+	try {
+		bundle = buildPlannerzBundle(lc, config, { fullStat4: query.stat4 === "full" });
+	} catch (e) {
+		lc.error?.("error building plannerz bundle", e);
+		await res.code(500).send({ error: String(e) });
+		return;
+	}
+	await res.header("Content-Type", "application/json").send(JSON.stringify(bundle, null, indent));
+}
+//#endregion
+export { handlePlannerzRequest };
+
+//# sourceMappingURL=plannerz.js.map

package/out/zero-cache/src/services/plannerz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plannerz.js","names":[],"sources":["../../../../../zero-cache/src/services/plannerz.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport auth from 'basic-auth';\nimport type {FastifyReply, FastifyRequest} from 'fastify';\nimport {Database} from '../../../zqlite/src/db.ts';\nimport {\n  decodeSampleKinds,\n  type SampleValueKind,\n} from '../../../zqlite/src/sqlite-stat4-sample.ts';\nimport type {NormalizedZeroConfig as ZeroConfig} from '../config/normalize.ts';\nimport {getOperatorAccess, getServerVersion} from '../config/zero-config.ts';\nimport {\n  computeZqlSpecsFromLiteSpecs,\n  listIndexes,\n  listTables,\n} from '../db/lite-tables.ts';\nimport {StatementRunner} from '../db/statements.ts';\nimport {getReplicationState} from './replicator/schema/replication-state.ts';\n\n/**\n * How the statistics in the replica were gathered. zero-cache only ever runs\n * `PRAGMA optimize`, and always under an `analysis_limit`, which samples rather\n * than scanning. A replica that someone ran `ANALYZE` on by hand has better\n * statistics, which is visible in `sqlite_stat4` having rows at all.\n */\nconst APPROXIMATE_METHOD =\n  'PRAGMA optimize under an analysis_limit. Row counts and per-key averages ' +\n  'are sampled estimates, and sqlite_stat4 is not collected.';\nconst FULL_METHOD =\n  'ANALYZE, with no analysis limit. sqlite_stat4 has rows, so a full ANALYZE ' +\n  'ran against this replica at some point.';\n\n/**\n * A fixed glossary, sent with every bundle. The audience is a language model\n * that has the user's codebase but has never seen these statistics, and would\n * otherwise read a sampled estimate as an exact count.\n */\nconst ABOUT = {\n  whatThisIs:\n    'Schema, indexes and SQLite statistics for the SQLite replica that ' +\n    'zero-cache queries. Use it to decide how to rewrite ZQL queries and ' +\n    'which indexes to add. It contains no row data.',\n  stat1Format:\n    'sqlite_stat1.stat is \"<rows> <avg rows per distinct 1-column prefix> ' +\n    '<... per 2-column prefix> ...\", parsed here into `rows` and ' +\n    '`avgRowsPerPrefix`. NULLs count as ordinary values, so a sparse column ' +\n    'looks less selective than it is. Trailing flags such as \"unordered\", ' +\n    '\"noskipscan\" and \"sz=N\" are kept in `flags`.',\n  stat4Format:\n    'sqlite_stat4 is a per-index histogram. For each sample, `nEq` is the ' +\n    'rows equal to it, `nLt` the rows less than it, and `nDLt` the distinct ' +\n    'values less than it, one entry per key column. A large `nEq` next to a ' +\n    'small `nDLt` means a skewed column, where the average in stat1 hides ' +\n    'the common values. Sample values are never returned: `sample` reports ' +\n    'only each key column’s type.',\n  howThePlannerUsesThis: [\n    'Cost comes from SQLite scanstatus estimates for the SQL each source ' +\n      'connection would run, so the statistics here are what the planner sees.',\n    'Join fanout comes from sqlite_stat4, else sqlite_stat1, else a default ' +\n      'of 3. With no stat4 (the usual case) fanout on a nullable foreign key ' +\n      'is overestimated, because stat1 counts NULLs.',\n    'The planner chooses per join whether to run it as a semi-join or to flip ' +\n      'it so the child drives. An index that matches the child’s ' +\n      'constraint plus ordering is what makes a flip cheap.',\n  ],\n  whatYouCanChange: [\n    'The ZQL query: `whereExists` vs `related`, the order of conditions, and ' +\n      'ordering that matches an existing index.',\n    'A `limit`, which lets the planner stop early.',\n    'Indexes: add them in Postgres, not on the replica. The replica copies ' +\n      'upstream indexes, so a new index reaches it through replication.',\n    'The planner flags in `server.planner`.',\n  ],\n  caveats: [\n    'Row counts are estimates from the statistics, not COUNT(*). This ' +\n      'endpoint never scans a table.',\n    'Statistics are as of the last time they were gathered, which SQLite does ' +\n      'not record. A table whose size changed a lot since then can be far off.',\n    'Tables in `tables` with `syncable: false` cannot be queried by clients: ' +\n      'they lack a primary key or unique index, or every column has a type ' +\n      'ZQL does not support.',\n  ],\n} as const;\n\nexport type Stat1 = {\n  /** The raw `sqlite_stat1.stat` text, in case a flag is not parsed here. */\n  raw: string;\n  /** Estimated rows in the table. */\n  rows: number;\n  /**\n   * Average rows per distinct key prefix: the first entry is for a 1-column\n   * prefix, the second for 2 columns, and so on.\n   */\n  avgRowsPerPrefix: number[];\n  /** Non-numeric tokens, e.g. `unordered`, `noskipscan`, `sz=N`. */\n  flags: string[];\n};\n\n/** A `sqlite_stat4` sample with its values replaced by their types. */\nexport type Stat4Sample = {\n  nEq: number[];\n  nLt: number[];\n  nDLt: number[];\n  /** One entry per key column, plus the trailing rowid. */\n  sample: SampleValueKind[];\n};\n\n/**\n * A digest of an index's `sqlite_stat4` histogram, one entry per key prefix\n * depth. This is what the default response carries: a full histogram runs to\n * hundreds of samples per index, which is a lot of context to spend on data an\n * LLM would only summarize anyway.\n */\nexport type Stat4PrefixSummary = {\n  /** Rows equal to the most common sampled key at this depth. */\n  maxRowsPerKey: number;\n  /** Median rows per sampled key at this depth. */\n  medianRowsPerKey: number;\n  /**\n   * Lower bound on distinct keys at this depth, from the last sample's count of\n   * distinct values less than it.\n   */\n  estimatedDistinctKeys: number;\n};\n\nexport type Stat4Summary = {\n  samples: number;\n  /** The type of each key column, and of the trailing rowid. */\n  sampleKinds: SampleValueKind[];\n  /** One entry per key prefix depth: 1 column, then 2, and so on. */\n  perPrefix: Stat4PrefixSummary[];\n};\n\nexport type IndexStats = {\n  name: string;\n  columns: {name: string; dir: 'ASC' | 'DESC'}[];\n  unique: boolean;\n  partial: boolean;\n  stat1?: Stat1 | undefined;\n  stat4?: Stat4Summary | undefined;\n  /** The full histogram, only with `?stat4=full`. */\n  stat4Samples?: Stat4Sample[] | undefined;\n};\n\nexport type ColumnStats = {\n  name: string;\n  dataType: string;\n  nullable: boolean;\n  /** The ZQL type, or `null` for a column clients cannot see. */\n  zqlType: string | null;\n  backfilling?: true | undefined;\n};\n\nexport type TableStats = {\n  name: string;\n  columns: ColumnStats[];\n  primaryKey: string[] | undefined;\n  estimatedRows: number | undefined;\n  syncable: boolean;\n  indexes: IndexStats[];\n};\n\nexport type PlannerzBundle = {\n  about: typeof ABOUT;\n  server: {\n    zeroVersion: string;\n    sqliteVersion: string;\n    replicaWatermark: string | undefined;\n    generatedAt: string;\n    planner: {\n      enableQueryPlanner: boolean;\n      enableCorrelatedPredicatePushdown: boolean;\n      enablePlannerAwarePushdown: boolean;\n    };\n  };\n  statsQuality: {\n    stat1Present: boolean;\n    stat4Rows: number;\n    method: string;\n    tablesWithoutStats: string[];\n  };\n  tables: TableStats[];\n};\n\n/**\n * Parses a `sqlite_stat1.stat` value.\n *\n * @visibleForTesting\n */\nexport function parseStat1(raw: string): Stat1 {\n  const tokens = raw.trim().split(SEPARATOR).filter(Boolean);\n  const numbers: number[] = [];\n  const flags: string[] = [];\n  for (const token of tokens) {\n    // Only leading tokens are counts; anything else is a flag, even if it\n    // parses as a number (e.g. a future \"sz=N\" spelled differently).\n    if (flags.length === 0 && COUNT.test(token)) {\n      numbers.push(parseInt(token, 10));\n    } else {\n      flags.push(token);\n    }\n  }\n  return {\n    raw,\n    rows: numbers[0] ?? 0,\n    avgRowsPerPrefix: numbers.slice(1),\n    flags,\n  };\n}\n\n/** Whitespace between the counts in a `sqlite_stat1` or `sqlite_stat4` value. */\nconst SEPARATOR = /\\s+/;\n/** A count, as opposed to a trailing flag such as `unordered` or `sz=N`. */\nconst COUNT = /^\\d+$/;\n\ntype Stat1Row = {tbl: string; idx: string | null; stat: string};\ntype Stat4Row = {\n  tbl: string;\n  idx: string;\n  neq: string;\n  nlt: string;\n  ndlt: string;\n  sample: Buffer;\n};\n\nfunction tableExists(db: Database, name: string): boolean {\n  return (\n    db\n      .prepare(\n        `SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`,\n      )\n      .all(name).length > 0\n  );\n}\n\nfunction parseCounts(raw: string): number[] {\n  return raw\n    .trim()\n    .split(SEPARATOR)\n    .filter(Boolean)\n    .map(n => parseInt(n, 10));\n}\n\n/**\n * Builds the `/plannerz` bundle from the replica's catalog, `sqlite_stat*`\n * tables and the server config. No user table is read, so the cost does not\n * depend on how much data the replica holds.\n *\n * @visibleForTesting\n */\nexport function buildPlannerzBundle(\n  lc: LogContext,\n  config: ZeroConfig,\n  opts: BundleOptions = {},\n): PlannerzBundle {\n  using db = new Database(lc, config.replica.file, {readonly: true});\n  return buildPlannerzBundleFromDB(lc, db, config, opts);\n}\n\nexport type BundleOptions = {\n  /** Include the full `sqlite_stat4` histogram, not just the digest. */\n  fullStat4?: boolean | undefined;\n};\n\n/** @visibleForTesting */\nexport function buildPlannerzBundleFromDB(\n  lc: LogContext,\n  db: Database,\n  config: ZeroConfig,\n  opts: BundleOptions = {},\n): PlannerzBundle {\n  const tables = listReplicaTables(lc, db);\n  const indexes = listIndexes(db);\n  const zqlSpecs = computeZqlSpecsFromLiteSpecs(\n    tables,\n    indexes,\n    {includeBackfillingColumns: false},\n    undefined,\n    undefined,\n    lc,\n  );\n\n  const stat1Present = tableExists(db, 'sqlite_stat1');\n  const stat1ByTableAndIndex = new Map<string, Stat1>();\n  const statsByTable = new Map<string, Stat1>();\n  if (stat1Present) {\n    for (const {tbl, idx, stat} of db\n      .prepare(`SELECT tbl, idx, stat FROM sqlite_stat1`)\n      .all() as Stat1Row[]) {\n      const parsed = parseStat1(stat);\n      if (idx !== null) {\n        stat1ByTableAndIndex.set(`${tbl}.${idx}`, parsed);\n      }\n      // Every row for a table starts with the table's row count. A row with a\n      // null `idx` is written for a table with no indexes, and is preferred\n      // because it is about the table itself.\n      if (idx === null || !statsByTable.has(tbl)) {\n        statsByTable.set(tbl, parsed);\n      }\n    }\n  }\n\n  const stat4Present = tableExists(db, 'sqlite_stat4');\n  const stat4ByTableAndIndex = new Map<string, Stat4Sample[]>();\n  let stat4Rows = 0;\n  if (stat4Present) {\n    for (const {tbl, idx, neq, nlt, ndlt, sample} of db\n      .prepare(`SELECT tbl, idx, neq, nlt, ndlt, sample FROM sqlite_stat4`)\n      .all() as Stat4Row[]) {\n      stat4Rows++;\n      const samples = stat4ByTableAndIndex.get(`${tbl}.${idx}`) ?? [];\n      samples.push({\n        nEq: parseCounts(neq),\n        nLt: parseCounts(nlt),\n        nDLt: parseCounts(ndlt),\n        // Values are deliberately dropped here: only the types are reported.\n        sample: decodeSampleKinds(sample),\n      });\n      stat4ByTableAndIndex.set(`${tbl}.${idx}`, samples);\n    }\n  }\n\n  const indexesByTable = new Map<string, IndexStats[]>();\n  for (const index of indexes) {\n    const key = `${index.tableName}.${index.name}`;\n    const stat4 = stat4ByTableAndIndex.get(key);\n    const forTable = indexesByTable.get(index.tableName) ?? [];\n    forTable.push({\n      name: index.name,\n      columns: Object.entries(index.columns).map(([name, dir]) => ({\n        name,\n        dir,\n      })),\n      unique: index.unique,\n      partial: index.partial === true,\n      stat1: stat1ByTableAndIndex.get(key),\n      stat4: stat4?.length ? summarizeStat4(stat4) : undefined,\n      stat4Samples: opts.fullStat4 && stat4?.length ? stat4 : undefined,\n    });\n    indexesByTable.set(index.tableName, forTable);\n  }\n\n  const tablesWithoutStats: string[] = [];\n  const tableStats = tables.map(table => {\n    const zqlSpec = zqlSpecs.get(table.name)?.zqlSpec;\n    if (!statsByTable.has(table.name)) {\n      tablesWithoutStats.push(table.name);\n    }\n    const backfilling = new Set(table.backfilling ?? []);\n    return {\n      name: table.name,\n      columns: Object.entries(table.columns).map(([name, spec]) => ({\n        name,\n        dataType: spec.dataType,\n        nullable: !spec.notNull,\n        zqlType: zqlSpec?.[name]?.type ?? null,\n        ...(backfilling.has(name) ? {backfilling: true as const} : {}),\n      })),\n      primaryKey: table.primaryKey ? [...table.primaryKey] : undefined,\n      estimatedRows: statsByTable.get(table.name)?.rows,\n      syncable: zqlSpec !== undefined,\n      indexes: indexesByTable.get(table.name) ?? [],\n    };\n  });\n\n  return {\n    about: ABOUT,\n    server: {\n      zeroVersion: getServerVersion(config),\n      sqliteVersion: sqliteVersion(db),\n      replicaWatermark: replicaWatermark(lc, db),\n      generatedAt: new Date().toISOString(),\n      planner: {\n        enableQueryPlanner: config.enableQueryPlanner,\n        // Both default to on, matching services/analyze.ts.\n        enableCorrelatedPredicatePushdown:\n          config.enableCorrelatedPredicatePushdown !== false,\n        enablePlannerAwarePushdown: config.enablePlannerAwarePushdown !== false,\n      },\n    },\n    statsQuality: {\n      stat1Present,\n      stat4Rows,\n      method: stat4Rows > 0 ? FULL_METHOD : APPROXIMATE_METHOD,\n      tablesWithoutStats,\n    },\n    tables: tableStats,\n  };\n}\n\n/**\n * Lists the replica's tables, tolerating a replica that has no metadata tables\n * yet. `listTables` reads `_zero.tableMetadata` for backfill status, which does\n * not exist until initial sync has created it. Reporting the schema without\n * backfill status beats failing the whole request.\n */\nfunction listReplicaTables(lc: LogContext, db: Database) {\n  try {\n    return listTables(db);\n  } catch (e) {\n    lc.debug?.('reading table metadata failed; listing tables without it', e);\n    return listTables(db, true, false);\n  }\n}\n\n/**\n * Digests an index's stat4 samples.\n *\n * Note that `nLt` and `nDLt` are stored as text, so SQL cannot order the\n * samples by them numerically. This works off the whole set rather than\n * relying on the samples' order: the highest `nDLt` is a lower bound on the\n * distinct keys, since the sample holding it has that many distinct keys below\n * it plus itself.\n *\n * @visibleForTesting\n */\nexport function summarizeStat4(samples: Stat4Sample[]): Stat4Summary {\n  const depth = Math.max(...samples.map(s => s.nEq.length));\n  const perPrefix: Stat4PrefixSummary[] = [];\n  for (let d = 0; d < depth; d++) {\n    const counts = samples\n      .map(s => s.nEq[d])\n      .filter(n => n !== undefined)\n      .sort((a, b) => a - b);\n    const maxDistinctBelow = Math.max(\n      ...samples.map(s => s.nDLt[d]).filter(n => n !== undefined),\n    );\n    perPrefix.push({\n      maxRowsPerKey: counts.at(-1)!,\n      medianRowsPerKey: counts[Math.floor((counts.length - 1) / 2)],\n      estimatedDistinctKeys: maxDistinctBelow + 1,\n    });\n  }\n  return {\n    samples: samples.length,\n    // Every sample of an index describes the same columns.\n    sampleKinds: samples[0].sample,\n    perPrefix,\n  };\n}\n\nfunction sqliteVersion(db: Database): string {\n  const [{version}] = db\n    .prepare(`SELECT sqlite_version() AS version`)\n    .all() as {version: string}[];\n  return version;\n}\n\nfunction replicaWatermark(lc: LogContext, db: Database): string | undefined {\n  try {\n    return getReplicationState(new StatementRunner(db)).stateVersion;\n  } catch (e) {\n    // A replica that has not finished initial sync has no replication state.\n    lc.debug?.('could not read replication state', e);\n    return undefined;\n  }\n}\n\n/**\n * Serves the replica's schema, indexes and SQLite statistics for consumption by\n * a language model, so that it can advise on query rewrites and indexes.\n *\n * Row data is never returned. See `designs/003_replica_stats_endpoint.md`.\n *\n * This is available to the operator password as well as the admin password\n * (see `--operator-password`). That does not extend to `/plannerz/analyze`,\n * which runs caller-supplied queries against the replica and so must require\n * the admin password (`isAdminPasswordValid`).\n *\n * HTTP query parameters:\n * * `pretty`: indents the JSON\n * * `stat4=full`: includes the full sqlite_stat4 histogram, which is large\n */\nexport async function handlePlannerzRequest(\n  lc: LogContext,\n  config: ZeroConfig,\n  req: FastifyRequest,\n  res: FastifyReply,\n) {\n  const credentials = auth(req);\n  if (getOperatorAccess(lc, config, credentials?.pass) === undefined) {\n    void res\n      .code(401)\n      .header('WWW-Authenticate', 'Basic realm=\"Plannerz Protected Area\"')\n      .send('Unauthorized');\n    return;\n  }\n\n  const query = req.query as Record<string, unknown>;\n  const indent = query.pretty !== undefined ? 2 : undefined;\n  let bundle: PlannerzBundle;\n  try {\n    bundle = buildPlannerzBundle(lc, config, {\n      fullStat4: query.stat4 === 'full',\n    });\n  } catch (e) {\n    lc.error?.('error building plannerz bundle', e);\n    await res.code(500).send({error: String(e)});\n    return;\n  }\n  await res\n    .header('Content-Type', 'application/json')\n    .send(JSON.stringify(bundle, null, indent));\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/profz.d.ts

@@ -0,0 +1,30 @@
+import type { LogContext } from '@rocicorp/logger';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import type { NormalizedZeroConfig } from '../config/normalize.ts';
+import { type Worker } from '../types/processes.ts';
+/**
+ * Serves CPU profiles. This is available to the operator password as well as
+ * the admin password (see `--operator-password`), so it must never serve
+ * application data to `operator` access.
+ *
+ * A V8 CPU profile describes code, not data: function names, script URLs and
+ * positions, and sample timings. The exception is a regular expression, which
+ * V8 names after its source (`RegExp: <source>`). zero-cache compiles `LIKE`
+ * and `ILIKE` patterns from client queries into regular expressions, so their
+ * sources are redacted for `operator` access. See {@link redactProfile}.
+ */
+export declare function handleProfzRequest(lc: LogContext, config: Pick<NormalizedZeroConfig, 'adminPassword' | 'operatorPassword'>, req: FastifyRequest, res: FastifyReply, getWorker?: (() => Promise<Worker>) | undefined, forcedWorker?: string | undefined, localProcessName?: string): Promise<void>;
+export declare function handleProfrmzRequest(lc: LogContext, config: NormalizedZeroConfig, req: FastifyRequest, res: FastifyReply, getWorker?: (() => Promise<Worker>) | undefined): Promise<void>;
+/**
+ * Returns a copy of the V8 CPU `profile` with the source of every regular
+ * expression replaced, since a pattern built at runtime can contain
+ * application data (e.g. a `LIKE` pattern from a client query). The time spent
+ * in regular expressions is still attributed to them.
+ *
+ * A `profile` that is not in the expected format is withheld rather than
+ * served unredacted.
+ *
+ * @visibleForTesting
+ */
+export declare function redactProfile(profile: unknown): unknown;
+//# sourceMappingURL=profz.d.ts.map

package/out/zero-cache/src/services/profz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profz.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/services/profz.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAEjE,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAI/B;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,eAAe,GAAG,kBAAkB,CAAC,EACxE,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,YAAY,EACjB,SAAS,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,EAC/C,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,EACjC,gBAAgB,GAAE,MAAqB,GACtC,OAAO,CAAC,IAAI,CAAC,CAuIf;AAED,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,YAAY,EACjB,SAAS,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,GAC9C,OAAO,CAAC,IAAI,CAAC,CAyDf;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAgBvD"}