Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Extension API Contract

Manifest Version: 2 Core API Version: 1.0.0 Last updated: 2026-02-21

​

Table of Contents

1. Versioning & Compatibility
2. Import Surface
3. Manifest Schema (v2)
4. Contribution Types
5. Lifecycle State Machine
6. EventBus Integration
7. ExtensionBaseService
8. Data Collections & Uninstall Policies
9. Migration System
10. Dependency Management
11. Health Monitoring & Auto-Disable
12. Registry & Resolution Flow
13. ESLint Boundary Enforcement
14. Breaking Change Policy

​

1. Versioning & Compatibility

​

Core API Version

CORE_API_VERSION = '1.0.0'

compatibility: {
  coreApiVersion: '^1.0.0',
}

​

Compatibility Checking

​

Manifest Version Field

manifestVersion?: 1 | 2;

​

2. Import Surface

@/shared/extension-api

​

Exported Values

​

Exported Enums

​

Exported Types

​

Widget & Command Registration Helpers

​

3. Manifest Schema (v2)

​

Required Fields

​

Optional Fields

​

Route Entry

interface ModuleRouteEntry {
  path: string;           // Relative to basePath (e.g. 'dashboard', 'indicators/:id')
  component?: string;     // Lazy import path relative to module root
  redirect?: string;      // Redirect target instead of rendering
}

​

Sidebar Entry

interface ModuleSidebarEntry {
  label: string;          // Display text
  icon: string;           // Lucide icon name
  to: string;             // Absolute path (e.g. '/impact')
  permission: string;     // Required permission to see item
  position: 'main' | 'bottom';  // Nav section
  sortOrder: number;      // Lower = higher in list
}

​

4. Contribution Types

​

4.1 Widgets (ExtensionWidgetContribution)

​

4.2 Commands (ExtensionCommandContribution)

​

4.3 Event Handlers (ExtensionEventHandlerDeclaration)

​

4.4 Settings Panels (ExtensionSettingsPanelContribution)

​

4.5 Agent Tools (ExtensionAgentToolContribution)

​

5. Lifecycle State Machine

​

State Definitions

​

Firestore Path

organizations/{orgId}/moduleInstallations/{moduleId}

​

State Transitions

​

Activation Flow (Detail)

1. Validate required dependencies are installed and active
2. Check API version compatibility via isCompatible()
3. Run pending data migrations via ExtensionMigrationService
4. Register widget contributions (Firestore persistence)
5. Register command contributions (in-memory ActionRegistry)
6. Subscribe event handler declarations (scoped EventBus)
7. Register agent tool contributions (AgentToolRegistry)
8. Track settings panel contributions (in-memory)
9. Call lifecycle.onActivate hook (if declared)

​

Deactivation Flow (Detail)

1. Call lifecycle.onDeactivate hook (if declared)
2. Unregister agent tools
3. Unsubscribe all extension event handlers via EventBus.unsubscribeExtension(extensionId)
4. Unregister command contributions
5. Unregister widget contributions (Firestore cleanup)
6. Clear tracked settings panels

​

6. EventBus Integration

​

Scoped Event Bus

const bus = createExtensionEventBus(extensionId, optionalBusInstance);

​

Subscription Lifecycle

• Subscriptions registered via subscribeForExtension() are tracked per extension ID
• On deactivation, unsubscribeExtension(extensionId) bulk-removes all subscriptions
• Each subscription also returns an individual unsubscribe function for manual cleanup
• getExtensionSubscriptionCount(extensionId) reports active subscription count

​

Type-Safe Subscriptions

// Single event type — payload is inferred from EventPayloadMap
bus.on(SystemEventType.EXPENSE_APPROVED, (event) => {
  // event.payload is typed as ExpenseApprovedPayload
});

// Multiple event types — generic payload
bus.on([SystemEventType.EXPENSE_APPROVED, SystemEventType.EXPENSE_REJECTED], (event) => {
  // event.payload is unknown — narrow manually
});

​

Event Emission Contract

