steward_runtime

Een compacte Dart workflow-runtime voor expliciete graph-definities, observeerbare execution en duurzame checkpoint/resume-paden.

Kernkenmerken

• Declaratieve graph-definitie: Bouw workflows met expliciete nodes, routes, branches en subgraphs.
• Observeerbare runtime: Elke run emit typed WorkflowEvent-events voor node-lifecycle, interruptions, failures en completion.
• Checkpoint en resume: Interrupt-, dispatch- en resume-flows gebruiken expliciete checkpoint-contracten via CheckpointStore, CheckpointCodec en ResumeToken.
• Parallel fan-out/fan-in: mergeAll- en chooseBest-flows zijn auditabel via expliciete parallel-resultaattypes.
• Opt-in runtime controls: RuntimeConfig ondersteunt nu timeout, retry en cancellation op runtime-boundaries.
• Codec-gedreven persistence: 2.1 bevat InMemoryCheckpointStore voor tests en FileCheckpointStore als eerste duurzame reference adapter.

Architectuurstatus

• lib/steward_runtime.dart is de primaire publieke v2-surface.
• De package draait nu op de v2 modules voor definition/, runtime/, state/, control/, persistence/, observability/, errors/ en integrations/.
• De oude publieke compat-surface en interne legacy migratielagen zijn verwijderd.
• De concrete as-built structuur voor Steward Runtime staat in:
  • doc/architecture/steward-runtime-v2-target-structure.md
• Het bevroren publieke barrel-contract en de support-levels staan in:
  • doc/architecture/public-api-contract.md
• Runtime-control contracten voor timeout, retry en cancellation staan in:
  • doc/architecture/runtime-control-semantics.md
• De eerste production-grade checkpoint-beslissing staat in:
  • doc/decisions/ADR-001-file-checkpoint-store-2-1.md
• Release- en publish-criteria voor deze package staan in:
  • doc/releases/2.1-release-criteria.md
  • doc/releases/repo-remote-strategy.md
• Dat document is leidend voor verdere package-brede surface-cleanups of nieuwe runtime-slices.

De claims in deze README zijn bewust beperkt tot gedrag dat ook echt door code, examples en test/v2 wordt gedragen.

Installatie

Voeg de package lokaal of via je interne Git-repository toe aan je pubspec.yaml:

dependencies:
  steward_runtime:
    path: ../steward-runtime # Of gebruik je Forgejo git URL

Snelstartgids

Hier is hoe je een minimale lineaire workflow opbouwt via de publieke v2 API:

import 'package:steward_runtime/steward_runtime.dart';

Future<void> main() async {
  const GraphDefinition<Map<String, Object?>> graph =
      GraphDefinition<Map<String, Object?>>(
        id: 'quickstart',
        startAt: 'start',
        nodes: <NodeId, NodeDefinition>{
          'start': NodeDefinition(id: 'start', description: 'Load input'),
          'validate': NodeDefinition(
            id: 'validate',
            description: 'Validate state',
          ),
          'finish': NodeDefinition(id: 'finish', description: 'Finish run'),
        },
        routes: <NodeId, List<RouteDefinition>>{
          'start': <RouteDefinition>[
            RouteDefinition(from: 'start', to: 'validate'),
          ],
          'validate': <RouteDefinition>[
            RouteDefinition(from: 'validate', to: 'finish'),
          ],
        },
      );

  final LinearGraphRuntime<Map<String, Object?>> runtime =
      LinearGraphRuntime<Map<String, Object?>>(
        handlers: <NodeId, NodeHandler<Map<String, Object?>>>{
          'start': (WorkflowState<Map<String, Object?>> state) async =>
              NodeResult<Map<String, Object?>>.next(
                state.copyWith(
                  value: <String, Object?>{
                    ...state.value,
                    'loaded': true,
                  },
                ),
              ),
          'validate': (WorkflowState<Map<String, Object?>> state) async =>
              NodeResult<Map<String, Object?>>.next(
                state.copyWith(
                  value: <String, Object?>{
                    ...state.value,
                    'valid': (state.value['loaded'] as bool?) ?? false,
                  },
                ),
              ),
          'finish': (WorkflowState<Map<String, Object?>> state) async =>
              NodeResult<Map<String, Object?>>.finish(
                state.copyWith(
                  value: <String, Object?>{
                    ...state.value,
                    'status': 'done',
                  },
                ),
              ),
        },
      );

  const WorkflowState<Map<String, Object?>> initialState =
      WorkflowState<Map<String, Object?>>(
        value: <String, Object?>{'requestId': 'demo-1'},
        currentNode: 'ignored-by-runtime',
        runId: 'quickstart-run',
      );

  await for (final WorkflowEvent<Map<String, Object?>> event in runtime.run(
    graph: graph,
    initialState: initialState,
    config: const RuntimeConfig(),
  )) {
    print('[${event.kind}] ${event.nodeId} -> ${event.payload}');
  }
}

Verwachte event-volgorde:

node_started -> node_completed -> node_started -> node_completed -> node_started -> node_completed -> run_completed

Voorbeelden

De top-level example/ directory is de gecureerde v2 showcase van de publieke API:

• example/persistence_workflow.dart — checkpoint, interrupt en resume-flow.
• example/factuur_workflow.dart — conditionele route + human approval.
• example/contract_workflow.dart — parallel fan-out/fan-in met mergeAll-semantiek.
• example/choose_best_workflow.dart — parallel fan-out/fan-in met chooseBest-selectie en audit trail.
• example/stream_workflow.dart — live event-stream observability.
• example/runtime_control_workflow.dart — timeout, retry en cancellation als compacte runtime-control showcase.