Zeayii.Vexo.Assembly 0.0.37

Zeayii.Vexo.Assembly.Core

Organization: zeayii
Module Type: Core Orchestration Layer
Target Framework: net10.0

1. Purpose

Zeayii.Vexo.Assembly.Core is the orchestration backbone of assembly flow. It does not parse protocol internals or container bytes. Instead, it coordinates:

1. descriptor input,
2. provider preparation output,
3. manifest extraction output,

into a deterministic incremental stream of ExecutionTask frames.

2. Responsibilities

• Provide unified assembly entry points (single-shot + incremental).
• Drive provider preparation stage and content-key obtain stage.
• Orchestrate DASH/HLS adapters and polling state transitions.
• Execute snapshot validation, stability validation, and delta building.
• Consume immutable AssemblyOptions snapshot consistently.

3. Non-Responsibilities

• No MPD/M3U8 parsing internals (Manifest module owns this).
• No MP4/WebM byte-level parse/remux (Media module owns this).
• No vendor-private business logic (Provider/private modules own this).
• No CLI argument mapping (host application owns this).

4. Layering and Dependency Direction

Vexo / Host
  -> Core (this module)
    -> Manifest
      -> Media
        -> Abstractions

Core exposes orchestration behavior only and keeps protocol internals behind adapters.

5. Public Usage

Use DI registration and resolve SerialTaskAssembler:

services.AddTaskAssemblyCoreRuntime(assemblyOptions);

var assembler = provider.GetRequiredService<SerialTaskAssembler>();
await foreach (var frame in assembler.AssembleFramesAsync(descriptor, context, ct))
{
    if (frame is WorkUnitFrame workUnitFrame)
    {
        // workUnitFrame.WorkUnit / workUnitFrame.Delta / workUnitFrame.LifecycleState
    }
}

6. Main Execution Flow

1. SerialTaskAssembler resolves provider via TaskAssemblyOrchestratorResolver.
2. Runs PrepareAsync in streaming mode (no full buffering).
3. For each preparation context, performs one extraction round (coordinator-based):
   • format sniffing,
   • DASH/HLS adapter extraction,
   • filter pipeline,
   • ExecutionTask build.
4. Applies snapshot/stability validation and delta build.
5. Continues or terminates based on refresh decision.

6.1 Group Timeline Finalization (New)

• After deduplication, the filter chain runs GroupTimelineFinalizeFilter to compute:
  • StartOffset (session-accumulated offset) per StreamGroup;
  • Duration (primary media duration) per StreamGroup.
• Offset state is kept in assembly session (TaskAssemblyUnitSession.AccumulatedOffset) and carried across rounds.
• Text subtitles receive group offset; container subtitles do not receive text-style shifting to keep execution-side container concat semantics intact.
• Per-round RoundAccumulatedDuration is committed by adapters at round completion and becomes the next round's start baseline.

7. Design Principles

• Streaming-first: preparation is yielded as it arrives.
• One-way dependency: no upward coupling into host/private code.
• State centralization: polling and lifecycle state are managed in Core.
• Extensible-private logic: provider extension points without polluting public pipeline.

8. Performance and AOT

• Explicit types + DI delegates; no runtime reflection dependency.
• Singleton registrations for high-frequency resolvers/adapters.
• Iterative polling flow without unnecessary intermediate materialization.

9. Collaboration with Other Modules

• Abstractions: contracts, models, filters, validators.
• Manifest: protocol extraction, refresh decision, protocol filters.
• Offline: sample orchestrator and default assembly wiring.

10. Commercial Release Checklist

• Freeze and document AssemblyOptions defaults.
• Run incremental assembly regression on real-world vectors.
• Keep private provider logic isolated from core orchestration path.

11. License

This module follows the repository root license.

12. Visibility Boundary (public / internal)

Core intentionally exposes only:

• SerialTaskAssembler as the runtime assembly entry point.
• ServiceCollectionExtensions as the DI composition entry.

All orchestration collaborators (adapters, resolvers, round requests) are internal because:

• the execution layer should not depend on Core internals,
• public API must represent capabilities, not wiring details,
• Core internals can evolve without forcing external breaking changes.