@foir/sdk 0.5.0 → 0.8.0

package/dist/{realtime.d.ts → realtime/index.d.ts}

@@ -1,6 +1,3 @@
-import * as Y from 'yjs';
-import { WebsocketProvider } from 'y-websocket';
-
 /**
  * @foir/sdk/realtime — optional thin web helper over y-websocket (EID-103).
  *
@@ -22,22 +19,45 @@ import { WebsocketProvider } from 'y-websocket';
  *
  * Wire-protocol contract: `docs/realtime-collab-contract.md` (EID-117).
  */
-
+import type * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
 type Awareness = WebsocketProvider['awareness'];
-interface RoomAddress {
+export interface RoomAddress {
     /** Room-type selector — e.g. `record`, `ephemeral`, `tilly_note`. */
     namespace: string;
-    /** Namespace-specific id. For `record`: `{modelKey}:{recordId}:{variantId}`. */
+    /**
+     * Namespace-specific id. For `record`: the triple
+     * `{modelKey}:{recordId}:{variantKey}` (contract §2).
+     *
+     * The third segment is the selected variant's HUMAN KEY — `vip`, `default`,
+     * or the reserved `live` — **never a variant row's id**. `default` is the key
+     * for a record on no variant, and the segment is positional, so it cannot be
+     * omitted (`page:rec_1:` is a different room and an empty part is rejected
+     * with a 400).
+     *
+     * That segment is a KEY space because the platform compares it against the
+     * reserved token `live` to select an EPHEMERAL persistence policy (EID-385):
+     * live co-edit only — no `editing_state`, no autosave, doc destroyed on last
+     * leave. A cuid2 row id can never equal `live`, so sending an id puts that
+     * policy out of reach by construction. Worse, variants are themselves rows in
+     * `records`, so a variant id still passes the join gate: the connection
+     * succeeds and edits a DIFFERENT record, with nothing reported on either side
+     * (TTS-953).
+     *
+     * The address to send is the one the API advertises — the `collab` field on
+     * every public record type returns `{ enabled, wsUrl, roomName }`, where
+     * `roomName` is exactly this triple.
+     */
     id: string;
 }
-interface CollabPresence {
+export interface CollabPresence {
     id: string;
     name: string;
     /** Stable per-user colour; derived deterministically from `id` when omitted. */
     color?: string;
     [key: string]: unknown;
 }
-interface CollabPeer {
+export interface CollabPeer {
     /** The remote peer's y-awareness client id. */
     clientId: number;
     id: string;
@@ -45,7 +65,7 @@ interface CollabPeer {
     color?: string;
     [key: string]: unknown;
 }
-interface CreateCollabSessionOptions {
+export interface CreateCollabSessionOptions {
     /** Explicit realtime origin, e.g. `wss://realtime.foir.io`. Never derived from the API host. */
     url: string;
     /** Room address; built into the canonical bare `{namespace}/{id}` path. A raw string path is also accepted. */
@@ -65,7 +85,7 @@ interface CreateCollabSessionOptions {
     /** WebSocket implementation for non-browser runtimes. */
     WebSocketPolyfill?: typeof WebSocket;
 }
-type CollabEventMap = {
+export type CollabEventMap = {
     /** Connection status flipped. */
     status: {
         connected: boolean;
@@ -77,7 +97,7 @@ type CollabEventMap = {
     /** A `getToken()` (or other internal) error surfaced. */
     error: unknown;
 };
-interface CollabSession {
+export interface CollabSession {
     /** The underlying y-websocket provider (escape hatch). */
     readonly provider: WebsocketProvider;
     /** The y-awareness instance (escape hatch). */
@@ -99,13 +119,12 @@ interface CollabSession {
     destroy(): void;
 }
 /** Deterministic per-id presence colour (stable across sessions and clients). */
-declare function colorForId(id: string): string;
+export declare function colorForId(id: string): string;
 /** Build the canonical bare `{namespace}/{id}` room path (contract §2). */
-declare function roomPath(room: RoomAddress | string): string;
+export declare function roomPath(room: RoomAddress | string): string;
 /**
  * Create a collaboration session: a wrapped `y-websocket` provider that conforms
  * to the Foir realtime contract and keeps its auth token fresh for reconnects.
  */
-declare function createCollabSession(options: CreateCollabSessionOptions): CollabSession;
-
-export { type CollabEventMap, type CollabPeer, type CollabPresence, type CollabSession, type CreateCollabSessionOptions, type RoomAddress, colorForId, createCollabSession, roomPath };
+export declare function createCollabSession(options: CreateCollabSessionOptions): CollabSession;
+export {};

package/dist/realtime.js

@@ -91,7 +91,7 @@ function createCollabSession(options) {
       if (clientId === awareness.clientID) return;
       const user = state["user"];
       if (user && typeof user.id === "string") {
-        next.push({ clientId, id: user.id, name: user.name, color: user.color });
+        next.push({ ...user, clientId, id: user.id, name: user.name, color: user.color });
       }
     });
     peers = next;

package/dist/server/callback-client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Callback client for extensions running async operations.
+ *
+ * The platform dispatches with `mode='async'` and includes a `callback`
+ * block in the operation payload. The extension acks 202, kicks the work
+ * off in its own durable runtime (CF Queue, BullMQ, etc.), and later
+ * calls back with one of:
+ *
+ *   - `complete(result)` — operation succeeded; result conforms to the
+ *     operation's `output_schema` (per-op typed via codegen).
+ *   - `fail(code, message, opts?)` — operation failed; `retryable=true`
+ *     pushes a DLQ entry.
+ *   - `progress({pct, message, metadata})` — non-terminal update; the
+ *     monotonic guard at the platform DB layer drops out-of-order packets.
+ *   - `cancel()` — extension self-cancels (rare; admins normally drive
+ *     cancel via the admin app's ConnectRPC path).
+ *
+ * Each call carries:
+ *   - `Authorization: Bearer <callback.token>` — Ed25519 scoped token.
+ *   - `X-Foir-Signature: sha256=<hex>` — HMAC of the raw request body
+ *     keyed on the project's `operations.signing_secret`. The secret is
+ *     out-of-band (CLI publishes it to the extension on push); the SDK
+ *     only handles the HMAC computation.
+ *
+ * Both response body shape and content-type follow the GraphQL spec —
+ * extensions importing this client receive typed result data.
+ */
+import type { OperationCallback } from './operation-types.js';
+/** Shape of a successful response from any callback mutation. */
+export interface CallbackResult {
+    /**
+     * Status as seen by the platform AFTER the call. One of:
+     * pending|dispatched|running|completed|failed|cancelled|timed_out|progress_stale.
+     * Always set even on idempotent / cancelled calls.
+     */
+    status: string;
+    /**
+     * True when the admin cancelled the execution while the extension was
+     * processing — the platform refused to overwrite the cancelled state.
+     * Extensions should stop work and (optionally) call `fail('CANCELLED')`.
+     */
+    cancelled: boolean;
+    /**
+     * Progress mutations only: false when the monotonic guard rejected an
+     * out-of-order update. Extensions can use this to detect packet
+     * reordering without erroring; missing on complete/fail/cancel.
+     */
+    applied?: boolean;
+}
+/**
+ * Per-operation callback client. `TResult` is the operation's typed result
+ * shape — supply the type generated by graphql-codegen against the
+ * api-public schema (`Complete{Op}ExecutionMutationVariables['result']`).
+ */
+export interface CallbackClient<TResult = unknown> {
+    complete(result: TResult): Promise<CallbackResult>;
+    fail(code: string, message: string, opts?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    }): Promise<CallbackResult>;
+    /**
+     * Returns `{cancelled: true}` when the admin has cancelled — extension
+     * must stop work. `applied: false` means the monotonic guard dropped
+     * the update because pct was lower than the persisted value.
+     */
+    progress(update: {
+        pct?: number;
+        message?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<CallbackResult>;
+    cancel(): Promise<CallbackResult>;
+}
+/**
+ * Construct a callback client from the dispatch payload's callback block
+ * plus the runtime-provided execution id and signing secret.
+ *
+ * `executionId` comes from the same operation payload that delivered
+ * `callback`; pass them together so the SDK doesn't have to re-parse the
+ * payload structure on every call.
+ *
+ * `signingSecret` lives on the extension (set as `FOIR_SIGNING_SECRET` or
+ * equivalent env var). `foir push` writes it there from the project's
+ * signing secret, so it's available before any callback runs.
+ *
+ * `fetch` is overridable for testability and to support runtimes (CF
+ * Workers, Node) where `fetch` may not be the global.
+ */
+export declare function createCallbackClient<TResult = unknown>(callback: OperationCallback, opts: {
+    executionId: string;
+    signingSecret: string;
+    fetch?: typeof fetch;
+}): CallbackClient<TResult>;

package/dist/server/events-client.d.ts

@@ -0,0 +1,279 @@
+/**
+ * `@foir/sdk/server`'s event-log client — cursor-resumable consumption of a
+ * project's durable event history (TTS-983, epic TTS-912).
+ *
+ * ```ts
+ * import { createEventsClient } from '@foir/sdk/server';
+ *
+ * const events = createEventsClient({
+ *   apiUrl: process.env.PLATFORM_API_URL!,
+ *   apiKey: process.env.FOIR_SECRET_KEY!, // sk_…, holding events:list.project
+ * });
+ *
+ * const page = await events.list({ after: lastSeq, limit: 500 });
+ * for (const event of page.events) {
+ *   await handle(event);
+ *   lastSeq = event.seq; // durable position; store it
+ * }
+ * ```
+ *
+ * ---------------------------------------------------------------------------
+ * OPERATOR SURFACE. This is not a customer-facing capability.
+ * ---------------------------------------------------------------------------
+ *
+ * DECIDED 2026-08-04 (TTS-981). The event log is reachable by an `sk_` api key
+ * and by an admin session. It is NOT reachable by a customer token, there is no
+ * customer lane for it on api-public, and a `pk_` key can never be minted
+ * holding `events:list.project` at all.
+ *
+ * The reason is a predicate asymmetry rather than a policy preference.
+ * `events.view` is plain tenant+project containment; `record.view` carries
+ * owner, admin_owner, access_mode, grantee, comp_parent, read_borrow and
+ * slice_parent terms on top of it. A containment-only read over the log
+ * therefore describes rows whose underlying records the same caller could not
+ * read — and every row carries `actor`, naming which OTHER customer acted. In a
+ * project with owner confinement that is a per-record activity feed of other
+ * people's actions.
+ *
+ * Three consequences for the shape of this file, all deliberate:
+ *
+ *   1. **It lives on `@foir/sdk/server` and nowhere else.** Not `./data`, not
+ *      `./client`, not `./react`. Those subpaths are the ones a storefront
+ *      bundles, and `./data` in particular is routinely constructed with a `pk_`
+ *      key in browser-reachable code. `src/server/__tests__/events-client.test.ts`
+ *      walks the import graph of every published subpath and fails if this
+ *      module becomes reachable from one that ships to a browser — because
+ *      "we only documented it on the server" is not a property anything checks.
+ *
+ *   2. **A `pk_` key is refused at construction**, before a request is made. The
+ *      server would refuse it anyway (403), but a 403 at 3am in a deploy log is
+ *      a worse teacher than a thrown error naming the key type at the line that
+ *      built the client.
+ *
+ *   3. **There is no `bearerToken` option, and an `Authorization` header is
+ *      refused.** On api-public a request presenting `sk_` plus a customer
+ *      bearer resolves the CUSTOMER as the authority, and `events` is stripped
+ *      from every customer authority upstream — so attaching a signed-in
+ *      shopper's token to an operator read turns a working call into a 403 that
+ *      reads like a scope problem. Refusing it here says what actually happened.
+ *
+ * Widening this later is easy. Teaching customers a capability they do not have
+ * is a support burden that cannot be retracted.
+ *
+ * ---------------------------------------------------------------------------
+ * Why `GET /v1/events` and not the GraphQL `events` field
+ * ---------------------------------------------------------------------------
+ *
+ * Both exist and both call the same platform RPC with the same credential and
+ * the same scope requirement, so this is not an authorization difference. It is
+ * a caching one: the GraphQL lane sits behind api-public's response cache, and
+ * a cursor-paged log served from a cached body can hand a consumer a page it has
+ * already processed while `hasMore` says there is nothing left. The REST twin is
+ * deliberately not response-cached, which is the property a durable consumer
+ * needs. It also keeps this module `graphql`-free, like `@foir/sdk/data`.
+ */
+import { FoirRequestError } from '../transport/foir-http';
+/** The path `GET /v1/events` is mounted on, inside api-public's api-key group. */
+export declare const FOIR_EVENTS_PATH = "/v1/events";
+/**
+ * The scope an `sk_` key must hold. Never mintable on a `pk_` — `events` is
+ * absent from the platform's `publicSafeScopeResources` — and never present in a
+ * customer's resolved authority.
+ */
+export declare const FOIR_EVENTS_SCOPE = "events:list.project";
+/**
+ * The flat retention window, in days. Reported on every page as
+ * {@link FoirEventRetention.windowDays} too; this constant is the one to compare
+ * a hard-coded expectation against, and the two are pinned to each other by
+ * `oldestRetainedAt` in the tests.
+ */
+export declare const FOIR_EVENTS_RETENTION_DAYS = 90;
+/** Who caused an event. `null` when the emit site attributed nobody. */
+export interface FoirEventActor {
+    /** e.g. `"customer"`, `"admin"`, `"api_key"`, `"system"`. */
+    kind?: string;
+    /** e.g. `"customer:cus_123"`. */
+    ref?: string;
+    [key: string]: unknown;
+}
+/** One row of the durable event log. */
+export interface FoirEvent {
+    id: string;
+    /**
+     * This event's position in the project's stream, assigned by the relay in
+     * COMMIT order — not at insert, and not by `created_at`.
+     *
+     * Store the highest one you have finished processing and pass it back as
+     * `after`. Gaps are normal: the stream carries events your filter did not
+     * match, and history ages out of the retention window. `seq` is for
+     * comparing, never for counting.
+     */
+    seq: number;
+    /** The registry name, e.g. `"record.created"`. */
+    event: string;
+    /**
+     * The event's own flat keys, plus `state` and `stateSchema`.
+     *
+     * `state` is the resource AS OF the event — self-contained, not a pointer to
+     * current state — for the customer, session, operation and workspace-plane
+     * families. It is null for `record.*` events, deliberately and permanently:
+     * `events.view` is plain tenant/project containment while `record.view`
+     * carries owner, grant, borrow and per-field terms, so a copy of record data
+     * in the log would escape every one of them for the whole retention window.
+     *
+     * A record event therefore carries the `recordId` / `modelKey` pointer and no
+     * field content — read the record back under your own credentials.
+     *
+     * `stateSchema` versions the snapshot's shape.
+     */
+    payload: Record<string, unknown>;
+    actor: FoirEventActor | null;
+    /** The operation-key history that led here. */
+    causationChain: string[];
+    /** RFC 3339, as sent. */
+    createdAt: string;
+}
+/**
+ * The retention window, reported on EVERY page rather than only when something
+ * has gone wrong — so a consumer can see how close its cursor is to the edge
+ * before it falls off, which is the difference between an alert and an incident.
+ */
+export interface FoirEventRetention {
+    /** The flat window in days. 90, no tiering. */
+    windowDays: number;
+    /** The oldest `createdAt` the API will serve. RFC 3339. */
+    oldestRetainedAt: string;
+    /**
+     * The lowest `seq` still inside the window for this project, or 0 when nothing
+     * is retained. Compare your stored cursor against it to see the runway left.
+     */
+    oldestAvailableSeq: number;
+}
+export interface FoirEventPage {
+    /** The page, ordered by `seq` ascending. */
+    events: FoirEvent[];
+    /**
+     * The cursor to persist and resume from: the `seq` of the last event on this
+     * page, or the request's `after` when the page is empty. Never moves
+     * backwards, so persisting it unconditionally is safe.
+     */
+    nextCursor: number;
+    /** True when more events are already available past `nextCursor`. */
+    hasMore: boolean;
+    retention: FoirEventRetention;
+}
+export interface FoirEventsListParams {
+    /**
+     * Exclusive cursor: return events with `seq > after`. Omit or pass 0 to start
+     * at the oldest event still inside the retention window.
+     */
+    after?: number;
+    /** Page size. The server defaults to 100 and caps at 1000. */
+    limit?: number;
+    /**
+     * Filter by event name, e.g. `['record.created', 'record.updated']`. Omit for
+     * every event.
+     */
+    events?: readonly string[];
+    /** Aborts the underlying request. */
+    signal?: AbortSignal;
+}
+export interface FoirEventsStreamParams extends FoirEventsListParams {
+    /**
+     * Called after each page is fetched and before its events are yielded, with
+     * the cursor that page ended on. Use it to checkpoint at page granularity
+     * instead of per event.
+     */
+    onPage?: (page: FoirEventPage) => void | Promise<void>;
+}
+export interface FoirEventsClientConfig {
+    /**
+     * Foir public API origin, e.g. `https://api.foir.dev`. A full
+     * `https://api.foir.dev/graphql` is accepted too, since that is what
+     * `PLATFORM_API_URL` conventionally holds.
+     */
+    apiUrl: string;
+    /**
+     * An `sk_` secret key holding `events:list.project`.
+     *
+     * A `pk_` key is refused here rather than at the server — see the operator
+     * note at the top of this file.
+     */
+    apiKey: string;
+    /**
+     * Extra headers. An `Authorization` header is refused: a customer bearer
+     * flips api-public's resolved authority to the customer, and no customer
+     * authority can contain `events:list.project`.
+     */
+    headers?: Readonly<Record<string, string>>;
+    /** `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Merged into every `fetch` call. Applied after method/headers, so those
+     * cannot be clobbered by accident.
+     */
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+}
+export interface FoirEventsClient {
+    /** One page of the project's event history. */
+    list(params?: FoirEventsListParams): Promise<FoirEventPage>;
+    /**
+     * Every event from `after` to the current end of the stream, paging as it
+     * goes. Finishes when the server reports no more — it does NOT poll, so a
+     * long-running consumer wraps it in its own interval.
+     *
+     * Each yielded event carries its own `seq`, which is the cursor: a consumer
+     * that stores `event.seq` after processing resumes exactly where it stopped,
+     * including mid-page after a crash.
+     */
+    stream(params?: FoirEventsStreamParams): AsyncGenerator<FoirEvent, void, void>;
+}
+/**
+ * The cursor named a position older than the retention window, so events the
+ * consumer had not read have expired. HTTP 410 Gone.
+ *
+ * The server REFUSES rather than serving a shortened page, deliberately: a flag
+ * on a successful response makes silent data loss the default for every consumer
+ * that does not read the flag. Acknowledging a gap should be one deliberate line
+ * of code, not an accident.
+ *
+ * ```ts
+ * try {
+ *   page = await events.list({ after: cursor });
+ * } catch (err) {
+ *   if (err instanceof FoirEventCursorExpiredError) {
+ *     await recordGap(cursor, err.resumeFrom);
+ *     page = await events.list({ after: err.resumeFrom ?? 0 });
+ *   } else throw err;
+ * }
+ * ```
+ */
+export declare class FoirEventCursorExpiredError extends FoirRequestError {
+    /**
+     * The cursor to resume from, accepting the gap — parsed out of the server's
+     * message, which names it.
+     *
+     * `undefined` only if the message ever stops naming one, in which case
+     * restarting from 0 and de-duplicating on `id` is the safe fallback. It is
+     * optional for that reason and not because the server omits it today; both
+     * refusal messages carry it, and both are pinned as fixtures in the tests.
+     */
+    readonly resumeFrom?: number;
+    /** The cursor that was rejected — whatever was passed as `after`. */
+    readonly requestedCursor?: number;
+    constructor(message: string, options: {
+        status: number;
+        resumeFrom?: number;
+        requestedCursor?: number;
+    });
+}
+/**
+ * True when the failure is a cursor that fell outside the retention window.
+ *
+ * Provided alongside the class because `instanceof` across two copies of the
+ * package — a monorepo with a hoisted and a nested `@foir/sdk` — is false even
+ * for the right error, and the SDK's other taxonomy helpers
+ * (`isFoirRateLimited`, `isFoirForbidden`) already set this precedent.
+ */
+export declare function isFoirEventCursorExpired(err: unknown): err is FoirEventCursorExpiredError;
+export declare function createEventsClient(config: FoirEventsClientConfig): FoirEventsClient;

package/dist/server/index.d.ts

@@ -0,0 +1,12 @@
+export { createServerClient, ServerClientError } from './server-client';
+export { verifyWebhookSignature } from './webhook-helpers';
+export { verifyScopedToken, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, type ScopedTokenClaims, type ScopedTokenSubject, type VerifyScopedTokenOptions, } from './verify-scoped-token';
+export { requireScopedToken, ScopedTokenError, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
+export type { ServerClient, ServerClientOptions, GraphQLResponse, EditorPlacement, } from './types';
+export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, } from './operation-types';
+export { createCallbackClient } from './callback-client';
+export type { CallbackClient, CallbackResult } from './callback-client';
+export { createEventsClient, FoirEventCursorExpiredError, isFoirEventCursorExpired, FOIR_EVENTS_PATH, FOIR_EVENTS_SCOPE, FOIR_EVENTS_RETENTION_DAYS, } from './events-client';
+export type { FoirEvent, FoirEventActor, FoirEventPage, FoirEventRetention, FoirEventsClient, FoirEventsClientConfig, FoirEventsListParams, FoirEventsStreamParams, } from './events-client';
+export { FoirRequestError, isFoirForbidden, isFoirNotFound, isFoirRateLimited, isFoirUnauthenticated, } from '../transport/foir-http';
+export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem } from '../transport/foir-http';

package/dist/server/operation-types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Type definitions for platform operations.
+ *
+ * These types match the platform's operation execution payload structure.
+ */
+/**
+ * Operation payload sent by the platform to extension endpoints.
+ *
+ * All operations receive this standardized payload structure regardless
+ * of how they're triggered (UI, API, lifecycle hook, schedule).
+ */
+export interface OperationPayload {
+    /** Execution id — present so the extension can include it in callbacks. */
+    executionId?: string;
+    /** Unique key identifying this operation (e.g., 'tilly-process-note') */
+    operationKey: string;
+    /** How this operation was triggered */
+    trigger: OperationTrigger;
+    /** Input data provided by the caller */
+    input: Record<string, unknown>;
+    /** Content/field value (for field-triggered operations) */
+    content: unknown;
+    /** Record context (if operation was triggered by a record event) */
+    record: OperationRecordContext | null;
+    /** Platform context (tenant, project, user, locale) */
+    context: OperationContext;
+    /** Extension credentials (auto-injected by platform) */
+    credentials?: Record<string, unknown>;
+    /** Extension config (auto-injected by platform) */
+    config?: Record<string, unknown>;
+    /**
+     * Async-callback dispatch metadata. Present iff the operation was
+     * dispatched in `async-callback` mode. Contains the scoped token, the
+     * api-public GraphQL endpoint, and the per-op typed mutation names the
+     * extension should call back to.
+     *
+     * Absent for SYNC operations — the extension returns its result in the
+     * HTTP response body and there's nothing to call back to.
+     */
+    callback?: OperationCallback;
+}
+/**
+ * Callback context the platform hands the extension when it dispatches an
+ * async-callback operation. Everything the extension needs to call back is
+ * here — endpoint, auth token, signing secret reference (the secret itself
+ * lives on the extension, set out of band; the platform only sends the
+ * token), and the per-op mutation names so the extension doesn't need to
+ * derive them from the operation key.
+ */
+export interface OperationCallback {
+    /** api-public GraphQL endpoint, e.g. https://api.foir.dev/graphql */
+    gqlEndpoint: string;
+    /** Bearer token for the Authorization header (Ed25519, single execution scope) */
+    token: string;
+    /** RFC3339 expiry — extensions can short-circuit work past this. */
+    expiresAt: string;
+    /** Per-op typed mutation names the extension should call back with. */
+    mutations: {
+        complete: string;
+        fail: string;
+        progress: string;
+        cancel: string;
+    };
+}
+/**
+ * Trigger information describing how the operation was invoked.
+ */
+export interface OperationTrigger {
+    /** Trigger type */
+    type: 'ui' | 'api' | 'lifecycle' | 'field';
+    /** Field key (for field-triggered operations) */
+    fieldKey?: string;
+    /** Field type (for field-triggered operations) */
+    fieldType?: string;
+}
+/**
+ * Record context provided when operation is triggered by a record event.
+ */
+export interface OperationRecordContext {
+    /** Record ID */
+    id: string;
+    /** Model key (e.g., 'tilly_note') */
+    modelKey: string;
+    /** Version ID (if versioned record) */
+    versionId?: string;
+    /** Record content/data */
+    data: Record<string, unknown>;
+    /** Record metadata */
+    metadata: {
+        /** Natural key (slug, handle, etc.) */
+        naturalKey?: string;
+        /** Additional metadata fields */
+        [key: string]: unknown;
+    };
+}
+/**
+ * Platform context provided to all operations.
+ */
+export interface OperationContext {
+    /** Tenant ID */
+    tenantId: string;
+    /** Project ID */
+    projectId: string;
+    /** User ID (if user-triggered) */
+    userId?: string;
+    /** Customer ID (if customer-scoped operation) */
+    customerId?: string;
+    /** Locale code (if locale-specific) */
+    locale?: string;
+    /** Timestamp when operation was triggered */
+    timestamp: string;
+}
+/**
+ * Standard operation result shape.
+ *
+ * All operations should return this structure.
+ */
+export interface OperationResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Operation result data (if successful) */
+    result?: unknown;
+    /** Error information (if failed) */
+    error?: {
+        /** Error code (e.g., 'MISSING_INPUT', 'PROCESSING_FAILED') */
+        code: string;
+        /** Human-readable error message */
+        message: string;
+        /** Additional error details */
+        details?: Record<string, unknown>;
+    };
+    /** Optional metadata (timing, cost, etc.) */
+    metadata?: Record<string, unknown>;
+}