@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/create-pyric-reference-api.md

@@ -0,0 +1,345 @@
+
+<!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+
+## Interfaces
+
+<a id="createargs"></a>
+
+### CreateArgs
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="flags"></a> `flags` | `Map`\<`string`, [`FlagValue`](#flagvalue)\> |
+| <a id="positional"></a> `positional` | `string`[] |
+
+***
+
+<a id="packagejsonmerge"></a>
+
+### PackageJsonMerge
+
+`create-pyric` — scaffold engine for `npm create pyric` and `pyric init`.
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="added"></a> `added` | `string`[] |
+| <a id="conflicts"></a> `conflicts` | \{ `existing`: `unknown`; `key`: `string`; `wanted`: `unknown`; \}[] |
+| <a id="contents"></a> `contents` | `string` |
+| <a id="unchanged"></a> `unchanged` | `boolean` |
+
+***
+
+<a id="scaffoldio"></a>
+
+### ScaffoldIo
+
+`create-pyric` — scaffold engine for `npm create pyric` and `pyric init`.
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="cwd"></a> `cwd?` | `string` |
+| <a id="exists"></a> `exists?` | (`path`: `string`) => `Promise`\<`boolean`\> |
+| <a id="mkdir"></a> `mkdir?` | \{ (`path`: `PathLike`, `options`: `MakeDirectoryOptions` & \{ \}): `Promise`\<`string`\>; (`path`: `PathLike`, `options?`: \| `Mode` \| `MakeDirectoryOptions` & \{ \}): `Promise`\<`void`\>; (`path`: `PathLike`, `options?`: `Mode` \| `MakeDirectoryOptions`): `Promise`\<`string`\>; \} |
+| <a id="readfile"></a> `readFile?` | \{ (`path`: `PathLike` \| `FileHandle`, `options?`: \{ \} & `Abortable`): `Promise`\<`NonSharedBuffer`\>; (`path`: `PathLike` \| `FileHandle`, `options`: \| `BufferEncoding` \| \{ \} & `Abortable`): `Promise`\<`string`\>; (`path`: `PathLike` \| `FileHandle`, `options?`: \| `BufferEncoding` \| `ObjectEncodingOptions` & `Abortable` & \{ \}): `Promise`\<`string` \| `NonSharedBuffer`\>; \} |
+| <a id="stderr"></a> `stderr?` | \{ `write`: `void`; \} |
+| `stderr.write` | `void` |
+| <a id="stdout"></a> `stdout?` | \{ `write`: `void`; \} |
+| `stdout.write` | `void` |
+| <a id="writefile"></a> `writeFile?` | (`file`: `PathLike` \| `FileHandle`, `data`: \| `string` \| `ArrayBufferView`\<`ArrayBufferLike`\> \| `Iterable`\<string \| ArrayBufferView\<ArrayBufferLike\>, `any`, `any`\> \| `AsyncIterable`\<string \| ArrayBufferView\<ArrayBufferLike\>, `any`, `any`\>, `options?`: \| `ObjectEncodingOptions` & \{ \} & `Abortable` \| `BufferEncoding`) => `Promise`\<`void`\> |
+
+***
+
+<a id="scaffoldrequest"></a>
+
+### ScaffoldRequest
+
+`create-pyric` — scaffold engine for `npm create pyric` and `pyric init`.
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="commandlabel"></a> `commandLabel?` | `string` | Label used in human report lines (`create-pyric` or `pyric init`). |
+| <a id="depsmode"></a> `depsMode?` | [`DepsMode`](#depsmode-2) | - |
+| <a id="dir"></a> `dir?` | `string` | Absolute or relative project directory (relative resolved against cwd). |
+| <a id="effectivetemplate"></a> `effectiveTemplate?` | [`ScaffoldTemplate`](#scaffoldtemplate) | Already-rewritten template; defaults to TEMPLATES[template] (+ npm pin). |
+| <a id="force"></a> `force?` | `boolean` | - |
+| <a id="json"></a> `json?` | `boolean` | - |
+| <a id="name"></a> `name?` | `string` | - |
+| <a id="pinversion"></a> `pinVersion?` | `string` | Version pin for npm-mode `@pyric/cli` / `pyric` ranges. |
+| <a id="precreated"></a> `preCreated?` | `string`[] | Extra paths already created (e.g. vendor tarballs) to list in the report. |
+| <a id="template"></a> `template?` | `"web"` \| `"node"` \| `"static"` | - |
+
+***
+
+<a id="scaffoldresult"></a>
+
+### ScaffoldResult
+
+Stable `--json` contract; agents parse this.
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="conflicts-1"></a> `conflicts` | \{ `existing`: `unknown`; `key`: `string`; `wanted`: `unknown`; \}[] |
+| <a id="created"></a> `created` | `string`[] |
+| <a id="depsmode-1"></a> `depsMode` | [`DepsMode`](#depsmode-2) |
+| <a id="dir-1"></a> `dir` | `string` |
+| <a id="merged"></a> `merged` | `string`[] |
+| <a id="nextsteps"></a> `nextSteps` | `string`[] |
+| <a id="skipped"></a> `skipped` | `string`[] |
+| <a id="template-1"></a> `template` | `"web"` \| `"node"` \| `"static"` |
+
+***
+
+<a id="scaffoldtemplate"></a>
+
+### ScaffoldTemplate
+
+Scaffold templates for `pyric init` (engine in `./init.js`).
+
+`web` (the default) scaffolds a **Vite app** wired to the `@pyric/cli/vite`
+plugin: `vite dev` runs the app's CANONICAL `firebase/*` imports against the
+in-process sandbox; `vite build` ships the real `firebase` package. One
+toolchain, no graduation cliff — the sandbox↔Firebase swap is environmental
+(dev vs build), never a code edit (the design rationale section 9).
+
+`static` is the serve-era scaffold (no bundler): a static app `pyric dev`
+runs against the in-page sandbox via a runtime import map. For pre-built /
+retrofit apps, or anyone who wants zero build step.
+
+`node` is the script-style scaffold (backend fixtures, agent loops). Its
+canonical imports are swapped by the dev command and remain Firebase under
+the production command.
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="dependencies"></a> `dependencies` | `Record`\<`string`, `string`\> | - |
+| <a id="devdependencies"></a> `devDependencies` | `Record`\<`string`, `string`\> | - |
+| <a id="dirs"></a> `dirs` | `string`[] | Directories created before writing files (relative to the project dir). |
+| <a id="nextsteps-1"></a> `nextSteps` | `string`[] | Literal commands for the report / `--json` consumers. |
+| <a id="overrides"></a> `overrides?` | `Record`\<`string`, `string`\> | npm/bun `overrides` (optional). Vendor mode sets `{ pyric: file:… }` so a transitive `pyric` dep can't resolve to the published placeholder. |
+| <a id="scripts"></a> `scripts` | `Record`\<`string`, `string`\> | package.json pieces merged into existing files / written into new ones. |
+
+#### Methods
+
+<a id="files"></a>
+
+##### files()
+
+```ts
+files(name: string): {
+  content: string;
+  name: string;
+}[];
+```
+
+Scaffold-owned files, relative path → content.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `name` | `string` |
+
+###### Returns
+
+\{
+  `content`: `string`;
+  `name`: `string`;
+\}[]
+
+## Type Aliases
+
+<a id="depsmode-2"></a>
+
+### DepsMode
+
+```ts
+type DepsMode = "vendor" | "npm";
+```
+
+Where the scaffold's `pyric` / `@pyric/cli` deps come from.
+
+***
+
+<a id="flagvalue"></a>
+
+### FlagValue
+
+```ts
+type FlagValue = string | boolean | (string | boolean)[];
+```
+
+Minimal argv parser for `create-pyric` (no subcommand — first bare
+arg is the target directory).
+
+## Variables
+
+<a id="templates"></a>
+
+### TEMPLATES
+
+```ts
+const TEMPLATES: Record<"web" | "node" | "static", ScaffoldTemplate>;
+```
+
+`create-pyric` — scaffold engine for `npm create pyric` and `pyric init`.
+
+## Functions
+
+<a id="applydepsmode"></a>
+
+### applyDepsMode()
+
+```ts
+function applyDepsMode(
+   t: ScaffoldTemplate,
+   mode: DepsMode,
+   opts: {
+  vendorSpecs?: Record<string, string>;
+  version?: string;
+}): ScaffoldTemplate;
+```
+
+Return a copy of `t` with `pyric` / `@pyric/cli` deps rewritten for `mode`.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `t` | [`ScaffoldTemplate`](#scaffoldtemplate) |
+| `mode` | [`DepsMode`](#depsmode-2) |
+| `opts` | \{ `vendorSpecs?`: `Record`\<`string`, `string`\>; `version?`: `string`; \} |
+| `opts.vendorSpecs?` | `Record`\<`string`, `string`\> |
+| `opts.version?` | `string` |
+
+#### Returns
+
+[`ScaffoldTemplate`](#scaffoldtemplate)
+
+***
+
+<a id="mergeintoexistingpackagejson"></a>
+
+### mergeIntoExistingPackageJson()
+
+```ts
+function mergeIntoExistingPackageJson(
+   raw: string,
+   projectName: string,
+   template: ScaffoldTemplate): PackageJsonMerge;
+```
+
+Merge template fields into an existing package.json. Never overwrites.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `raw` | `string` |
+| `projectName` | `string` |
+| `template` | [`ScaffoldTemplate`](#scaffoldtemplate) |
+
+#### Returns
+
+[`PackageJsonMerge`](#packagejsonmerge)
+
+***
+
+<a id="normalizeboolflags"></a>
+
+### normalizeBoolFlags()
+
+```ts
+function normalizeBoolFlags(flags: Map<string, FlagValue>, positional: string[]): void;
+```
+
+Reclaim `--force dir` / `--json dir` when a parser bound the value as the flag.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `flags` | `Map`\<`string`, [`FlagValue`](#flagvalue)\> |
+| `positional` | `string`[] |
+
+#### Returns
+
+`void`
+
+***
+
+<a id="packagejsonfor"></a>
+
+### packageJsonFor()
+
+```ts
+function packageJsonFor(name: string, t: ScaffoldTemplate): string;
+```
+
+`create-pyric` — scaffold engine for `npm create pyric` and `pyric init`.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `name` | `string` |
+| `t` | [`ScaffoldTemplate`](#scaffoldtemplate) |
+
+#### Returns
+
+`string`
+
+***
+
+<a id="parsecreateargs"></a>
+
+### parseCreateArgs()
+
+```ts
+function parseCreateArgs(argv: string[]): CreateArgs;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `argv` | `string`[] |
+
+#### Returns
+
+[`CreateArgs`](#createargs)
+
+***
+
+<a id="runscaffold"></a>
+
+### runScaffold()
+
+```ts
+function runScaffold(request: ScaffoldRequest, deps?: ScaffoldIo): Promise<number>;
+```
+
+Write the scaffold into `dir`. Caller prepares vendor tarballs / pin when
+needed and may pass `effectiveTemplate`.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `request` | [`ScaffoldRequest`](#scaffoldrequest) |
+| `deps?` | [`ScaffoldIo`](#scaffoldio) |
+
+#### Returns
+
+`Promise`\<`number`\>

package/dist/serve/docs-ui/docs/firestore-rules-limits/index.html

@@ -0,0 +1,59 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Firestore Rules compiler and evaluator limits · Pyric Studio</title><meta name="description" content="Use measured production compiler and evaluator limits before a ruleset reaches Firebase."><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" open> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/" aria-current="page"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct" open> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/" aria-current="page"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference"> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="#nav-group-inspect-and-correct">Inspect and correct</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <a href="#nav-section-inspect-and-correct-correct-security-rules">Correct Security Rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Rules limits</span> </li> </ol> </nav>  <article class="prose">  <h1 id="firestore-rules-compiler-and-evaluator-limits">Firestore Rules compiler and evaluator limits</h1>
+<p>A ruleset can be syntactically perfect and still fail two ways: a 400 at deploy with no useful message, or a silent 403 at runtime that looks exactly like a denial you wrote. Both come from real limits in the production compiler and evaluator. The numbers below are researched and observed behavior: Pyric’s tooling probed production Firestore directly, isolating one variable at a time, and recorded what it measured. They ship inside Pyric’s linter as thresholds, so you do not have to remember them. It helps to know they exist.</p>
+<h2 id="256-kb-of-source">256 KB of source</h2>
+<p>For a long time the working assumption was a “30 to 37 KB practical limit” on rules source. It was wrong. That number was chain depth in disguise: complex rulesets happened to hit the depth limit at around that size, and size took the blame. Isolate the variable with a large file of trivial single-comparison rules and 250 KB compiles while 256 KB fails. The real source ceiling is 256 KB, and 58 KB of simple functions compiles without complaint.</p>
+<h2 id="98-terms-in-a-chain">98 terms in a chain</h2>
+<p>A flat chain of <code>a &#x26;&#x26; b &#x26;&#x26; c &#x26;&#x26; ...</code> compiles at 98 terms and fails at 99. Same for <code>||</code>. The limit is the depth of the top-level binary chain, not the number of comparisons: 90 OR branches of <code>(a &#x26;&#x26; b)</code> pairs is 180 leaf expressions and compiles fine, because nesting halves the chain. When the linter reports CHAIN_DEPTH, the fix is grouping. <code>a &#x26;&#x26; b &#x26;&#x26; c &#x26;&#x26; d</code> becomes <code>(a &#x26;&#x26; b) &#x26;&#x26; (c &#x26;&#x26; d)</code>.</p>
+<h2 id="11-let-bindings-per-function">11 let bindings per function</h2>
+<p>Eleven <code>let</code> bindings in a function compile. Twelve fail, with the same unexplained 400 as every other compilation failure. The fix is inlining expressions into the return statement, or splitting the function.</p>
+<h2 id="10-get-calls-per-evaluation">10 get() calls per evaluation</h2>
+<p>This limit is in Firebase’s own documentation. What matters in practice is the caching: results are cached per unique path, so a shared <code>config()</code> helper called from six functions costs one read, while six different paths cost six. The linter warns past 5 distinct calls and errors at the documented 10.</p>
+<h2 id="the-runtime-evaluation-budget">The runtime evaluation budget</h2>
+<p>The compile-time limits fail loudly at deploy. This one does not. A rule whose evaluation is too expensive returns 403 PERMISSION_DENIED at runtime, indistinguishable from a denial you intended.</p>
+<p>Pinning it down took a deploy-once, test-five-times methodology, and the result is not a single number:</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>Shape</th><th>Total expressions</th><th>Result</th></tr></thead><tbody><tr><td>1 function of 98 expressions</td><td>98</td><td>5/5 pass</td></tr><tr><td>2 functions of 60</td><td>120</td><td>5/5 pass</td></tr><tr><td>2 functions of 65</td><td>130</td><td>2/5 pass</td></tr><tr><td>3 functions of 20</td><td>60</td><td>2/5 pass</td></tr><tr><td>3 functions of 50</td><td>150</td><td>0/5 pass</td></tr></tbody></table></div>
+<p>Read the second row against the fourth. Two function calls with 120 total expressions always pass. Three calls with half that total are already failing intermittently. Function calls carry heavy overhead, so the budget is call-count-dependent. And between “always passes” and “never passes” sits a genuine flaky zone, where the same rule passes most of the time and intermittently denies under load. The linter models this with conservative tiers: at one or two function calls it warns at 100 total expressions, at three or four it warns at 60, at five or more it warns at 40.</p>
+<h2 id="about-40000-index-entries-in-a-config-document">About 40,000 index entries in a config document</h2>
+<p>The config-document pattern has a ceiling on the data side. A 129 KB config document with 19 thousand index entries writes fine. A 207 KB one with 39 thousand fails with “too many index entries for entity”. If your lookup document is large, budget its keys, not only its bytes.</p>
+<h2 id="the-budget-that-spans-rules">The budget that spans rules</h2>
+<p>The runtime expression budget is shared across all the allow rules of a match block, evaluated in order. Non-matching rules spend from the same account as the rule that will eventually match, and the evidence was unambiguous: with sixteen checkers rules, reordering them changed which category of move failed. The structural fix, a unique first expression per rule, is covered in <a href="../rules-patterns/">rules patterns</a>. The linter flags the hazard as SHARED_GATE.</p>
+<h2 id="use-the-measured-limits-in-the-linter">Use the measured limits in the linter</h2>
+<p><code>pyric firestore rules lint</code> carries every number above as a threshold and reports the specific function, chain, or rule that crosses it, with a fix. It runs in-process, without a deploy, so the first time production sees your rules they already fit. From an agent, the same check is <code>firestore_lint_rules</code>.</p>
+<p>One honest note. The Firebase emulator does not reproduce the cross-rule budget and does not enforce these thresholds at production values. Rules that pass there can still fail to deploy, or deny at runtime. The numbers on this page were measured against production because that is where they apply.</p>
+<h2 id="where-to-go-next">Where to go next</h2>
+<p>Lint and simulate together in <a href="../simulate-and-lint/">simulate and lint before you deploy</a>. To see rules engineered against these exact limits, read the <a href="../whats-possible/">case studies</a>.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#256-kb-of-source">256 KB of source</a> </li><li data-depth="2"> <a href="#98-terms-in-a-chain">98 terms in a chain</a> </li><li data-depth="2"> <a href="#11-let-bindings-per-function">11 let bindings per function</a> </li><li data-depth="2"> <a href="#10-get-calls-per-evaluation">10 get() calls per evaluation</a> </li><li data-depth="2"> <a href="#the-runtime-evaluation-budget">The runtime evaluation budget</a> </li><li data-depth="2"> <a href="#about-40000-index-entries-in-a-config-document">About 40,000 index entries in a config document</a> </li><li data-depth="2"> <a href="#the-budget-that-spans-rules">The budget that spans rules</a> </li><li data-depth="2"> <a href="#use-the-measured-limits-in-the-linter">Use the measured limits in the linter</a> </li><li data-depth="2"> <a href="#where-to-go-next">Where to go next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/firestore-rules-limits.md

@@ -0,0 +1,54 @@
+
+# Firestore Rules compiler and evaluator limits
+
+A ruleset can be syntactically perfect and still fail two ways: a 400 at deploy with no useful message, or a silent 403 at runtime that looks exactly like a denial you wrote. Both come from real limits in the production compiler and evaluator. The numbers below are researched and observed behavior: Pyric's tooling probed production Firestore directly, isolating one variable at a time, and recorded what it measured. They ship inside Pyric's linter as thresholds, so you do not have to remember them. It helps to know they exist.
+
+## 256 KB of source
+
+For a long time the working assumption was a "30 to 37 KB practical limit" on rules source. It was wrong. That number was chain depth in disguise: complex rulesets happened to hit the depth limit at around that size, and size took the blame. Isolate the variable with a large file of trivial single-comparison rules and 250 KB compiles while 256 KB fails. The real source ceiling is 256 KB, and 58 KB of simple functions compiles without complaint.
+
+## 98 terms in a chain
+
+A flat chain of `a && b && c && ...` compiles at 98 terms and fails at 99. Same for `||`. The limit is the depth of the top-level binary chain, not the number of comparisons: 90 OR branches of `(a && b)` pairs is 180 leaf expressions and compiles fine, because nesting halves the chain. When the linter reports CHAIN_DEPTH, the fix is grouping. `a && b && c && d` becomes `(a && b) && (c && d)`.
+
+## 11 let bindings per function
+
+Eleven `let` bindings in a function compile. Twelve fail, with the same unexplained 400 as every other compilation failure. The fix is inlining expressions into the return statement, or splitting the function.
+
+## 10 get() calls per evaluation
+
+This limit is in Firebase's own documentation. What matters in practice is the caching: results are cached per unique path, so a shared `config()` helper called from six functions costs one read, while six different paths cost six. The linter warns past 5 distinct calls and errors at the documented 10.
+
+## The runtime evaluation budget
+
+The compile-time limits fail loudly at deploy. This one does not. A rule whose evaluation is too expensive returns 403 PERMISSION_DENIED at runtime, indistinguishable from a denial you intended.
+
+Pinning it down took a deploy-once, test-five-times methodology, and the result is not a single number:
+
+| Shape | Total expressions | Result |
+|---|---|---|
+| 1 function of 98 expressions | 98 | 5/5 pass |
+| 2 functions of 60 | 120 | 5/5 pass |
+| 2 functions of 65 | 130 | 2/5 pass |
+| 3 functions of 20 | 60 | 2/5 pass |
+| 3 functions of 50 | 150 | 0/5 pass |
+
+Read the second row against the fourth. Two function calls with 120 total expressions always pass. Three calls with half that total are already failing intermittently. Function calls carry heavy overhead, so the budget is call-count-dependent. And between "always passes" and "never passes" sits a genuine flaky zone, where the same rule passes most of the time and intermittently denies under load. The linter models this with conservative tiers: at one or two function calls it warns at 100 total expressions, at three or four it warns at 60, at five or more it warns at 40.
+
+## About 40,000 index entries in a config document
+
+The config-document pattern has a ceiling on the data side. A 129 KB config document with 19 thousand index entries writes fine. A 207 KB one with 39 thousand fails with "too many index entries for entity". If your lookup document is large, budget its keys, not only its bytes.
+
+## The budget that spans rules
+
+The runtime expression budget is shared across all the allow rules of a match block, evaluated in order. Non-matching rules spend from the same account as the rule that will eventually match, and the evidence was unambiguous: with sixteen checkers rules, reordering them changed which category of move failed. The structural fix, a unique first expression per rule, is covered in [rules patterns](../rules-patterns/). The linter flags the hazard as SHARED_GATE.
+
+## Use the measured limits in the linter
+
+`pyric firestore rules lint` carries every number above as a threshold and reports the specific function, chain, or rule that crosses it, with a fix. It runs in-process, without a deploy, so the first time production sees your rules they already fit. From an agent, the same check is `firestore_lint_rules`.
+
+One honest note. The Firebase emulator does not reproduce the cross-rule budget and does not enforce these thresholds at production values. Rules that pass there can still fail to deploy, or deny at runtime. The numbers on this page were measured against production because that is where they apply.
+
+## Where to go next
+
+Lint and simulate together in [simulate and lint before you deploy](../simulate-and-lint/). To see rules engineered against these exact limits, read the [case studies](../whats-possible/).