@run402/sdk 4.31.0 → 4.32.1

package/core-dist/binding-file.d.ts

@@ -0,0 +1,24 @@
+/** The committed binding file. Safe to check in — it names, never authorizes. */
+export declare const BINDING_FILE = ".run402.json";
+/** The personal override. Gitignored; beats the committed file key-by-key. */
+export declare const BINDING_LOCAL_FILE = ".run402.local.json";
+export interface BindingKeyHit {
+    /** The trimmed value found. */
+    value: string;
+    /** The file it came from — surfaced in provenance and conflict messages. */
+    file: string;
+}
+/**
+ * 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 declare function findBindingKey(startDir: string, key: string): BindingKeyHit | null;
+/** Path of the committed binding file for a directory. */
+export declare function bindingFilePath(dir?: string): string;
+/** Parse a directory's committed binding file, or `{}` when absent/unreadable. */
+export declare function readBindingFile(dir?: string): Record<string, unknown>;
+//# sourceMappingURL=binding-file.d.ts.map

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/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/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/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/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/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/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/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/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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@run402/sdk",
-  "version": "4.31.0",
+  "version": "4.32.1",
   "description": "Typed TypeScript client for the Run402 API. Kernel shared by the run402-mcp server, the run402 CLI, and user-deployed run402 functions.",
   "type": "module",
   "main": "dist/index.js",