@pome-sh/cli 0.2.0 → 0.4.0

package/node_modules/@pome-sh/twin-github/node_modules/@pome-sh/shared-types/dist/task.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// shared-types §3 — TASKS. Task config, the parsed task markdown shape, and the
+// persisted task row, plus their deprecated `scenario*` aliases. The provider
+// seed-state schemas consumed by `taskSchema.seedState` live in `./seed-state.ts`.
+// Re-exported through the `@pome-sh/shared-types` barrel (index.ts).
+import { z } from "zod";
+import { criterionSchema, judgeModelSchema } from "./run.js";
+import { seedStateSchema } from "./seed-state.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. TASKS (formerly "scenarios") — originally adopted verbatim from
+//    oslo/pome/src/scenario/scenarioSchema.ts
+//
+// W3 vocab (FDRS-653): "task" is the canonical name; the `scenario*` exports
+// below are deprecated aliases kept for the 0.3.0 window (FDRS-654 swaps the
+// consumers).
+//
+// `criterionSchema` and `judgeModelSchema` were moved to `./run.ts` (2026-05-11
+// split) because CriterionResult depends on them; imported here from `./run.js`
+// and re-exported to consumers via the index.ts barrel.
+// ─────────────────────────────────────────────────────────────────────────────
+export const taskConfigSchema = z.object({
+    twins: z.array(z.string()).default(["github"]),
+    timeout: z.number().int().positive().default(60), // seconds
+    runs: z.number().int().positive().default(1),
+    passThreshold: z.number().min(0).max(100).default(100),
+    judge: judgeModelSchema.default("claude-haiku-4-5"), // CLI's BYOK config decides which endpoint serves this
+});
+/** @deprecated FDRS-653 — use `taskConfigSchema`. Removed after the 0.3.0 window. */
+export const scenarioConfigSchema = taskConfigSchema;
+// The parsed task (formerly "scenario") markdown shape. Criterion kinds inside
+// `criteria` normalize D→code, P→model (tolerant reader, FDRS-653).
+export const taskSchema = z.object({
+    slug: z.string().min(1),
+    title: z.string().min(1),
+    setup: z.string().default(""), // human-readable prose; ignored at runtime
+    prompt: z.string().min(1),
+    expectedBehavior: z.string().default(""), // evaluator-only, NEVER sent to agent
+    criteria: z.array(criterionSchema).min(1),
+    config: taskConfigSchema,
+    seedState: seedStateSchema,
+});
+/** @deprecated FDRS-653 — use `taskSchema`. Removed after the 0.3.0 window. */
+export const scenarioSchema = taskSchema;
+// Persisted Task row (dashboard upload path; cloud DB `tasks` table). Per
+// 04-data-model.md. Row ids keep the historical `scn_` prefix (persisted data;
+// renaming ids is a data migration, deliberately NOT part of FDRS-653).
+export const persistedTaskSchema = z.object({
+    id: z.string(), // scn_<nanoid>
+    team_id: z.string(),
+    name: z.string(),
+    source: z.string(), // raw markdown
+    source_hash: z.string(), // sha256(source)
+    uploaded_by: z.string(), // user_id
+    created_at: z.string().datetime(),
+    archived_at: z.string().datetime().nullable(),
+});
+/** @deprecated FDRS-653 — use `persistedTaskSchema`. Removed after the 0.3.0 window. */
+export const persistedScenarioSchema = persistedTaskSchema;
+//# sourceMappingURL=task.js.map

package/node_modules/@pome-sh/twin-github/node_modules/@pome-sh/shared-types/dist/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,gFAAgF;AAChF,8EAA8E;AAC9E,mFAAmF;AACnF,qEAAqE;AAErE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,gFAAgF;AAChF,qEAAqE;AACrE,8CAA8C;AAC9C,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,cAAc;AACd,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAEhF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAU,UAAU;IACpE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IACtD,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAQ,uDAAuD;CACnH,CAAC,CAAC;AAGH,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAIrD,+EAA+E;AAC/E,oEAAoE;AACpE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAgB,2CAA2C;IACxF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAK,sCAAsC;IACnF,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,EAAE,gBAAgB;IACxB,SAAS,EAAE,eAAe;CAC3B,CAAC,CAAC;AAGH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;AAIzC,0EAA0E;AAC1E,+EAA+E;AAC/E,wEAAwE;AACxE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAA+B,eAAe;IAC5D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAA2B,eAAe;IAC5D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,EAAsB,iBAAiB;IAC9D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,EAAsB,UAAU;IACvD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC;AAGH,wFAAwF;AACxF,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAC"}

