Registry API

This page is the precise op-by-op reference for every registry/catalog actor. Each section is reproduced from the actor's static accepts block in code.

system.registry (ServiceRegistryActor)

Mounted at system.registry. Tracks live mount claims with heartbeat-based liveness.

Compatibility ops (service.*)

'service.register':   { name: 'string', mount: 'string' }
'service.resolve':    { name: 'string' }
'service.list':       { includeAll: 'boolean?' }
'service.deregister': { name: 'string' }

Op	Returns
service.register	{ registered: boolean, name, mount }
service.resolve	{ ok, mount? }
service.list	{ ok, services }
service.deregister	{ ok }

Product ops (registry.*)

'registry.register': {
  logicalMount: 'string',
  componentId: 'string?',
  providerRuntimeId: 'string?',
  localMount: 'string?',
  // (additional fields: componentType, authorityRoot, scope,
  //  runtimeWireRoot, packageName, metadata, heartbeatTtlMs)
}
'registry.heartbeat': {
  logicalMount: 'string?',
  componentId: 'string?',
  providerRuntimeId: 'string?',
}
'registry.unregister': {
  logicalMount: 'string?',
  componentId: 'string?',
  providerRuntimeId: 'string?',
}
'registry.list':      { prefix: 'string?', includeStale: 'boolean?' }
'registry.resolve':   { logicalMount: 'string', includeStale: 'boolean?' }
'registry.children':  { prefix: 'string?', includeStale: 'boolean?' }
'registry.providers': { logicalMount: 'string?', includeStale: 'boolean?' }

Op	Returns
registry.register	{ ok, registered, logicalMount }
registry.heartbeat	{ ok, refreshed: number }
registry.unregister	{ ok, removed: number }
registry.list	{ ok, claims: IRegistryView[] }
registry.resolve	{ ok, providers: IRegistryEntry[] }
registry.children	{ ok, children: IRegistryChild[] }
registry.providers	{ ok, providers: IRegistryEntry[] }

Emissions

'service.registered'     // service.register success
'service.deregistered'   // service.deregister success
'registry.registered'    // registry.register first-time success
'registry.heartbeat'     // registry.heartbeat success
'registry.unregistered'  // registry.unregister success

system.packages (SystemPackageRegistryActor)

Mounted at system.packages. Searches discovery-index.json.

Op

'registry.search': {
  text: 'string?',
  tag: 'string?',
  inferredKind: 'string?',
  declaredKind: 'string?',
  capability: 'string?',
  accepts: 'string?',
  emits: 'string?',
  skill: 'string?',
  shells: 'string?',
  registryRoot: 'string?',
  limit: 'number?',
}

Returns:

{
  ok: true,
  registryRoot: string,
  results: IPackageRegistrySearchResult[]
}

Errors

Error	When
REGISTRY_SEARCH_INVALID: limit must be an integer from 1 to 100	limit outside [1, 100]
REGISTRY_ROOT_INVALID: registryRoot must be under MATRIX_HOST_HOME (...)	registryRoot argument not inside $MATRIX_HOST_HOME

system.catalog (SystemCatalogActor)

Mounted at system.catalog. Read projection over system.registry, system.runtimes, system.gateway.http.

Ops

'catalog.list':     { prefix: 'string?' }
'catalog.resolve':  { mount: 'string' }
'catalog.roots':    { options: 'object?' }
'catalog.children': { prefix: 'string?' }
'catalog.tree':     { prefix: 'string?' }
'catalog.search': {
  text: 'string?',
  prefix: 'string?',
  mount: 'string?',
  packageName: 'string?',
  accepts: 'string?',
  emits: 'string?',
  skill: 'string?',
  kind: 'string?',
  inferredKind: 'string?',
  declaredKind: 'string?',
  shells: 'string?',
  status: 'running|stopped|all?',
}

Returns

Op	Shape
catalog.list	{ ok, count, catalog: ISystemCatalogEntry[], bindings, runtimes, source: 'system.catalog' }
catalog.resolve	{ ok, mount, entry: ISystemCatalogEntry | null }
catalog.roots	{ ok, count, roots: NamespaceRoot[] }
catalog.children	{ ok, prefix, count, children: NamespaceRoot[] }
catalog.tree	{ ok, prefix, count, tree: IBindingNamespaceNode[] }
catalog.search	{ ok, count, results: ISystemCatalogSearchResult[], source: 'system.catalog' }

See Catalog schema for the result type definitions.

See also

• Catalog schema
• Error codes

Source: static accepts blocks in projects/matrix-3/packages/system-platform/src/ServiceRegistryActor.ts, projects/matrix-3/packages/system-catalog/src/SystemPackageRegistryActor.ts, projects/matrix-3/packages/system-catalog/src/SystemCatalogActor.ts.