run402 4.31.0 → 4.32.0

package/cli.mjs

@@ -63,7 +63,7 @@ Commands:
   ai          AI translation and moderation tools
   image       Generate AI images via x402 or MPP micropayments
   email       Send template-based emails from your project
-  message     Send messages to Run402 developers
+  feedback    Send feedback to the Run402 developers (free with an active tier)
   auth        Manage project user authentication (magic link, passwords, settings)
   billing     Email organizations, Stripe tier checkout, email packs
   contracts   KMS signers ($0.04/day rental + $0.000005/sign)

package/core-dist/binding-file.js

@@ -0,0 +1,83 @@
+/**
+ * The per-directory binding file — `.run402.json`, and its gitignored personal
+ * override `.run402.local.json`.
+ *
+ * A checkout binds itself to a wallet profile, an organization, a room, by
+ * committing a small JSON file. That is a CHECKOUT-LEVEL CONTRACT, not a CLI
+ * implementation detail: every agent working in the directory inherits the
+ * same one, whichever surface it reaches Run402 through.
+ *
+ * It lives in core because two surfaces now read it. The CLI has always walked
+ * this chain; the MCP server needs the same answer for the same directory, and
+ * `run402-mcp` ships only `dist` + `core/dist` + `sdk/dist` — `cli/` is not in
+ * the published package, so the MCP server cannot import the CLI's copy even
+ * if it wanted to. One reader, in the one place both can see it, rather than
+ * two that agree until they don't.
+ *
+ * Deliberately pure: `node:fs` + `node:path`, no logging, no process exit, no
+ * validation of what a value MEANS. Callers decide whether a value is
+ * well-shaped and what to do when it isn't — the CLI exits, the MCP server
+ * returns an error, and neither behaviour belongs in a file reader.
+ *
+ * Unknown keys are ignored on purpose: that is what makes an older client
+ * forward-compatible with a binding file written by a newer one.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** The committed binding file. Safe to check in — it names, never authorizes. */
+export const BINDING_FILE = ".run402.json";
+/** The personal override. Gitignored; beats the committed file key-by-key. */
+export const BINDING_LOCAL_FILE = ".run402.local.json";
+/** Read one key from a single directory's binding files, override first. */
+function readBindingKeyFrom(dir, key) {
+    for (const fname of [BINDING_LOCAL_FILE, BINDING_FILE]) {
+        const p = join(dir, fname);
+        try {
+            const parsed = JSON.parse(readFileSync(p, "utf8"));
+            const v = parsed?.[key];
+            if (typeof v === "string" && v.trim())
+                return { value: v.trim(), file: p };
+        }
+        catch {
+            /* missing / unreadable / malformed → skip */
+        }
+    }
+    return null;
+}
+/**
+ * Nearest binding of `key`, walking up from `startDir` to the filesystem root.
+ *
+ * Resolution is PER KEY, not per file: the nearest file that carries the key
+ * wins, so `/work/.run402.json` may supply the organization while
+ * `/work/api/.run402.json` supplies the wallet. A worktree nested under a bound
+ * checkout therefore inherits the binding without restating it.
+ */
+export function findBindingKey(startDir, key) {
+    let dir = resolve(startDir);
+    for (;;) {
+        const hit = readBindingKeyFrom(dir, key);
+        if (hit)
+            return hit;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Path of the committed binding file for a directory. */
+export function bindingFilePath(dir = process.cwd()) {
+    return join(dir, BINDING_FILE);
+}
+/** Parse a directory's committed binding file, or `{}` when absent/unreadable. */
+export function readBindingFile(dir = process.cwd()) {
+    try {
+        const parsed = JSON.parse(readFileSync(bindingFilePath(dir), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=binding-file.js.map

package/lib/events.mjs

@@ -30,7 +30,8 @@ Usage:
 
 Options:
   --project <id>    Project to read (defaults to the active project)
-  --org <id>        Read the org-wide feed instead (union across the org's projects)
+  --org <id>        Read the org-wide feed instead — a SUPERSET of the project
+                    feeds: it also carries org-level facts (project_id null)
   --cursor <cursor> Opaque cursor from a previous response. Returns events strictly
                     after it. Omit on first contact to start from the earliest
                     retained event.
@@ -52,28 +53,41 @@ App events vs platform events:
   one your app already uses — the source field is what disambiguates.
   Omit --source to read both lanes in one merged, cursor-ordered feed.
 
-The cursor model:
+The cursor model — an id is not a cursor:
   - Every response carries "cursor": the high-water mark. Store it (a file in
     your repo, a memory note — wherever you keep state) and pass it back as
     --cursor next time. One call then returns everything you missed.
-  - Cursors are opaque (evc_...). Never parse or compare them; any event's
-    "id" is also a valid --cursor value to resume right after that event.
-  - Events become visible within a couple of seconds of the change committing
-    (a short visibility watermark orders concurrent writes). After that they
-    are never lost: a cursor read misses nothing that committed before the
-    cursor was issued.
+  - Two opaque tokens, and they are different things. An event's "id" names a
+    FACT: the same event has the same id in the project feed and the org feed,
+    which is how you dedup across both. The page "cursor" names a POSITION,
+    and a position only means something inside the row set it came from.
+  - So a cursor is NOT portable. Replaying a --project cursor against --org,
+    an unfiltered cursor against a --source/--type read, or an event "id" in
+    place of a cursor all return "reset": true instead of resuming — because
+    resuming would silently skip exactly the rows the other view omitted.
+    Store each cursor against the read shape that produced it.
+  - Never parse or compare either token.
+  - Events become visible within a couple of seconds of the change committing.
+    That watermark is a bound, not a proof: it gives a write's commit window
+    time to close, so in practice a cursor read misses nothing that committed
+    before it was issued.
   - "has_more": true means more events are immediately available — call again
     with the new cursor right away.
 
-When your cursor is too old (reset semantics):
+When your cursor is unusable (reset semantics):
   - Feed retention is 90 days (365 for security/recovery/billing-critical
-    classes). A cursor older than that — or malformed — still returns 200,
-    with "reset": true and "earliest_cursor": the point to restart from.
-    Nothing is silently skipped; you are told exactly what happened and how
-    to proceed.
+    classes). A cursor older than that — malformed, from another view, or an
+    event id — still returns 200, with "reset": true and "earliest_cursor":
+    the point to restart from. Nothing is silently skipped; you are told
+    exactly what happened and how to proceed.
 
 Event shape:
-  { "id", "event_type", "class", "occurred_at", "payload", "next_actions" }
+  { "id", "project_id", "event_type", "class", "occurred_at", "payload",
+    "next_actions" }
+  project_id is what the fact is ABOUT. It is null for an org-level fact —
+  one that belongs to the org and to no project, visible only via --org. It
+  may also name a project that no longer exists: a fact outlives the project
+  it describes, so deleting a project no longer erases its history.
   event_type is flat snake_case: deploy_activated, mailbox_suspended,
   project_transfer_completed, organization_past_due, verification_failed,
   webhook_disabled, ... Each event's next_actions[] is the platform's own

package/lib/wallet-context.mjs

@@ -19,15 +19,26 @@
  * wallets and no flag is given, that is a hard error (not a silent pick).
  */
 
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { existsSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { fail } from "./sdk-errors.mjs";
 import { isValidProfileName } from "../core-dist/config.js";
 import { getDefaultWallet, profileExists, readMeta, profileDir } from "../core-dist/profiles.js";
 import { readAllowance } from "../core-dist/allowance.js";
+// The binding file is a CHECKOUT-LEVEL CONTRACT read by more than one surface,
+// so its reader lives in core — `run402-mcp` ships core/dist but not cli/, and
+// two readers of one file format is exactly the drift worth not having.
+// Re-exported here under the names the rest of the CLI already imports.
+import {
+  findBindingKey,
+  bindingFilePath,
+  readBindingFile,
+  BINDING_FILE,
+} from "../core-dist/binding-file.js";
+
+export { findBindingKey, bindingFilePath, readBindingFile };
 
 const DEFAULT = "default";
-const BINDING_FILE = ".run402.json";
 const GLOBAL_FLAGS = new Set(["--wallet", "--profile"]);
 // The `wallets` group is the management + escape surface — it must work even
 // when selection is ambiguous (so you can `wallets unbind`), and it validates
@@ -70,36 +81,6 @@ export function splitWalletFlag(rawArgv = []) {
   return { argv, walletFlag: flag };
 }
 
-function readBindingKeyFrom(dir, key) {
-  // .run402.local.json (gitignored personal override) beats .run402.json.
-  for (const fname of [".run402.local.json", ".run402.json"]) {
-    const p = join(dir, fname);
-    try {
-      const parsed = JSON.parse(readFileSync(p, "utf8"));
-      const v = parsed?.[key];
-      if (typeof v === "string" && v.trim()) return { value: v.trim(), file: p };
-    } catch {
-      /* missing / unreadable / malformed → skip */
-    }
-  }
-  return null;
-}
-
-/** Path of the committed binding file for a directory. */
-export function bindingFilePath(dir = process.cwd()) {
-  return join(dir, BINDING_FILE);
-}
-
-/** Parse a directory's committed binding file, or `{}` when absent/unreadable. */
-export function readBindingFile(dir = process.cwd()) {
-  try {
-    const parsed = JSON.parse(readFileSync(bindingFilePath(dir), "utf8"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
 /**
  * MERGE keys into a directory's binding file. A `null` value removes its key;
  * a file left with no keys is deleted rather than committed empty.
@@ -124,26 +105,6 @@ export function updateBindingFile(dir, patch) {
   return { file, contents: next, removed: false };
 }
 
-/**
- * Nearest binding carrying `key`, walking up from `startDir` to the root.
- *
- * Keys bind INDEPENDENTLY (add-cli-current-org, design D7): a file declaring
- * only `org` leaves wallet resolution untouched, and each key resolves at the
- * nearest file that carries it — so `/work/.run402.json` may supply the org
- * while `/work/api/.run402.json` supplies the wallet. Unknown keys are ignored,
- * which is what makes older CLIs forward-compatible with these files.
- */
-export function findBindingKey(startDir, key) {
-  let dir = resolve(startDir);
-  for (;;) {
-    const hit = readBindingKeyFrom(dir, key);
-    if (hit) return hit;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
 /** Nearest wallet binding walking up from `startDir` to the filesystem root. */
 export function findBinding(startDir) {
   const hit = findBindingKey(startDir, "wallet");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.31.0",
+  "version": "4.32.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/core-dist/binding-file.js

@@ -0,0 +1,83 @@
+/**
+ * The per-directory binding file — `.run402.json`, and its gitignored personal
+ * override `.run402.local.json`.
+ *
+ * A checkout binds itself to a wallet profile, an organization, a room, by
+ * committing a small JSON file. That is a CHECKOUT-LEVEL CONTRACT, not a CLI
+ * implementation detail: every agent working in the directory inherits the
+ * same one, whichever surface it reaches Run402 through.
+ *
+ * It lives in core because two surfaces now read it. The CLI has always walked
+ * this chain; the MCP server needs the same answer for the same directory, and
+ * `run402-mcp` ships only `dist` + `core/dist` + `sdk/dist` — `cli/` is not in
+ * the published package, so the MCP server cannot import the CLI's copy even
+ * if it wanted to. One reader, in the one place both can see it, rather than
+ * two that agree until they don't.
+ *
+ * Deliberately pure: `node:fs` + `node:path`, no logging, no process exit, no
+ * validation of what a value MEANS. Callers decide whether a value is
+ * well-shaped and what to do when it isn't — the CLI exits, the MCP server
+ * returns an error, and neither behaviour belongs in a file reader.
+ *
+ * Unknown keys are ignored on purpose: that is what makes an older client
+ * forward-compatible with a binding file written by a newer one.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** The committed binding file. Safe to check in — it names, never authorizes. */
+export const BINDING_FILE = ".run402.json";
+/** The personal override. Gitignored; beats the committed file key-by-key. */
+export const BINDING_LOCAL_FILE = ".run402.local.json";
+/** Read one key from a single directory's binding files, override first. */
+function readBindingKeyFrom(dir, key) {
+    for (const fname of [BINDING_LOCAL_FILE, BINDING_FILE]) {
+        const p = join(dir, fname);
+        try {
+            const parsed = JSON.parse(readFileSync(p, "utf8"));
+            const v = parsed?.[key];
+            if (typeof v === "string" && v.trim())
+                return { value: v.trim(), file: p };
+        }
+        catch {
+            /* missing / unreadable / malformed → skip */
+        }
+    }
+    return null;
+}
+/**
+ * Nearest binding of `key`, walking up from `startDir` to the filesystem root.
+ *
+ * Resolution is PER KEY, not per file: the nearest file that carries the key
+ * wins, so `/work/.run402.json` may supply the organization while
+ * `/work/api/.run402.json` supplies the wallet. A worktree nested under a bound
+ * checkout therefore inherits the binding without restating it.
+ */
+export function findBindingKey(startDir, key) {
+    let dir = resolve(startDir);
+    for (;;) {
+        const hit = readBindingKeyFrom(dir, key);
+        if (hit)
+            return hit;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Path of the committed binding file for a directory. */
+export function bindingFilePath(dir = process.cwd()) {
+    return join(dir, BINDING_FILE);
+}
+/** Parse a directory's committed binding file, or `{}` when absent/unreadable. */
+export function readBindingFile(dir = process.cwd()) {
+    try {
+        const parsed = JSON.parse(readFileSync(bindingFilePath(dir), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=binding-file.js.map

package/sdk/dist/namespaces/events.d.ts

@@ -36,10 +36,19 @@ export declare class Events {
      */
     list(projectId: string, opts?: ListEventsOptions): Promise<ProjectEventFeedPage>;
     /**
-     * Read the org-wide feed — the union across every project the org owns
-     * (`GET /orgs/v1/:org_id/events`). Principal-only: requires an active org
-     * membership; a project service_key is rejected by the gateway. Same
-     * `opts.source` / `opts.eventType` filters as {@link list}.
+     * Read the org-wide feed (`GET /orgs/v1/:org_id/events`) — every fact the
+     * organization owns. That is a SUPERSET of its project feeds, not a union
+     * of them: it also carries organization-level facts, which belong to no
+     * project, arrive with `project_id: null`, and are unreachable from any
+     * project feed.
+     *
+     * Principal-only: requires an active org membership; a project service_key
+     * is rejected by the gateway. Same `opts.source` / `opts.eventType` filters
+     * as {@link list}.
+     *
+     * Cursors do NOT interchange with {@link list}, even though an event's `id`
+     * is the same in both — a cursor names a position inside one projection.
+     * Carrying one across returns `reset: true`; see {@link ListEventsOptions.cursor}.
      */
     listForOrg(orgId: string, opts?: ListEventsOptions): Promise<ProjectEventFeedPage>;
 }

package/sdk/dist/namespaces/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/namespaces/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAcjF,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE3C;;;;;;;OAOG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAU1F;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAS7F"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/namespaces/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAcjF,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE3C;;;;;;;OAOG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAU1F;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAS7F"}

package/sdk/dist/namespaces/events.js

@@ -56,10 +56,19 @@ export class Events {
         return this.client.request(`/projects/v1/${encodeURIComponent(projectId)}/events${feedQuery(opts)}`, { method: "GET", context: "reading project events feed" });
     }
     /**
-     * Read the org-wide feed — the union across every project the org owns
-     * (`GET /orgs/v1/:org_id/events`). Principal-only: requires an active org
-     * membership; a project service_key is rejected by the gateway. Same
-     * `opts.source` / `opts.eventType` filters as {@link list}.
+     * Read the org-wide feed (`GET /orgs/v1/:org_id/events`) — every fact the
+     * organization owns. That is a SUPERSET of its project feeds, not a union
+     * of them: it also carries organization-level facts, which belong to no
+     * project, arrive with `project_id: null`, and are unreachable from any
+     * project feed.
+     *
+     * Principal-only: requires an active org membership; a project service_key
+     * is rejected by the gateway. Same `opts.source` / `opts.eventType` filters
+     * as {@link list}.
+     *
+     * Cursors do NOT interchange with {@link list}, even though an event's `id`
+     * is the same in both — a cursor names a position inside one projection.
+     * Carrying one across returns `reset: true`; see {@link ListEventsOptions.cursor}.
      */
     async listForOrg(orgId, opts = {}) {
         if (!orgId) {

package/sdk/dist/namespaces/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/namespaces/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,SAAS,SAAS,CAAC,OAA0B,EAAE;IAC7C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,OAAO,MAAM;IACY;IAA7B,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,OAA0B,EAAE;QACxD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,UAAU,CAAC,kCAAkC,EAAE,6BAA6B,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,UAAU,SAAS,CAAC,IAAI,CAAC,EAAE,EACxE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAC1D,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,KAAa,EAAE,OAA0B,EAAE;QAC1D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAAC,qCAAqC,EAAE,yBAAyB,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,YAAY,kBAAkB,CAAC,KAAK,CAAC,UAAU,SAAS,CAAC,IAAI,CAAC,EAAE,EAChE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,EAAE,CACtD,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/namespaces/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,SAAS,SAAS,CAAC,OAA0B,EAAE;IAC7C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,OAAO,MAAM;IACY;IAA7B,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,OAA0B,EAAE;QACxD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,UAAU,CAAC,kCAAkC,EAAE,6BAA6B,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,UAAU,SAAS,CAAC,IAAI,CAAC,EAAE,EACxE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAC1D,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,UAAU,CAAC,KAAa,EAAE,OAA0B,EAAE;QAC1D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAAC,qCAAqC,EAAE,yBAAyB,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,YAAY,kBAAkB,CAAC,KAAK,CAAC,UAAU,SAAS,CAAC,IAAI,CAAC,EAAE,EAChE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,EAAE,CACtD,CAAC;IACJ,CAAC;CACF"}

package/sdk/dist/namespaces/events.types.d.ts

@@ -6,8 +6,18 @@
  * The feed is the platform's durable, ordered record of operationally
  * significant facts (deploy activations, mailbox suspensions, transfers,
  * lifecycle cliffs, verification outcomes, and `platform_incident`
- * fault-attribution events). Cursors are OPAQUE (`evc_…`): store the page's
- * `cursor` and pass it back as `{ cursor }` next time — never parse it. The
+ * fault-attribution events).
+ *
+ * An ORGANIZATION owns each fact and `project_id` says what it is about, so
+ * three things follow. The org feed is a SUPERSET of the project feeds: it
+ * also carries organization-level facts, which belong to no project and
+ * arrive with `project_id: null`. A fact OUTLIVES the project it describes —
+ * deleting a project no longer erases its history, so a row may name a
+ * project that no longer exists. And an event's `id` is NOT a page cursor:
+ * see {@link ProjectEvent.id} and {@link ListEventsOptions.cursor}.
+ *
+ * Both tokens are OPAQUE (`evc_…`) — store the page's `cursor`, pass it back
+ * as `{ cursor }` next time, and never parse either one. The
  * platform owns the event vocabulary, `next_actions` synthesis, and reset
  * behavior; the SDK passes everything through (index signatures keep unknown
  * future fields, including the additive `platform_incidents[]` overlay and
@@ -32,10 +42,27 @@ export interface ProjectEventNextAction {
     why?: string;
     [key: string]: unknown;
 }
-/** One immutable fact from the project events feed. */
+/** One immutable fact from the events feed. */
 export interface ProjectEvent {
-    /** Opaque event cursor (`evc_…`) — also a valid `cursor` input to resume after this event. */
+    /**
+     * This event's opaque identity (`evc_…`). The SAME event carries the SAME
+     * `id` in the project feed and the organization feed, which is what lets
+     * you dedup across both.
+     *
+     * NOT a page cursor. An id names a FACT; a cursor names a POSITION inside
+     * one projection, and only the page's `cursor` is that. Passing an `id` as
+     * `{ cursor }` returns `reset: true` rather than resuming.
+     */
     id: string;
+    /**
+     * What this fact is ABOUT — `null` for an organization-level fact, which
+     * belongs to the organization and to no project. Those appear only on the
+     * organization feed; a project feed can never show them.
+     *
+     * May name a project that NO LONGER EXISTS: a fact outlives the project it
+     * describes, so do not assume this resolves.
+     */
+    project_id: string | null;
     /** Flat snake_case event name, e.g. `deploy_activated`, `mailbox_suspended`. */
     event_type: string;
     /** Event class stamped at write time (drives retention: mandatory classes keep 365 days, others 90). */
@@ -50,9 +77,18 @@ export interface ProjectEvent {
 /** Options for {@link Events.list} / {@link Events.listForOrg}. */
 export interface ListEventsOptions {
     /**
-     * Opaque cursor from a prior page (`cursor` field or an event `id`).
-     * Returns events strictly after it. Omit on first contact to start from
-     * the earliest retained event.
+     * Opaque page cursor from a prior page's `cursor` field. Returns events
+     * strictly after it. Omit on first contact to start from the earliest
+     * retained event.
+     *
+     * A page cursor is bound to the PROJECTION that issued it — the feed you
+     * read plus any `source` / `eventType` filters. It is not portable:
+     * replaying a project feed's cursor against the organization feed, an
+     * unfiltered cursor against a filtered read, or an event `id` in place of a
+     * cursor all return `reset: true` instead of resuming, because resuming
+     * would silently skip exactly the rows the other projection omitted.
+     *
+     * So key any cursor you persist by the read shape it came from.
      */
     cursor?: string;
     /** Page size (server default 50, max 200). */
@@ -81,12 +117,17 @@ export interface ProjectEventFeedPage {
     /** True when more events are immediately available past `cursor`. */
     has_more: boolean;
     /**
-     * True when the supplied cursor was unusable (malformed or older than the
-     * retention floor). The page restarts from the earliest retained event and
-     * `earliest_cursor` is provided — never a bare error, never a silent skip.
+     * True when the supplied cursor was unusable — malformed, older than the
+     * retention floor, issued for a DIFFERENT projection (another feed or
+     * filter set), or actually an event `id`. The page restarts from the
+     * earliest retained event and `earliest_cursor` is provided — never a bare
+     * error, never a silent skip.
      */
     reset: boolean;
-    /** Present only when `reset` is true: a cursor just before the earliest retained event. */
+    /**
+     * Present only when `reset` is true: a page cursor just before the earliest
+     * retained event, issued for the projection you actually read.
+     */
     earliest_cursor?: string;
     /**
      * Sidecar overlay of open GLOBAL (unattributed) platform incidents, each

package/sdk/dist/namespaces/events.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.types.d.ts","sourceRoot":"","sources":["../../src/namespaces/events.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,8FAA8F;IAC9F,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,wGAAwG;IACxG,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,yHAAyH;IACzH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,4EAA4E;IAC5E,YAAY,EAAE,sBAAsB,EAAE,CAAC;IACvC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC/B;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}
+{"version":3,"file":"events.types.d.ts","sourceRoot":"","sources":["../../src/namespaces/events.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,wGAAwG;IACxG,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,yHAAyH;IACzH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,4EAA4E;IAC5E,YAAY,EAAE,sBAAsB,EAAE,CAAC;IACvC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC/B;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/sdk/dist/namespaces/events.types.js

@@ -6,8 +6,18 @@
  * The feed is the platform's durable, ordered record of operationally
  * significant facts (deploy activations, mailbox suspensions, transfers,
  * lifecycle cliffs, verification outcomes, and `platform_incident`
- * fault-attribution events). Cursors are OPAQUE (`evc_…`): store the page's
- * `cursor` and pass it back as `{ cursor }` next time — never parse it. The
+ * fault-attribution events).
+ *
+ * An ORGANIZATION owns each fact and `project_id` says what it is about, so
+ * three things follow. The org feed is a SUPERSET of the project feeds: it
+ * also carries organization-level facts, which belong to no project and
+ * arrive with `project_id: null`. A fact OUTLIVES the project it describes —
+ * deleting a project no longer erases its history, so a row may name a
+ * project that no longer exists. And an event's `id` is NOT a page cursor:
+ * see {@link ProjectEvent.id} and {@link ListEventsOptions.cursor}.
+ *
+ * Both tokens are OPAQUE (`evc_…`) — store the page's `cursor`, pass it back
+ * as `{ cursor }` next time, and never parse either one. The
  * platform owns the event vocabulary, `next_actions` synthesis, and reset
  * behavior; the SDK passes everything through (index signatures keep unknown
  * future fields, including the additive `platform_incidents[]` overlay and

package/sdk/dist/namespaces/events.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.types.js","sourceRoot":"","sources":["../../src/namespaces/events.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}
+{"version":3,"file":"events.types.js","sourceRoot":"","sources":["../../src/namespaces/events.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}