Context Object Specification (COS)

Version: 0.2
Chapter: 410 — Adapter
Status: Normative — Adapter Profile
Category: Plugin Model

1. Purpose

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

Adapters provide the integration boundary between external systems and COS.

An Adapter translates external representations into COS-compatible structures while preserving the semantics of the original source.

2. Definition

An Adapter is a specialized Plugin responsible for translating external system data, events, or capabilities into COS representations.

An Adapter connects:

External System
    ↓
Adapter
    ↓
COS Model

3. Core Principle

Adapters follow:

Translate, Don’t Redefine

An Adapter:

MUST:

map external concepts into COS concepts
preserve source information
respect Core Model constraints

MUST NOT:

create alternative COS models
modify Core Model definitions
hide source semantics

4. Adapter Model

An Adapter is defined as:

interface Adapter {
  id: string;
  version: string;
  source: AdapterSource;
  adapt(input: unknown): AdapterResult;
}

5. Adapter Source

Adapter Source identifies the external environment.

interface AdapterSource {
  type: string;
  name?: string;
  version?: string;
}

Examples:

{
  "type": "pdf",
  "name": "PDF.js",
  "version": "5.x"
}

6. Adapter Responsibilities

An Adapter MAY perform:

source parsing
coordinate mapping
event translation
structure extraction
metadata mapping

An Adapter MUST NOT perform:

AI reasoning
recommendation generation
user intent inference

Those belong to Pipeline stages.

7. Adapter Boundary Model

The Adapter boundary:

External Representation
        ↓
Normalization
        ↓
COS Representation

Example:

Browser selection:

External:

{
  "domRange": "...",
  "text": "hello"
}

Adapter output:

{
  "selection": {
    "text": "hello"
  }
}

8. Adapter Output

An Adapter produces COS-compatible input.

interface AdapterResult {
  selection?: Selection;
  source?: SourceContext;
  context?: Context;
  meta?: Meta;
  extensions?: ExtensionEntry[];
}

9. Source Mapping

Adapters SHOULD preserve mapping information between:

original source
COS representation

Example:

PDF:

PDF Coordinate
      ↓
COS Extension

{
 "namespace":"org.example.pdf",
 "version":"1.0.0",
 "payload":{
   "page":12,
   "bbox":{
     "x":100,
     "y":200
   }
 }
}

10. Browser Selection Mapping (Informative)

A Browser Adapter SHOULD map DOM Selection and Range concepts into COS Selection fields without exposing DOM objects directly.

Recommended mapping:

DOM concept	COS field
`Selection.toString()`	`selection.text`
`Range.startOffset`	`selection.range.startOffset`
`Range.endOffset`	`selection.range.endOffset`
`Range.startContainer` logical node id	`selection.range.startNodeId`
`Range.endContainer` logical node id	`selection.range.endNodeId`
document URL	`source.uri` and, when useful, `source.id`
host document type	`source.type`

A Browser Adapter SHOULD derive stable logical node identifiers from source structure. An internal Document or Hierarchy model MAY provide those identifiers.

Adapters MUST NOT serialize live DOM Node, Range, or Selection objects into a Context Object.

Collapsed selections MAY be represented only when the implementation treats cursor focus as a supported Selection. Otherwise they SHOULD be ignored.

11. Event Adaptation

Adapters MAY translate external events.

Example:

Browser:

mouseup
selectionchange

becomes:

context.selection.created

PDF:

annotationCreated

becomes:

context.extensions.updated

12. Adapter and Pipeline Relationship

Adapters provide Pipeline input.

Relationship:

External System
        ↓
Adapter
        ↓
Pipeline
        ↓
Context Object

Adapters do not replace Pipeline stages.

13. Adapter and Plugin Relationship

An Adapter is a Plugin specialization.

Relationship:

Plugin

 ├── Adapter
 |
 ├── Enrichment Plugin
 |
 └── Capability Plugin

14. Adapter Lifecycle

Adapters follow Plugin lifecycle:

Register
    ↓
Initialize
    ↓
Available
    ↓
Adapt
    ↓
Dispose

15. Multiple Adapter Support

A COS implementation MAY support multiple Adapters simultaneously.

Example:

Browser Adapter
        +
PDF Adapter
        +
Editor Adapter
        ↓
Same COS Runtime

16. Adapter Compatibility

Adapters SHOULD declare:

supported source versions
supported capabilities
output mapping version

Example:

{
 "source":"PDF.js",
 "version":"5.x",
 "capabilities":[
   "selection",
   "annotation"
 ]
}

17. Adapter Error Handling

Adapter failures MUST be isolated.

Example:

PDF Adapter Failed
        ↓
Context Object

still valid with:

Selection
Document
Metadata(error)

18. Adapter Security Boundary

Adapters interact with external systems.

Implementations SHOULD consider:

permission boundaries
source validation
input sanitization

19. Example Adapter

PDF Adapter:

PDF.js
    |
    |
PDF Adapter
    |
    +-- Selection
    +-- Document
    +-- PDF Extension
    |
    ↓
COS Pipeline

20. Design Notes

Adapters are intentionally limited to translation responsibilities.

They provide interoperability without introducing domain-specific intelligence into COS Core.

This separation enables COS to support:

browsers
PDF viewers
editors
applications

while maintaining one unified Context Object model.

21. Summary

Adapters define the bridge between external environments and COS.

They translate source-specific representations into standardized Context Objects while preserving protocol stability.

Adapters make COS portable across different platforms and domains.