Zeayii.Vexo.Assembly.Abstractions 0.0.37

Zeayii.Vexo.Assembly.Abstractions

English | 简体中文

Organization: zeayii
Project: vexo

1. Introduction

Zeayii.Vexo.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                               │
│ Zeayii.Vexo.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:

• ExecutionTask
• ExecutionStream
• ExecutionSegment

Properties

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

This metadata forms a hard execution boundary.

6.1 Timeline Contracts (New)

• SegmentTiming now uses TimeSpan for Start, End, and TimestampOffset to avoid repeated unit conversions across modules.
• SegmentTimingStatePolicy explicitly models timeline availability: Resolved or Unavailable.
• ExecutionStreamGroup now carries StartOffset and Duration (TimeSpan):
  • StartOffset: group start on the global task timeline.
  • Duration: primary media duration for the group (video first, audio fallback).
• Unresolvable timing is modeled with explicit state instead of nullable timing objects, so execution can branch deterministically.

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:

• TaskAssemblyOrchestrator / TaskAssemblyOrchestrator<TSessionState>: extension points for implementation modules.
• Assembly output/session contracts: ExecutionTask, TaskAssemblyUnitSession<TSessionState>, and AssemblyFrame.

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

13.1 Visibility Boundary Policy (public / internal)

To prevent responsibility leakage and API bloat, the layer follows:

• public: stable cross-module contracts that callers must depend on directly.
• internal: internal implementation details (filter-chain internals, plan resolvers, default validator implementations).

This keeps:

• external API focused on domain semantics,
• internal composition details hidden behind public facades,
• internal refactoring safe without unnecessary public breaking changes.

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-domain-kebab format ([a-z0-9.-]+).
• AASM1007 (Warning): TaskInput should be declared as sealed.
• AASM1008 (Warning): TaskInput must not be generic.
• AASM1009 (Error): every concrete TaskInput must define [CommandLineName].
• AASM1010 (Error): CommandLineName.Name format is invalid (only [a-z0-9-]+ allowed).
• AASM1012 (Error): duplicate command token conflict (Name).
• AASM1013 (Error): every public writable property must define [CommandLineOption].
• AASM1014 (Error): CommandLineOption.Name format is invalid (--[a-z0-9][a-z0-9-]*).
• AASM1015 (Error): CommandLineOption.Alias format is invalid (-[a-z0-9][a-z0-9-]*).
• AASM1016 (Error): DescriptionKey must be non-empty on both CommandLineName and CommandLineOption.
• AASM1017 (Error): duplicate option token (long name or alias) inside one TaskInput.
• AASM1018 (Error): CommandLineOption.DefaultValue is incompatible with the target property type (for collections, JSON shape is required).

AASM1005 whitelist (including Nullable<T>):

• Scalars: string, char, bool, sbyte/byte, short/ushort, int/uint, long/ulong, float/double/decimal, Guid, Uri, DateTime, DateTimeOffset, DateOnly, TimeOnly, TimeSpan
• Enums: any enum (including [Flags])
• Collections: T[], List<T>, IList<T>, IReadOnlyList<T>, ICollection<T>, IReadOnlyCollection<T>, HashSet<T>, ISet<T>, IEnumerable<T> (T must be a supported scalar or enum)
• Dictionaries: Dictionary<TKey,TValue> / IDictionary<TKey,TValue> / IReadOnlyDictionary<TKey,TValue>, where TKey is only string or Guid, and TValue must be a supported scalar or enum

Additional command metadata constraints:

• CommandLineName is required and should use lowercase kebab token (for example dmm, mgstage).
• CommandLineOption.Name must start with -- (for example --content-id).
• CommandLineOption.Alias is optional, but if provided it must start with - (for example -cid).
• CommandLineOption.DefaultValue is optional and always expressed as string text.
  • Scalar / enum: literal text (for example 1, true, Main).
  • List / array: JSON array text (for example []).
  • Dictionary: JSON object text (for example {}).
• Descriptions are key-based (DescriptionKey) and should be resolved by a localizer implementation.

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.