kitcn 0.16.0 → 0.17.0

package/dist/watcher.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Dt as generateMeta, F as resolveRunDeps, Ot as getConvexConfig, j as resolveConfiguredBackend, kt as logger, q as withLocalCodegenEnv } from "./backend-core-DqPydYyx.mjs";
+import { At as PARSE_SNAPSHOT_SUFFIX, Dt as generateMeta, F as resolveRunDeps, Ot as getConvexConfig, j as resolveConfiguredBackend, kt as logger, q as withLocalCodegenEnv } from "./backend-core-BsKP1LVg.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -44,7 +44,7 @@ function shouldIgnoreWatchPath(watchedPath, functionsDir, outputFile) {
 	if (normalizedPath === generatedFile) return true;
 	if (normalizedPath === convexGeneratedDir || normalizedPath.startsWith(`${convexGeneratedDir}${path.sep}`)) return true;
 	if (normalizedPath === generatedDir || normalizedPath.startsWith(`${generatedDir}${path.sep}`)) return true;
-	return normalizedPath.endsWith(".runtime.ts") || normalizedPath.endsWith(".kitcn-parse.ts");
+	return normalizedPath.endsWith(".runtime.ts") || normalizedPath.endsWith(PARSE_SNAPSHOT_SUFFIX);
 }
 async function runWatcherCodegen(params, deps = {}) {
 	const resolveRunDepsFn = deps.resolveRunDeps ?? resolveRunDeps;

package/dist/{where-clause-compiler-WF9UcrAB.d.ts → where-clause-compiler-BRhLW1dp.d.ts}

@@ -2436,6 +2436,19 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _compareByOrderSpecs;
   private _getTableConfigByDbName;
   private _matchLike;
+  /**
+   * True when the expression can be fully enforced by Convex's own `.filter()`.
+   *
+   * `_toConvexExpression` compiles the string/array operators to `() => true`
+   * because Convex filters cannot run JavaScript string methods; those are
+   * evaluated later by `_evaluatePostFetchFilter`. Pushing such an expression
+   * into `.filter()` is not merely useless, it is wrong in two ways: a `take()`
+   * downstream spends its budget on rows that have not been filtered yet, and a
+   * surrounding `NOT` turns the `true` placeholder into `q.not(true)`, which
+   * matches nothing. So the caller must know whether Convex can carry the whole
+   * expression before relying on it.
+   */
+  private _isConvexEnforceableFilter;
   /**
    * Evaluate a filter expression against a fetched row
    * Used for post-fetch filtering (string operators, etc.)
@@ -2461,6 +2474,15 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _resolveWithVariantsState;
   private _assertPolymorphicAliasCollisions;
   private _synthesizePolymorphicRows;
+  /**
+   * Validate role-scoped policies for every table this read plan touches before
+   * relations are loaded. Relation loaders skip work when a parent page is
+   * empty, so per-row evaluation alone would make a misconfigured table fail
+   * only once it holds rows. Mirrors the `_loadRelations` depth budget so the
+   * plan walked here matches the plan that would be executed.
+   */
+  private _assertRlsSelectPlan;
+  private _assertRelationCountRlsPlan;
   private _finalizeRows;
   private _getSchemaDefinitionOrThrow;
   private _applyEqBounds;
@@ -2470,7 +2492,36 @@ declare class GelRelationalQuery<TSchema extends TablesRelationalConfig, TTableC
   private _isPredicateWhereClause;
   private _createFilterOperators;
   private _resolveWhereCallbackExpression;
+  /**
+   * Read an id-only `where` through the primary key instead of scanning for it.
+   *
+   * The where-clause compiler is built from declared indexes only, and `_id` is
+   * never one of them, so an `id` filter can never be index-selected: it lands
+   * in the post-filters and the stream walks the creation-time index until it
+   * happens on the row. `db.get()` reads exactly the rows asked for, so the ids
+   * are fetched directly and replayed as a creation-time-ordered stream — the
+   * order the scan would have produced, so stage order and cursors are the same.
+   *
+   * Returns null when something else already owns the read: a pinned index, an
+   * index the compiler did select, a `where(predicate)`, or an `orderBy` that
+   * walks a different index.
+   */
+  private _buildIdLookupStream;
   private _buildBasePipelineStream;
+  /**
+   * Stream equivalent of the `db.query(...)` chain, used when a post-fetch
+   * filter has to run in JavaScript before `limit` or a page boundary can be
+   * applied. `filterWith` evaluates the predicate as rows are pulled, so
+   * `take`/`paginate` size by matches instead of by scanned rows.
+   *
+   * It deliberately mirrors the index and order decisions the caller already
+   * made for the plain query rather than re-deriving them, so switching to the
+   * stream cannot change which index is scanned or in what direction.
+   *
+   * Returns null when the schema definition needed by `stream()` is missing;
+   * the caller then falls back to its plain-query path.
+   */
+  private _buildResidualFilterStream;
   private _buildUnionSourceStream;
   private _applyFlatMapStage;
   private _applyPipelineStages;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",

package/skills/kitcn/SKILL.md

@@ -484,6 +484,7 @@ Before calling a feature done:
 - `references/features/aggregates.md`: aggregate component patterns
 - `references/features/migrations.md`: built-in online data migrations (defineMigration, CLI, deploy, drift). Load when: task involves data backfills, optional→required field hardening, field renames/removals, type narrowing, or `kitcn migrate` CLI commands. Skip for backward-compatible changes (new optional fields, new tables, code-level defaults).
 - `references/features/create-plugins.md`: canonical plugin authoring patterns (split package entries, token config, scaffold/lockfile/CLI manifest rules). Load when: creating or refactoring plugins.
+- `references/features/ratelimit.md`: ratelimit runtime accounting (shard budget dealing, `check()` vs `limit()`, snapshot conversion, read accuracy, failure modes). Load when: tuning `shards`, reading remaining quota, or debugging unexpected denials. Skip for plain `ratelimit.middleware()` wiring, which `setup/server.md` owns.
 - `references/features/auth.md`: full Better Auth core flow
 - `references/features/auth-admin.md`: admin plugin details
 - `references/features/auth-organizations.md`: org/multi-tenant plugin details

package/skills/kitcn/references/features/create-plugins.md

@@ -107,7 +107,7 @@ Trigger composition rules:
 3. Non-function helpers live under `convex/<paths.lib>/plugins/<plugin>/...`.
 4. `kitcn codegen` must not generate plugin runtime modules.
 5. Scaffold templates need stable template IDs.
-6. `add` can merge/upsert scaffold mappings; never clobber custom files unless overwrite is explicit.
+6. `add` can merge/upsert scaffold mappings; never clobber custom files unless overwrite is explicit. Plan files of kind `scaffold`, `config`, and `env` need explicit consent to replace an existing file, so a builder that renders a whole template is safe by default. Only a builder that reads the existing source and patches it may set `requiresExplicitOverwrite: false`. List every shape another kitcn plugin can leave behind in `managedBaselineContent` so a file kitcn itself wrote is still recognized as managed. A refused file makes `add` exit non-zero and report `refused` in `--json`.
 7. `add --dry-run`, `add --diff [path]`, and `add --view [path]` preview one shared install plan: scaffold files, env bootstrap, `kitcn.json`, schema registration, lockfile write, dependency install status, codegen/hooks, env reminders.
 8. Preview comparisons for `.ts`, `.tsx`, `.js`, `.jsx`, and `.json` should be semantic enough to ignore formatter-only churn.
 9. `view` is read-only plan inspection. Default template source is lockfile mappings, fallback is the resolved preset, `--preset` forces preset selection.

package/skills/kitcn/references/features/orm.md

@@ -922,12 +922,22 @@ rlsPolicy("admin_only", {
   using: (ctx, t) => eq(t.ownerId, ctx.viewerId),
 });
 
-// Provide roleResolver
+// roleResolver is required by any policy scoped to a named role
 const ormDb = orm.db(ctx, {
   rls: { ctx, roleResolver: (ctx) => ctx.roles ?? [] },
 });
 ```
 
+**Important:** a policy scoped to a named role throws `RLS_ROLE_RESOLVER_REQUIRED` when no `roleResolver` is configured, instead of granting the policy to every caller. Queries and mutations validate this per table before reading rows, so an empty table throws too. The SQL pseudo-roles `public`, `current_user`, `current_role`, and `session_user` apply to everyone and need no resolver.
+
+### Null handling
+
+Policy expressions use SQL null semantics: a comparison against a missing document field or a missing context value is unknown, and unknown denies. An unauthenticated caller (`ctx.viewerId` is `undefined`) never matches rows whose column is unset. Use `isNull` to match absent columns on purpose.
+
+### Relations
+
+`with` enforces the related table's policies, and for many-to-many relations the junction table's policies as well, so a caller only traverses links it may read.
+
 **Important:** `ctx.db` bypasses RLS. Only `ctx.orm` enforces policies. FK cascade fan-out also bypasses child-table RLS.
 
 ## Triggers

package/skills/kitcn/references/features/ratelimit.md

@@ -0,0 +1,105 @@
+# Ratelimit Reference
+
+Runtime accounting for the ratelimit plugin. Prerequisites: `setup/server.md` (scaffold, buckets, `ratelimit.middleware()`).
+
+The API mirrors Upstash Ratelimit (`limit`, `check`, `getRemaining`, `resetUsedTokens`, `blockUntilReady`). This file covers only where kitcn's behavior is load-bearing or differs.
+
+## Algorithms
+
+```ts
+import { MINUTE, Ratelimit } from 'kitcn/ratelimit';
+
+Ratelimit.fixedWindow(limit, window, options?);            // limit tokens per window
+Ratelimit.slidingWindow(limit, window, options?);          // weighted across window boundary
+Ratelimit.tokenBucket(refillRate, interval, maxTokens, options?);
+```
+
+`options`: `shards`, `maxReserved`, `capacity` (fixedWindow only), `start` (fixedWindow only). `maxReserved` must be finite and non-negative when present. Reserved fixed-window and token-bucket requests have uncapped headroom when it is omitted.
+
+`capacity` is the stored ceiling, `limit` is the per-window refill. Set `capacity > limit` for burst headroom.
+
+## Sharding — delta from parity
+
+`shards > 1` distributes writes to cut contention. The configured budget is **dealt** across shards, never duplicated.
+
+- Shares are whole tokens that sum to the configured budget, with the remainder going to the low-numbered shards. `fixedWindow(5, '1 m', { shards: 2 })` deals `3` and `2`, and enforces exactly 5/min.
+- Fractional totals deal their whole portion first and retain the fraction on one shard, so whole requests are not stranded.
+- Whole-token `maxReserved` headroom is dealt the same way, so configured reservations remain usable under sharding.
+- `tokenBucket` deals `maxTokens` and allocates `refillRate` in proportion to each shard's capacity share, so uneven capacities refill without clipping the configured total.
+- One call spends from one shard, so `count` can never exceed that shard's share. Aim for a share of ten or more times your largest `count`.
+- Builders **throw** when `limit / shards`, `capacity / shards`, or `maxTokens / shards` drops below `1`. `setDynamicLimit()` rejects non-positive, non-finite, or unservable overrides before writing them.
+- The ephemeral block cache is keyed per shard, requested count, and reservation mode, so an exhausted shard never blocks peers and a failed large or ordinary request never blocks a smaller or reserved one. Cache writes prune expired variants, skip infinite resets, and retain at most 32 variants per identifier.
+- Preferred shards are tried first; if none can serve the request, the limiter reads each remaining candidate concurrently before denying it.
+- Failure `reset` is the earliest retry across both cached and freshly evaluated shards.
+
+Default to `shards: 1`. Raise it only after observing write contention on hot identifiers.
+
+## Reads
+
+| Call | Shards read | Accuracy |
+| --- | --- | --- |
+| `getRemaining(id)` | all | exact at one common read timestamp |
+| `getValue(id, { sampleShards })` | `sampleShards` (default 1) | estimate, scaled up by the sampled share |
+| `limit()` / `check()` → `remaining` | the serving shard | estimate under `shards > 1` |
+
+Use `getRemaining()` for quota headers and banners. Use `getValue()` for the React hook and custom projections where a cheap read matters more than exactness.
+
+Fixed-window projections scale by stored `capacity`; the response `limit` remains the configured per-window refill.
+`getRemaining()` evaluates every raw shard at one common timestamp and sums each shard's independently usable whole tokens. It never lets a full shard absorb another shard's refill, nets reserved debt against an open peer, or combines unusable fractions across isolated shards.
+
+## `check()` vs `limit()`
+
+`check()` runs the same evaluation as `limit()` for the requested `count` / `rate` and never writes. A `check()` that returns `success: true` is what `limit()` would decide at that moment.
+
+```ts
+const gate = await limiter.check(userId, { count: 5 });
+if (!gate.success) return { retryAt: gate.reset };
+```
+
+## Snapshots
+
+`getValue()` returns tokens **left**; `calculateRatelimit()` takes stored **state**. Sliding windows store the used count, so the two differ. Always convert:
+
+```ts
+import { calculateRatelimit, snapshotToState } from 'kitcn/ratelimit';
+
+const snapshot = await limiter.getValue('user_123');
+const result = calculateRatelimit(
+  snapshotToState(snapshot),
+  snapshot.config,
+  Date.now(),
+  1
+);
+```
+
+`result.remaining` is floored to `0`. `result.remainingRaw` is exact and goes negative when the request overdraws — use it to rank shards or size a backoff.
+
+`RatelimitSnapshot.shard` is the sampled shard holding the most tokens, not "the" shard.
+`RatelimitSnapshot.state` retains the projected aggregate plus every sampled shard state. Sliding windows preserve `value`, `auxValue`, `ts`, and `auxTs`. When every shard is sampled, `snapshotToState()` preserves independent saturation and decay across later projections; partial samples remain estimates.
+
+For denied reserved fixed-window and token-bucket requests, `reset` is when the request fits within `maxReserved`, not when all debt reaches zero.
+
+A request larger than every shard's capacity plus finite reservation headroom can never succeed. It returns `reason: 'requestTooLarge'` and `reset: 0` without reading shard state. When only smaller shards cannot serve a request, they are excluded from retry calculations. Fresh, full, and partial snapshot projections preserve permanent denial as `retryAfter: Infinity`, and the React hook reports `ok: false` without scheduling a retry timer. Reduce `count`, reduce `shards`, or raise the configured capacity.
+
+## Convex constraints
+
+- `blockUntilReady()` needs `setTimeout`, so it only runs in actions or non-Convex runtimes. It throws with that guidance inside queries and mutations. `limit()` and `check()` never touch timers.
+- `limit()`, `resetUsedTokens()`, and `setDynamicLimit()` write state, so they need a mutation `ctx.db`. `check()`, `getValue()`, `getRemaining()`, and `getDynamicLimit()` are read-only and work from a query reader.
+- Missing tables throw actionable setup guidance — run `bunx kitcn add ratelimit` and register `ratelimitExtension()`.
+
+## Failure modes
+
+| Option | Effect |
+| --- | --- |
+| `failureMode: 'closed'` (default) | a timeout denies the request, `reason: 'timeout'` |
+| `failureMode: 'open'` | a timeout allows the request, `success: true` with `reason: 'timeout'` |
+
+`reason` is `'timeout' \| 'cacheBlock' \| 'denyList' \| 'requestTooLarge'`. `success: true` with `reason: 'timeout'` is reachable only under `failureMode: 'open'` — do not treat `reason` as proof of denial.
+
+## Dynamic limits
+
+Requires `dynamicLimits: true` in the constructor, otherwise `setDynamicLimit()` / `getDynamicLimit()` throw. The override replaces `limit` (or `refillRate`) at read time and must be a positive finite budget that every configured shard can serve. Setting or clearing it advances the limiter's cache generation, invalidates snapshots and ephemeral block decisions, and prevents older in-flight operations from restoring them.
+
+```ts
+await limiter.setDynamicLimit({ limit: 20 }); // false clears the override
+```

package/skills/kitcn/references/setup/server.md

@@ -365,7 +365,7 @@ import { ratelimitExtension } from "../lib/plugins/ratelimit/schema";
 export default defineSchema(tables).extend(ratelimitExtension());
 ```
 
-Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()` from mutation builders. Use the default bucket for normal writes and reserve `.meta({ ratelimit: ... })` for named overrides.
+Create `convex/lib/plugins/ratelimit/plugin.ts` and call `ratelimit.middleware()` from mutation builders. Use the default bucket for normal writes and reserve `.meta({ ratelimit: ... })` for named overrides. Runtime accounting (`shards`, `check()`, snapshots, read accuracy) lives in `features/ratelimit.md`.
 
 Use `RatelimitPlugin` from `kitcn/ratelimit`:
 

package/dist/query-options-C96zLANM.js

@@ -1,121 +0,0 @@
-import { getFunctionName } from "convex/server";
-
-//#region src/crpc/query-options.ts
-/**
-* Query options factory for Convex query function subscriptions.
-* Requires `convexQueryClient.queryFn()` set as the default `queryFn` globally.
-*/
-function convexQuery(funcRef, args, meta, opts) {
-	const finalArgs = args ?? {};
-	const isSkip = finalArgs === "skip";
-	const funcName = getFunctionName(funcRef);
-	const [namespace, fnName] = funcName.split(":");
-	const authType = meta?.[namespace]?.[fnName]?.auth;
-	const skipUnauth = opts?.skipUnauth;
-	return {
-		queryKey: [
-			"convexQuery",
-			funcName,
-			isSkip ? "skip" : finalArgs
-		],
-		staleTime: Number.POSITIVE_INFINITY,
-		refetchInterval: false,
-		refetchOnMount: false,
-		refetchOnReconnect: false,
-		refetchOnWindowFocus: false,
-		...isSkip ? { enabled: false } : {},
-		meta: {
-			authType,
-			skipUnauth,
-			subscribe: true
-		}
-	};
-}
-/**
-* Query options factory for Convex action functions.
-* Actions are NOT reactive - they follow normal TanStack Query semantics.
-*
-* @example
-* ```ts
-* useQuery(convexAction(api.ai.generate, { prompt }))
-* ```
-*
-* @example With additional options (use spread):
-* ```ts
-* useQuery({
-*   ...convexAction(api.files.process, { fileId }),
-*   staleTime: 60_000
-* });
-* ```
-*/
-function convexAction(funcRef, args, meta, opts) {
-	const finalArgs = args ?? {};
-	const isSkip = finalArgs === "skip";
-	const funcName = getFunctionName(funcRef);
-	const [namespace, fnName] = funcName.split(":");
-	const authType = meta?.[namespace]?.[fnName]?.auth;
-	const skipUnauth = opts?.skipUnauth;
-	return {
-		queryKey: [
-			"convexAction",
-			funcName,
-			isSkip ? {} : finalArgs
-		],
-		staleTime: Number.POSITIVE_INFINITY,
-		refetchInterval: false,
-		refetchOnMount: false,
-		refetchOnReconnect: false,
-		refetchOnWindowFocus: false,
-		...isSkip ? { enabled: false } : {},
-		meta: {
-			authType,
-			skipUnauth,
-			subscribe: false
-		}
-	};
-}
-/**
-* Infinite query options factory for paginated Convex queries.
-* Server-safe (non-hook) - can be used in RSC.
-*
-* Uses flat { cursor, limit } input like tRPC.
-*/
-function convexInfiniteQueryOptions(funcRef, args, opts = {}, meta) {
-	const { limit, skipUnauth, enabled, ...queryOptions } = opts;
-	const finalArgs = args === "skip" ? {} : args;
-	const isSkip = args === "skip";
-	const funcName = getFunctionName(funcRef);
-	const [namespace, fnName] = funcName.split(":");
-	const authType = (meta?.[namespace]?.[fnName])?.auth;
-	const firstPageArgs = {
-		...finalArgs,
-		cursor: null,
-		limit
-	};
-	const finalEnabled = enabled === false || isSkip ? false : void 0;
-	return {
-		queryKey: [
-			"convexQuery",
-			funcName,
-			firstPageArgs
-		],
-		staleTime: Number.POSITIVE_INFINITY,
-		refetchInterval: false,
-		refetchOnMount: false,
-		refetchOnReconnect: false,
-		refetchOnWindowFocus: false,
-		...queryOptions,
-		...finalEnabled === false ? { enabled: false } : {},
-		meta: {
-			authType,
-			skipUnauth,
-			subscribe: true,
-			queryName: funcName,
-			args: finalArgs,
-			limit
-		}
-	};
-}
-
-//#endregion
-export { convexInfiniteQueryOptions as n, convexQuery as r, convexAction as t };