Runtime Symbol Migration Playbook

Purpose

This playbook covers the runtime API rename in pinocchio/pkg/inference/runtime where compatibility aliases were removed. It explains what changed, how to update imports and types, and how to verify your integration after migration.

Use this guide if your code imports any of:

• RuntimeComposeRequest
• RuntimeArtifacts
• RuntimeComposer
• RuntimeComposerFunc
• ComposeEngineFromSettings
• MiddlewareFactory
• ToolFactory
• MiddlewareUse

Old-to-New Symbol Map

Why This Rename Happened

The previous names leaked historical webchat terminology and were too generic in a few places. The new names make the ownership and intent explicit:

• request DTOs are conversation-runtime requests,
• composed outputs are runtime artifacts for execution,
• factories are builders/registrars, not generic factories.

This improves API readability for downstream users and makes future runtime abstractions easier to evolve.

Migration Steps

1. Replace type names in signatures

Before:

func build(r infruntime.RuntimeComposer) error

After:

func build(r infruntime.RuntimeBuilder) error

2. Replace function adapters and request/response DTOs

Before:

composer := infruntime.RuntimeComposerFunc(
    func(ctx context.Context, req infruntime.RuntimeComposeRequest) (infruntime.RuntimeArtifacts, error) {
        // ...
    },
)

After:

composer := infruntime.RuntimeBuilderFunc(
    func(ctx context.Context, req infruntime.ConversationRuntimeRequest) (infruntime.ComposedRuntime, error) {
        // ...
    },
)

3. Replace runtime engine assembly symbols

Before:

eng, err := infruntime.ComposeEngineFromSettings(ctx, stepSettings, prompt, uses, factories)

After:

eng, err := infruntime.BuildEngineFromSettings(ctx, stepSettings, prompt, uses, factories)

4. Replace middleware/tool helper type names

Before:

uses := []infruntime.MiddlewareUse{...}
factories := map[string]infruntime.MiddlewareFactory{...}
tools := map[string]infruntime.ToolFactory{...}

After:

uses := []infruntime.MiddlewareSpec{...}
factories := map[string]infruntime.MiddlewareBuilder{...}
tools := map[string]infruntime.ToolRegistrar{...}

Suggested Search-and-Replace Commands

Run these from repository root:

rg -n "RuntimeComposeRequest|RuntimeArtifacts|RuntimeComposerFunc|RuntimeComposer|ComposeEngineFromSettings|MiddlewareFactory|ToolFactory|MiddlewareUse"

Then replace symbols in this order:

1. DTOs (RuntimeComposeRequest, RuntimeArtifacts)
2. Interfaces/adapters (RuntimeComposer, RuntimeComposerFunc)
3. Builders/factories (ComposeEngineFromSettings, MiddlewareFactory, ToolFactory, MiddlewareUse)

Validation Checklist

1. go test ./pkg/inference/runtime -count=1
2. go test ./cmd/web-chat -count=1
3. go test ./cmd/web-chat/... -count=1
4. go test ./... -count=1

Troubleshooting

See Also

• pinocchio/pkg/doc/topics/webchat-backend-reference.md
• pinocchio/pkg/doc/topics/webchat-framework-guide.md
• pinocchio/pkg/doc/topics/webchat-http-chat-setup.md