@yottagraph-app/aether-instructions 1.1.37 → 1.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.37",
+    "version": "1.1.39",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/agents-data.mdc

@@ -71,6 +71,45 @@ In production, all Elemental API calls go through the Portal Gateway at
 `broadchurch.yaml`) and the portal injects its own Auth0 M2M token
 upstream.
 
+## Agent secrets (DATABASE_URL etc.)
+
+For runtime values that aren't shipped in `broadchurch.yaml` and can't be
+sourced from Vercel — most commonly `DATABASE_URL` for tenants whose
+Postgres is provisioned via the Vercel Neon integration — use
+`get_agent_secret()` from `broadchurch_auth`. It fetches from the portal
+at `GET /api/agent-secrets/{org_id}` using the same `X-Api-Key` the agent
+already carries, and caches per-process.
+
+```python
+try:
+    from broadchurch_auth import get_agent_secret
+except ImportError:
+    from .broadchurch_auth import get_agent_secret
+
+def my_db_tool() -> str:
+    db_url = get_agent_secret("DATABASE_URL")
+    if not db_url:
+        return "DATABASE_URL is not configured for this tenant."
+    # ... use db_url ...
+```
+
+Resolution order is `os.environ[name]` → portal-stored secret → default.
+The env var path means local dev "just works" with `export DATABASE_URL=...`
+without touching the portal.
+
+Set values via the portal admin endpoint:
+
+```bash
+curl -X PUT $GATEWAY_URL/api/projects/$ORG_ID/agent-secrets \
+  -H 'Content-Type: application/json' \
+  -d '{"vars": {"DATABASE_URL": "postgresql://..."}}'
+```
+
+Secrets are stored encrypted-at-rest in Firestore on the tenant doc.
+There is no per-tenant Vercel/Neon integration — when credentials rotate,
+push the new value via the same endpoint and let the agent cold-start
+pick it up (or call `get_agent_secrets(refresh=True)`).
+
 ## MCP-based agents
 
 When the project uses **MCP-only data architecture**, agents access the

package/rules/data.mdc

@@ -142,8 +142,8 @@ Elemental API patterns. **Use these instead of writing from scratch:**
 ```typescript
 const { flavors, properties, flavorByName, pidByName, refresh } = useElementalSchema();
 await refresh();                                // fetches once, then cached
-const articleFid = flavorByName('article');      // → number | null
-const namePid = pidByName('name');              // → typically 8
+const articleFid = flavorByName('article');      // → string | null
+const namePid = pidByName('name');              // → string | null
 ```
 
 Handles the dual response shapes (`res.schema.flavors` vs `res.flavors`)
@@ -297,15 +297,31 @@ Same value, different key. Always use a fallback:
 
 ```typescript
 const articleFlavor = flavors.find(f => f.name === 'article');
-const articleFid = articleFlavor?.fid ?? articleFlavor?.findex ?? null;
+// Always use String() — safe for small IDs (12) and required for large ones
+const articleFid = String(articleFlavor?.fid ?? articleFlavor?.findex ?? '');
 
 // When building a FID lookup map:
-const fidMap = new Map(flavors.map(f => [f.fid ?? f.findex, f.name]));
+const fidMap = new Map(flavors.map(f => [String(f.fid ?? f.findex), f.name]));
 ```
 
 The `is_type` expression in `/elemental/find` always uses the `fid` key
 regardless of which schema endpoint provided the value.
 
+### Some FIDs and PIDs are 64-bit -- `JSON.parse` will silently corrupt them
+
+FIDs and PIDs are stored as 64-bit signed integers. Many are small
+(e.g. `12`), but others exceed JavaScript's `Number.MAX_SAFE_INTEGER`
+(2^53 - 1) -- for example, `3466547124233281063`. `JSON.parse` silently
+rounds these large values (that example becomes `3466547124233281000`). An `is_type` query with
+the rounded FID returns empty results and no error, making it look like
+the data doesn't exist.
+
+**Always treat FIDs and PIDs as strings in TypeScript/JavaScript.**
+Before `JSON.parse`, rewrite large numeric `fid`/`pid` fields to
+quoted strings. Store them as `string`, not `number`. Build expressions
+and `pids` arrays via string interpolation, not `JSON.stringify` of a
+JS number. This is safe for small IDs too.
+
 ### Relationship property values need zero-padding to form valid NEIDs
 
 Relationship properties (`data_nindex`) return linked entity IDs as raw