iterate 0.3.0 → 0.4.0

package/README.md

@@ -1,107 +1,189 @@
 # iterate
 
-CLI for OS Next (`apps/os-next`). Requires Node >=22.15; no Bun runtime.
-
-```sh
-npx iterate                       # offline help
-npx iterate login                 # browser OAuth with project consent
-npx iterate projects list
-npx iterate orgs list
-npx iterate ping
-npx iterate repl --project my-project   # local Node REPL
-npx iterate itx run --project my-project --eval 'return await itx.whoami();'
-npx iterate use-my-computer --project my-project --name myComputer
-npx iterate menubar --project my-project   # macOS app
-npx iterate logout
-```
-
-The default server is `https://os.iterate2.com`. Login uses that server's OAuth
-issuer, PKCE and a loopback callback. Tokens refresh automatically before a
-command when close to expiry. `ITERATE_BEARER_TOKEN` supplies a token for scripts;
-`APP_CONFIG_ADMIN_API_SECRET` supplies operator credentials and takes precedence.
-`ITERATE_SKIP_BROWSER_OPEN=1` prints the login URL without opening a browser.
-
-## Running scripts
-
-`itx run` executes a JavaScript function body on OS Next with `itx` in scope.
-Use `return` for the result. The server records the run and its settlement;
-the CLI never retries a script automatically. Scripts execute on the server,
-so local Node APIs and local filesystem access are unavailable.
-
-```sh
-iterate itx run --project my-project --context /notes --eval '
-  await itx.append({ type: "note", payload: { text: "hello" } });
-  return await itx.readEvents(0, 10);
-'
-iterate itx run --project my-project --file ./script.js
-cat script.js | iterate itx run --project my-project --file -
-```
+The SDK for Iterate (`apps/os`): context APIs, stream processors, reactive clients, React
+bindings, and OAuth app sessions, under `iterate/*`. The package exports source in this
+workspace and compiled JavaScript with declarations when packed. The `iterate` command is
+[`@iterate-com/cli`](../cli/README.md).
+
+## The SDK/platform line
+
+The SDK holds what user code runs or speaks, and the platform is its first user: apps/os builds
+its own entities on `iterate/sdk`, and the first-party apps' code uses only `iterate/*`. Each
+subpath in `package.json`'s `exports` is one public module; nothing else is importable.
+
+- A module belongs here when user code runs it or speaks it: a loaded worker, a facet, a
+  processor, a browser or Node client, or the wire contract between them and the platform. It
+  belongs in apps/os when only the platform's Worker runs it, and in packages/shared when more
+  than one app needs it and user code never does.
+- Outside apps/os, no package and no app imports apps/os. `import-js/no-restricted-paths` in
+  `.oxlintrc.json` resolves each import under `packages/**` and `apps/**` to a file, so type
+  imports, re-exports, dynamic `import()` and an app added later are covered, and
+  `lint/oxlintrc-platform-line.test.ts` pins it. Tests may import apps/os's two harnesses,
+  `apps/os/e2e/support/` and `apps/os/__workers-tests__/support.ts`, which drive a real platform.
+- The one known exception: the git codec (`@iterate-com/shared/git-wire`) and the GitHub template
+  reader live in packages/shared, though only the platform's Worker runs them. packages/shared is
+  private, so they do not cross the line.
+- No private core package behind a thin `iterate`: apps/os would then import modules user code
+  cannot, and the SDK's types would have to be bundled or published anyway.
+
+Follow-ups: move the git codec and the template reader into `apps/os/src/repo/`, and type the test
+harnesses against `iterate/api`. The decision's reasons, and how workerd, the Agents SDK, Convex,
+Supabase, tRPC, Hono and Wrangler draw the same line:
+[the decision record](https://github.com/iterate/iterate/blob/d52a4e8e0f791c96b683fe178b56570532123c05/docs/2026-09-24-sdk-platform-line.md)
+(#3018).
+
+## Reaching the context from loaded code
+
+Code the platform loads for a project (a config worker, a facet, a worker behind a rewrite rule)
+imports the SDK as `./processor.js` and reaches its context through `withItx`: one round trip,
+after which the scope, every call made through it and every handle it awaited are released.
 
-Specify exactly one of `--eval` or `--file`. `--context` is a project-local path
-(default `/`). `--project` accepts an id or slug; otherwise the CLI uses the
-config's `defaultProject`, or the only project accessible to the session.
+```js
+import { ConfigWorker, withItx } from "./processor.js";
 
-## Use my computer
+export default class extends ConfigWorker {
+  async fetch() {
+    // An SDK host (ConfigWorker, StreamProcessorDurableObject) has it as a method.
+    const { projectSlug } = await this.withItx((itx) => itx.whoami());
+    return new Response(`Homepage of ${projectSlug}`);
+  }
+}
 
-`use-my-computer` shares a Mac as a live OS Next capability until Ctrl-C:
+// Anywhere else: withItx(this.env.ITX, (itx) => itx.kv.get("key"))
+```
 
-- `itx.myComputer.ask({ question, buttons? })`: native choice dialog.
-- `itx.myComputer.notify({ message, title? })`: desktop notification.
-- `itx.myComputer.runSwift({ code })`: Swift with the owner's local permissions.
-- `itx.myComputer.__describe()`: usage instructions and method signatures.
+Never keep what `env.ITX.get()` hands out, and answer data, not handles, from `withItx`: a kept
+scope, step or handle keeps the context, and any facet holding it, resident after the project goes
+idle. An object that needs
+reach takes a `WithItx` accessor (`(call) => withItx(this.env.ITX, call)`), never a scope; work
+that outlives the call runs under a processor's `runInBackground` claim. Lint refuses a raw
+`ITX.get()` in this repository (`iterate/no-raw-itx-get`).
 
-The command requires macOS, AppleScript and Swift. Share only with a project
-you trust: its callers can run local code. The capability belongs to the live
-connection and is released on exit. A disconnect or token expiry ends sharing
-with an error; rerun the command to refresh authentication and reconnect.
+## Testing a processor
 
-## Configs and migration
+`iterate/stream/test-support` (Node) is the harness the SDK's own engine tests use:
 
-Configs live in `${XDG_CONFIG_HOME:-~/.config}/iterate/config.json`. Selection
-order is `--config`, a parent-directory workspace mapping, the default config,
-a single saved config, then built-in `prd`.
+```ts
+import { reduceProcessor } from "iterate/stream/test-support";
 
-```sh
-iterate config set --name next --os-base-url https://os.iterate2.com \
-  --default-project my-project --set-default
-iterate --config next login
-iterate config set --name local --os-base-url http://localhost:8787 --set-workspace
-iterate config list
-iterate config get
+// apps/os/src/client/presence/processor.test.ts: durable ticks are reduced, ephemeral pokes are not
+const state = reduceProcessor(new PresenceProcessor(), [{ type: "tick" }, { type: "poke" }]);
+// state.ticks === 1
 ```
 
-Existing configs keep their server URL. For a config that targets the old OS,
-set its `--os-base-url` to an OS Next deployment and log in again. Changing the
-server clears that config's session. There is no separate `authBaseUrl` setting.
-
-The old chat TUI and remotely discovered `iterate os ...` commands are removed.
-The menu bar supports sign-in and computer sharing. Approval code is retained
-but dormant until OS Next supports it. Use `iterate itx run` for scripts;
-its `--project` selects the project and `--context` selects a path within it.
-
-## Node REPL
-
-`iterate repl` opens a local Node REPL with the authenticated session as `itx`
-(try `await itx.projects.list()`) and the transport's `RpcTarget` constructor.
-Pass `--project my-project --context /` to bind `itx` to a project context;
-a configured `defaultProject` also selects a project. Top-level `await`, Node APIs and `.load` are available. The bindings remain available after `.clear`; `.exit` releases the context and connection. A lost connection
-ends the REPL visibly; it never silently repeats your commands.
+`memoryStream`, `memoryStorage` and `settle` drive a whole `ProcessorEngine` against an
+in-memory log (`src/stream/processor.test.ts` shows how).
 
 ## Node connections
 
-`iterate/next/node` exposes a connection owner for OS Next scripts and live
+`iterate/node` exposes a connection owner for Iterate scripts and live
 providers. It uses the same protocol and cleanup as the CLI:
 
 ```js
-import { connectOsNext } from "iterate/next/node";
+import { connectIterate } from "iterate/node";
 
-using connection = await connectOsNext({
-  baseUrl: "https://os.iterate2.com",
+using connection = await connectIterate({
+  baseUrl: "https://os.iterate.com",
   auth: { type: "bearer", token: process.env.ITERATE_BEARER_TOKEN },
 });
 using project = await connection.session.projects.get("my-project");
 console.log(await project.run("async (itx) => await itx.whoami()"));
 ```
 
-The package launcher delegates to repository source during development and
-uses the published build when installed through `npx`.
+## Event types
+
+A platform event type is `events.iterate.com/<namespace>/<event>`: one namespace segment and one
+event segment, both lowercase kebab-case, and never a third segment.
+
+Every type under `events.iterate.com/` follows these rules, test types included. A type without
+that prefix belongs to whoever appends it and is opaque to the platform: tests use types like
+`demo/ping` on purpose, and a project may use its own domain (`events.garple.com/sales/…`).
+
+### Namespaces
+
+- **`itx`** holds the context engine's own events: everything the core contract
+  (`apps/os/src/stream/core-processor.ts`) reduces, validates or refuses, plus the records the
+  Stream, the context Durable Object and the SDK processor host write themselves. Where the schema
+  and the reduce live decides it, not which contexts hold the event: fetch routes and the apex
+  ingress target are core state, so they are `itx` even though only a project root's copy is read.
+  A domain processor may consume an `itx` event (the agent consumes `itx/run-*`, the Project
+  processor `itx/ingress-configured`); it names the core's catalog in its `processorDeps` rather than
+  defining the event itself. The core's checkpoint slug is `core`: it is a storage key, not a type
+  prefix.
+- **A domain namespace** is the singular name of the kind of context whose log the event belongs
+  to, which is the defining contract's slug when there is one: `account`, `organization`,
+  `project`, `repo`, `workspace`, `secret`, `agent`, `voice-agent`. A fact cross-posted to another
+  log keeps its own namespace: `repo/created` on `/` is still a repo fact.
+- **An integration** uses its own name as its namespace, for example `chrome`.
+- **`test`** holds types that only tests append. Production code never matches a `test/*` type. A
+  test contract may keep a slug of its own (`counter`), but its events go under `test/`. A test must
+  not borrow a production namespace for a type that does not exist.
+
+### Event names
+
+- **A fact is past tense**: `<object>-<verb-ed>`, or a bare `<verb-ed>` when the object is the
+  namespace's own subject (`itx/created` is the context, `agent/paused` is the agent). The object
+  comes first and is singular.
+- **Spell words out.** Clipped words are not allowed (`spk`); a real word is (`mic`), and so is an
+  acronym the API already spells (`llm`, `rpc`, `itx`).
+- **Asking and answering.** `<x>-requested` asks, and its offset identifies the ask. The answer
+  takes one of three shapes:
+  - `<x>-settled` is the one terminal fact when the asker reads a result. It names
+    `requestOffset` and carries the outcome: succeeded, failed or cancelled, a status, or an error.
+    Examples: `itx/run-*`, `agent/llm-request-*`, `project/hostname-add-*`.
+  - `<verb-ed>` or `<verb>-failed` is used when success is a fact that other logs wait on, like a
+    certificate: `create-requested` → `created` or `create-failed`, `delete-requested` → `deleted`,
+    `hostname-remove-requested` → `hostname-removed`. A failure that is retried rather than
+    reported gets no `-failed` fact.
+  - An answer that is also a fact of its own names the ask by id:
+    `voice-agent/delegation-requested` is answered by one `commentary-added` carrying its
+    `delegationId`.
+- **One verb pair per kind of change:**
+  - `added` / `removed` for membership in a set: `organization/member-added`,
+    `organization/project-added`, hostnames.
+  - `created` / `deleted` for an entity with a lifecycle: projects, repos, workspaces, agents.
+  - `set` / `deleted` for a keyed value: `secret/*`.
+  - `set` / `cancelled` for a schedule: `itx/schedule-*`. Each occurrence is `fired` or `failed`.
+  - `-configured` for one fact that sets a row or clears it with `null`
+    (`itx/subscription-configured`, `itx/rewrite-rule-configured`, `itx/fetch-route-configured`),
+    sets a singleton (`itx/ingress-configured`), or merges a partial configuration
+    (`agent/configured`: omitted keys keep their values).
+- **Things the platform does on its own** are plain facts about the object: `itx/schedule-fired`,
+  `itx/schedule-failed`, `itx/subscription-delivery-halted`.
+- **Ephemeral events.** An ephemeral event that records something happening is named like any other
+  fact: `itx/rpc-stub-attached`, `itx/live-state-changed`, `chrome/navigated`. Three kinds may be
+  singular nouns: a sequenced slice of a live stream is a `<stream>-frame`
+  (`voice-agent/mic-frame`, `agent/llm-response-frame`), a heartbeat (`voice-agent/keepalive`), and
+  a diagnostic record (`itx/alarm-trace`). A durable event is never a noun.
+- **Families and prefixes.** Code matches some families by prefix: `…/itx/run-`,
+  `…/itx/subscription-`, `…/itx/schedule-`, `…/project/hostname-`. Before naming a new type, check
+  it doesn't join one of these families by accident. Never match `…/itx/` as a whole: it is not a
+  permission boundary, and it catches live-state deltas, stub presence and child
+  announcements.
+- **Code follows the type.** A constant, schema, test fixture or idempotency key built from a type
+  follows its name (`itx/child-created:<path>`). Broader concepts, modules and Workers log
+  event names keep theirs: the Stream, scheduled appends, `core`, `scheduled-append.completed`.
+- **Renaming.** A rename has to serve one of these rules, not taste. If a type is stored outside the
+  platform's Durable Objects (device firmware, a published SDK, a project's config repo),
+  rename it only in a change that migrates that store too.
+
+| Namespace                                                           | Defined in                                                                                                                                                                                                                                                                                                 |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `itx`                                                               | `apps/os/src/stream/core-processor.ts` (and its leaf event catalog), `stream.ts`, `scheduled-appends.ts`, `subscription-delivery.ts`, `apps/os/src/context/built-ins.ts`, `apps/os/src/fetch-routes.ts`, `apps/os/src/iterate-context-durable-object.ts`, `packages/iterate/src/stream/{run,processor}.ts` |
+| `account`, `organization`, `project`, `repo`, `workspace`, `secret` | `apps/os/src/<name>/contract.ts` (repo and workspace also use `project/entity-lifecycle.ts`)                                                                                                                                                                                                               |
+| `agent`                                                             | `apps/agents/runtime/contract.ts`                                                                                                                                                                                                                                                                          |
+| `voice-agent`                                                       | `apps/agents/voice/voice-agent.ts`, `apps/agents/voice/events.ts`                                                                                                                                                                                                                                          |
+| `chrome`                                                            | `apps/browser-extension/panel.js`                                                                                                                                                                                                                                                                          |
+| `test`                                                              | tests only                                                                                                                                                                                                                                                                                                 |
+
+Two types break these rules until the Kit firmware migrates:
+
+- `voice-agent/spk-frame` will become `voice-agent/speaker-frame`.
+- `voice-agent/conversation-ended` will become `voice-agent/call-ended`. It pairs with `call-started`
+  and names the activation; the provider session is the `conversation`.
+
+`note/added` is only an example in the Agents composer; no contract defines `note`.
+`email/received` is only an integration's transcript in an agent UI test; no contract defines
+`email`.
+`capability-host/script-run-*` is never written to a log: the agent UI's adapter builds it in
+memory.

package/dist/{next/api.d.ts → api.d.ts}

@@ -1,5 +1,5 @@
 import type { Ai } from "@cloudflare/workers-types";
-import type { FacetHandle, InvokeHandle, ItxExpressionInput } from "./expression.ts";
+import type { InvokeHandle, ItxExpression, ItxExpressionInput } from "./expression.ts";
 import type { ConsentScope } from "./oauth-scopes.ts";
 import type { Principal } from "./principal.ts";
 import type { IngressRouting } from "./project-ingress.ts";
@@ -33,8 +33,8 @@ export type WaitForEventFilter = {
     afterOffset?: number;
     timeoutMs?: number;
 };
-/** The `rewrite-rule-configured` event's payload — what `provide` takes, what `itx.append` writes
- *  durably: make `match` mean `target` (an expression, or `null` to deny). `description` is the one
+/** The `rewrite-rule-configured` event's payload — what `itx.append` writes durably and `provide`
+ *  writes for its session: make `match` mean `target` (an expression, or `null` to deny). `description` is the one
  *  line a model reads for the name; it rides the row into `rewriteRules.list()`. */
 export type RewriteRuleConfigured = {
     match: ItxExpressionInput;
@@ -85,8 +85,8 @@ export type ScheduleReceipt = {
 /** A secret's material: one string (`getSecret("/secrets/<name>")` is the whole value) or a JSON
  *  object whose string fields `getSecret("/secrets/<name>", { field: "a.b" })` picks — the
  *  multidimensional shape a credential exchange needs (`{ username, password, accessToken }`,
- *  `{ clientId, clientSecret, refreshToken, accessToken }`). A JSON STRING still works as an object
- *  (`set(name, JSON.stringify({...}))`). */
+ *  `{ clientId, clientSecret, refreshToken, accessToken }`). A string is always the one value: it has
+ *  no fields, whether or not it parses as JSON. */
 export type SecretMaterial = string | Record<string, unknown>;
 /** How a token endpoint wants the client credential — the RFC 8414 `token_endpoint_auth_methods_supported`
  *  registry values, so a provider's discovery document pastes straight in: `client_secret_basic`
@@ -141,6 +141,47 @@ export type CollectSecretLink = {
     path: string;
     url: string;
 };
+/** WHICH requests a fetch route takes — every field given must hold: the host's routing slug
+ *  (`blog` for `blog--<project>`), a `URLPattern` over the URL the app sees (its init's fields, each a
+ *  pattern string), exact header values. `{}` takes every request. */
+export type FetchRouteRequestMatcher = {
+    routingSlug?: string;
+    url?: {
+        protocol?: string;
+        username?: string;
+        password?: string;
+        hostname?: string;
+        port?: string;
+        pathname?: string;
+        search?: string;
+        hash?: string;
+        baseURL?: string;
+    };
+    headers?: Record<string, string>;
+};
+/** A route as `itx.fetchRoutes.set(name, route)` takes it: the requests it takes, the itx
+ *  expression they go to, who may use it (`project-members`: the config worker answers anyone else
+ *  the sign-in challenge; absent or null: public) and its priority (higher first, then by name). */
+export type FetchRouteInput = {
+    requestMatcher: FetchRouteRequestMatcher;
+    target: ItxExpressionInput;
+    authRequirement?: {
+        visitors: "project-members";
+    } | null;
+    priority?: number;
+};
+/** A live route as `list()` and `match` answer it, its target parsed, with the offset of the
+ *  `itx/fetch-route-configured` fact that set it. */
+export type FetchRouteEntry = {
+    fetchRouteName: string;
+    requestMatcher: FetchRouteRequestMatcher;
+    target: ItxExpression;
+    authRequirement: {
+        visitors: "project-members";
+    } | null;
+    priority: number;
+    configuredOffset: number;
+};
 /** A context (a project, a user, an organization): every `itx` root, reached through `invoke`. */
 export interface IterateContextApi {
     invoke(call: ItxExpressionInput, ...args: unknown[]): Promise<unknown>;
@@ -176,6 +217,24 @@ export interface IterateContextApi {
         projectUrl?: string;
     }>;
     append(...events: StreamEventInput[]): Promise<StreamEvent[]>;
+    /** This project's public URL over HTTP: the apex, or a routing slug's host (`blog--<project>`),
+     *  at `path`. Only from a session, which carries the origin to compose it with. */
+    url(target?: {
+        routingSlug?: string;
+        path?: string;
+    }): Promise<string>;
+    /** RESET this context (Cloudflare's `ctx.abort`): its Durable Object drops everything it holds in
+     *  memory and the next call starts a fresh incarnation from durable storage. Resolves with the
+     *  `events.iterate.com/itx/aborted { reason?, callerPath?, app? }` event it recorded — durable
+     *  and attributed to the caller before anything resets — and the reset follows the answer.
+     *  SURVIVES: the log and everything derived from it (rewrite rules, subscriptions, schedules),
+     *  every facet's storage, kv. GOES: in-memory state, every facet instance and its in-flight work,
+     *  every socket on the context (a provider's re-dials), and every other call in flight there — it
+     *  rejects with the reset's message (`itx.abort() reset the context <path>: <reason>`). A handle
+     *  you kept names its target by expression, so its next call reaches the new incarnation.
+     *  Another context of the project: `itx.cd(path).abort()`. A rewrite rule masks it like any name
+     *  (`provide("itx.abort", null)`). */
+    abort(reason?: string): Promise<StreamEvent>;
     readEvents(afterOffset?: number, limit?: number, options?: {
         includeEphemeral?: boolean;
     }): Promise<StreamPage>;
@@ -217,6 +276,21 @@ export interface IterateContextApi {
          * from an agent context, a successful submission messages that same agent with the path only. */
         collectFromUser(input: CollectSecretInput): Promise<CollectSecretLink>;
     };
+    /** The project's fetch routes, on its root `/`: which requests on its hosts go to which itx
+     *  expression. `set` appends one `itx/fetch-route-configured` fact (`null` deletes the route);
+     *  `match` answers the route a request takes, which the config worker forwards with
+     *  `env.ITX.fetch` naming `itx.fetchRoutes.fetch('<name>')` (a WebSocket upgrade included). */
+    fetchRoutes: {
+        set(fetchRouteName: string, route: FetchRouteInput | null): Promise<{
+            fetchRouteName: string;
+        }>;
+        list(): Promise<FetchRouteEntry[]>;
+        match(request: {
+            method: string;
+            url: string;
+            headers: Headers | Record<string, string> | [string, string][];
+        }): Promise<FetchRouteEntry | null>;
+    };
     /** The table this context resolves against, described — the tree a model reads. `list()` follows a
      *  bare hop row into the context it names (a Durable Object hop, hence async). */
     rewriteRules: {
@@ -224,13 +298,26 @@ export interface IterateContextApi {
         get(match: string): Promise<RewriteRuleListEntry | null>;
         resolve(call: ItxExpressionInput): string[];
     };
+    /** A facet of this context: a caller reaches only what its class lists in `static publicMethods`
+     *  (sdk/index.ts `FacetDurableObject`); anything else is refused FORBIDDEN. */
     facets: {
-        get(name: string, spec?: FacetSpec): FacetHandle;
+        get(name: string, spec?: FacetSpec): InvokeHandle;
+        /** RESET one facet of this context, from the context that hosts it — any facet, whether or not
+         *  it extends the SDK's host, including one that would never answer a call. Its instance and
+         *  in-memory state go, and every call in flight on it rejects `FACET_ABORTED`; its storage
+         *  stays, and its next call starts it fresh. The context itself is not reset. Resolves with the
+         *  `events.iterate.com/itx/facet-aborted { name, reason?, callerPath?, app? }` event;
+         *  `NO_FACET` for a name never hosted here. */
+        abort(name: string, reason?: string): Promise<StreamEvent>;
     };
     subscriptions: {
         list(): SubscriptionListEntry[];
         get(name: string): SubscriptionListEntry | null;
     };
+    /** The rpc stubs lent to this context right now, by key (a live session's `provide`). */
+    rpcStubs: {
+        list(): string[];
+    };
     processors: {
         enable(name: string, spec?: (FacetSpec & {
             consumes?: string[];
@@ -263,18 +350,19 @@ export interface IterateContextApi {
     }): Promise<{
         [Symbol.dispose](): void;
     }>;
-    /** A rewrite rule of this context, session-scoped (the handle's dispose removes it): the event's
-     *  payload `{ match, target, description? }`, or the shorthand `(match, target)`. `target` is an
-     *  expression, or null to deny. The durable spelling is the same payload through `itx.append`. */
-    provide(input: RewriteRuleConfigured): Promise<{
-        [Symbol.dispose](): void;
-    }>;
-    provide(match: ItxExpressionInput, target: unknown): Promise<{
+    /** A rewrite rule of this context, session-scoped (the handle's dispose removes it): make `match`
+     *  mean `target`, an expression, a live stub, or null to deny. `description` is the one line a
+     *  model reads for the name. The durable spelling is the rule's event (`RewriteRuleConfigured`)
+     *  through `itx.append`. */
+    provide(match: ItxExpressionInput, target: unknown, options?: {
+        description?: string;
+    }): Promise<{
         [Symbol.dispose](): void;
     }>;
     /** A script — the text of `async (itx) => { … }` — run once against this context, on its log:
-     *  `context/run-requested` under the caller, the context's runner, `run-settled` (JSON in, JSON
-     *  out); resolves with the result or rejects with the settlement's error. Never re-run. */
+     *  `itx/run-requested` under the caller, the context's runner, `run-settled` (JSON in, JSON
+     *  out); resolves with the result or rejects with the settlement's error. Never re-run. A script
+     *  still running ten minutes after it started is settled failed (`failureKind: "deadline"`). */
     run(script: string): Promise<unknown>;
     /** The project's repos, workspaces and agents as domain objects — one shape each: `get(path)` is
      *  the entity's facet on the context at `path` (its verbs, plus the typed `append` on that
@@ -343,21 +431,32 @@ export interface IterateContextApi {
         }[]>;
     };
 }
-/** One OAuth grant as `grants.list()` shows it: a session, a connected app, a minted token. */
+/** What a grant is: a sign-in not yet exchanged, a device's key, a personal access token, or a
+ *  browser or app session. A client labels it for display. */
+export type GrantKind = "pending" | "device" | "personal" | "session";
+/** One grant as `grants.list()` shows it: a session or a connected app (an OAuth grant), or a
+ *  personal access token or a device's key (the account's own API key, `pat_…`). */
 export interface GrantRecord {
     id: string;
     clientId?: string;
     logoUri?: string;
     clientDomain?: string;
     name: string;
-    kind: string;
+    kind: GrantKind;
+    /** An OAuth grant's one resource: Cap'n Web at `/api` (and the projects' hosts), or `/mcp`. A
+     *  personal access token has none: it works at `/api`, at `/mcp` and on its projects' hosts. */
+    resource?: "api" | "mcp";
+    /** A personal access token's projects, by id: all it reaches. */
+    projects?: string[];
     createdAt: number;
     expiresAt: number | null;
     lastUsedAt: number | null;
-    cleanupPending: boolean;
     expired: boolean;
     /** The grant this very session rides on. */
     current?: boolean;
+    /** A personal access token's: the grant of the session that minted it (listed here while it
+     *  lives). */
+    mintedBy?: string;
 }
 /** What the consent screen shows for an authorization request. */
 export type ConsentAnswer = {
@@ -382,12 +481,20 @@ export type ConsentAnswer = {
     kind: "invalid";
     description: string;
 };
+/** An organization's invitation link as its owners see it (`expiresAt` ISO). */
+export interface InvitationRecord {
+    id: string;
+    orgId: string;
+    role: "owner" | "member";
+    emailHint: string | null;
+    expiresAt: string;
+}
 /** An organization as the session lists it: its minted id, its free-text name, the person's role
  *  in it, and how many projects it holds (every one of them, not only those this grant lists). */
 export interface OrgRecord {
     id: string;
     name: string;
-    role?: string;
+    role?: "owner" | "member";
     projects: number;
 }
 /** A project as the catalog lists it: addressed by `id` everywhere (`projects.get`, a grant's list,
@@ -411,17 +518,9 @@ export interface IterateSessionApi {
         /** the MCP server's origin (the dash's connect page) — "" when this deployment serves none */
         mcpOrigin: string;
     };
-    /** The organizations this session reaches. */
-    orgs(): Promise<OrgRecord[]>;
-    /** A new organization — `organizations:write`; the person is its owner. */
-    createOrg(name: string): Promise<OrgRecord>;
-    /** Rename an organization the person owns — `organizations:write`. */
-    updateOrg(orgId: string, input: {
-        name: string;
-    }): Promise<OrgRecord>;
-    /** Delete an organization the person owns, while it holds no project — `organizations:write`. */
-    deleteOrg(orgId: string): Promise<void>;
-    /** OAuth grants this session may manage (a signed-in person's): list, end, mint one for a device. */
+    /** The grants this session may manage (a signed-in person's with the `account` scope): list and
+     *  end its sessions and personal access tokens, and mint a personal access token — its bearer
+     *  answered once, `expiresAt` null for a key that never expires. */
     grants: {
         list(cursor?: string): Promise<{
             items: GrantRecord[];
@@ -431,9 +530,18 @@ export interface IterateSessionApi {
         }>;
         end(grantId: string): Promise<unknown>;
         endCurrent(): Promise<unknown>;
-        mint(input: unknown): Promise<{
+        mint(input: {
+            name: string;
+            /** project ids, each one the person reaches */
+            projects: string[];
+            /** epoch ms; omitted, the key never expires */
+            expiresAt?: number;
+            /** a device's public client metadata document (Kit): the key is listed as that device */
+            clientId?: string;
+        }): Promise<{
+            id: string;
             token: string;
-            expiresAt: number;
+            expiresAt: number | null;
         }>;
     };
     /** The consent screen's methods (the OAuth authorize flow): describe a request, approve it. */
@@ -452,7 +560,8 @@ export interface IterateSessionApi {
         list(): Promise<ProjectRecord[]>;
         /** the project's root context, by its slug or its id */
         get(project: string): Promise<IterateContextApi>;
-        /** Config repository presets available on this platform. */
+        /** Config repository presets available on this platform, besides the default config a
+         *  creation that names no template gets. */
         templates(): Promise<{
             label: string;
             reference: string;
@@ -467,8 +576,63 @@ export interface IterateSessionApi {
             restoreProjectId?: string;
         }): Promise<IterateContextApi>;
     };
+    /** The organizations this session reaches — the person's memberships (a grant narrowed to
+     *  projects sees only their organizations, unless it holds `organizations:write`): the rows, the
+     *  organization's context by membership, and the verbs (`organizations:write`; the person is the
+     *  owner of what they create, and only an owner renames, deletes or changes members). Each verb is
+     *  a request the control plane answers; a refusal is a coded error (FORBIDDEN, INVALID_INPUT). */
     organizations: {
+        list(): Promise<OrgRecord[]>;
+        /** the organization's context — `session.user` for an organization — by membership */
         get(orgId: string): Promise<IterateContextApi>;
+        create(input: {
+            name: string;
+        }): Promise<OrgRecord>;
+        rename(orgId: string, input: {
+            name: string;
+        }): Promise<OrgRecord>;
+        /** only while it holds no project */
+        delete(orgId: string): Promise<void>;
+        addMember(orgId: string, input: {
+            userId: string;
+            role?: "owner" | "member";
+        }): Promise<void>;
+        removeMember(orgId: string, input: {
+            userId: string;
+        }): Promise<void>;
+        /** the members with their emails — the operator's alone (the project-seed CLI) */
+        members(orgId: string): Promise<{
+            userId: string;
+            email: string;
+            role: "owner" | "member";
+        }[]>;
+        /** an owner's invitation link: whoever accepts it first joins in `role` (default member),
+         *  until it expires (`expiresInDays`, default 7, 1–30). `token` is the link's secret, answered
+         *  this once — the dash's `/invitations/<token>`. */
+        createInvitation(orgId: string, input?: {
+            role?: "owner" | "member";
+            emailHint?: string;
+            expiresInDays?: number;
+        }): Promise<InvitationRecord & {
+            token: string;
+        }>;
+        /** an owner withdraws an open link by its id */
+        revokeInvitation(orgId: string, input: {
+            invitationId: string;
+        }): Promise<void>;
+        /** what a link opens, for the signed-in person holding it; null when it names nothing */
+        invitation(token: string): Promise<(InvitationRecord & {
+            orgName: string;
+            status: "pending" | "accepted" | "revoked" | "expired";
+            /** the reader already belongs */
+            member: boolean;
+            /** the reader is the one who accepted it — accepting again answers the same and lands
+             *  the membership's facts again */
+            acceptedByYou: boolean;
+        }) | null>;
+        /** join the organization a link opens, in its role — single use: the first person to accept
+         *  consumes it (again by them answers the same; anyone after is refused INVALID_INPUT) */
+        acceptInvitation(token: string): Promise<OrgRecord>;
     };
     user: IterateContextApi;
     logout(): unknown;