package/node_modules/@pome-sh/twin-github/node_modules/@pome-sh/shared-types/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pome-sh/shared-types",
+  "version": "0.11.0",
+  "description": "Shared wire-format contract for Pome — Zod schemas for traces, recorder events, runs, OTel mapping, and secret redaction.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./recorder-events": {
+      "types": "./dist/recorder-events.d.ts",
+      "default": "./dist/recorder-events.js"
+    },
+    "./run": {
+      "types": "./dist/run.d.ts",
+      "default": "./dist/run.js"
+    },
+    "./otel": {
+      "types": "./dist/otel/index.d.ts",
+      "default": "./dist/otel/index.js"
+    },
+    "./otel/fixtures": {
+      "types": "./dist/otel/fixtures/index.d.ts",
+      "default": "./dist/otel/fixtures/index.js"
+    },
+    "./redaction": {
+      "types": "./dist/redaction.d.ts",
+      "default": "./dist/redaction.js"
+    }
+  },
+  "files": [
+    "dist",
+    "trace-contract.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pome-sh/digital-twins.git",
+    "directory": "packages/shared-types"
+  },
+  "homepage": "https://github.com/pome-sh/digital-twins/tree/main/packages/shared-types",
+  "bugs": {
+    "url": "https://github.com/pome-sh/digital-twins/issues"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/node_modules/@pome-sh/twin-github/node_modules/@pome-sh/shared-types/trace-contract.json

@@ -0,0 +1,41 @@
+{
+  "package": "@pome-sh/shared-types",
+  "version": "0.11.0",
+  "zod": {
+    "range": "^4.1.13",
+    "major": 4
+  },
+  "exports": {
+    "root": "@pome-sh/shared-types",
+    "recorderEvents": "@pome-sh/shared-types/recorder-events",
+    "run": "@pome-sh/shared-types/run",
+    "otel": "@pome-sh/shared-types/otel",
+    "redaction": "@pome-sh/shared-types/redaction"
+  },
+  "canonicalSchemas": [
+    "recorderEventSchema",
+    "eventSchema",
+    "otelEventSchema",
+    "runSchema"
+  ],
+  "fixtures": [
+    "test/fixtures/v1/createSessionRequest/multi-twin-permissive-seed-idempotency.json",
+    "test/fixtures/v1/createSessionRequest/scenario-source-github.json",
+    "test/fixtures/v1/createSessionRequest/stored-scenario.json",
+    "test/fixtures/v1/createSessionRequestTaskVocab/stored-task.json",
+    "test/fixtures/v1/createSessionRequestTaskVocab/task-source-github.json",
+    "test/fixtures/v1/createSessionResponse/full-multi-twin.json",
+    "test/fixtures/v1/createSessionResponse/legacy-single-twin.json",
+    "test/fixtures/v1/planTier/enterprise.json",
+    "test/fixtures/v1/planTier/free.json",
+    "test/fixtures/v1/planTier/hobby.json",
+    "test/fixtures/v1/planTier/pro.json",
+    "test/fixtures/v1/planTier/self_host_annual.json",
+    "test/fixtures/v1/planTier/team.json",
+    "test/fixtures/v1/run/full-production.json",
+    "test/fixtures/v1/run/legacy-minimal.json",
+    "test/fixtures/v1/runTaskVocab/full-production-task-vocab.json",
+    "test/fixtures/v1/usage/free-tier.json",
+    "test/fixtures/v1/usage/team-tier-exhausted.json"
+  ]
+}

package/node_modules/@pome-sh/twin-github/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pome-sh/twin-github",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Deterministic GitHub-shaped twin for agent testing — REST + MCP, SQLite-backed state.",
   "private": false,
   "type": "module",
@@ -33,9 +33,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@hono/node-server": "^2.0.8",
-    "@pome-sh/sdk": "0.4.0",
-    "@pome-sh/shared-types": "0.9.0",
+    "@hono/node-server": "^2.0.10",
+    "@pome-sh/sdk": "0.5.0",
+    "@pome-sh/shared-types": "0.11.0",
     "hono": "^4.12.27",
     "zod": "^4.1.13"
   },
