workflow/.cards/registry.md

Registry

workflow.yaml — the local file that maps workflow names to their current and historical bundle hashes, plus global LLM provider configuration.

Overview

The registry is a single YAML file at <storageRoot>/workflow.yaml (default: ~/.uncaged/workflow/workflow.yaml). It is the authoritative index of which bundles are available on a machine and what name each one is known by. All CLI workflow commands read or write this file.

The registry is read on every uncaged-workflow run invocation to look up the bundle hash for a given name, then used again to resolve the extract model configuration. It is written atomically via the writeWorkflowRegistry function.

Schema

config:
  maxDepth: 3
  supervisorInterval: 5
  providers:
    openrouter:
      baseUrl: "https://openrouter.ai/api/v1"
      apiKey: "sk-or-..."
  models:
    extract: "openrouter/anthropic/claude-sonnet-4-5"
    supervisor: "openrouter/anthropic/claude-haiku-3-5"

workflows:
  solve-issue:
    hash: "3TNKQRJ7BM4XH"
    timestamp: 1716000000000
    history:
      - hash: "2BMJPQ6YAK3WG"
        timestamp: 1715000000000
  develop:
    hash: "7VQWX8NRHK1ZT"
    timestamp: 1716100000000
    history: []

Types

type WorkflowRegistryFile = {
  config: WorkflowConfig | null;
  workflows: Record<string, WorkflowRegistryEntry>;
};

type WorkflowRegistryEntry = {
  hash: string;       // current bundle hash (13-char Crockford Base32)
  timestamp: number;  // Unix epoch ms when this version was registered
  history: WorkflowHistoryEntry[];
};

type WorkflowHistoryEntry = {
  hash: string;
  timestamp: number;
};

Bundle Registration Flow

1. uncaged-workflow workflow add <name> <file.esm.js> is called.
2. The bundle bytes are hashed with XXH64 → 13-char Crockford Base32.
3. The bundle file is copied into <storageRoot>/bundles/<hash>/ (if not already present).
4. registerWorkflowVersion prepends the current head to history and sets the new hash as head.
5. The updated registry is written back to workflow.yaml.

Version History

Every workflow add on an already-registered name pushes the previous hash into history. History is ordered most-recent-first. workflow rollback <name> [hash] swaps the specified history entry back to head (or defaults to history[0]).

Model Resolution

The config.models section uses provider/model references (e.g., "openrouter/anthropic/claude-sonnet-4-5"). resolveModel splits the reference on the first /, looks up the provider in config.providers, and returns a ResolvedModel with { baseUrl, apiKey, model }. This is used by the engine to configure the extract LLM.

// packages/workflow-register/src/config/resolve-model.ts
export function resolveModel(
  config: WorkflowConfig,
  modelKey: string,
): Result<ResolvedModel, string>

Code Pointers

Package	File	What it does
@uncaged/workflow-register	src/registry/registry.ts	readWorkflowRegistry, writeWorkflowRegistry, registerWorkflowVersion, rollbackWorkflowToHistoryHash
@uncaged/workflow-register	src/registry/types.ts	WorkflowRegistryFile, WorkflowRegistryEntry, WorkflowHistoryEntry
@uncaged/workflow-register	src/registry/registry-normalize.ts	YAML normalization for the registry root
@uncaged/workflow-register	src/config/resolve-model.ts	resolveModel — splits provider/model refs
@uncaged/workflow-register	src/bundle/extract-bundle-exports.ts	Validates bundle exports before registration
@uncaged/workflow-protocol	src/types.ts	WorkflowConfig, ProviderConfig, ResolvedModel

See Also

• Bundle — what is stored and indexed in the registry