@drawbridge/drawbridge-agents 0.1.24 → 0.1.25

package/conventions/cross-repo-contracts.md

@@ -54,6 +54,7 @@ skill) so it stops living only in tribal memory.
   index manually is not enough; until the boot collMod lands, every insert carrying the field
   fails Mongo 121 (not E11000), so keyed-idempotency writers silently drop their writes
   (2026-07-30 `notification.key` dev outage, Sentry DRAWBRIDGE-SYNC-32).
+- Scraped-asset file reuse keys on `organization + meta.origin + meta.element` **plus
   `meta.render` for pipeline-rendered marks** (sync `resolveAsset` writes/queries it; the field
   and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
   `render` content-hashes the rendered output — drop `render` from either side and a rendering
@@ -99,6 +100,32 @@ skill) so it stops living only in tribal memory.
   `createdAt`. Re-adding a TTL shorter than any billing interval silently under-bills long cycles
   and blanks reporting past the window — any retention change must clear billing + reporting.
 
+## Query params + the OAuth resume target (utils ↔ app-web ↔ api ↔ shopify-app)
+
+- `request()` in `@drawbridge/drawbridge-utils` (`lib/fetch.js`) builds EVERY family GET query and
+  MUST percent-encode param values — `qs.stringify( params, { encodeValuesOnly : true } )`, never
+  `encode : false` (≥0.0.90; pinned by `test/fetch.test.js`). Param values routinely carry user input
+  and whole URLs, and with encoding off the first `&` inside a value ends that value while its
+  remainder arrives as sibling params. This silently truncated every list search (`search.value` of
+  `Smith & Sons` reached the api as `Smith `) and cost the Shopify account link its `redirect_uri`.
+  `encodeValuesOnly` — not full encoding — keeps the bracket notation (`search[keys][0]=`) so every
+  query the api already parses is byte-identical whenever values needed no escaping.
+- The OAuth resume target (`redirectTo`) is **a URL carrying its own query string**, not a scalar:
+  `/api/oauth/authorize?client_id=…&redirect_uri=…&state=…&code_challenge=…`. Every hop must preserve
+  it whole — app-web's authorize BFF requires BOTH `client_id` and `redirect_uri` and otherwise falls
+  back to `/organizations`, which reads to a merchant as "connecting silently did nothing" rather
+  than as an error. Hops that carry it: the `/auth` ↔ `/auth/signup` links, `POST /api/auth/signin`,
+  `/oauth/google/start` → the api's `oauth.state` token row → `/api/auth/google`, `/api/switch/:id`,
+  and app-web's `proxy.js` auth gate.
+- app-web's `/api/oauth/authorize` stamps `resumed=1` on the resume url when it bounces to `/auth`.
+  `getSession()` returns null both for "no session" and for "the api session lookup failed", so a
+  blip sends the browser to `/auth`, which resolves the session itself and sends it straight back;
+  the marker makes a second unresolved arrival stop instead of trading redirects until the browser
+  gives up.
+- The api's `POST /oauth/google/callback` returns `redirectTo` in its 400 body when it read the state
+  row before failing, so app-web can keep the resume target across `/auth?error=oauth`. A
+  `oauth.state.invalid` failure cannot — that row is what carried the target.
+
 ## Reporting (api ↔ app-web)
 
 - Every reporting request (usage/revenue/redemptions/analytics, org + admin) carries the viewer's
@@ -145,6 +172,12 @@ skill) so it stops living only in tribal memory.
 - The poster worker `$set`s `poster : 0` on every run and APPENDS to `frames[]`. Any script that
   generates a frame must snapshot and restore `poster`/`posterTimestamp`, **including on the
   failure path**, or a retry silently discards the user's thumbnail choice.
+- **Never compare frame timestamps as strings.** drawbridge-api writes `'HH:MM:SS'` (upload
+  default `'00:00:00'`) while app-web's scrubber writes `'HH:MM:SS.mmm'`, so `=== '00:00:00'`
+  misses the starting frame. That single mistake defeated the api's duplicate guard AND app-web's
+  own zero-check on the same day, letting the picker create a second starting frame. Compare
+  parsed milliseconds — `frameMilliseconds` in api `route/organization-file.js`, `lib/frames.js`
+  in app-web.
 
 ## Import surfaces
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {