@pyric/cli 0.1.0-alpha.9

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

@@ -0,0 +1,348 @@
+
+<!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+
+## Interfaces
+
+<a id="deliverspec"></a>
+
+### DeliverSpec
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="data"></a> `data?` | `Record`\<`string`, `string`\> | - |
+| <a id="from"></a> `from?` | `string` | - |
+| <a id="messageid"></a> `messageId?` | `string` | - |
+| <a id="notification"></a> `notification?` | \{ `body?`: `string`; `image?`: `string`; `title?`: `string`; \} | - |
+| `notification.body?` | `string` | - |
+| `notification.image?` | `string` | - |
+| `notification.title?` | `string` | - |
+| <a id="visibilitystate"></a> `visibilityState?` | `"visible"` \| `"hidden"` | Simulated visibility of the (single) window client at delivery time. |
+
+***
+
+<a id="deliveryresult"></a>
+
+### DeliveryResult
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="handlercount"></a> `handlerCount` | `number` | Handlers actually invoked on the chosen route. |
+| <a id="payload"></a> `payload` | `DeliveredPayload` | - |
+| <a id="route"></a> `route` | `DeliveryRoute` | - |
+
+***
+
+<a id="fcmoptions"></a>
+
+### FcmOptions
+
+Options carried on a client [MessagePayload](#messagepayload).
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="analyticslabel"></a> `analyticsLabel?` | `string` |
+| <a id="link"></a> `link?` | `string` |
+
+***
+
+<a id="gettokenoptions"></a>
+
+### GetTokenOptions
+
+Options for getToken.
+
+#### Properties
+
+| Property | Type | Description |
+| :------ | :------ | :------ |
+| <a id="serviceworkerregistration"></a> `serviceWorkerRegistration?` | `object` | A (simulated) service-worker registration; token stability keys on its identity. |
+| <a id="vapidkey"></a> `vapidKey?` | `string` | - |
+
+***
+
+<a id="messagepayload"></a>
+
+### MessagePayload
+
+Received message envelope delivered to `onMessage` / `onBackgroundMessage`.
+`from` / `collapseKey` / `messageId` are typed required (upstream parity);
+captured production deliveries carry top-level keys
+`data` / `from` / `messageId` (+ `notification`) — `collapseKey` was not
+observed on the wire and the sandbox likewise omits it at runtime.
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="collapsekey"></a> `collapseKey` | `string` |
+| <a id="data-1"></a> `data?` | \{ \[`key`: `string`\]: `string`; \} |
+| <a id="fcmoptions-1"></a> `fcmOptions?` | [`FcmOptions`](#fcmoptions) |
+| <a id="from-1"></a> `from` | `string` |
+| <a id="messageid-1"></a> `messageId` | `string` |
+| <a id="notification-1"></a> `notification?` | [`NotificationPayload`](#notificationpayload) |
+
+***
+
+<a id="messaging"></a>
+
+### Messaging
+
+The FCM `Messaging` instance mirror — exposes the bound app as `app`
+(upstream `@firebase/messaging` public-types parity).
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="app"></a> `app` | `readonly` | `FirebaseApp` |
+
+***
+
+<a id="notificationpayload"></a>
+
+### NotificationPayload
+
+Display-notification block inside a [MessagePayload](#messagepayload).
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="body"></a> `body?` | `string` |
+| <a id="icon"></a> `icon?` | `string` |
+| <a id="image"></a> `image?` | `string` |
+| <a id="title"></a> `title?` | `string` |
+
+***
+
+<a id="observer"></a>
+
+### Observer
+
+#### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `T` |
+
+#### Properties
+
+| Property | Type |
+| :------ | :------ |
+| <a id="complete"></a> `complete` | () => `void` |
+| <a id="error"></a> `error` | (`error`: `Error`) => `void` |
+| <a id="next"></a> `next` | [`NextFn`](#nextfn)\<`T`\> |
+
+***
+
+<a id="simulatedserviceworkerregistration"></a>
+
+### SimulatedServiceWorkerRegistration
+
+Minimal structural stand-in for a `ServiceWorkerRegistration` in the
+headless sandbox (bun has no DOM lib). Identity is what matters: token
+stability is keyed per registration object.
+
+#### Properties
+
+| Property | Modifier | Type |
+| :------ | :------ | :------ |
+| <a id="active"></a> `active` | `readonly` | \{ `state`: `"activated"`; \} |
+| `active.state` | `readonly` | `"activated"` |
+| <a id="scope"></a> `scope` | `readonly` | `string` |
+
+## Type Aliases
+
+<a id="nextfn"></a>
+
+### NextFn()
+
+```ts
+type NextFn<T> = (value: T) => void;
+```
+
+Callback / observer / teardown shapes — structurally identical to the
+`@firebase/util` types the upstream entry re-exports (declared locally
+because `@firebase/util` is not a direct dependency of `pyric`; the
+tier-2 assignability census closes exact type parity).
+
+#### Type Parameters
+
+| Type Parameter |
+| :------ |
+| `T` |
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `value` | `T` |
+
+#### Returns
+
+`void`
+
+***
+
+<a id="unsubscribe"></a>
+
+### Unsubscribe()
+
+```ts
+type Unsubscribe = () => void;
+```
+
+#### Returns
+
+`void`
+
+## Variables
+
+<a id="sandbox"></a>
+
+### sandbox
+
+```ts
+const sandbox: {
+  deliver: Promise<DeliveryResult>;
+  registration: SimulatedServiceWorkerRegistration;
+};
+```
+
+#### Type Declaration
+
+<a id="deliver"></a>
+
+##### deliver()
+
+```ts
+deliver(messaging: Messaging, spec: DeliverSpec): Promise<DeliveryResult>;
+```
+
+Same driver as the client entry — see `pyric/messaging`'s `sandbox.deliver`.
+
+###### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `messaging` | [`Messaging`](#messaging) |
+| `spec` | [`DeliverSpec`](#deliverspec) |
+
+###### Returns
+
+`Promise`\<[`DeliveryResult`](#deliveryresult)\>
+
+<a id="registration"></a>
+
+##### registration()
+
+```ts
+registration(): SimulatedServiceWorkerRegistration;
+```
+
+The module-default simulated service-worker registration.
+
+###### Returns
+
+[`SimulatedServiceWorkerRegistration`](#simulatedserviceworkerregistration)
+
+## Functions
+
+<a id="experimentalsetdeliverymetricsexportedtobigqueryenabled"></a>
+
+### experimentalSetDeliveryMetricsExportedToBigQueryEnabled()
+
+```ts
+function experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging: Messaging, enable: boolean): void;
+```
+
+Toggle delivery-metrics export to BigQuery at runtime; default off. The
+sandbox records the flag (observable via repeated calls) but exports
+nothing — there is no BigQuery plane to export to.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `messaging` | [`Messaging`](#messaging) |
+| `enable` | `boolean` |
+
+#### Returns
+
+`void`
+
+***
+
+<a id="getmessaging"></a>
+
+### getMessaging()
+
+```ts
+function getMessaging(app?: FirebaseApp): Messaging;
+```
+
+Return the FCM `Messaging` instance for the given (or default) app —
+service-worker plane (upstream: `getMessagingInSw`, component name
+`messaging-sw`).
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `app?` | `FirebaseApp` |
+
+#### Returns
+
+[`Messaging`](#messaging)
+
+***
+
+<a id="issupported"></a>
+
+### isSupported()
+
+```ts
+function isSupported(): Promise<boolean>;
+```
+
+Whether every API FCM requires exists in this (simulated) sw context — always true.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+***
+
+<a id="onbackgroundmessage"></a>
+
+### onBackgroundMessage()
+
+```ts
+function onBackgroundMessage(messaging: Messaging, nextOrObserver:
+  | NextFn<MessagePayload>
+  | Observer<MessagePayload>): Unsubscribe;
+```
+
+Called when a message arrives while the app has NO visible window client
+(oracle: `messaging-web-onbackgroundmessage`,
+`messaging-web-visibility-routing`). A DATA-ONLY message still fires with
+no `notification` key (oracle: `messaging-web-data-only-background`), and
+registering a handler suppresses the SDK auto-display — the sandbox has
+no display plane, so suppression is the (only) modeled behavior.
+
+#### Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| `messaging` | [`Messaging`](#messaging) |
+| `nextOrObserver` | \| [`NextFn`](#nextfn)\<[`MessagePayload`](#messagepayload)\> \| [`Observer`](#observer)\<[`MessagePayload`](#messagepayload)\> |
+
+#### Returns
+
+[`Unsubscribe`](#unsubscribe)

package/dist/serve/docs-ui/docs/pyric-rules/index.html

@@ -0,0 +1,87 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>pyric/rules · Pyric Studio</title><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"> <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/"> 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" open> <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/" aria-current="true"> 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"> <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/"> 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" open> <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/" aria-current="true"> 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="/__pyric/ui/docs/pyric-rules/">pyric / rules</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Overview</span> </li> </ol> </nav>  <article class="prose">  <h1 id="pyricrules"><code>pyric/rules</code></h1>
+<p>Pyric-native Firestore Security Rules tooling. A browser-safe parser, linter, modules resolver, in-process simulator, and Rules Test API client, packaged so the data-plane swap-in (<code>pyric/firestore</code>) stays minimal.</p>
+<p>The surface is grouped around the things you can do with a rules source:</p>
+<ul>
+<li><strong>Parse</strong> it into a typed AST you can walk.</li>
+<li><strong>Lint</strong> it for compilation limits, runtime-budget risks, and known agent failure modes.</li>
+<li><strong>Validate</strong> it for security and quality findings (<code>SEC-1</code> … <code>STR-3</code>).</li>
+<li><strong>Resolve</strong> <code>2+modules</code> imports against a stdlib of reusable functions.</li>
+<li><strong>Simulate</strong> it locally against test cases. No network, no propagation wait.</li>
+<li><strong>Test</strong> it against the live Firebase Rules Test API.</li>
+<li><strong>Wrap</strong> it in agent-tool factories for <code>@inbrowser/agent</code> registries.</li>
+</ul>
+<p>Parse, Lint, Validate, Simulate, and Test all sit behind the public front door: <code>firestoreRules</code>, <code>rtdbRules</code>, <code>lint</code>, <code>assertCase</code>, and <code>explainCase</code>. The parser, linter, validator, simulator, modules resolver, and agent-tool factories are internal engine seams, exposed only under <code>pyric/rules/internal*</code> for callers that need them directly. They may change without notice.</p>
+<h2 id="install">Install</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#61AFEF">bun</span><span style="color:#98C379"> add</span><span style="color:#98C379"> pyric</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic"># or</span></span>
+<span class="line"><span style="color:#61AFEF">npm</span><span style="color:#98C379"> install</span><span style="color:#98C379"> pyric</span></span></code></pre>
+<h2 id="a-30-second-example">A 30-second example</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">firestoreRules</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> source</span><span style="color:#56B6C2"> =</span><span style="color:#98C379"> `rules_version = '2';</span></span>
+<span class="line"><span style="color:#98C379">service cloud.firestore {</span></span>
+<span class="line"><span style="color:#98C379">  match /databases/{db}/documents {</span></span>
+<span class="line"><span style="color:#98C379">    match /notes/{id} {</span></span>
+<span class="line"><span style="color:#98C379">      allow read: if request.auth != null;</span></span>
+<span class="line"><span style="color:#98C379">      allow write: if request.auth.uid == resource.data.ownerId;</span></span>
+<span class="line"><span style="color:#98C379">    }</span></span>
+<span class="line"><span style="color:#98C379">  }</span></span>
+<span class="line"><span style="color:#98C379">}`</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> ruleset</span><span style="color:#56B6C2"> =</span><span style="color:#61AFEF"> firestoreRules</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">source</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">ruleset</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">lint</span><span style="color:#ABB2BF">()); </span><span style="color:#7F848E;font-style:italic">// []</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">const</span><span style="color:#ABB2BF"> { </span><span style="color:#E5C07B">passed</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">failed</span><span style="color:#ABB2BF"> } </span><span style="color:#56B6C2">=</span><span style="color:#E5C07B"> ruleset</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">simulate</span><span style="color:#ABB2BF">([</span></span>
+<span class="line"><span style="color:#ABB2BF">  {</span></span>
+<span class="line"><span style="color:#E06C75">    description</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'authed read is allowed'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    expectation</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'ALLOW'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    method</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'get'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    path</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'notes/n1'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    auth</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">  },</span></span>
+<span class="line"><span style="color:#ABB2BF">]);</span></span>
+<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">passed</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">failed</span><span style="color:#ABB2BF">); </span><span style="color:#7F848E;font-style:italic">// 1 0</span></span></code></pre>
+<p><code>firestoreRules(source)</code> throws <code>RulesCompileError</code> if the source doesn’t parse. <code>simulate</code> never throws on rule outcomes; failures and unsupported cases come back in the result, not as exceptions.</p>
+<p>The RTDB constraints DSL (<code>defineRtdbRules</code>, <code>ruleset</code>, <code>schemaRules</code>, and the combinators) is public and lives on the same root entry:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">rtdbRules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">defineRtdbRules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">ruleset</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">allow</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>The parser, validator, simulator internals, modules resolver, and agent-tool factories live on <code>pyric/rules/internal</code> and <code>pyric/rules/internal/node</code>. They’re not part of the public contract:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">resolveModules</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">createFirestoreRulesTools</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/rules/internal/node'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<h2 id="where-to-go-next">Where to go next</h2>
+<p>Documentation is organised under <a href="../pyric-rules/"><code>docs/</code></a> following the <a href="https://diataxis.fr/" target="_blank" rel="noopener noreferrer" class="external-link">Diataxis</a> framework:</p>
+<div class="table-scroll">
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<table><thead><tr><th>If you want to</th><th>Read</th></tr></thead><tbody><tr><td>Learn the package by following a complete lesson</td><td>Tutorials</td></tr><tr><td>Accomplish a specific task</td><td>How-to guides</td></tr><tr><td>Look up an exact symbol, lint rule, or schema</td><td>Reference</td></tr><tr><td>Understand why the package is shaped this way</td><td>Explanation</td></tr></tbody></table></div>
+<h3 id="starting-points-by-role">Starting points by role</h3>
+<ul>
+<li><strong>First time here?</strong> Work through <a href="../simulate-and-lint/">Lint your first rules file</a>, then <a href="../write-a-rules-test-suite/">Write a test suite for your rules</a>.</li>
+<li><strong>Building an agent or CLI?</strong> See <a href="../pyric-rules-how-to-register-tools-with-an-agent/">Register rules tools with an agent</a> and the <a href="https://pyric.dev/docs/pyric-rules-reference-api/" target="_blank" rel="noopener noreferrer" class="external-link"><code>pyric/rules</code> API reference</a>.</li>
+<li><strong>Triaging a lint warning?</strong> Jump to <a href="../pyric-rules-reference-lint-rules/">Lint rules reference</a>.</li>
+<li><strong>Debugging an <code>UNSUPPORTED</code> test result?</strong> Read <a href="../pyric-rules-explanation-simulator-vs-rules-test-api/">Simulator vs Rules Test API</a>.</li>
+</ul>
+<h2 id="position-in-the-pyric-stack">Position in the Pyric stack</h2>
+<p><code>pyric/rules</code> is the <strong>rules-tooling</strong> sibling of <code>pyric/firestore</code> (the modular Web-SDK swap-in). The split is deliberate: the data-plane swap-in must mirror the production Firestore surface and nothing more. Anything that is <em>about</em> rules (parsing them, linting them, simulating them) lives here. See <a href="../pyric-rules-explanation-why-this-package-exists/">Why this package exists</a> for the longer story.</p>
+<h2 id="licence">Licence</h2>
+<p>Same as the parent workspace.</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="#install">Install</a> </li><li data-depth="2"> <a href="#a-30-second-example">A 30-second example</a> </li><li data-depth="2"> <a href="#where-to-go-next">Where to go next</a> </li><li data-depth="3"> <a href="#starting-points-by-role">Starting points by role</a> </li><li data-depth="2"> <a href="#position-in-the-pyric-stack">Position in the Pyric stack</a> </li><li data-depth="2"> <a href="#licence">Licence</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>