feat: add step handler registry for library embedding

[jlouvel]

Related Issue

Closes #394

---

What does this PR do?

Adds a programmatic embedding API that allows Java applications to use the Naftiko Framework as a library. Embedders register StepHandler implementations by step name via StepHandlerRegistry; when the engine encounters a registered step during orchestration, it delegates to the handler instead of the normal call/script/lookup path.

Key components:

• StepHandler interface — receives StepHandlerContext, returns JsonNode
• StepHandlerContext — immutable view of execution context (input parameters, prior step outputs, with values)
• StepHandlerRegistry — maps step names to handlers, executes them with context
• NaftikoEngine.builder() — fluent API to load YAML from classpath/file and register handlers
• Integration into OperationStepExecutor — registry check before normal dispatch (single continue path)

The Naftiko Specification (naftiko-schema.json) remains unchanged. This is the prerequisite for Polychro Phase 12 (MCP Server Mode).

---

Tests

• StepHandlerRegistryTest — 10 tests covering register/get/has/unregister/execute/null guards
• StepHandlerContextTest — 8 tests covering accessibility, convenience methods, immutability, null safety
• NaftikoEngineBuilderTest — 5 tests covering classpath loading, missing resource, handler registration, registry propagation
• EngineStepHandlerOverrideTest — 5 integration tests verifying handler override, normal path fallback, null output, multi-handler, and step chaining

---

Checklist

• CI is green (build, tests, schema validation, security scans)
• Rebased on latest main
• Small and focused — one concern per PR
• Commit messages follow Conventional Commits

---

Agent Context (optional)

agent_name: GitHub Copilot
llm: Claude Opus 4.6
tool: VS Code Chat
confidence: high
source_event: user request to implement java-class-invocation-step blueprint
review_focus: src/main/java/io/naftiko/engine/step/, src/main/java/io/naftiko/engine/util/OperationStepExecutor.java:184-225

[jlouvel]

@eskenazit This is a dependency for Polychro built-in MCP server

[eskenazit]

PR #395 — Step Handler Registry / Embedding API review. One blocking issue (wrong method names in error message) and several smaller findings below.

[eskenazit]

Review from Claude Sonnet 4.6

[jlouvel]

@eskenazit Should be good now

[eskenazit]

Good progress — 4 of 5 threads are resolved. One non-blocking item remains before merge.

Still open: ConcurrentHashMap on local variables in OperationStepExecutor\nThe resolved copy-for-with was fixed, but params, runtimeParameters (top of executeSteps) and stepParams (in mergeStepParameters) are still ConcurrentHashMap. All three are single-threaded stack variables; HashMap is the right type.

New nit: Javadoc @code example in Capability.Builder still shows .capabilityFromClasspath(...) — should be .loadFromClasspath(...) to match the actual API.

Everything else looks clean: the blocking error-message fix, the registry hoisting, the encoding, the test assertions, and the test deduplication are all good.

[jlouvel]

@eskenazit Should be good now

[eskenazit]

LGTM