Zeayii.Vexo.Task.Assembly.Abstractions 0.0.32

Vexo.Task.Assembly.Abstractions

English | 简体中文

Organization: zeayii
Project: vexo

1. Introduction

Vexo.Task.Assembly.Abstractions is the contract layer of the Vexo Task Assembly system. It defines the formal boundary between task description and task execution.

This module answers only three questions:

1. What inputs must a task assembly accept?
2. What metadata must a successful assembly produce?
3. How must assembly failures be expressed?

Everything else — media parsing, manifest parsing, DRM, networking, execution, concurrency — is explicitly out of scope.

Design axiom
Abstractions describe obligations and guarantees, never capabilities or implementations.

2. Architectural Role

┌──────────────────────────────────────────────┐
│ Implementation Layer                         │
│ (Offline / Vendor / Private Assemblers)      │
└──────────────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────┐
│ Contract Layer                               │
│ Vexo.Task.Assembly.Abstractions              │
└──────────────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────┐
│ Execution Layer                              │
│ (Pipeline / Workers / Download / Merge)      │
└──────────────────────────────────────────────┘

This module is the only legal bridge between user intent and execution-ready data.

3. Core Design Principles

3.1 Minimalism Over Convenience

Only unavoidable abstractions are exposed.

Rejected on purpose:

• Helper utilities
• Default implementations
• Protocol hints (DASH / HLS)
• Provider or DRM identifiers

This prevents abstraction drift and long-term API bloat.

3.2 Determinism

Assembly must be deterministic:

• Same input → same metadata
• No runtime inference in execution
• No partial success states

If metadata cannot be fully constructed, the assembly must fail.

3.3 Execution Independence

Execution consumes metadata as-is.

Execution MUST NOT:

• Parse manifests
• Parse init or index segments
• Guess encryption schemes
• Mutate metadata

All ambiguity is resolved during assembly.

3.4 AOT / Trim Safety

The abstraction layer is designed for:

• NativeAOT
• IL trimming
• Minimal object graphs

Rules enforced by design:

• No reflection
• No dynamic dispatch requirements
• No plugin discovery mechanisms

4. TaskDescriptor

TaskDescriptor represents the complete and immutable description of a task to be assembled.

Responsibilities

• Declare output intent (directories, naming)
• Carry the task input (ITaskInput)
• Guarantee self-consistency

Non-Responsibilities

• Protocol identification
• Provider selection
• DRM routing
• Execution strategy

A TaskDescriptor describes what the user wants, not how the system should do it.

5. Task Inputs (TaskInput)

Task inputs are modeled as TaskInput subtypes (runtime-distinguished), not enums or flags.

Rationale

• Avoid forcing users to understand protocol taxonomy
• Allow heterogeneous input models
• Keep the contract open for private extensions

Example

• OfflineTaskInput: local or pre-resolved resources
• Future inputs may include authenticated or vendor-specific sources

Assembly logic selects behavior via runtime type checks:

if (descriptor.Input is OfflineTaskInput input)
{
    // offline assembly
}

6. Metadata Model

Assembly produces execution-grade metadata:

• TaskWorkUnit
• Stream
• Fragment

Properties

• Immutable after creation
• Free of runtime state
• Complete enough for execution

This metadata forms a hard execution boundary.

7. Exception Model

Assembly failures are intentional control boundaries, not incidental errors.

Exception Types

• TaskAssemblyException
• TaskDescriptorInvalidException
• TaskAssemblyNotSupportedException

Design Rules

• No field-level exception granularity
• No error codes
• No partial results

Failure always aborts the current task.

8. What This Module Explicitly Does NOT Contain

• Media parsing (MP4 / WebM / EBML)
• Manifest parsing (MPD / M3U8)
• Networking or cookies
• DRM / CDM logic
• Worker or pipeline code

These belong to capability or implementation layers.

9. Implementing an Assembler

To implement a task assembler:

1. Reference this package
2. Validate TaskDescriptor
3. Check supported TaskInput types
4. Produce full metadata or throw

Pseudocode

Validate(descriptor);

if (descriptor.Input is OfflineTaskInput input)
{
    return AssembleOffline(input);
}

throw new TaskAssemblyNotSupportedException(...);

13. Current Public Contracts

The abstraction layer is intentionally narrowed to two contract groups:

• ITaskAssembler: the assembly entry point consumed by the execution layer (implemented by Core).
• TaskAssemblyProvider / TaskAssemblyProvider<TState>: extension points for implementation modules.

TaskAssemblyProvider<TState> enforces an explicit provider state type TState, so the lifecycle from prepare stage to content-key obtain stage remains strongly typed.

14. Compile-Time Contract Analyzer Rules (TaskInput)

The Abstractions package ships a buildTransitive analyzer to validate TaskInput implementations at compile time.

• AASM1001 (Error): typeId must be a compile-time constant.
• AASM1002 (Error): typeId must not be empty or whitespace.
• AASM1003 (Error): typeId must be unique (case-insensitive).
• AASM1004 (Error): constructors must be parameterless (including primary constructor shape).
• AASM1005 (Error): public writable property type must be in the supported whitelist.
• AASM1006 (Error): typeId naming must match lower-kebab-case ([a-z0-9-]+).
• AASM1007 (Warning): TaskInput should be declared as sealed.
• AASM1008 (Warning): TaskInput must not be generic.

10. Versioning & Compatibility

• Semantic Versioning
• Breaking changes are rare and deliberate
• Contract stability is prioritized over feature growth

11. Intended Audience

• Vexo core developers
• Private vendor implementers
• Advanced integrators

12. License & Legal

This module contains no DRM, encryption keys, or restricted logic. It is safe for open-source distribution.