@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/bridges/smartart-bridge.d.ts

@@ -0,0 +1,217 @@
+/**
+ * SmartArt Bridge Interface
+ *
+ * Defines the contract for SmartArt diagram management and layout computation.
+ * This interface bridges the SmartArt system to the engine's reactive system.
+ *
+ * Features:
+ * - Computed layout caching (invalidated on structure/style changes)
+ * - Event subscriptions for reactive updates
+ * - Node operations (add, remove, update, move)
+ * - Layout and style management
+ *
+ * Architecture Notes:
+ * - ComputedLayout is a runtime cache, NOT persisted to storage
+ * - The bridge listens to EventBus for automatic cache invalidation
+ * - Provides ctx.smartArt.* access pattern
+ * - Handles serialization/deserialization between TS interfaces and storage
+ *
+ * Layout Cache Invalidation Strategy:
+ * - All node events trigger invalidation: node-added, node-removed, node-updated, node-moved
+ * - Layout/style events trigger invalidation: layout-changed, style-changed
+ * - Batch events trigger invalidation: nodes-batch-added, nodes-batch-removed
+ *
+ * @see contracts/src/smartart/types.ts - Core SmartArt types
+ * @see engine/src/state/bridges/smartart-bridge.ts - Implementation
+ */
+import type { ComputedLayout, NodeId, SmartArtDiagram, SmartArtNode } from '../smartart/types';
+import type { NodeMoveDirection, NodePosition } from '../api/worksheet/smartart';
+export type { NodeMoveDirection, NodePosition };
+/**
+ * Cache entry for computed SmartArt layout.
+ *
+ * This is a runtime-only cache, NOT persisted to Yjs.
+ * Invalidated whenever diagram structure or styling changes.
+ */
+export interface ComputedLayoutCache {
+    /** SmartArt object ID this cache entry belongs to */
+    objectId: string;
+    /** The computed layout result */
+    layout: ComputedLayout;
+    /** Timestamp when the layout was computed (ms since epoch) */
+    lastComputed: number;
+    /** Version number, incremented on each invalidation */
+    version: number;
+}
+/**
+ * Bridge interface for SmartArt diagram management.
+ *
+ * This interface provides methods for managing SmartArt diagrams,
+ * computing layouts, and handling node operations.
+ *
+ * LIFECYCLE:
+ * 1. Bridge is created during engine initialization
+ * 2. start() subscribes to ALL SmartArt events on EventBus
+ * 3. Event handlers filter by objectId and call invalidateLayout() automatically
+ * 4. stop()/destroy() unsubscribes all event listeners during shutdown
+ *
+ * CACHE MANAGEMENT:
+ * - Cache is per-objectId, stored in Map<objectId, ComputedLayoutCache>
+ * - getComputedLayout() returns cached result if valid, recomputes otherwise
+ * - invalidateLayout() marks a specific diagram for recomputation
+ * - invalidateAllLayouts() clears the entire cache (e.g., on style changes)
+ */
+export interface ISmartArtBridge {
+    /**
+     * Start the SmartArt bridge - subscribe to events for reactive updates.
+     *
+     * Subscribes to the following events for automatic cache invalidation:
+     * - smartart:node-added, smartart:node-removed, smartart:node-updated
+     * - smartart:node-moved, smartart:nodes-batch-added, smartart:nodes-batch-removed
+     * - smartart:layout-changed, smartart:style-changed
+     *
+     * @returns Cleanup function to stop the bridge
+     */
+    start(): () => void;
+    /**
+     * Stop the SmartArt bridge and clean up subscriptions.
+     */
+    stop(): void;
+    /**
+     * Destroy the bridge - alias for stop().
+     */
+    destroy(): void;
+    /**
+     * Get a SmartArt diagram by object ID.
+     * Returns the deserialized TypeScript interface view.
+     *
+     * @param objectId - SmartArt floating object ID
+     * @returns The diagram or undefined if not found
+     */
+    getDiagram(objectId: string): SmartArtDiagram | undefined | Promise<SmartArtDiagram | undefined>;
+    /**
+     * Get all SmartArt diagrams on a sheet.
+     *
+     * @param sheetId - Sheet ID
+     * @returns Array of diagrams on the sheet
+     */
+    getDiagramsOnSheet(sheetId: string): SmartArtDiagram[] | Promise<SmartArtDiagram[]>;
+    /**
+     * Add a node to a diagram.
+     *
+     * The new node is positioned relative to the reference node:
+     * - 'before': Insert as sibling before reference node
+     * - 'after': Insert as sibling after reference node
+     * - 'above': Insert as parent of reference node (promote reference)
+     * - 'below': Insert as child of reference node
+     * - 'child': Same as 'below', insert as last child
+     *
+     * If referenceNodeId is null, the node is added as a new root.
+     *
+     * @param objectId - SmartArt object ID
+     * @param text - Initial text content for the node
+     * @param position - Position relative to reference node
+     * @param referenceNodeId - Reference node ID (null for root)
+     * @returns The ID of the newly created node
+     */
+    addNode(objectId: string, text: string, position: NodePosition, referenceNodeId: NodeId | null): NodeId | Promise<NodeId>;
+    /**
+     * Remove a node and optionally its children.
+     *
+     * By default, children are promoted to the removed node's parent.
+     * If the node is a root node with no parent, children become new roots.
+     *
+     * @param objectId - SmartArt object ID
+     * @param nodeId - Node ID to remove
+     */
+    removeNode(objectId: string, nodeId: NodeId): void | Promise<void>;
+    /**
+     * Update node properties.
+     *
+     * Only provided properties are updated; others remain unchanged.
+     * Passing undefined for an optional property removes it.
+     *
+     * @param objectId - SmartArt object ID
+     * @param nodeId - Node ID to update
+     * @param updates - Partial node properties to update
+     */
+    updateNode(objectId: string, nodeId: NodeId, updates: Partial<SmartArtNode>): void | Promise<void>;
+    /**
+     * Move a node in the hierarchy.
+     *
+     * Movement directions:
+     * - 'promote': Move up one level (become sibling of current parent)
+     * - 'demote': Move down one level (become child of previous sibling)
+     * - 'move-up': Move earlier in sibling order
+     * - 'move-down': Move later in sibling order
+     *
+     * @param objectId - SmartArt object ID
+     * @param nodeId - Node ID to move
+     * @param direction - Direction to move the node
+     */
+    moveNode(objectId: string, nodeId: NodeId, direction: NodeMoveDirection): void | Promise<void>;
+    /**
+     * Get a node by ID.
+     *
+     * @param objectId - SmartArt object ID
+     * @param nodeId - Node ID to retrieve
+     * @returns The node or undefined if not found
+     */
+    getNode(objectId: string, nodeId: NodeId): SmartArtNode | undefined | Promise<SmartArtNode | undefined>;
+    /**
+     * Change the diagram layout.
+     *
+     * Layout changes may affect node constraints (e.g., max levels, max nodes).
+     * The bridge validates the change and adjusts the diagram if needed.
+     *
+     * @param objectId - SmartArt object ID
+     * @param newLayoutId - New layout ID (e.g., 'hierarchy/org-chart')
+     */
+    changeLayout(objectId: string, newLayoutId: string): void | Promise<void>;
+    /**
+     * Change the quick style.
+     *
+     * Quick styles control shape fill, stroke, and effects.
+     *
+     * @param objectId - SmartArt object ID
+     * @param quickStyleId - Quick style ID (e.g., 'subtle-effect', 'intense-effect')
+     */
+    changeQuickStyle(objectId: string, quickStyleId: string): void | Promise<void>;
+    /**
+     * Change the color theme.
+     *
+     * Color themes control the color palette used for shapes.
+     *
+     * @param objectId - SmartArt object ID
+     * @param colorThemeId - Color theme ID (e.g., 'colorful-1', 'accent-1')
+     */
+    changeColorTheme(objectId: string, colorThemeId: string): void | Promise<void>;
+    /**
+     * Get the computed layout for a diagram.
+     * Returns cached result if valid, otherwise recomputes.
+     *
+     * This is the PRIMARY method for accessing layout - it manages the cache.
+     * Layout computation can be expensive, so caching is important for performance.
+     *
+     * @param objectId - SmartArt object ID
+     * @returns Computed layout or undefined if diagram not found
+     */
+    getComputedLayout(objectId: string): ComputedLayout | undefined | Promise<ComputedLayout | undefined>;
+    /**
+     * Invalidate the cached layout for a diagram.
+     * Called automatically when diagram structure or styling changes.
+     *
+     * After invalidation, the next call to getComputedLayout() will recompute.
+     *
+     * @param objectId - SmartArt object ID
+     */
+    invalidateLayout(objectId: string): void;
+    /**
+     * Invalidate all cached layouts.
+     * Called on sheet changes or global style changes.
+     *
+     * Use sparingly as it forces recomputation of all diagrams.
+     */
+    invalidateAllLayouts(): void;
+}
+//# sourceMappingURL=smartart-bridge.d.ts.map

