Catalog schema

This page is the type reference for what comes out of the registry/catalog actors and what lives in discovery-index.json.

ISystemCatalogEntry

Returned by catalog.list and catalog.resolve.

// SystemCatalogActor.ts:67-80
interface ISystemCatalogEntry {
  mount: string;             // canonical logical mount, e.g. "system.devices"
  type: string;              // class name, package name, or "binding"
  purpose?: string;          // free-form description
  ops?: string[];            // op names accepted at this mount
  packageName?: string;
  providerCount: number;
  providers: ICatalogProviderEntry[];
  runtimeRoot?: string;      // session/runtime mount of the owning runtime
  runtimeId?: string;
  runtimeType?: string;
  authorityRoot?: string;
  localMount?: string;       // mount path relative to the owning runtime
}

interface ICatalogProviderEntry {
  provider: string;
  runtimeId?: string;
  packageName?: string;
  localMount: string;
  runtimeRoot?: string;
  runtimeType?: string;
  authorityRoot?: string;
}

ISystemCatalogSearchResult

Returned by catalog.search.

// SystemCatalogActor.ts:107-129
interface ISystemCatalogSearchResult {
  mount: string;
  source: 'actor' | 'webapp';
  runtimeId?: string;
  packageRef?: string;
  displayName?: string;
  description?: string;
  icon?: string;
  routePrefix?: string;        // present for webapp results
  shells?: readonly string[];  // present for webapp results
  type?: string;
  kind?: string;
  inferredKind?: string;
  declaredKind?: string;
  accepts?: readonly string[];
  emits?: readonly string[];
  skills?: readonly string[];
  tags?: readonly string[];
  capabilities?: readonly string[];
  status?: string;
  providerCount?: number;
  localMount?: string;
}

IBindingNamespaceNode

Returned by catalog.roots, catalog.children, catalog.tree.

interface IBindingNamespaceNode {
  mount: string;          // full canonical mount, e.g. "system"
  segment: string;        // last dot-segment, e.g. "system"
  isBinding: boolean;     // true if this exact mount has a registered claim
  providerCount: number;  // number of live providers at this mount (0 if not isBinding)
  children: IBindingNamespaceNode[];
}

IPackageDiscoveryMetadata (discovery-index.json entry)

Each version under discovery-index.json:packages.<pkg>.versions.<ver>.metadata:

// SystemPackageRegistryActor.ts:21-51
interface IPackageDiscoveryMetadata {
  packageName: string;
  version: string;
  displayName?: string;
  description?: string;
  inferredKind?: string;
  declaredKind?: string;
  tags: readonly string[];
  capabilities: readonly string[];
  webapp?: {
    appName?: string;
    displayName?: string;
    description?: string;
    shells: readonly string[];
    icon?: string;
    routePrefix?: string;
  };
  components: readonly {
    type?: string;
    exportName?: string;
    mount?: string;
    surface?: string;
    description?: string;
    kind?: string;
    accepts: readonly string[];
    emits: readonly string[];
    skills: readonly string[];
    tags: readonly string[];
    capabilities: readonly string[];
  }[];
}

IPackageRegistrySearchResult

Returned by system.packages.registry.search.

// SystemPackageRegistryActor.ts:53-63
interface IPackageRegistrySearchResult {
  packageName: string;
  version: string;
  displayName?: string;
  description?: string;
  inferredKind?: string;
  declaredKind?: string;
  keywords: readonly string[];
  matchedFields: readonly string[];
  score: number;
}

IPackageDiscoveryIndex (file shape)

Top-level shape of discovery-index.json:

// projects/matrix-3/packages/mx-cli/src/utils/discovery-index.ts
interface IPackageDiscoveryIndex {
  packages: Record<string, {
    versions: Record<string, {
      indexedAt: string;          // ISO timestamp
      indexedBy: string;          // tool identifier
      metadata: IPackageDiscoveryMetadata;
    }>
  }>;
}

Example:

{
  "packages": {
    "@open-matrix/chat": {
      "versions": {
        "0.2.3": {
          "indexedAt": "2026-04-30T12:00:00Z",
          "indexedBy": "publish-pipeline",
          "metadata": {
            "packageName": "@open-matrix/chat",
            "version": "0.2.3",
            "displayName": "Chat",
            "inferredKind": "webapp",
            "tags": ["chat", "ui"],
            "capabilities": ["chat", "ui"],
            "webapp": {
              "appName": "chat",
              "shells": ["platform"]
            },
            "components": [
              {
                "type": "ChatActor",
                "mount": "chat",
                "accepts": ["chat.send"],
                "emits": ["chat.message"],
                "skills": []
              }
            ]
          }
        }
      }
    }
  }
}

See also

• Registry API
• Metadata

Source: Type declarations in projects/matrix-3/packages/system-catalog/src/SystemCatalogActor.ts:67-129, projects/matrix-3/packages/system-catalog/src/SystemPackageRegistryActor.ts:21-63, projects/matrix-3/packages/mx-cli/src/utils/discovery-index.ts.