{
  type: SystemEventType;       // Event type enum value
  organizationId: string;      // Tenant scope
  userId: string;              // Acting user
  severity: EventSeverity;     // INFO, WARNING, ERROR, CRITICAL
  timestamp: Date;             // When the event occurred
  payload: T;                  // Event-specific payload
  metadata?: {                 // Optional metadata
    source?: string;           // Auto-set by scoped bus: 'extension:{id}'
    [key: string]: unknown;
  };
}

​

7. ExtensionBaseService

​

Abstract Members

​

Behavioral Differences from BaseService

​

Inherited Capabilities

​

8. Data Collections & Uninstall Policies

interface ModuleDataCollection {
  name: string;                        // Firestore collection name
  label: string;                       // Human-readable label
  orgIdField?: string;                 // Tenant scope field (default: 'organizationId')
  uninstallPolicy?: 'retain' | 'archive' | 'delete';
}

​

Uninstall Policies

​

9. Migration System

​

Declaration

migrations: [
  {
    fromVersion: '1.0.0',
    toVersion: '1.1.0',
    description: 'Add priority field to calendar events',
    migrationPath: 'migrations/v1_1_addPriority',
  },
]

​

Execution

1. ExtensionMigrationService.getPendingMigrations() compares installation.installedVersion against manifest.version
2. Pending migrations are sorted by fromVersion and executed in order
3. Each migration module is dynamically imported from src/extensions/{codeDirectory}/{migrationPath}
4. The module must export a default async function receiving MigrationContext:

interface MigrationContext {
  extensionId: string;
  organizationId: string;
  fromVersion: string;
  toVersion: string;
}

​

Failure Handling

​

Timing

• Initial install() (if installedVersion < manifest.version)
• activate() / reactivate() (if an upgrade occurred while inactive)

​

10. Dependency Management

​

Declaration

requiredModules: ['impact', 'compliance-vault'],

​

Validation Points

​

Dependency Resolution

​

11. Health Monitoring & Auto-Disable

​

ExtensionHealthService

​

Behavior

1. Extension route groups are wrapped in <ErrorBoundary>
2. Crashes are reported to ExtensionHealthService
3. If threshold exceeded within window: extension is suspended via ExtensionInstallationService.suspend()
4. Events emitted: EXTENSION_AUTO_DISABLED, EXTENSION_HEALTH_CHECK_FAILED

​

Health Record

interface ExtensionHealthRecord {
  extensionId: string;
  errorTimestamps: Date[];
  totalErrorCount: number;
  lastError?: { message: string; timestamp: Date };
}

​

Widget & Event Handler Isolation

• Widget crashes show a placeholder, not a broken dashboard
• Event handler failures are tracked — repeated failures auto-unsubscribe the handler
• Agent tool failures are reported and credit costs may be refunded

​

12. Registry & Resolution Flow

​

ModuleRegistry (Compile-Time Catalog)

​

Resolution Flow

ModuleRegistry.getAllManifests()     → Static catalog (12 built-in extensions)
                 +
Firestore: org/{id}/moduleInstallations → Per-org installation state
                 ↓
ModuleRegistry.resolveModules()     → ResolvedModule[] (manifest + installation + flags)
                 ↓
ExtensionContext (React)            → isActive, isTrialing, isSuspended per module

​

ResolvedModule

interface ResolvedModule {
  manifest: ModuleManifest;
  installation: ModuleInstallation | null;
  isActive: boolean;
  isTrialing: boolean;
  isSuspended: boolean;
  LayoutComponent?: ComponentType<{ children?: React.ReactNode }>;
}

​

13. ESLint Boundary Enforcement

​

custom/no-eventbus-in-components (warn)

​

custom/no-direct-firestore-import (warn)

​

Import Guidance

​

14. Breaking Change Policy

​

What Constitutes a Breaking Change

• Removing or renaming an export from @/shared/extension-api
• Changing the signature of ExtensionBaseService methods
• Removing fields from ModuleManifest that extensions depend on
• Changing the SystemEvent envelope structure
• Altering contribution registration behavior (e.g. ID qualification scheme)
• Modifying lifecycle hook calling conventions

​

Semver Guarantees

​

Migration Path

1. Bump CORE_API_VERSION to the new major
2. Update all built-in extension manifests to declare the new coreApiVersion range
3. Extensions with older compatibility.coreApiVersion will fail activation with a clear error message
4. Document migration steps in release notes

​

Appendix: File Map