Context Object Specification (COS)

Version: 0.2
Chapter: 310 — Pipeline Stages
Status: Normative — Runtime Profile
Category: Pipeline Model

1. Purpose

This chapter defines the Pipeline Stage Model of the Context Object Specification (COS).

Pipeline Stages are the fundamental execution units responsible for progressively enriching ContextState during Pipeline execution.

This chapter defines:

• Stage responsibilities
• Stage interfaces
• Stage execution rules
• Stage composition
• Stage result handling

2. Definition

A Pipeline Stage is an isolated enrichment unit that receives ContextState and produces an updated ContextState.

Conceptually:

ContextState
|
▼
Pipeline Stage
|
▼
Enriched ContextState

A Stage represents one specific capability within the Context Enrichment Pipeline.

3. Core Principle

Pipeline Stages follow:

Single Responsibility + Incremental Enrichment

Each Stage:

MUST:

• perform one logical enrichment task
• preserve existing ContextState
• produce explicit results

MUST NOT:

• control the entire Pipeline
• directly invoke unrelated stages
• modify external state

4. Stage Model

A Pipeline Stage is represented as:

interface PipelineStage {
  id: string;
  name: string;
  execute(
    context: ContextState
  ): Promise<StageResult>;
}

5. Stage Identity

Each Stage MUST have a unique identifier.

interface StageIdentity {
  id: string;
  version: string;
}

The identity is used for:

• execution tracing
• debugging
• compatibility management

6. Stage Input

Each Stage receives:

interface StageInput {
  context: ContextState;
}

A Stage MUST NOT require hidden state.

All required information MUST be accessible through:

• ContextState
• Stage Configuration

7. Stage Output

A Stage returns:

interface StageResult {
  status: StageStatus;
  context?: ContextState;
  metadata?: StageMetadata;
}

8. Stage Status

type StageStatus =
  | "success"
  | "failed"
  | "skipped";

9. Successful Execution

A successful Stage:

MUST:

• return updated ContextState
• describe produced enrichment
• preserve previous valid information

Example:

Before:

ContextState
 ├── Selection
 └── Document


After SemanticStage:

ContextState
 ├── Selection
 ├── Document
 └── Semantic

10. Failed Execution

A failed Stage MUST:

• report failure status
• preserve previous ContextState
• provide diagnostic information

Example:

SemanticStage

FAILED

Result:

ContextState
 ├── Selection
 ├── Document
 └── Metadata(error)

A failed Stage MUST NOT destroy previously generated context.

11. Skipped Execution

A Stage MAY be skipped when:

• required capability is unavailable
• conditions are not satisfied
• consumer does not require the result

Skipped execution MUST be observable through metadata.

12. Stage Ordering

Stages execute according to Pipeline configuration.

Default COS execution order:

Selection Stage
        ↓
Source Stage
        ↓
Context Stage
        ↓
Meta Stage

Optional stages MAY run after the lean Context Object is constructed:

Extension Stage
        ↓
Product Recommendation Stage

13. Stage Dependency

A Stage MAY depend on previous enrichment results.

Example:

Context Stage

requires:

Selection
Source

A Stage MUST explicitly declare required capabilities.

14. Stage Capability Model

Stages SHOULD expose their capabilities.

interface StageCapability {
  provides: string[];
  requires: string[];
}

Example:

{
  "provides": [
    "context.segments"
  ],
  "requires": [
    "selection",
    "source"
  ]
}

15. Built-in Stages

COS v0.2 defines the following standard stages:

15.1 Selection Stage

Purpose:

Initialize ContextState from Adapter output or direct Pipeline input.

Provides:

Selection Context

Responsibilities:

• validate that Selection contains text and optional range information
• preserve the original Selection without semantic enrichment
• preserve the original user-selected text

15.2 Source Stage

Purpose:

Attach source-level context.

Provides:

Source Context

Responsibilities:

• identify where the Selection came from
• expose source type, id, uri, title, app, and language when available
• avoid duplicating source data in Selection or Meta

15.3 Context Stage

Purpose:

Construct the local context needed by Consumers.

Provides:

Context

Responsibilities:

• extract covered context segments in source order
• preserve each segment’s full text and selected text
• preserve before/after text within segment boundaries
• attach deterministic segment-level and selection-level relations
• classify segment type using deterministic source signals

15.4 Meta Stage

Purpose:

Record minimal object generation metadata.

Provides:

Meta

Responsibilities:

• record creation time when needed
• record adapter identity when useful
• avoid duplicating source, context, or debug traces

15.5 Extension Stage

Purpose:

Attach optional platform-specific or debug information.

Provides:

Extensions

Responsibilities:

• attach browser DOM paths, PDF coordinates, editor block ids, debug traces, or integrity data
• keep platform-specific data outside the lean core object
• avoid making Extensions required for ordinary Consumer understanding

15.6 Product Recommendation Stage

Purpose:

Derive optional product-level actions outside the lean core object.

Product Recommendations

Responsibilities:

• derive UI actions, shortcuts, or suggestions after receiving the Context Object
• keep recommendations advisory
• avoid adding recommendation fields to the lean core object

16. Stage Isolation

Each Stage MUST be isolated.

A Stage:

MAY:

• read existing ContextState
• add enrichment data

MUST NOT:

• directly modify another Stage’s result
• bypass Pipeline ordering
• access unrelated execution state

17. Custom Stages

Implementations MAY introduce custom stages.

Custom stages MUST:

• define unique identifiers
• declare capabilities
• follow enrichment rules
• remain compatible with Context Object Model

Examples:

PDFAnnotationStage

CodeAnalysisStage

VisionSemanticStage

Custom stages MAY be contributed by Plugins.

A Plugin MAY register multiple custom stages.

Each registered Stage MUST declare the Plugin that provides it.

One Stage SHOULD belong to one Plugin for lifecycle and compatibility purposes.

If multiple stages provide the same capability, the Pipeline configuration MUST select one provider explicitly or define a deterministic ordering rule.

A custom Stage MUST NOT silently override a built-in Stage that provides the same capability.

18. Stage Observability

Each Stage execution SHOULD produce trace information:

interface StageMetadata {
  stageId: string;
  startedAt?: number;
  completedAt?: number;
  durationMs?: number;
}

This information is consumed by Metadata Layer.

19. Relationship to Pipeline

Pipeline manages:

• execution order
• lifecycle
• state transitions

Stages manage:

• individual enrichment logic

Relationship:

Pipeline
    |
    +-- Stage 1
    |
    +-- Stage 2
    |
    +-- Stage 3

20. Summary

Pipeline Stages define the executable units of COS enrichment.

A Stage is intentionally small, isolated, and additive.

Through Stage composition, COS enables different implementations while preserving a stable Context Object model.