package/dist/bridges/smartart-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smartart-bridge.d.ts","sourceRoot":"","sources":["../../src/bridges/smartart-bridge.ts"],"names":[],"mappings":"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"}

package/dist/bridges/wordart-bridge.d.ts

@@ -0,0 +1,86 @@
+/**
+ * WordArt Rendering Bridge Interface
+ *
+ * Defines the contract for WordArt rendering via DrawingObject[].
+ * The bridge computes DrawingObjects from WordArt config; the scene graph renders them.
+ *
+ * Architecture Notes:
+ * - DrawingObject[] is a runtime cache, NOT persisted to Yjs
+ * - The bridge listens to EventBus for automatic cache invalidation
+ * - Provides ctx.wordArt.* access pattern in DocumentContext
+ *
+ * @see contracts/src/objects/drawing-object.ts - DrawingObject type
+ * @see engine/src/bridges/wordart-bridge.ts - Implementation
+ */
+import type { DrawingObject } from '../objects/drawing-object';
+/**
+ * Bridge interface for WordArt rendering.
+ *
+ * This interface provides a single computation method that produces
+ * DrawingObject[] from WordArt config, plus cache management.
+ *
+ * LIFECYCLE:
+ * 1. Bridge is created during engine initialization
+ * 2. start() subscribes to WordArt change events for cache invalidation
+ * 3. stop()/destroy() cleans up resources and event subscriptions
+ *
+ * CACHE MANAGEMENT:
+ * - Cache is per-objectId, storing computed DrawingObject[]
+ * - computeDrawingObjects() returns cached result if valid, recomputes otherwise
+ * - invalidateCache() marks a specific object for recomputation
+ * - clearCache() clears the entire cache
+ */
+export interface IWordArtRenderingBridge {
+    /**
+     * Start the WordArt rendering bridge - subscribe to events for reactive updates.
+     *
+     * Call this after creating the bridge to begin listening for WordArt changes.
+     * The bridge will automatically invalidate the render cache when changes occur.
+     *
+     * @returns Cleanup function to stop the bridge
+     */
+    start(): () => void;
+    /**
+     * Stop the WordArt rendering bridge and clean up subscriptions.
+     *
+     * Call this to pause event listening. Can be restarted with start().
+     */
+    stop(): void;
+    /**
+     * Compute DrawingObjects for a WordArt object.
+     *
+     * Uses caching to avoid recomputation on every frame. Returns cached result
+     * if the config, text, and bounds haven't changed.
+     *
+     * @param objectId - Floating object ID of the WordArt
+     * @param bounds - Optional bounds override (uses object bounds if not provided)
+     * @returns Array of DrawingObjects or null if object not found/not WordArt
+     */
+    computeDrawingObjects(objectId: string, bounds?: {
+        width: number;
+        height: number;
+    }): Promise<DrawingObject[] | null>;
+    /**
+     * Invalidate render cache for an object.
+     *
+     * Called automatically when WordArt config, text, or bounds change.
+     * After invalidation, the next call to computeDrawingObjects() will recompute.
+     *
+     * @param objectId - Floating object ID to invalidate
+     */
+    invalidateCache(objectId: string): void;
+    /**
+     * Clear entire render cache.
+     *
+     * Forces recomputation of all WordArt objects on next render.
+     * Use sparingly as it impacts performance.
+     */
+    clearCache(): void;
+    /**
+     * Clean up resources and event subscriptions.
+     *
+     * Call during engine shutdown or when the bridge is no longer needed.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=wordart-bridge.d.ts.map

package/dist/bridges/wordart-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wordart-bridge.d.ts","sourceRoot":"","sources":["../../src/bridges/wordart-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAM/D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,KAAK,IAAI,MAAM,IAAI,CAAC;IAEpB;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;;;;;;;;OASG;IACH,qBAAqB,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC;IAEnC;;;;;;;OAOG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExC;;;;;OAKG;IACH,UAAU,IAAI,IAAI,CAAC;IAEnB;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/capabilities/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Capability Errors - Error types for capability-related failures
+ *
+ * This file defines:
+ * - CapabilityErrorCode type
+ *
+ * Runtime error classes, type guards, and factory functions moved to
+ * @mog/spreadsheet-utils/capabilities/errors.
+ *
+ * @see plans/active/permission/CAPABILITY-IMPLEMENTATION.md
+ */
+/**
+ * Error codes for capability-related failures.
+ */
+export type CapabilityErrorCode = 'CAPABILITY_DENIED' | 'CAPABILITY_SCOPE_MISMATCH' | 'CAPABILITY_EXPIRED' | 'CAPABILITY_NOT_GRANTED' | 'CAPABILITY_REQUIRES_AUTH' | 'INVALID_SCOPE' | 'UNBOUNDED_WILDCARD';
+//# sourceMappingURL=errors.d.ts.map

package/dist/capabilities/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/capabilities/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,2BAA2B,GAC3B,oBAAoB,GACpB,wBAAwB,GACxB,0BAA0B,GAC1B,eAAe,GACf,oBAAoB,CAAC"}

package/dist/capabilities/gated-api.d.ts

@@ -0,0 +1,355 @@
+/**
+ * Gated API Interfaces - Capability-based API access (Types Only)
+ *
+ * This file defines ONLY type/interface definitions:
+ * - IGatedAppKernelAPI interface (optional interfaces per capability)
+ * - ICapabilityIntrospection interface
+ * - Gated sub-API interfaces
+ *
+ * Runtime code (type guard functions: hasTableReadAccess, hasTableFullAccess,
+ * hasFilesystemAccess, hasNetworkAccess) has been moved to
+ * @mog/kernel/services/capabilities (gated-api.ts).
+ *
+ * @see plans/active/permission/CAPABILITY-IMPLEMENTATION.md
+ */
+import type { IAppClipboardAPI, IAppColumnsAPI, IAppEventsAPI, IAppRecordsAPI, IAppRelationsAPI, IAppTablesAPI } from '../apps/api';
+import type { INotificationsService, IUndoService } from '../services';
+import type { CapabilityScope } from './scope';
+import type { CapabilityType } from './types';
+/**
+ * Interface for apps to introspect their granted capabilities.
+ *
+ * Apps can use this to:
+ * - Check what capabilities they have before trying to use APIs
+ * - Adapt UI based on available capabilities
+ * - Determine if they have scoped or full access
+ */
+export interface ICapabilityIntrospection {
+    /**
+     * Check if the app has a specific capability.
+     *
+     * This checks for both direct grants and implied capabilities.
+     * For example, if the app has 'cells:write', has('cells:read') returns true.
+     *
+     * @param capability - The capability to check
+     * @returns True if the app has this capability
+     */
+    has(capability: CapabilityType): boolean;
+    /**
+     * List all capabilities the app currently has.
+     *
+     * Includes both directly granted capabilities and implied capabilities.
+     *
+     * @returns Array of all effective capabilities
+     */
+    list(): CapabilityType[];
+    /**
+     * Check if a capability is scoped (limited to specific resources).
+     *
+     * @param capability - The capability to check
+     * @returns True if the capability is scoped
+     */
+    isScoped(capability: CapabilityType): boolean;
+    /**
+     * Get the scope for a capability.
+     *
+     * @param capability - The capability to get scope for
+     * @returns The scope, or null if unscoped or not granted
+     */
+    getScope(capability: CapabilityType): CapabilityScope | null;
+    /**
+     * Check if the app has access to a specific resource.
+     *
+     * This is a convenience method combining has() and scope checking.
+     *
+     * @param capability - The capability required
+     * @param resourceType - The type of resource (e.g., 'table')
+     * @param resourceId - The ID of the resource (e.g., 'contacts')
+     * @returns True if the app can access this resource
+     */
+    hasAccessTo(capability: CapabilityType, resourceType: string, resourceId: string): boolean;
+    /**
+     * Request a capability at runtime.
+     *
+     * This triggers the consent flow for the requested capability.
+     * Returns a promise that resolves to true if granted, false if denied.
+     *
+     * @param capability - The capability to request
+     * @param reason - User-facing reason for the request
+     * @returns Promise resolving to grant result
+     */
+    request(capability: CapabilityType, reason: string): Promise<boolean>;
+    /**
+     * Subscribe to capability changes.
+     *
+     * Called when capabilities are granted, revoked, or expire.
+     * Apps can use this to adapt their UI in real-time.
+     *
+     * @param callback - Called when capabilities change
+     * @returns Unsubscribe function
+     */
+    onChange(callback: (capabilities: CapabilityType[]) => void): () => void;
+    /**
+     * Subscribe to capability expiration warnings.
+     *
+     * Called when a session-only capability is about to expire.
+     * Default warning is 60 seconds before expiration.
+     *
+     * @param callback - Called with the expiring capability
+     * @returns Unsubscribe function
+     */
+    onExpiring(callback: (capability: CapabilityType, expiresInMs: number) => void): () => void;
+}
+/**
+ * Gated cells API - only methods allowed by granted capabilities.
+ */
+export interface IGatedCellsAPI {
+    readonly get?: (sheetId: string, row: number, col: number) => unknown;
+    readonly getRange?: (sheetId: string, range: string) => unknown[][];
+    readonly set?: (sheetId: string, row: number, col: number, value: unknown) => void;
+    readonly setRange?: (sheetId: string, range: string, values: unknown[][]) => void;
+}
+/**
+ * Gated sheets API - only methods allowed by granted capabilities.
+ */
+export interface IGatedSheetsAPI {
+    readonly list?: () => Array<{
+        id: string;
+        name: string;
+    }>;
+    readonly get?: (sheetId: string) => {
+        id: string;
+        name: string;
+    } | null;
+    readonly create?: (name: string) => {
+        id: string;
+        name: string;
+    };
+    readonly delete?: (sheetId: string) => void;
+    readonly rename?: (sheetId: string, newName: string) => void;
+}
+/**
+ * Gated formulas API - only methods allowed by granted capabilities.
+ */
+export interface IGatedFormulasAPI {
+    readonly get?: (sheetId: string, row: number, col: number) => string | null;
+    readonly set?: (sheetId: string, row: number, col: number, formula: string) => void;
+}
+/**
+ * Gated formatting API - only methods allowed by granted capabilities.
+ */
+export interface IGatedFormattingAPI {
+    readonly get?: (sheetId: string, row: number, col: number) => Record<string, unknown>;
+    readonly set?: (sheetId: string, row: number, col: number, format: Record<string, unknown>) => void;
+}
+/**
+ * Gated checkpoints API - only methods allowed by granted capabilities.
+ */
+export interface IGatedCheckpointsAPI {
+    readonly list?: () => Array<{
+        id: string;
+        name: string;
+        createdAt: number;
+    }>;
+    readonly create?: (name: string) => {
+        id: string;
+        name: string;
+        createdAt: number;
+    };
+    readonly restore?: (checkpointId: string) => void;
+}
+/**
+ * Gated filesystem API - only methods allowed by granted capabilities.
+ */
+export interface IGatedFilesystemAPI {
+    readonly read?: (path: string) => Promise<ArrayBuffer>;
+    readonly readText?: (path: string) => Promise<string>;
+    readonly exists?: (path: string) => Promise<boolean>;
+    readonly list?: (path: string) => Promise<string[]>;
+    readonly write?: (path: string, data: ArrayBuffer) => Promise<void>;
+    readonly writeText?: (path: string, text: string) => Promise<void>;
+    readonly delete?: (path: string) => Promise<void>;
+}
+/**
+ * Gated dialogs API - only methods allowed by granted capabilities.
+ */
+export interface IGatedDialogsAPI {
+    readonly open?: (options?: {
+        filters?: Array<{
+            name: string;
+            extensions: string[];
+        }>;
+        multiple?: boolean;
+    }) => Promise<string[] | null>;
+    readonly save?: (options?: {
+        defaultPath?: string;
+        filters?: Array<{
+            name: string;
+            extensions: string[];
+        }>;
+    }) => Promise<string | null>;
+}
+/**
+ * Gated shell API - only methods allowed by granted capabilities.
+ */
+export interface IGatedShellAPI {
+    readonly setWindowTitle?: (title: string) => void;
+    readonly openExternal?: (url: string) => Promise<void>;
+}
+/**
+ * Gated network API - only methods allowed by granted capabilities.
+ */
+export interface IGatedNetworkAPI {
+    /**
+     * Make an HTTP request.
+     *
+     * The allowed URLs depend on the granted network capabilities:
+     * - network:sameorigin: Only same-origin URLs
+     * - network:allowlist: Only user-approved domains
+     * - network:localhost: localhost/127.0.0.1
+     * - network:any: Any remote URL (excludes localhost unless also granted)
+     *
+     * Throws CapabilityDeniedError if URL is not allowed.
+     */
+    readonly fetch?: (url: string, options?: RequestInit) => Promise<Response>;
+    /**
+     * Get the list of allowed domains (for network:allowlist).
+     */
+    readonly getAllowedDomains?: () => string[];
+    /**
+     * Request to add a domain to the allowlist (shows consent dialog).
+     */
+    readonly requestDomain?: (domain: string, reason: string) => Promise<boolean>;
+}
+/**
+ * Gated connections API - only methods allowed by granted capabilities.
+ */
+export interface IGatedConnectionsAPI {
+    readonly list?: () => Array<{
+        id: string;
+        name: string;
+        type: string;
+    }>;
+    readonly query?: (connectionId: string, query: unknown) => Promise<unknown[]>;
+    readonly execute?: (connectionId: string, mutation: unknown) => Promise<unknown>;
+    readonly create?: (config: unknown) => Promise<{
+        id: string;
+    }>;
+    readonly delete?: (connectionId: string) => Promise<void>;
+    readonly executeNative?: (connectionId: string, rawQuery: string) => Promise<unknown>;
+}
+/**
+ * The Capability-Gated App Kernel API.
+ *
+ * Unlike IAppKernelAPI where all interfaces are always present,
+ * IGatedAppKernelAPI only exposes interfaces for granted capabilities.
+ *
+ * Apps check if interfaces exist before using them:
+ * ```typescript
+ * if (api.tables) {
+ *   const tables = api.tables.list();
+ * }
+ * ```
+ *
+ * Or use capability introspection:
+ * ```typescript
+ * if (api.capabilities.has('tables:read')) {
+ *   const tables = api.tables!.list();
+ * }
+ * ```
+ *
+ * Design:
+ * - All sub-APIs are optional (undefined if not granted)
+ * - Methods within sub-APIs may also be optional based on read/write capabilities
+ * - capabilities introspection is ALWAYS available
+ * - batch() is always available (validates capabilities per operation)
+ */
+export interface IGatedAppKernelAPI {
+    /**
+     * Capability introspection - always available.
+     * Apps can check their capabilities and request new ones.
+     */
+    readonly capabilities: ICapabilityIntrospection;
+    /** Cell operations (requires cells:read and/or cells:write) */
+    readonly cells?: IGatedCellsAPI;
+    /** Sheet operations (requires sheets:* capabilities) */
+    readonly sheets?: IGatedSheetsAPI;
+    /** Formula operations (requires formulas:read and/or formulas:write) */
+    readonly formulas?: IGatedFormulasAPI;
+    /** Formatting operations (requires formatting:read and/or formatting:write) */
+    readonly formatting?: IGatedFormattingAPI;
+    /** Trigger recalculation (requires recalc:trigger) */
+    readonly recalc?: {
+        readonly trigger: () => void;
+    };
+    /**
+     * Table operations (requires tables:* capabilities).
+     * From base IAppTablesAPI, but methods may be undefined based on capabilities.
+     */
+    readonly tables?: Partial<IAppTablesAPI>;
+    /**
+     * Column operations (requires tables:* capabilities).
+     */
+    readonly columns?: Partial<IAppColumnsAPI>;
+    /**
+     * Record operations (requires tables:* capabilities).
+     */
+    readonly records?: Partial<IAppRecordsAPI>;
+    /**
+     * Relation operations (requires tables:read).
+     */
+    readonly relations?: Partial<IAppRelationsAPI>;
+    /**
+     * Event subscriptions (requires events:subscribe).
+     * Events are filtered by the app's read capabilities.
+     */
+    readonly events?: IAppEventsAPI;
+    /**
+     * Clipboard operations (requires clipboard:read and/or clipboard:write).
+     */
+    readonly clipboard?: Partial<IAppClipboardAPI>;
+    /**
+     * Undo/redo operations (requires undo:read and/or undo:write).
+     */
+    readonly undo?: Partial<IUndoService>;
+    /**
+     * Notifications (requires notifications:send).
+     */
+    readonly notifications?: Pick<INotificationsService, 'notify' | 'info' | 'success' | 'warning' | 'error'>;
+    /**
+     * Checkpoint operations (requires checkpoints:* capabilities).
+     */
+    readonly checkpoints?: IGatedCheckpointsAPI;
+    /**
+     * Filesystem operations (requires filesystem:* capabilities).
+     */
+    readonly filesystem?: IGatedFilesystemAPI;
+    /**
+     * File dialogs (requires dialogs:open and/or dialogs:save).
+     */
+    readonly dialogs?: IGatedDialogsAPI;
+    /**
+     * Shell operations (requires shell:* capabilities).
+     */
+    readonly shell?: IGatedShellAPI;
+    /**
+     * Network operations (requires network:* capabilities).
+     */
+    readonly network?: IGatedNetworkAPI;
+    /**
+     * Database connections (requires connections:* capabilities).
+     */
+    readonly connections?: IGatedConnectionsAPI;
+    /**
+     * Execute multiple operations in a single transaction.
+     *
+     * CRITICAL: Each operation is validated against the app's capabilities
+     * BEFORE any operation executes. If any operation is denied, the entire
+     * batch fails without executing anything.
+     *
+     * @param fn - Function containing operations to batch
+     * @param description - Description for undo history
+     */
+    batch<T>(fn: () => T, description?: string): T;
+}
+//# sourceMappingURL=gated-api.d.ts.map