@@ -49,12 +49,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pome-sh/pome-twins.git",
+    "url": "git+https://github.com/pome-sh/digital-twins.git",
     "directory": "packages/twin-github"
   },
-  "homepage": "https://github.com/pome-sh/pome-twins/tree/main/packages/twin-github",
+  "homepage": "https://github.com/pome-sh/digital-twins/tree/main/packages/twin-github",
   "bugs": {
-    "url": "https://github.com/pome-sh/pome-twins/issues"
+    "url": "https://github.com/pome-sh/digital-twins/issues"
   },
   "license": "Apache-2.0",
   "engines": {

package/node_modules/@pome-sh/twin-gmail/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @pome-sh/twin-gmail — CHANGELOG
+
+## 0.1.0 — 2026-07-20
+
+First public release of the deterministic Gmail twin:
+
+- Broad frozen Gmail v1 REST and upload surface with loud named 501 gaps.
+- Captured ten-tool first-party Gmail MCP listing and structured results.
+- Deterministic SQLite mailbox state, MIME handling, search, history, labels,
+  drafts, settings, bounded state export, and recorder payload projection.
+- CLI, scenario, runtime-contract, package, and signed-image integration.
+
+Authentication is Pome-owned. `POME_GMAIL_TOKEN` aliases the session JWT and
+the package does not implement Google OAuth or add `provider_credentials.gmail`.

package/node_modules/@pome-sh/twin-gmail/HOSTED.md

@@ -0,0 +1,23 @@
+# Hosted Gmail handoff
+
+The OSS package and CLI are release-ready independently of hosted support.
+Pome Cloud must complete this consumer gate before advertising hosted Gmail:
+
+1. Add `gmail` to the mounted/provisionable twin registry and consume
+   `@pome-sh/shared-types@0.11.0`.
+2. Mint the session JWT with
+   `gmail_email: "pome-agent@pome-twin.test"` by default, or the normalized
+   primary mailbox email from the accepted Gmail seed.
+3. Do **not** add `provider_credentials.gmail`. Return the normal
+   `agent_token`; clients expose it as both `POME_AUTH_TOKEN` and
+   `POME_GMAIL_TOKEN`.
+4. Route the signed `ghcr.io/pome-sh/twins:gmail-*` digest and publish Gmail
+   `api_url`, `mcp_url`, and `openapi_url` entries under `per_twin.gmail`.
+5. Forward the Gmail seed unchanged to the pod, capture `/_pome/state` and
+   `/_pome/events`, and retain MIME/attachment projection redaction.
+6. Run the packaged official-client, ten-tool MCP parity, and multi-twin
+   scenarios against the hosted route before enabling the product flag.
+7. Add the signed digest to fidelity watch/dashboard registration.
+
+Until that gate passes, documentation must describe Gmail as local/OSS-ready,
+not hosted-ready.

package/node_modules/@pome-sh/twin-gmail/LIMITS.md

@@ -0,0 +1,41 @@
+# Domain limits
+
+Pinned limits enforced by seed, MIME, search, REST list/batch, and MCP pageSize.
+
+| Limit | Value | Notes |
+| --- | --- | --- |
+| Raw MIME bytes (accept) | `36700160` | Checked before parse and after base64url decode |
+| Decoded MIME bytes | `36700160` | Canonical raw upper bound |
+| Header count / header bytes | `1000` / `262144` | Folded headers count after unfolding |
+| MIME parts / nesting depth | `500` / `20` | Multipart boundaries fail loudly |
+| Recipients (To+Cc+Bcc) | `500` per field in seeds | Send delivery is deduplicated by normalized address |
+| Attachment count / filename bytes / attachment bytes | `100` / `512` / bounded by raw | Recording projects to `{sha256,size}` |
+| `messages.send` / insert media `maxSize` (discovery) | `36700160` | From discovery; twin may lower |
+| `messages.insert` / `import` media `maxSize` (discovery) | `157286400` | From discovery; twin may lower |
+| Draft create/update media `maxSize` (discovery) | `36700160` | From discovery; twin may lower |
+| Search query bytes / tokens / nesting / branches | `4096` / `256` / `20` / `256` | Shared AST for domain + filters |
+| In-memory search mailbox messages | `10000` | Intentional bound: hydrate + JS predicate; **loud fail** above budget. Parameterized SQL compile of the AST is deferred |
+| Colored-star `has:*-star` | unsupported | Loud reject; use `is:starred` (system `STARRED` only) |
+| Labels per mailbox / per message | `5000` / `100` in seeds | |
+| Filters per mailbox | `1000` in seeds | `action.forward` → 501 (no forwarding delivery) |
+| Batch modify/delete ID count | `1000` | Enforced on `batchModify` / `batchDelete` |
+| List `maxResults` | default `100`, max `500` | REST messages/threads/drafts/history |
+| History page size | default `100`, max `500` | Same `maxResults` cap as other lists |
+| MCP `pageSize` | default `20`, max `50` | `search_threads` / `list_drafts` / `list_labels` |
+| State export message bodies | always digested | `/_pome/state` never includes plaintext text/html/headers/snippet (sha256 digests only); collections capped at `2000` rows; **history** keeps the newest 2000 when truncated (messages/attachments/labels keep oldest-first); body-omission flag set when mailbox exceeds `500` messages |
+| SQLite bind parameters | parameterized only | Query text is never interpolated |
+| Packaged boot | ≤ 3s | Contract gate (later) |
+
+## Page tokens
+
+Opaque page tokens are HMAC-signed and bound to mailbox email, route, normalized
+query/filter, and the mailbox history high-water mark. The signing key resolves as:
+
+1. `POME_GMAIL_PAGE_TOKEN_SECRET` when set
+2. else a key derived from `TWIN_AUTH_SECRET`
+3. else a per-process ephemeral secret
+
+There is no forgeable public default string. Cross-mailbox, cross-query, and stale
+snapshot tokens fail with `invalidArgument`.
+
+See `performanceBudgets` in [`fidelity.inventory.json`](fidelity.inventory.json).

package/node_modules/@pome-sh/twin-gmail/README.md

@@ -0,0 +1,109 @@
+# `@pome-sh/twin-gmail`
+
+Deterministic Gmail-shaped twin for agent testing (Pome).
+
+**Status: OSS release candidate.** This package includes the deterministic
+SQLite mailbox model, strict seed/reset APIs, canonical MIME storage, identity,
+delivery, drafts, labels/history/search, bounded semantic state export,
+recording projection, the frozen Gmail REST/upload surface, and the captured
+ten-tool first-party MCP contract.
+
+## Auth identity (frozen)
+
+| Item | Value |
+| --- | --- |
+| Claim | `gmail_email` on the Pome session JWT |
+| Default local mailbox | `pome-agent@pome-twin.test` |
+| Agent token env | `POME_GMAIL_TOKEN` (alias of `POME_AUTH_TOKEN`) |
+| Bearer | Pome session JWT — **not** a Google OAuth access token |
+
+Pome owns authentication. This twin does **not** implement Google consent
+screens, OAuth codes, refresh tokens, JWKS, or scope issuance.
+
+Mailbox resolution accepts only `me` or the exact `gmail_email` value.
+Unknown/cross-mailbox access returns the captured Gmail not-found shape without
+revealing mailbox existence.
+
+## Gate 0 artifacts
+
+| Path | Role |
+| --- | --- |
+| [`fixtures/rest-surface.json`](fixtures/rest-surface.json) | Frozen launch REST method/parameter/media matrix from Gmail v1 discovery |
+| [`fixtures/mcp-tools-list.*.json`](fixtures/) | Official Gmail MCP `tools/list` raw + canonical (10-tool launch set) |
+| [`fidelity.inventory.json`](fidelity.inventory.json) | Heat × fidelity × evidence for every launch REST/MCP row |
+| [`REFERENCE-DIVERGENCES.md`](REFERENCE-DIVERGENCES.md) | Emulate rejected; never an oracle |
+| [`LIMITS.md`](LIMITS.md) | Limit placeholders (discovery maxima + TBD local caps) |
+
+See [`fixtures/README.md`](fixtures/README.md) for capture provenance and SHA-256.
+
+## Launch MCP tools (exactly 10)
+
+`create_draft`, `list_drafts`, `get_thread`, `search_threads`, `label_thread`,
+`unlabel_thread`, `list_labels`, `label_message`, `unlabel_message`,
+`create_label`.
+
+Order and schemas are frozen from the live listing capture (relative order among
+the launch set). Three extra preview tools seen live are **out of launch scope**
+(named cold in the inventory).
+
+## Named 501 gaps (not fake success)
+
+- `users.watch` / `users.stop` — no Pub/Sub; loud 501
+- Resumable upload initiation/chunks — loud 501
+- Filter `action.forward` — loud 501 (no forwarding delivery)
+- `processForCalendar=true`, `deleted=true` on insert/import — loud 501
+
+## Non-goals
+
+- External SMTP / network mail delivery (`messages.send` is a mailbox-state transition)
+- Pub/Sub push notifications
+- Google OAuth/OIDC
+- Calendar, Drive, Contacts, client UI, CSE, delegates, S/MIME, admin controls
+- HTTP batch API
+- Resumable upload
+- Expanding MCP beyond the frozen 10-tool launch set without a new Gate 0 ruling
+
+## Limits
+
+See [`LIMITS.md`](LIMITS.md). Defaults/maxima from discovery are frozen in
+`rest-surface.json`. Page tokens are HMAC-bound to mailbox/query/snapshot; set
+`POME_GMAIL_PAGE_TOKEN_SECRET` or rely on `TWIN_AUTH_SECRET` (see LIMITS.md).
+
+## Stateful parity with other first-party twins
+
+Gmail follows the same SDK chassis as GitHub / Slack / Stripe:
+
+| Capability | Gmail | Notes vs peers |
+| --- | --- | --- |
+| `defineTwin` + SQLite domain | yes | Same `@pome-sh/sdk` boot path |
+| `/_pome/state` | yes | Bounded digests; history prefers newest 2000 when capped |
+| `/_pome/events` + durable recorder | yes | `recordingProjection` redacts MIME/bodies |
+| `/admin/reset` + `/admin/seed` | yes | Reports `state_delta` like GitHub (Stripe freezes admin unrecorded) |
+| MCP `reportDelta` / no-op `state_mutation=false` | yes | Aligned with REST `rest-routes-kit` |
+| Session identity claim | `gmail_email` | Peers use provider-shaped claims |
+
+Intentional differences: no Google OAuth (Pome JWT only); watch/stop 501; Stripe-style idempotency/failure-injection middleware is Stripe-only.
+
+## Development
+
+```bash
+npm test -w @pome-sh/twin-gmail
+npm run typecheck -w @pome-sh/twin-gmail
+```
+
+Fixture smoke tests assert launch tool count/order and that watch/stop are
+marked `named_gap_501`; domain tests cover seed/identity, MIME round-trip,
+draft replacement, message labels and computed thread labels, history, search,
+local delivery/Bcc privacy, state export, and recorder payload projection.
+
+## CLI
+
+```bash
+npx @pome-sh/cli twin start gmail
+# prints POME_GMAIL_REST_URL, POME_GMAIL_MCP_URL, POME_AUTH_TOKEN,
+# and the identical POME_GMAIL_TOKEN alias
+```
+
+Use `pome scenarios gmail --copy` for the inbox-triage and captured first-party
+MCP parity scenarios. Hosted rollout is gated separately; see
+[`HOSTED.md`](HOSTED.md).

package/node_modules/@pome-sh/twin-gmail/REFERENCE-DIVERGENCES.md

@@ -0,0 +1,42 @@
+# Reference divergences — Emulate is not an oracle
+
+Emulate (and similar Gmail fakes) may be useful as a **coverage checklist** for which
+surfaces agents poke. They are **never** a behavioral oracle for `@pome-sh/twin-gmail`.
+
+The oracles for this twin are:
+
+1. Frozen Gmail API v1 discovery → [`fixtures/rest-surface.json`](fixtures/rest-surface.json)
+2. Captured / documented official Gmail MCP listing → [`fixtures/mcp-tools-list.canonical.json`](fixtures/mcp-tools-list.canonical.json)
+3. Sanitized live Gmail REST captures (when reconciled later)
+4. This package’s invariants (draft ID replacement, mailbox-local IDs, no false watch success, etc.)
+
+## Explicitly rejected Emulate-known-bad behaviors
+
+| Rejected behavior | Twin rule |
+| --- | --- |
+| **In-place draft message IDs** — updating a draft keeps the same underlying Gmail message id | Draft **id** is stable; each update **replaces** the underlying Gmail message id. Send deletes the draft/draft message and creates a new `SENT` message id. |
+| **Permissive malformed JSON** — accepting broken bodies / wrong types with silent coercion | Reject malformed JSON and schema violations with the captured Gmail/MCP error envelope. No silent coercion. |
+| **Numeric offset page tokens** — `pageToken` as an integer offset | Page tokens are opaque, versioned, tamper-evident, bound to mailbox/route/query/sort/snapshot. Malformed/cross-query tokens fail loudly. |
+| **Shallow search** — substring-only or partial operator support presented as Gmail search | Implement the full operator grammar declared by the captured `search_threads` tool; message-first match then thread expansion. Unknown operators (and unknown `category:` values) fail loudly — they never silently fall back to full-text match. `category:primary` maps to `CATEGORY_PERSONAL`. Colored-star `has:*-star` operators are **loud-rejected** (twin has system `STARRED` only via `is:starred`). Search evaluation is intentionally in-memory with a hard mailbox-size budget (`LIMITS.md`); SQL compile of the AST is deferred. |
+| **Incomplete settings methods** — advertising filters/sendAs/forwarding while omitting declared launch methods or inventing extras | Launch settings surface is exactly the frozen set in `rest-surface.json` (`filters` list/get/create/delete, `forwardingAddresses` list/get, `sendAs` list/get). Everything else is unsupported/501. |
+| **Nondeterministic values** — random ids, wall-clock-only dates, unordered collections | Reset/seed produces deterministic ids, dates, and sorted exports. Tests pin order and values. |
+| **Successful inert `watch` / `stop`** — HTTP 200 registration that does nothing | `users.watch` and `users.stop` are **named gaps** returning the loud **501** unsupported envelope. No fake Pub/Sub success. No network I/O. |
+
+## Offline fidelity notes (no Google OAuth required)
+
+Checked against frozen discovery / public API docs (not live authenticated Gmail):
+
+| Surface | Official expectation | Twin behavior | Evidence |
+| --- | --- | --- | --- |
+| `threadId` on send/insert/import/draft | Optional; when present and owned, message joins that thread | Honors explicit owned `threadId` even without In-Reply-To/References | `storage.resolveThread`, domain/REST send paths |
+| Draft send identity | Send removes draft; sent message retains draft's thread | Solo drafts keep thread id across delete→send (empty thread preserved until send) | `domain.sendDraft` |
+| Bad search `q` | Client input error → `400 INVALID_ARGUMENT` | Search/MIME client failures throw `GmailError(400)`; REST `asInputError` + MCP `errorEnvelope` | `search.ts`, `mime.ts`, `errors.ts` |
+| `users.watch` / `users.stop` | Live Gmail uses Pub/Sub | Named gap **501** (never fake registration) | `rest-routes-resources`, `rest-surface.json` |
+
+Live authenticated Gmail calls were **not** run (no OAuth credentials). Offline checks used `fixtures/rest-surface.json`, packaged discovery raw fixture, `npm run fidelity:parity`, and `npm run preview:drift` when available.
+
+## Other non-oracles
+
+- Google OAuth/OIDC consent screens, refresh tokens, JWKS, and scope issuance are **out of scope**. Pome session auth + frozen `gmail_email` claim only.
+- External SMTP delivery, Pub/Sub push, forwarding delivery, Calendar, Drive, Contacts, CSE, HTTP batch, and resumable upload are **out of scope** (loud failure, never silent success).
+- Live Developer Preview MCP may expose tools beyond the launch 10; the twin does **not** expand the listing to chase preview drift without a new Gate 0 ruling.