Context Object Specification v0.2

Version: 0.2
Release Status: Draft
Short Name: COS v0.2

1. Purpose

This catalog is the canonical table of contents for Context Object Specification v0.2.

The files listed here define the current v0.2 specification set.

COS v0.2 has not been publicly released. This directory MAY be revised freely until the first release package is published.

1.1 Requirement language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in BCP 14, RFC 2119 and RFC 8174, when and only when they appear in all capitals.

1.2 Conformance authority

Chapter 200 defines the canonical exchange shape. Normative prose is authoritative for semantics; the JSON Schema is normative for structural validation. The Pipeline and Plugin parts define a reference runtime architecture and are not required for exchange-format conformance.

The normative Conformance chapter defines independent implementation classes. Security and Privacy Considerations apply to all conforming implementations.

2. Reading Order

Implementers SHOULD read the specification in this order:

1. Part I — Foundation
2. Part II — Core Model
3. Part III — Pipeline
4. Part IV — Plugin
5. Part V — Adoption Evolution

3. Catalog

Part I — Foundation

Part II — Core Model

Part III — Pipeline

Part IV — Plugin

Part V — Adoption Evolution

4. Specification layers

The Core Exchange Format consists of Conformance, Security, Chapters 100, 130-140, and Chapters 200, 210, 225, and 270.

Chapters 220, 230, 235, 240, 250, and 260 provide supporting or optional models. They do not add required top-level fields.

Part III is the normative Runtime Profile only for implementations claiming Runtime conformance. Part IV is the normative Plugin/Adapter Profile only for implementations claiming those classes.

Informative chapters provide motivation, examples, best practices, and future direction. They do not define additional protocol requirements.

5. Draft Policy

COS v0.2 is the working baseline for the first reference implementation.

Until the first public release, changes SHOULD prioritize:

• Consumer usability
• object simplicity
• removal of duplicated fields
• deterministic source-grounded context
• alignment with the first-principle purpose of COS

The specification SHOULD NOT preserve unused fields or structures only for historical compatibility before release.

COS v0.2 Conformance

Version: 0.2
Status: Normative
Category: Conformance

1. Conformance classes

COS defines independent conformance classes. An implementation MUST state which class or classes it claims.

1.1 Core Producer

A Core Producer emits Context Objects. Every emitted object MUST satisfy the normative Core Model prose and the v0.2 JSON Schema. It MUST preserve observed selection text, MUST derive context from source-grounded signals, and MUST NOT require an Extension to interpret core fields.

1.2 Core Consumer

A Core Consumer reads Context Objects. It MUST interpret core fields according to Part II, MUST NOT reinterpret the selected text, and MUST safely ignore Extension namespaces it does not support.

1.3 Runtime

A conforming Runtime implements the Pipeline profile in Part III. It MUST also conform as a Core Producer whenever it emits Context Objects.

1.4 Plugin

A conforming Plugin implements the Plugin and compatibility profile in Part IV. Plugin conformance does not by itself imply Core Producer or Consumer conformance.

1.5 Adapter

A conforming Adapter implements Chapter 410. It MUST produce input that can be completed into a conforming Context Object and MUST NOT expose live source-runtime objects in the exchange representation.

2. Structural and semantic conformance

The JSON Schema is authoritative for JSON structure. Normative prose is authoritative for field meaning and behavior. Passing schema validation is necessary but not sufficient.

3. Optional features

Omitting an optional field or profile does not make a core object non-conforming. If an implementation emits an optional field, that field MUST satisfy all requirements that apply to it.

4. Claims

A public conformance claim SHOULD identify the COS protocol version, conformance classes, supported Extension namespaces, and known limitations.

Security and Privacy Considerations

Version: 0.2
Status: Normative
Category: Security

1. Untrusted input

Producers and Consumers MUST treat source text, labels, URIs, metadata, and Extension payloads as untrusted data. A Context Object does not grant permission to execute, fetch, render, or dereference any contained value.

2. Data minimization

Producers SHOULD emit only the context needed for the intended Consumer. They SHOULD avoid secrets, credentials, hidden page content, unrelated personal data, and content outside the authorized source scope.

3. Extension isolation

Unknown Extensions MUST be ignored safely. Consumers MUST NOT interpret an unknown payload as executable instructions. Failure to process one Extension MUST NOT invalidate otherwise usable core fields.

4. Source boundaries

Adapters MUST respect platform permission and origin boundaries. A browser Adapter, for example, MUST NOT bypass same-origin restrictions or serialize privileged live objects.

5. Integrity and authenticity

COS v0.2 does not define signing, encryption, identity, or transport security. Applications that require authenticity or confidentiality MUST provide them at the transport or application layer and MUST NOT infer trust from schema validity alone.

6. AI consumers

Text inside a Context Object can contain prompt-injection or adversarial content. AI Consumers SHOULD distinguish source content from application instructions and SHOULD apply their own trust and authorization controls.

Context Object Specification (COS)

Version: 0.2
Chapter: 100 — Core Philosophy
Status: Normative
Category: Foundation

1. Purpose

This chapter defines the core philosophy of the Context Object Specification (COS).

Unlike implementation details, APIs, or programming interfaces, the philosophy described here is intended to remain stable throughout the lifetime of the specification.

Every component of the specification—including the data model, pipeline architecture, extension mechanism, and future implementations—MUST follow the principles defined in this document.

Whenever an implementation decision conflicts with one of these principles, the principles defined here take precedence.

2. Why Context Object Exists

Large Language Models (LLMs) have fundamentally changed how software consumes information.

However, most applications still provide context in an extremely primitive form.

For example:

llm(selection.text)

Although technically valid, plain text rarely represents what the user is actually focusing on.

A text selection alone cannot answer questions such as:

• Where did this content come from?
• What document does it belong to?
• What section is it located in?
• What surrounds it?
• What is its semantic meaning?
• Why is the user likely interested in it?

These missing pieces are collectively referred to as Context.

The purpose of the Context Object is not to replace user content.

Its purpose is to describe the user’s current focus in a structured, portable, and machine-understandable way.

3. The Philosophy of Context

The Context Object Specification is built upon five fundamental philosophies.

These philosophies define the identity of the project and guide every future design decision.

Philosophy 1 — Context Over Content

Statement

Applications SHOULD describe context rather than only transmitting content.

Rationale

Content represents what the user selected.

Context represents what the selection means within its environment.

For example, these two selections may contain identical text:

this

Yet they may represent entirely different meanings depending on their surrounding context.

Without contextual information, downstream systems are forced to infer meaning from incomplete data.

The Context Object exists to eliminate this ambiguity.

Philosophy 2 — Attention Over Selection

Statement

The specification describes user attention rather than browser selection.

Rationale

A browser selection is only one possible way users express interest.

Other examples include:

• clicking an element
• tapping on mobile devices
• focusing an editor block
• selecting a PDF region
• selecting an image
• selecting OCR results
• voice highlighting
• AI-generated focus

These interactions all represent the same underlying concept:

The user is currently paying attention to something.

Therefore, the specification models attention, not browser APIs.

Browser selections are simply one implementation.

Philosophy 3 — Structure Over Prompt

Statement

Structured data MUST always be the primary representation.

Prompt generation SHOULD be treated as an adapter.

Rationale

Prompts are optimized for individual AI models.

Structures are optimized for interoperability.

A Context Object should remain valid regardless of whether it is consumed by:

• OpenAI
• Claude
• Gemini
• DeepSeek
• Search engines
• Workflow systems
• Automation tools

Prompt generation is therefore considered an output format rather than part of the specification itself.

Philosophy 4 — Protocol Over SDK

Statement

The Context Object Specification defines a protocol rather than an SDK.

Rationale

SDKs evolve.

Frameworks evolve.

Programming languages evolve.

Protocols tend to remain stable for decades.

The specification defines:

• object structures
• relationships
• semantics
• compatibility rules

Implementations are expected to follow the specification rather than define it.

Philosophy 5 — AI Is a Consumer, Not the Center

Statement

Artificial Intelligence is one consumer of Context Objects.

It is not the owner of the specification.

Rationale

Although the project originated from AI applications, the Context Object is intentionally designed as a general-purpose representation of user attention.

Potential consumers include:

• AI assistants
• Search engines
• Knowledge systems
• Browser extensions
• Automation workflows
• Multi-agent systems
• IDE tooling
• Analytics engines

The specification therefore avoids assumptions that only apply to AI systems.

4. What This Specification Defines

The Context Object Specification defines:

• how user attention is represented
• how contextual information is organized
• how semantic understanding is attached
• how implementations remain compatible
• how extensions integrate with the core model

The specification intentionally does NOT define:

• LLM APIs
• Prompt templates
• AI providers
• Embedding models
• Vector databases
• Chat history
• Agent orchestration

These concerns belong to higher-level application layers.

5. Long-Term Vision

The long-term vision of the Context Object Specification is to establish a common language for representing user attention across different document types, platforms, and intelligent systems.

Regardless of whether the source is:

• HTML
• Markdown
• PDF
• Office documents
• Rich text editors
• Images
• Future document formats

they should all be capable of producing a compatible Context Object.

Applications consuming Context Objects SHOULD NOT need to understand how the original content was produced.

Instead, they consume a unified representation of context.

6. Design Consequences

The philosophies defined in this chapter have several direct consequences.

1. The specification MUST remain implementation-independent.

2. Every pipeline stage MUST enrich the same Context Object rather than replace it.

3. New document formats SHOULD require adapters rather than changes to the core model.

4. Prompt builders SHOULD be implemented as optional consumers.

5. Extensions MUST NOT modify the semantics of the core specification.

These consequences guide every chapter that follows.

7. Summary

The Context Object Specification is not an AI SDK.

It is not a browser library.

It is not a prompt framework.

It is a protocol for describing user attention in a structured, portable, and extensible manner.

Everything defined in subsequent chapters is expected to follow this philosophy.

This philosophy is considered normative for the entire specification.

Context Object Specification (COS)

Version: 0.2
Chapter: 110 — Vision
Status: Informative
Category: Informative

1. Purpose

This chapter defines the long-term vision of the Context Object Specification (COS).

Unlike the Core Philosophy, which establishes the immutable principles of the specification, the Vision describes the future ecosystem that COS intends to enable.

This chapter is informative rather than normative.

It provides direction for future evolution but does not define implementation requirements.

2. The Missing Layer

Modern AI applications have become increasingly capable of understanding natural language.

However, the information supplied to AI systems has changed very little.

Today, most applications still send isolated fragments of text:

llm(selection.text)

This approach ignores the environment in which the content exists.

It loses information such as:

• document structure
• surrounding paragraphs
• section hierarchy
• semantic meaning
• source metadata
• user focus

As a result, every AI application is forced to reconstruct context independently.

This duplicated effort exists across browsers, editors, PDF viewers, documentation platforms, and countless other applications.

The missing layer is not another AI model.

The missing layer is a standardized representation of contextual information.

The Context Object Specification exists to define that layer.

3. A Shared Language for Context

HTML became successful because it provided a common language for describing documents.

Regardless of which browser rendered the page, the structure remained understandable.

Similarly, JSON became a universal language for structured data exchange.

Applications no longer needed to understand each other’s internal representations.

The Context Object Specification follows the same philosophy.

Rather than describing how a document should be rendered, it describes how a user’s selection should be understood.

Instead of standardizing presentation, it standardizes context.

4. A Future Beyond Plain Text

The future of intelligent software should not depend on plain text alone.

A browser selection contains significantly more information than the visible characters.

Every selection exists within a larger environment.

For example:

• a heading belongs to a section
• a paragraph belongs to an article
• a code fragment belongs to a programming language
• a table belongs to a document
• a citation belongs to a reference

These relationships provide meaning.

Meaning should not be discarded before reaching downstream systems.

The Context Object preserves these relationships in a structured form.

5. A Common Representation

Different applications expose user selections differently.

Examples include:

• Web browsers
• Markdown editors
• Rich text editors
• PDF viewers
• Documentation systems
• Knowledge bases

Although their implementations differ, they all share the same underlying concept:

A user has intentionally selected a portion of information.

The Context Object Specification provides a common representation for that selection.

Applications producing Context Objects SHOULD follow the same structural model regardless of their internal implementation.

Applications consuming Context Objects SHOULD NOT require knowledge of the original source.

6. AI Is Only One Consumer

The Context Object Specification originated from AI-assisted workflows.

However, AI is not the only consumer of contextual information.

The same Context Object can also be consumed by:

• search engines
• workflow systems
• browser extensions
• automation platforms
• knowledge management systems
• developer tools
• document analysis systems

For this reason, the specification intentionally avoids assumptions that only apply to AI models.

Its responsibility is to describe context.

How that context is used is the responsibility of downstream consumers.

7. Interoperability as the Primary Goal

The primary objective of COS is interoperability.

A Context Object generated from one application should be understandable by another application without additional transformation.

For example:

• a browser extension
• a PDF viewer
• a Markdown editor

should all be capable of producing compatible Context Objects.

Consumers should interact with the Context Object rather than implementation-specific APIs.

This separation allows applications to evolve independently while maintaining compatibility.

8. Reference Implementation

The standalone COS Web Adapter is the first reference implementation of the Context Object Specification. It originated in the earlier Selection Ready for AI project and now evolves independently from the specification.

Its responsibilities include:

• extracting browser selections
• constructing Context Objects
• enriching contextual information
• exposing developer-friendly APIs

It does not define the specification.

Instead, it demonstrates one possible implementation.

Future implementations may target different environments while remaining compatible with the same Context Object model.

9. Long-Term Ecosystem

The long-term vision of COS is to establish a shared ecosystem in which contextual information becomes portable.

Instead of exchanging isolated text fragments, applications exchange Context Objects.

Instead of rebuilding contextual understanding for every product, applications reuse a common representation.

Over time, this enables a richer ecosystem of compatible tools, libraries, plugins, and intelligent systems.

The specification does not attempt to replace existing standards.

Instead, it complements them by introducing a standardized description of user selections.

10. Vision Statement

The long-term vision of the Context Object Specification can be summarized as follows:

Define a universal representation of browser selections so that contextual understanding becomes portable, interoperable, and reusable across intelligent systems.

The Context Object Specification is not intended to become another application framework.

Its purpose is to become a common language for contextual information.

11. Summary

The Core Philosophy explains why the specification exists.

The Vision explains what future it intends to create.

Subsequent chapters define how that vision is realized through the Context Object model, pipeline architecture, and extension mechanisms.

Together, these chapters establish the conceptual foundation of the Context Object Specification.

Context Object Specification (COS)

Version: 0.2
Chapter: 120 — Problem Statement
Status: Informative
Category: Informative

1. Purpose

This chapter explains the problems that motivated the creation of the Context Object Specification (COS).

Unlike the Core Philosophy, which defines the guiding principles of the specification, or the Vision, which describes the future ecosystem, this chapter focuses on the limitations of existing approaches.

Understanding these limitations is essential for understanding why a new protocol is necessary.

This chapter is informative.

It does not define requirements.

Instead, it establishes the motivation for the specification.

2. The Current State

Modern browsers already provide mechanisms for obtaining user selections.

Typical examples include:

window.getSelection()

or

Selection.toString()

These APIs are sufficient for retrieving the characters selected by a user.

However, they provide very little information about the selection itself.

Applications typically receive only plain text.

For example:

const text = window.getSelection()?.toString();

Once the text leaves the browser API, almost all contextual information has already been lost.

3. Plain Text Is Not Context

Plain text answers only one question:

What characters were selected?

It does not answer more important questions such as:

• Where does the selection come from?
• What document contains it?
• Which section is it located in?
• Is it code, prose, a heading, or a table?
• What language is it written in?
• What content appears before or after it?
• What surrounding structure gives it meaning?

Without these answers, downstream systems must reconstruct context using incomplete information.

This reconstruction is often inaccurate, expensive, and inconsistent.

4. Every Application Rebuilds Context

Today, every AI-enabled application performs similar work.

Whether the application is:

• a browser extension
• a documentation website
• a PDF viewer
• a note-taking application
• an online editor

the workflow is usually similar.

1. Obtain the selected text.
2. Search for surrounding content.
3. Detect document structure.
4. Determine semantic information.
5. Build prompts.
6. Send data to AI.

Although implementations differ, the underlying process is remarkably similar.

Each product rebuilds the same contextual understanding independently.

This duplication results in:

• repeated engineering effort
• inconsistent behavior
• incompatible data structures
• difficult integration

The industry lacks a common representation for contextual information.

5. Existing Browser APIs Stop Too Early

Browser APIs intentionally provide low-level primitives.

Their responsibility ends once the user’s selection has been identified.

Everything beyond that point is left to individual applications.

For example, browser APIs do not describe:

• document hierarchy
• semantic meaning
• surrounding nodes
• reading order
• contextual relationships
• recommended downstream actions

These responsibilities belong to higher-level software.

The Context Object Specification defines a standard way to represent this higher-level information.

6. AI Applications Need Structure

Large Language Models consume text.

Software applications consume structured data.

When AI becomes part of software systems, both requirements exist simultaneously.

Applications therefore need a representation that is:

• structured
• portable
• deterministic
• extensible

Passing plain text directly into AI models tightly couples applications to prompt engineering.

Instead, applications should first produce a structured representation.

Prompt generation becomes a separate concern.

This separation improves interoperability and long-term maintainability.

7. The Missing Standard

Many standards already exist.

Examples include:

These standards successfully describe documents.

None of them describe the contextual meaning of a user’s current selection.

Consequently, every application invents its own representation.

The result is fragmentation.

The Context Object Specification addresses this gap.

8. Context Should Be Portable

A browser extension and a PDF viewer may implement completely different technologies.

However, if a user selects the same paragraph, downstream consumers should not care how that selection was produced.

They should receive the same contextual representation.

This portability allows:

• reusable AI integrations
• reusable workflow engines
• reusable automation
• reusable plugins
• reusable prompt adapters

Portability is impossible without a shared representation.

9. Why Another Protocol?

The purpose of COS is not to replace existing standards.

Existing standards already solve different problems.

Instead, COS introduces a new layer.

Browser APIs
        │
        ▼
Selection
        │
        ▼
Context Object
        │
        ▼
AI / Search / Workflow / Automation

The Context Object acts as a bridge between low-level browser interactions and higher-level intelligent systems.

Without this intermediate layer, every application must repeatedly solve the same problem.

10. Design Implications

The problems described in this chapter directly influence the design of the specification.

Therefore:

• Context MUST be represented as structured data.
• Browser APIs MUST remain implementation details.
• AI models MUST remain consumers rather than producers.
• Prompt generation SHOULD remain outside the core protocol.
• Context Objects SHOULD be portable across applications.

These implications are explored in subsequent chapters.

11. Summary

The Context Object Specification does not exist because browsers cannot obtain selections.

Browsers already solve that problem.

The specification exists because software lacks a standard representation of contextual understanding.

The missing capability is not text extraction.

The missing capability is context representation.

The Context Object Specification defines that representation.

Context Object Specification (COS)

Version: 0.2
Chapter: 130 — Terminology
Status: Normative
Category: Normative

1. Purpose

This chapter defines the normative terminology used throughout the Context Object Specification (COS).

Every capitalized term defined in this chapter has a specific meaning within the protocol.

Unless otherwise stated, implementations, documentation, plugins, and future specifications MUST use these terms consistently.

The terminology defined here serves as the common language shared by Producers, Consumers, Adapters, Plugins, and future implementations.

2. Terminology Conventions

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

Unless explicitly redefined, each term has exactly one meaning within the Context Object Specification.

Implementations SHOULD avoid introducing alternative names for existing concepts.

For example, if the specification defines the term Selection, implementations SHOULD NOT replace it with:

• Highlight
• Selected Text
• User Highlight
• Current Selection

Consistency of terminology is considered essential for interoperability.

3. Selection

Definition

A Selection is the portion of content explicitly chosen by a user within a supported environment.

In Version 1.x of the specification, the Selection is the primary source from which a Context Object is constructed.

Motivation

A Selection represents the starting point of contextual understanding.

The protocol does not attempt to describe the entire document.

Instead, it begins with the information intentionally selected by the user.

Normative Requirements

A Selection MUST represent a single continuous user interaction.

A Selection MUST NOT contain inferred semantic information.

Semantic understanding belongs to later stages of the Pipeline.

Related Terms

• Context
• Target
• Pipeline

4. Context

Definition

Context is the collection of information that explains the meaning of a Selection.

Context extends beyond the selected content itself.

Examples include:

• surrounding content
• document hierarchy
• semantic information
• metadata
• structural relationships

Motivation

Without Context, identical selections may have completely different meanings.

The purpose of the protocol is to standardize the representation of Context.

Normative Requirements

Context MUST always be represented as structured data.

Context MUST NOT rely solely on plain text.

5. Context Object

Definition

A Context Object (CO) is the standardized representation of a Selection together with its associated Context.

It is the primary data structure defined by this specification.

Motivation

Rather than exchanging isolated text fragments, applications exchange Context Objects.

This allows contextual understanding to become portable across implementations.

Normative Requirements

Every Context Object MUST conform to the schema defined in Chapter 200.

Context Objects MUST remain implementation-independent.

6. Pipeline

Definition

A Pipeline is the ordered sequence of processing stages that transforms a Selection and its associated Document into a Context Object.

Motivation

Building contextual understanding requires multiple independent steps.

The Pipeline separates these responsibilities into predictable stages.

Normative Requirements

Pipeline stages MUST execute in the order defined by the specification.

Each stage MUST enrich the same ContextState during Pipeline execution.

Pipeline stages MUST NOT replace previously generated information unless explicitly permitted.

7. Stage

Definition

A Stage is an individual processing step within a Pipeline.

Each Stage has a clearly defined responsibility.

Examples include:

• Extract
• Normalize
• Enrich
• Analyze
• Recommend

Normative Requirements

Each Stage SHOULD perform one logical responsibility.

Stages SHOULD NOT duplicate work performed by earlier stages.

8. Producer

Definition

A Producer is any implementation capable of generating a Context Object.

Examples include:

• Browser SDK
• PDF SDK
• Markdown SDK
• Rich Text SDK

Motivation

Different environments may produce Context Objects through different implementations while remaining compatible with the same protocol.

Normative Requirements

Every Producer MUST generate a valid Context Object.

A Producer MAY implement only a subset of optional capabilities.

9. Consumer

Definition

A Consumer is any system that receives and uses a Context Object.

Examples include:

• AI assistants
• Search engines
• Workflow systems
• Browser extensions
• Knowledge platforms

Motivation

The protocol intentionally separates Context production from Context consumption.

Normative Requirements

Consumers SHOULD rely only on the standardized Context Object.

Consumers SHOULD NOT depend on implementation-specific metadata.

10. Adapter

Definition

An Adapter is a component responsible for converting implementation-specific data into protocol-compatible input.

Examples include:

• HTML Adapter
• PDF Adapter
• Markdown Adapter
• Editor Adapter

Motivation

Adapters isolate implementation differences from the core protocol.

Normative Requirements

Adapters MUST preserve the meaning of the original Selection.

Adapters MUST NOT modify protocol semantics.

11. Semantic

Definition

Semantic information describes the machine-understandable meaning of a Selection.

Examples include:

• code
• table
• heading
• citation
• formula

Motivation

Semantic understanding enables downstream systems to reason about content without re-analyzing raw text.

Normative Requirements

Semantic information MUST be generated independently of presentation.

Semantic information SHOULD remain deterministic whenever possible.

12. Hierarchy

Definition

Hierarchy describes the structural position of a Selection within its parent document.

Examples include:

• document
• section
• heading
• paragraph
• list
• table

Motivation

Hierarchy provides structural meaning beyond the selected text itself.

Normative Requirements

Hierarchy SHOULD describe logical structure rather than visual layout.

13. Recommendation

Definition

A Recommendation is a suggested downstream action derived from the current Context.

Examples include:

• Explain
• Translate
• Summarize
• Optimize
• Review

Motivation

Recommendations improve user experience while remaining independent from AI implementations.

Normative Requirements

Recommendations MUST remain optional.

Recommendations MUST NOT execute actions directly.

14. Metadata

Definition

Metadata describes information about how a Context Object was generated.

Typical metadata includes:

• producer
• version
• timestamp
• source type

Normative Requirements

Metadata MUST describe the generation process rather than document content.

15. Extension

Definition

An Extension is an optional protocol component that augments the Context Object without modifying the core specification.

Examples include:

• PDF extensions
• Markdown extensions
• Code extensions
• Table extensions

Motivation

Extensions allow innovation while preserving compatibility.

Normative Requirements

Extensions MUST NOT redefine existing protocol semantics.

Extensions SHOULD use namespaced identifiers.

16. Relationship Between Terms

The following conceptual relationships exist among the core terminology.

Selection
     │
     ▼
Pipeline
     │
     ▼
Context Object
     │
     ├────────► Consumer
     │
     └────────► Extension

Producer
     │
     └────────► Pipeline

Adapter
     │
     └────────► Producer

These relationships are informative and intended to assist understanding of the protocol architecture.

17. Summary

The terminology defined in this chapter establishes the shared vocabulary of the Context Object Specification.

Subsequent chapters MUST use these definitions consistently.

Implementations SHOULD adopt these terms directly in documentation, APIs, and architectural discussions whenever practical.

Context Object Specification (COS)

Version: 0.2
Chapter: 140 — Design Principles
Status: Normative
Category: Normative

1. Purpose

This chapter defines the normative design principles of the Context Object Specification (COS).

These principles establish the constraints under which all future components of the specification MUST be designed.

They serve as the constitutional layer of the protocol.

Any contradiction between implementation details and these principles MUST be resolved in favor of this chapter.

2. Protocol First Principle

Statement

The Context Object Specification is a protocol, not a software library.

Requirement

All design decisions MUST prioritize protocol stability over implementation convenience.

Implications

• SDKs are secondary artifacts.
• Interfaces are derived from the protocol.
• No implementation detail SHOULD influence the core model.

3. Structure First Principle

Statement

Structured data is the primary representation of context.

Requirement

All contextual information MUST be represented as structured data before any transformation into prompts or natural language.

Implications

• Prompt engineering is an output concern, not a core concern.
• Text-only representations are insufficient as a protocol foundation.

4. Incremental Enrichment Principle

Statement

The runtime ContextState is progressively enriched, not replaced.

Requirement

Each Pipeline stage MUST only add or refine information in ContextState.

A stage MUST NOT replace or invalidate previously established fields unless explicitly defined.

Implications

• ContextState evolves step-by-step during Pipeline execution.
• A finalized Context Object is the immutable published result of a ContextState version.
• No stage is allowed to “rebuild” the object from scratch.
• Data integrity across stages is required.

5. Implementation Independence Principle

Statement

The specification MUST remain independent of any implementation technology.

Requirement

The following MUST NOT appear in the core specification:

• Framework-specific APIs
• UI libraries
• Rendering engines
• AI providers
• Runtime environments

Implications

The protocol MUST be implementable in:

• browsers
• servers
• editors
• CLI tools
• embedded systems

6. Deterministic Output Principle

Statement

Given the same input, the system SHOULD produce the same Context Object.

Requirement

Pipeline behavior SHOULD be deterministic unless explicitly marked as non-deterministic.

Implications

• Debuggability is a first-class concern.
• Randomness MUST NOT affect core structural fields.

7. Extensibility Principle

Statement

The protocol MUST support extension without modifying the core specification.

Requirement

Extensions MUST:

• be namespaced
• not modify core fields
• not override semantic meaning of existing fields

Implications

• New domains (PDF, Markdown, Code, etc.) are handled via extensions.
• Core model remains stable across versions.

8. Portable Context Principle

Statement

A Context Object MUST be portable across systems.

Requirement

A Context Object generated in one environment SHOULD be consumable in another without transformation of meaning.

Implications

• Producers and Consumers are decoupled.
• Transport format is irrelevant to semantics.

9. Semantic Over Presentation Principle

Statement

The specification MUST prioritize semantic meaning over visual representation.

Requirement

The Context Object MUST NOT encode presentation-level concerns such as:

• CSS styles
• UI layout
• rendering decisions

Implications

• Hierarchy represents logical structure, not visual appearance.
• Semantic interpretation is preferred over formatting signals.

10. Minimal Core Principle

Statement

The core specification MUST remain minimal and stable.

Requirement

Only concepts that are universally applicable across all Producers and Consumers MAY be included in the core model.

Implications

• Domain-specific features belong to Extensions.
• The core model MUST resist feature inflation.

11. AI is a Consumer, Not a Driver Principle

Statement

Artificial Intelligence systems are Consumers of Context Objects, not the authority defining them.

Requirement

The specification MUST NOT be shaped by model-specific behaviors.

Implications

• Prompt formats MUST NOT influence core schema design.
• AI capabilities MUST NOT dictate structural decisions.

12. Draft Simplicity Principle

Statement

Before first public release, the specification MUST prefer simplicity over preserving unused draft structures.

Requirement

• Fields that do not serve Consumer understanding SHOULD be removed.
• Duplicated structures SHOULD be collapsed.
• Draft structures SHOULD NOT be retained only because they appeared in an earlier draft.

Implications

• The pre-release specification can change shape while the first-principle purpose remains stable.
• The first released object should be concise, clear, and useful.

13. System Boundaries Principle

Statement

The Context Object Specification defines boundaries between systems.

Requirement

The specification MUST clearly separate:

• Producers (generate context)
• Consumers (use context)
• Adapters (translate input sources)
• Pipeline (process context)
• Extensions (enhance capabilities)

Implications

Cross-responsibility coupling MUST be avoided.

14. Summary

The Design Principles defined in this chapter are normative constraints that govern the entire Context Object Specification.

All future chapters, implementations, and extensions MUST conform to these principles.

If a design decision violates any principle in this chapter, the design MUST be reconsidered.

Context Object Specification (COS)

Version: 0.2
Chapter: 200 — Context Object
Status: Normative
Category: Core Model

1. Purpose

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

The Context Object is the portable data object handed from a Producer to a Consumer.

Its purpose is simple:

Preserve what the user selected, where it came from, and the minimum source-grounded context needed to use it correctly.

2. First Principle

COS exists because raw selected text is not enough.

Raw selected text answers only:

What characters did the user select?

A Context Object answers:

• what was selected
• where it came from
• what local context surrounds it
• what deterministic relationships make it meaningful

COS MUST optimize for Consumer usefulness, not protocol ceremony.

3. Definition

A Context Object is a JSON-compatible object representing a user Selection together with source and context.

It MUST be:

• concise
• deterministic
• source-grounded
• easy for Consumers to read
• independent of UI rendering and AI prompt formats

It MUST NOT include:

• prompt text
• generated answers
• reasoning chains
• execution plans
• UI state
• inferred user intent

4. Lean Core Model

COS v0.2 defines the following lean core shape:

interface ContextObject {
  version: "0.2";
  source: SourceContext;
  selection: Selection;
  context: Context;
  meta?: Meta;
  extensions?: ExtensionEntry[];
}

The core object intentionally has few top-level fields.

Top-level fields SHOULD NOT duplicate the same source, structure, or lifecycle information in multiple places.

5. Source

source describes the origin of the selected content.

interface SourceContext {
  type: "webpage" | "pdf" | "markdown" | "editor" | "richtext" | "unknown";
  id?: string;
  uri?: string;
  title?: string;
  app?: string;
  language?: string;
}

source is the single place for origin information in the emitted Context Object.

Consumers SHOULD use source to answer:

Where did this selected content come from?

6. Selection

selection describes the exact user-selected text and optional range.

interface Selection {
  text: string;
  range?: SelectionRange;
}

Selection MUST preserve the selected text as observed by the Producer.

Selection SHOULD NOT carry duplicated source metadata. Source belongs to the top-level source field.

7. Context

context describes the source-grounded local context that makes the Selection usable.

interface Context {
  scope: "inline" | "container" | "multi-container";
  segments: ContextSegment[];
  relations?: ContextRelation[];
}

context.segments is the primary context surface for Consumers.

Each segment describes one logical source container covered by the Selection.

context.relations describes deterministic relationships that apply to the whole Selection or summarize covered relationships.

The normative definition of Context is provided in Chapter 225.

8. Meta

meta describes minimal system-level information about object generation.

interface Meta {
  createdAt?: number;
  adapter?: string;
  stages?: string[];
}

COS v0.2 keeps meta intentionally small.

createdAt is the number of milliseconds since the Unix epoch, equivalent to JavaScript Date.now().

stages MAY list the minimal generation stages that contributed to the object, such as selection, source, context, and relations.

Detailed pipeline traces, integrity hashes, and debug data SHOULD be placed in Extensions unless a Consumer explicitly requires them.

9. Extensions

extensions provide platform-specific or implementation-specific data.

Examples:

• browser DOM path
• selected HTML
• PDF coordinates
• editor block IDs
• debug pipeline trace

Extensions MUST NOT be required to understand the core Context Object.

10. Output Shape Rule

The emitted COS v0.2 object MUST use only the lean top-level fields defined in this chapter:

version
source
selection
context
meta?
extensions?

Supporting concepts in later chapters explain how Producers derive these fields.

They MUST NOT introduce additional top-level domains.

This keeps the emitted object easy to consume without cross-field joins.

11. Example: Table Cell

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Product Table",
    "uri": "about:srcdoc"
  },
  "selection": {
    "text": "$19"
  },
  "context": {
    "scope": "container",
    "segments": [
      {
        "id": "cell-1",
        "type": "table",
        "text": "$19",
        "selectedText": "$19",
        "relations": [
          { "type": "column_header", "label": "Base price" },
          { "type": "row_header", "label": "Starter" }
        ]
      }
    ]
  },
  "meta": {
    "adapter": "web-adapter"
  }
}

12. Example: Multi-Container Selection

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Mixed Article"
  },
  "selection": {
    "text": "adapter should preserve nearby context...\nSelections can begin..."
  },
  "context": {
    "scope": "multi-container",
    "segments": [
      {
        "id": "p1",
        "type": "paragraph",
        "text": "The adapter should preserve nearby context without turning the selection into a prompt.",
        "selectedText": "adapter should preserve nearby context without turning the selection into a prompt.",
        "beforeText": "The "
      },
      {
        "id": "li1",
        "type": "list",
        "text": "Selections can begin in ordinary prose.",
        "selectedText": "Selections can begin in ordinary prose."
      }
    ],
    "relations": [
      { "type": "section", "label": "Pricing Rules" }
    ]
  }
}

13. Consumer Rule

Consumers SHOULD be able to use a Context Object by reading only:

source
selection.text
context.segments
context.relations

If a Consumer must inspect Extensions to understand the selected content, the Producer has failed to provide sufficient core context.

14. Summary

The Context Object is not a protocol showcase.

It is the smallest useful object that lets Consumers understand selected content without guessing.

Context Object Specification (COS)

Version: 0.2
Chapter: 210 — Selection
Status: Normative
Category: Core Model

1. Purpose

This chapter defines the abstract concept of Selection within the Context Object Specification (COS).

Selection is the primary input signal of the protocol and serves as the origin point for Context Object generation.

This chapter redefines Selection as a protocol-level concept, independent of any browser or UI implementation.

2. Conceptual Shift

In traditional browser environments, Selection refers to a DOM-based API:

window.getSelection()

Within COS, this interpretation is insufficient.

The protocol redefines Selection as:

A structured representation of an explicit focus signal within a content environment.

This shift separates Selection from any specific runtime implementation.

3. Definition

A Selection is an explicit, source-bounded focus region that serves as the input anchor for Context Object generation.

A Selection represents intentional focus, not just raw text extraction.

4. Selection vs Raw Text

A Selection is NOT equivalent to extracted text.

Raw text only represents character data:

"useEffect"

A Selection includes additional conceptual attributes:

• origin context
• structural position
• content boundaries
• interaction metadata (optional)

The protocol distinguishes between:

5. Selection Characteristics

A valid Selection MUST satisfy the following properties:

5.1 Bounded

A Selection MUST have clearly defined start and end boundaries within a content source.

5.2 Explicit

A Selection MUST represent an explicit focus signal exposed by the source environment or deliberately supplied by a Producer.

A Producer MUST NOT create a Selection by inferring focus from content alone. Human text selection, an explicit programmatic focus request, and an explicitly identified AI-generated text focus MAY qualify when their non-empty text, boundaries, and source are known. A collapsed cursor with no selected text is not a COS v0.2 Selection.

5.3 Source-Linked

A Selection MUST be associated with the Context Object’s top-level source.

Selection itself SHOULD NOT duplicate source details.

6. Selection Scope (v0.2)

In version 0.2 of COS:

The Selection concept is scoped to:

• text-based content environments
• browser-based interfaces
• document-like structures

Supported environments include:

• Web pages
• Markdown documents
• Rich text editors
• PDF viewers (via adapter)

Unsupported (future extensions):

• voice input
• gaze tracking
• full-screen vision context
• autonomous agent attention models

7. Selection Structure (Conceptual Model)

A Selection is conceptually defined as:

interface Selection {
  text: string;
  range?: SelectionRange;
}

This structure is conceptual and may be adapted by different Producers.

8. Selection Range

A Selection Range defines the boundaries of the selection.

interface SelectionRange {
  startOffset: number;
  endOffset: number;
  startNodeId?: string;
  endNodeId?: string;
  direction?: "forward" | "backward" | "unknown";
}

Range is defined relative to logical content nodes, not visual rendering.

Offsets MUST count UTF-16 code units in the referenced logical node’s text, matching DOM Range offsets for text nodes. Adapters for sources with different native coordinate systems MUST convert their offsets or preserve native coordinates in an Extension.

Producers SHOULD include range when the source supports stable range extraction.

When range is omitted, Consumers can still read selection.text and context.segments, but they may not be able to precisely locate the original selection inside the source.

For single-node selections, startNodeId and endNodeId MAY be identical or omitted when the source context makes the node unambiguous.

For cross-node selections, startNodeId and endNodeId MUST identify the logical content nodes that contain the start and end offsets.

When both offsets refer to the same logical node, endOffset MUST be greater than or equal to startOffset.

Cross-node range ordering MUST follow a deterministic logical source order defined by the Producer. Implementing or serializing the supporting Document Hierarchy model is not required.

9. Source Separation

Selection MUST NOT duplicate full source metadata in COS v0.2 lean core.

The origin of the Selection is represented by the top-level source field of the Context Object.

Selection range node identifiers MAY reference context segment identifiers.

10. Selection Metadata

Selection-specific metadata is not part of the lean core Selection object.

If a Producer needs to preserve interaction metadata, it SHOULD place it in meta or an Extension.

Examples:

• timestamp of selection
• user interaction type
• device context
• input modality

Metadata MUST NOT alter the meaning of Selection.

11. Selection Lifecycle

A Selection exists at the moment an explicit focus signal is established:

Explicit Focus Signal
    ↓
Selection Created
    ↓
Context Pipeline Starts
    ↓
Selection Transformed into Context Object

Selection is not persistent in the protocol layer.

Only Context Objects are persisted and transported.

12. Relationship to Context Object

Selection is the input primitive of the Context Object.

Transformation rule:

Selection → Context Enrichment Pipeline → Context Object

A Context Object cannot exist without an originating Selection (within v0.2 scope).

13. Design Constraints

A Selection MUST NOT:

• contain semantic interpretation
• contain inferred meaning
• include AI-generated enrichment
• include structural hierarchy data

These responsibilities belong to later pipeline stages.

14. Implementation Independence

Although Selection is inspired by browser APIs, the protocol does NOT depend on:

• DOM Selection API
• Range API
• UI rendering systems

Any system capable of producing equivalent structured input MAY implement Selection.

15. Example (Informative)

{
  "text": "useEffect",
  "range": {
    "startOffset": 120,
    "endOffset": 129,
    "startNodeId": "code-1",
    "endNodeId": "code-1",
    "direction": "forward"
  }
}

Source information belongs to the containing Context Object’s top-level source. Interaction-specific data belongs in meta when it fits the lean model, or in an Extension.

16. Summary

Selection is the minimal input primitive of the Context Object Specification.

It represents an explicit, source-bounded focus within a content environment.

It is deliberately kept minimal to ensure that all semantic understanding is deferred to the Context Object Pipeline.

Selection exists only as an input signal.

Context Object is where meaning begins.

Context Object Specification (COS)

Version: 0.2
Chapter: 220 — Document
Status: Informative — Supporting
Category: Core Model

1. Purpose

This chapter defines the abstract concept of a Document within the Context Object Specification (COS).

A Document represents the structural and logical container in which a Selection exists.

It provides the spatial, hierarchical, and semantic boundary for contextual interpretation.

2. Conceptual Role

A Document is the source environment of a Selection.

While Selection represents user intent, Document represents contextual space.

Without Document, a Selection has no meaningful interpretation.

3. Definition

A Document is a structured content container that provides:

• structural hierarchy
• logical segmentation
• content continuity
• reference boundaries for Selection

A Document is NOT a rendering artifact.

It is a logical representation of content space.

4. Document vs File vs Page

A Document MUST NOT be confused with physical or storage-level concepts.

A Document MAY be derived from files or pages, but is not equivalent to them.

5. Document Scope

In COS v0.2, a Document MAY originate from:

• Web pages (HTML documents)
• Markdown files
• PDF documents
• Rich text editors
• Documentation systems

Future extensions MAY include:

• database records
• knowledge graphs
• agent-generated content spaces

6. Relationship to Lean Core

In COS v0.2 lean core, Document is a supporting concept rather than a required top-level field.

Producer implementations MAY use an internal Document model to derive:

• top-level source
• context.segments
• context.relations
• stable segment identifiers

The emitted Context Object SHOULD NOT duplicate a full Document tree unless a Consumer explicitly needs it.

7. Document Structure (Conceptual Model)

When an implementation needs a Document model, it MAY use:

interface Document {
  id: string;
  type: DocumentType;
  title?: string;
  content: ContentNode;
  structure: DocumentStructure;
  metadata?: DocumentMetadata;
}

This definition is conceptual and independent of implementation.

8. Document Type

A Document MUST declare its type:

type DocumentType =
  | "webpage"
  | "pdf"
  | "markdown"
  | "editor"
  | "richtext";

Document type influences interpretation strategies in later Pipeline stages.

9. Content Model

A Document contains structured content represented as nodes.

interface ContentNode {
  type: string;
  text?: string;
  children?: ContentNode[];
}

This structure enables hierarchical traversal.

10. Document Structure

The Document structure represents logical organization.

It defines how content is organized into meaningful hierarchical units.

interface DocumentStructure {
  sections?: Section[];
  hierarchyDepth: number;
}

Structure is independent of visual layout.

10.1 Document Metadata

Definition

DocumentMetadata describes non-semantic information about a Document.

It does NOT describe content meaning.

It only describes origin, lifecycle, and system-level attributes.

Conceptual Model

interface DocumentMetadata {
  source: DocumentSource;
  createdAt?: number;
  updatedAt?: number;
  language?: string;
  version?: string;
}

Document Source

interface DocumentSource {
  type: "webpage" | "pdf" | "markdown" | "editor" | "unknown";
  uri?: string;
}

Constraints

DocumentMetadata MUST NOT contain:

• semantic interpretation of content
• structural hierarchy information
• selection-related data
• AI-generated reasoning

Motivation

Metadata exists to ensure:

• traceability
• reproducibility
• system-level observability

It is strictly non-semantic.

11. Relationship to Selection

A Producer MAY maintain an internal Document model when the source has reusable logical structure. The emitted Selection is linked to its origin by the Context Object’s top-level source field and does not require a serialized Document.

Relationship:

Document
   │
   ├── contains
   ▼
Selection

A Selection without a Document is invalid within COS.

11.1 Selection Anchor References

A Document SHOULD expose stable logical content identifiers that can be referenced by Selection ranges and Hierarchy nodes.

These identifiers allow Consumers to locate the selected region from either direction:

• from Selection to Document, through source.id and range node identifiers
• from Document to Selection, through matching logical content node identifiers

The Document itself MUST NOT embed user Selection state.

Selection state belongs to the Context Object lifecycle, not to the source Document.

12. Document Immutability Principle

A Document SHOULD be treated as immutable during a Pipeline execution.

If modifications are required:

• a new Document instance MUST be created
• existing Selection references MUST remain valid

13. Document as Context Space

A Document defines the contextual boundary for interpretation.

It provides:

• local meaning scope
• hierarchical relationships
• semantic grouping

Without Document, semantic inference becomes undefined.

14. Document vs Context Object

It is critical to distinguish:

Flow:

Document → Selection → Context Object

15. Implementation Independence

A Document is NOT tied to any specific format:

• HTML DOM is NOT required
• File system structure is NOT required
• Rendering engine is NOT required

Any system capable of representing hierarchical content MAY implement a Document.

16. Example (Informative)

{
  "id": "doc-123",
  "type": "markdown",
  "title": "React Hooks Guide",
  "content": {
    "type": "root",
    "children": [
      {
        "type": "paragraph",
        "text": "useEffect is a React Hook..."
      }
    ]
  },
  "structure": {
    "hierarchyDepth": 3
  },
  "metadata": {
    "author": "example"
  }
}

17. Design Notes (Informative)

Document is intentionally defined in a minimal form.

The goal is not to replicate DOM or file systems.

Instead, it defines a portable semantic container that can be adapted across environments.

18. Summary

A Document is the logical content space in which a Selection exists.

It provides structural and semantic boundaries necessary for contextual interpretation.

Within the Context Object Specification, Document is the foundational spatial abstraction that enables meaningful enrichment in later pipeline stages.

Context Object Specification (COS)

Version: 0.2
Chapter: 225 — Context
Status: Normative
Category: Core Model

1. Purpose

This chapter defines the Context field of the COS v0.2 lean Context Object.

Context is the main surface a Consumer reads after Selection.

It answers:

What source-grounded information makes this selected text usable?

2. Definition

Context is a deterministic representation of the local source containers and relationships covered by a Selection.

interface Context {
  scope: ContextScope;
  segments: ContextSegment[];
  relations?: ContextRelation[];
}

Context MUST be derived from source structure or explicit source metadata.

Context MUST NOT be generated from model inference or guessed user intent.

3. Context Scope

type ContextScope =
  | "inline"
  | "container"
  | "multi-container";

inline means the Selection is inside one logical container but does not cover the whole container.

container means the Selection corresponds to one logical container.

multi-container means the Selection spans more than one logical container.

4. Context Segment

A Context Segment represents one logical source container relevant to the Selection.

interface ContextSegment {
  id?: string;
  type: ContextSegmentType;
  text: string;
  selectedText?: string;
  beforeText?: string;
  afterText?: string;
  role?: ContextRole;
  relations?: ContextRelation[];
}

text is the full local container text.

selectedText is the selected portion inside this segment.

beforeText and afterText describe deterministic text before and after selectedText inside the same segment.

A segment that intersects the Selection MUST include non-empty selectedText. Context-only segments MUST omit selectedText. Selected portions in source order MUST correspond to selection.text under the source’s documented text serialization; Producers MUST NOT rewrite or summarize them.

When beforeText, selectedText, and afterText are all present, their concatenation MUST equal text.

For multi-container selections, Producers SHOULD emit one segment per covered logical container in document order.

5. Segment Type

type ContextSegmentType =
  | "text"
  | "paragraph"
  | "heading"
  | "list"
  | "table"
  | "code"
  | "quote"
  | "formula"
  | "unknown";

Segment type is a deterministic structural classification.

It replaces the need for a separate top-level Semantic object in the common case.

6. Segment Role

type ContextRole =
  | "definition"
  | "reference"
  | "output"
  | "code_snippet";

Role is optional.

Role MUST be emitted only when a strong source signal exists.

Examples:

• HTML dfn MAY produce definition
• HTML cite or links MAY produce reference
• HTML output or samp MAY produce output
• Code containers MAY produce code_snippet

Producers SHOULD omit role rather than guess.

7. Context Relation

Context Relation describes deterministic relationships.

interface ContextRelation {
  type: ContextRelationType;
  label?: string;
  value?: string;
  targetId?: string;
}

type ContextRelationType =
  | "container"
  | "section"
  | "row_header"
  | "column_header"
  | "label"
  | "list_item";

Relations MAY appear:

• on context.relations, when the relationship applies to the whole Selection
• on segment.relations, when the relationship applies to one segment

8. Relation Rules

Relations MUST be deterministic.

Valid sources include:

• table headers
• list item position
• section headings
• form labels
• description list terms
• explicit adapter metadata

Invalid sources include:

• keyword matching alone
• visual proximity without source structure
• language-specific wording alone
• inferred user intent

9. Minimum Useful Context

A valid Context SHOULD include enough information for a Consumer to avoid treating selection.text as isolated text.

For a word in a paragraph:

• segment text
• selected text
• before/after text when useful

For a table cell:

• cell text
• row and column header relations when available

For a multi-container selection:

• one segment per covered container
• common section relation when available

10. Example: Word in Paragraph

{
  "scope": "inline",
  "segments": [
    {
      "id": "p1",
      "type": "paragraph",
      "text": "The adapter should preserve nearby context without turning the selection into a prompt.",
      "selectedText": "nearby",
      "beforeText": "The adapter should preserve ",
      "afterText": " context without turning the selection into a prompt."
    }
  ]
}

11. Example: Table Cell

{
  "scope": "container",
  "segments": [
    {
      "id": "price-cell",
      "type": "table",
      "text": "$19",
      "selectedText": "$19",
      "relations": [
        { "type": "column_header", "label": "Base price" },
        { "type": "row_header", "label": "Starter" }
      ]
    }
  ]
}

12. Example: Multi-Container Selection

{
  "scope": "multi-container",
  "segments": [
    {
      "id": "p1",
      "type": "paragraph",
      "text": "The adapter should preserve nearby context without turning the selection into a prompt.",
      "selectedText": "adapter should preserve nearby context without turning the selection into a prompt.",
      "beforeText": "The "
    },
    {
      "id": "li1",
      "type": "list",
      "text": "Selections can begin in ordinary prose.",
      "selectedText": "Selections can begin in ordinary prose."
    },
    {
      "id": "li2",
      "type": "list",
      "text": "They can cross list items and code blocks.",
      "selectedText": "They can cross list items and code ",
      "afterText": "blocks."
    }
  ],
  "relations": [
    { "type": "section", "label": "Pricing Rules" }
  ]
}

13. Summary

Context is the heart of COS v0.2.

Selection tells Consumers what text was selected.

Context tells Consumers why that text is usable.

Context Object Specification (COS)

Version: 0.2
Chapter: 230 — Hierarchy
Status: Informative — Supporting
Category: Core Model

1. Purpose

This chapter defines the Hierarchy Model within a Document in the Context Object Specification (COS).

Hierarchy describes how content is structurally organized and how meaning is distributed across nested units of a Document.

This model is independent of visual layout and rendering systems.

2. Conceptual Role

Hierarchy represents the structural skeleton of a Document.

If:

• Document defines the space
• Content defines the material

Then:

Hierarchy defines the structure of meaning within that space.

3. Definition

A Hierarchy is a tree-structured representation of logical content organization inside a Document.

It defines:

• containment relationships
• structural nesting
• logical segmentation

Hierarchy does NOT define:

• visual appearance
• layout rules
• rendering behavior

4. Core Principle

Hierarchy in COS is:

Logical Structure, not Visual Structure

This distinction is fundamental.

A visually similar layout MAY represent different hierarchy.

A structurally identical hierarchy MAY render differently.

5. Hierarchy Model (Conceptual)

A Document Hierarchy is defined as a tree:

interface Hierarchy {
  root: HierarchyNode;
}

6. Hierarchy Node

A Hierarchy Node represents a structural unit in a Document.

interface HierarchyNode {
  id: string;
  type: HierarchyType;
  title?: string;
  children?: HierarchyNode[];
  parentId?: string;
  depth: number;
}

7. Hierarchy Type

Hierarchy nodes MUST declare their type:

type HierarchyType =
  | "document"
  | "section"
  | "subsection"
  | "paragraph"
  | "list"
  | "table"
  | "codeblock";

This type represents logical role, not rendering format.

8. Tree Structure Constraint

Hierarchy MUST form a strict tree structure.

Rules:

• Each node MAY have only one parent
• Root node MUST be unique
• Cycles are NOT allowed
• Depth MUST be deterministic

9. Relationship to Document

Hierarchy is a sub-component of Document:

Document
   │
   └── Hierarchy
          │
          └── Nodes (Tree)

When an implementation uses this conceptual model, a Document SHOULD contain one Hierarchy root.

10. Relationship to Selection

A Selection MAY reference logical node identifiers supplied by an internal Hierarchy. Exchange-format conformance does not require a serialized Hierarchy.

A Selection is always anchored to a Hierarchy Node.

This ensures:

• structural traceability
• semantic consistency
• reproducible context extraction

11. Structural vs Semantic Separation

Hierarchy defines structure only.

It does NOT define meaning.

Example:

A section node:

• defines grouping
• does NOT define semantic interpretation

Semantic meaning is handled in Chapter 240.

12. Depth Semantics

Depth represents structural nesting level.

Rules:

• root depth = 0
• children increment depth by 1
• depth MUST be consistent across traversal

Depth is used for:

• structural reasoning
• context expansion
• selection anchoring

13. Hierarchy Integrity Rules

A valid Hierarchy MUST satisfy:

• single root node
• acyclic structure
• consistent parent-child relationships
• deterministic traversal order

14. Immutability Principle

Hierarchy MUST NOT change during a Pipeline execution.

If modification is required:

• a new Hierarchy MUST be created
• existing Selection references MUST remain valid

15. Informal Example

{
  "root": {
    "id": "doc-root",
    "type": "document",
    "depth": 0,
    "children": [
      {
        "id": "sec-1",
        "type": "section",
        "title": "Introduction",
        "depth": 1,
        "children": [
          {
            "id": "p-1",
            "type": "paragraph",
            "depth": 2
          }
        ]
      }
    ]
  }
}

16. Design Notes

Hierarchy is intentionally strict to ensure:

• predictable traversal
• stable Selection mapping
• deterministic Context Object generation

Although real-world documents may behave like graphs, COS enforces a tree model in v0.2 for simplicity and consistency.

Future versions MAY extend this to graph-based relationships, cross-references, citations, footnotes, and other non-tree structural links.

17. Summary

Hierarchy defines the structural organization of a Document.

It provides the backbone for Selection anchoring and later semantic interpretation.

Within the Context Object Specification, Hierarchy is the bridge between raw document space and semantic understanding.

Context Object Specification (COS)

Version: 0.2
Chapter: 235 — Association
Status: Informative — Supporting
Category: Core Model

1. Purpose

This chapter defines association guidance for COS v0.2.

In the lean core object, association is not a separate top-level field.

Association is represented as:

• context.relations
• context.segments[].relations

2. First Principle

Association exists to answer:

What deterministic source relationship makes this selected text meaningful?

Examples:

• a table value belongs to a column header
• a table value belongs to a row header
• a value belongs to a label
• a selected paragraph belongs to a section
• a selected item belongs to a list position

Association MUST be source-grounded.

Association MUST NOT guess user intent.

3. Relation Model

interface ContextRelation {
  type: ContextRelationType;
  label?: string;
  value?: string;
  targetId?: string;
}

type ContextRelationType =
  | "container"
  | "section"
  | "row_header"
  | "column_header"
  | "label"
  | "list_item";

This relation model is intentionally small.

Producers SHOULD omit relationships that cannot be derived deterministically.

4. Top-Level vs Segment-Level Relations

Use context.relations when the relationship applies to the whole Selection.

Use context.segments[].relations when the relationship applies only to one segment.

Example:

{
  "context": {
    "scope": "multi-container",
    "segments": [
      {
        "id": "cell-1",
        "type": "table",
        "text": "$19",
        "selectedText": "$19",
        "relations": [
          { "type": "column_header", "label": "Base price" },
          { "type": "row_header", "label": "Starter" }
        ]
      },
      {
        "id": "cell-2",
        "type": "table",
        "text": "8%",
        "selectedText": "8%",
        "relations": [
          { "type": "column_header", "label": "Tax rate" },
          { "type": "row_header", "label": "Starter" }
        ]
      }
    ],
    "relations": [
      { "type": "section", "label": "Quarterly Pricing Snapshot" }
    ]
  }
}

5. Deterministic Signals

Valid signals include:

• table header structure
• form labels
• description list terms
• heading ancestry
• list item position
• explicit source metadata

Invalid signals include:

• keyword matching alone
• visual proximity without structural support
• language-specific phrasing alone
• inferred user intent

6. Relation Types

6.1 container

The segment is contained by a logical content unit.

6.2 section

The segment or Selection appears under a deterministic section heading.

6.3 row_header

The segment is a table cell associated with a row header.

6.4 column_header

The segment is a table cell associated with a column header.

6.5 label

The segment is associated with a deterministic label.

6.6 list_item

The segment appears in a list item.

7. Summary

Association is a relation vocabulary, not a separate object domain.

Its job is to make context segments usable without forcing Consumers to understand every source format.

Context Object Specification (COS)

Version: 0.2
Chapter: 240 — Semantic
Status: Informative — Supporting
Category: Core Model

1. Purpose

This chapter defines optional semantic classification guidance for the Context Object Specification (COS).

In COS v0.2 lean core, semantic classification is represented by context.segments[].type and optional context.segments[].role.

This chapter exists to explain classification constraints. It does not define a required top-level semantic field.

2. Conceptual Role

If:

• Document = space
• Hierarchy = structure
• Selection = input anchor

Then:

Semantic = meaning attribution layer

It answers:

“What does this part of the document represent?”

3. Definition

A Semantic Context is a structured annotation that assigns interpretability to a node or region within a Document.

It does NOT interpret meaning in natural language terms.

It assigns categorical, structural, or functional meaning.

4. Core Principle

Semantic in COS is:

Classification of meaning, not explanation of meaning

This is critical.

Semantic layer MUST NOT:

• generate explanations
• produce summaries
• infer user intent
• perform reasoning

It ONLY classifies content.

5. Semantic Scope

Semantic annotations MAY apply to:

• text nodes
• hierarchy nodes
• selections
• document fragments

But semantic MUST always reference a structural anchor (Hierarchy Node or Selection).

6. Lean Core Representation

interface ContextSegment {
  type: SemanticType;
  role?: SemanticRole;
}

7. Semantic Type

SemanticType defines what kind of content this is structurally.

type SemanticType =
  | "text"
  | "code"
  | "table"
  | "list"
  | "heading"
  | "quote"
  | "formula";

These types are intentionally closed in v0.2 to ensure stability.

Metadata-like source fields, such as HTML meta tags or document front matter, MUST NOT use a separate SemanticType in v0.2.

They SHOULD be represented as ordinary content when selected, or as Document Metadata / Extension data when they describe system or source attributes.

8. Semantic Role

SemanticRole defines functional meaning inside a system context.

type SemanticRole =
  | "definition"
  | "example"
  | "instruction"
  | "argument"
  | "reference"
  | "output"
  | "code_snippet";

Role is optional and context-dependent.

9. Anchoring Rule

Every SemanticContext MUST be anchored to:

• a Hierarchy Node OR
• a Selection-derived Node

Unanchored semantic data is invalid.

This ensures traceability.

10. Whole-Selection Classification

When a SemanticContext is attached to a Selection, it represents a deterministic classification of the Selection as a whole.

If a Selection spans multiple structural nodes with the same SemanticType, Producers MAY emit one SemanticContext anchored to a Selection-derived or Hierarchy node.

If a Selection spans multiple structural nodes with different SemanticTypes, Producers MUST NOT collapse the result into text.

In such cases, Producers SHOULD omit SemanticContext and allow Consumers to inspect document.content.children and Hierarchy for the mixed structure.

This preserves the distinction between:

• a Selection that is semantically ordinary text
• a Selection whose structure is mixed and therefore cannot be assigned one deterministic SemanticType

11. Separation from Hierarchy

Hierarchy answers:

“Where is this?”

Semantic answers:

“What is this?”

Example:

They MUST NOT be merged.

12. Deterministic Constraint

Semantic classification SHOULD be deterministic under identical inputs.

If nondeterminism exists (e.g., ML inference), confidence MUST be provided.

13. No Reasoning Rule

Semantic layer MUST NOT include:

• reasoning chains
• explanations
• interpretations of intent
• natural language summaries

Those belong to Consumer Layer (AI or external systems).

14. Relationship to Context Object

Semantic classification is embedded in Context Segments:

Context Object
   └── context
        └── segments[]
             ├── type
             └── role?

15. Example (Informative)

{
  "nodeId": "p-1",
  "type": "code",
  "role": "definition",
  "confidence": 0.97
}

16. Design Notes

Semantic layer is intentionally minimal in v0.2.

Its purpose is to:

• enable downstream reasoning systems
• standardize content classification
• avoid coupling with AI-specific logic

Future versions MAY expand role taxonomy or introduce graph-based semantic relations.

17. Summary

Semantic layer defines what content is, not what content means in natural language.

It is the bridge between structural representation and higher-level interpretation systems.

Within COS, it is the first layer that introduces meaning classification without reasoning.

Context Object Specification (COS)

Version: 0.2
Chapter: 250 — Recommendation
Status: Informative — Optional
Category: Core Model

1. Purpose

This chapter defines optional recommendation guidance for systems built around COS.

Recommendation describes potential downstream actions that may be derived from a Context Object.

Recommendation is not part of the COS v0.2 lean core object.

Producers SHOULD NOT emit recommendations in the core Context Object.

Products MAY derive recommendations after receiving the Context Object.

It does NOT execute actions.

It does NOT represent user intent.

It only expresses structured suggestions for consumers.

2. Conceptual Role

If:

• Hierarchy = structure
• Semantic = meaning

Then:

Recommendation = action possibility space

It answers:

“Given this context, what could be done?”

3. Definition

A Recommendation is a structured, non-executed suggestion derived from the Context Object that describes possible consumer actions.

Recommendations are advisory only.

They do not represent decisions.

They do not represent execution plans.

4. Core Principle

Recommendation layer is:

Suggestion without execution

This principle enforces strict separation between:

• context generation
• decision making
• action execution

5. Non-Execution Constraint

A Recommendation MUST NOT:

• execute any action
• trigger workflows
• invoke external systems
• modify state

It is strictly declarative.

6. Recommendation Model (Conceptual)

interface RecommendationContext {
  actions: RecommendationAction[];
}

7. Recommendation Action

A Recommendation Action describes a possible operation a Consumer MAY perform.

interface RecommendationAction {
  type: RecommendationType;
  label?: string;
  confidence?: number;
  payload?: Record<string, any>;
}

8. Recommendation Type

RecommendationType defines high-level action categories.

type RecommendationType =
  | "explain"
  | "summarize"
  | "translate"
  | "analyze"
  | "expand"
  | "refactor"
  | "search"
  | "generate"
  | "navigate"
  | "bookmark"
  | "annotate"
  | "cite"
  | "extract"
  | "compare";

These are intentionally generic and non-executable.

Recommendation types include AI-oriented actions and non-AI actions so that search systems, annotation tools, knowledge systems, and workflow consumers can use the same layer without depending on model-specific behavior.

9. Confidence Rule

Confidence expresses how strongly a recommendation aligns with the semantic interpretation of the Context Object.

• MUST be in range [0, 1]
• OPTIONAL in v0.2
• MUST NOT influence execution

10. Relationship to Context Object

Recommendation MUST NOT be required to understand a Context Object.

If recommendations are transported, they SHOULD appear in an Extension or product-specific layer:

Context Object → Consumer/Product → Recommendation

This keeps COS factual and avoids embedding product decisions into the core object.

11. Consumer Responsibility

Recommendations are designed for Consumers only.

Consumers MAY:

• ignore recommendations
• rank recommendations
• transform recommendations into UI suggestions
• map recommendations to actions

Consumers MUST NOT:

• assume recommendations are authoritative
• execute them without external validation

12. Separation of Concerns

Recommendation layer MUST NOT include:

• reasoning chains
• prompt templates
• execution logic
• tool invocation logic

It remains strictly declarative.

13. Deterministic Constraint

If input Context Object is identical, Recommendation output SHOULD be deterministic.

Non-deterministic systems MUST provide confidence scoring.

14. Example (Informative)

{
  "actions": [
    {
      "type": "explain",
      "label": "Explain this code",
      "confidence": 0.92
    },
    {
      "type": "refactor",
      "label": "Suggest refactoring",
      "confidence": 0.74
    }
  ]
}

15. Design Notes

Recommendation is intentionally outside the lean COS core.

It is constrained to avoid:

• becoming an agent framework
• embedding workflow orchestration logic
• coupling with AI toolchains

Its purpose is to guide product-level action suggestions, not the Context Object itself.

16. Summary

Recommendation defines what could be done without defining what will be done.

In COS v0.2, recommendations SHOULD be derived by Consumers or product layers after receiving a Context Object.

Context Object Specification (COS)

Version: 0.2
Chapter: 260 — Metadata
Status: Informative — Supporting
Category: Core Model

1. Purpose

This chapter defines metadata guidance for the Context Object Specification (COS).

In COS v0.2 lean core, metadata is intentionally small.

It exists purely for observability, traceability, and versioning.

It does NOT describe content meaning.

2. Conceptual Role

If:

• Semantic = meaning
• Recommendation = action possibility

Then:

Metadata = system-level truth about the Context Object itself

It answers:

“How was this Context Object created and transformed?”

3. Definition

Metadata is a structured, non-semantic layer that describes the lifecycle and provenance of a Context Object.

It is independent of:

• content
• structure
• semantic interpretation
• recommendations

4. Core Principle

Metadata is:

about the system, not about the content

This principle enforces strict separation between:

• content understanding
• system observability

5. Lean Meta Model

interface Meta {
  createdAt?: number;
  adapter?: string;
  stages?: string[];
}

createdAt is an integer count of milliseconds since the Unix epoch.

Detailed source information belongs to the top-level source field.

stages MAY list minimal generation stages such as:

["selection", "source", "context", "relations"]

stages is not a detailed pipeline trace. It exists only to indicate which major parts of the lean object were produced.

Detailed pipeline traces and integrity data SHOULD be placed in Extensions.

6. Extended Metadata (Optional)

Implementations MAY expose extended metadata for debugging or audit use cases.

interface ExtendedMetadata {
  pipeline?: PipelineTrace;
  integrity?: IntegrityInfo;
}

7. Pipeline Trace

Represents how the Context Object was transformed.

interface PipelineTrace {
  stages: PipelineStageTrace[];
}

interface PipelineStageTrace {
  name: string;
  timestamp?: number;
  durationMs?: number;
  status?: "success" | "failed" | "skipped";
}

8. Integrity Information

Optional verification and consistency metadata.

interface IntegrityInfo {
  hash?: string;
  checksumAlgorithm?: "sha256";
  validated?: boolean;
}

9. Immutability Rule

Metadata MUST reflect the history of a Context Object.

It MUST NOT be used to modify or reinterpret:

• semantic content
• hierarchy structure
• recommendations

10. Observability Principle

Metadata MUST enable:

• debugging pipeline execution
• tracing transformation stages
• verifying data consistency
• reproducing Context Object generation

11. Non-Semantic Constraint

Metadata MUST NOT include:

• content interpretation
• semantic labeling
• user intent inference
• recommendation logic

It is strictly system-level.

12. Relationship to Context Object

Meta is an optional top-level component of the Context Object:

Context Object
   ├── source
   ├── selection
   ├── context
   └── meta?

13. Determinism Note

Metadata MAY include non-deterministic fields (e.g., timestamps).

However:

• pipeline trace SHOULD be reproducible
• structural metadata SHOULD remain consistent across runs

14. Example (Informative)

{
  "createdAt": 1720250000000,
  "adapter": "web-adapter",
  "stages": ["selection", "source", "context"]
}

15. Design Notes

Metadata is deliberately kept outside content context to avoid:

• mixing system telemetry with content meaning
• contaminating Consumer reasoning with execution details
• coupling protocol with implementation internals

It ensures COS remains both interpretable and debuggable at scale.

16. Summary

Metadata defines optional system-level facts about a Context Object.

It provides limited observability without interfering with source, selection, or context interpretation.

Detailed observability belongs in Extensions.

Context Object Specification (COS)

Version: 0.2
Chapter: 270 — Extension
Status: Normative
Category: Core Model

1. Purpose

This chapter defines the Extension System of the Context Object Specification (COS).

The Extension System enables COS to support domain-specific enhancements without modifying the Core Model.

Extensions are the only sanctioned mechanism for evolving COS capabilities.

2. Conceptual Role

If:

• Core Model = stable foundation
• Semantic = meaning layer
• Recommendation = action layer

Then:

Extension = controlled expansion mechanism

It answers:

“How can COS evolve without breaking compatibility?”

3. Definition

An Extension is a namespaced, optional augmentation to the Context Object that introduces domain-specific structure or behavior.

Extensions:

• do not modify Core Model
• do not override existing semantics
• do not alter interpretation rules

They only add isolated capability domains.

4. Core Principle

Extensions MUST follow:

Additive only, never invasive

This ensures:

• core object isolation
• predictable evolution
• isolation of complexity

5. Extension Model (Conceptual)

interface ExtensionEntry {
  namespace: string;
  version: string;
  payload: Record<string, unknown>;
}

A Context Object carries extensions as an optional list:

interface ExtensionCollection {
  extensions?: ExtensionEntry[];
}

6. Namespace Rule

Every Extension MUST define an owner-qualified namespace using reverse-domain notation. A namespace contains at least two dot-separated lowercase labels; labels MAY contain ASCII digits and interior hyphens.

Examples:

• org.example.pdf
• io.github.context-object-spec.browser
• com.example.editor.code

An owner MUST control the corresponding domain or project namespace. A Context Object MUST NOT contain the same Extension namespace more than once. COS v0.2 does not operate a central namespace registry.

7. Isolation Principle

Each Extension MUST operate in isolation.

This means:

• Extensions MUST NOT modify Core fields:

  • version
  • source
  • selection
  • context
  • meta

• Extensions MAY reference Core fields but MUST NOT alter their defined meaning.

8. Optionality Rule

Extensions are OPTIONAL by design.

A valid Context Object:

• MAY contain zero extensions
• MAY contain multiple extensions
• MUST remain valid without any extension

9. Versioning Rule

Each Extension MUST declare its version explicitly.

Versioning MUST:

• be independent of COS version
• follow semantic versioning (MAJOR.MINOR.PATCH)

This allows independent evolution.

10. Extension Data Model

The payload field contains namespace-specific data.

Its structure is defined by the owning Extension namespace, not by COS Core.

Consumers that do not support the namespace MUST ignore the payload safely.

11. Execution Boundary

Extensions MUST NOT introduce execution logic into COS core.

They MAY:

• define domain-specific structure
• define parsing rules (external to COS core)
• define interpretation hints

They MUST NOT:

• execute actions
• trigger pipelines
• alter recommendation behavior directly

12. Compatibility Guarantee

A Context Object MUST remain valid regardless of:

• unknown extensions
• unsupported extensions
• missing extensions

Consumers MUST ignore unknown namespaces safely.

13. Forward Compatibility Principle

Consumers SHOULD:

• ignore unknown extensions
• preserve extension payload during transport
• avoid destructive normalization

14. Relationship to Core Model

Extensions attach to the Context Object as an independent layer:

Context Object
   ├── version
   ├── source
   ├── selection
   ├── context
   ├── meta?
   └── extensions?   ← this chapter

15. Example (Informative)

{
  "extensions": [
    {
      "namespace": "org.example.pdf",
      "version": "1.0.0",
      "payload": {
        "pageNumber": 12,
        "bbox": {
          "x": 120,
          "y": 340,
          "width": 200,
          "height": 80
        }
      }
    }
  ]
}

16. Design Notes

The Extension system is intentionally minimal but strict.

It is designed to:

• prevent core model pollution
• enable domain specialization
• support ecosystem growth

Without this layer, COS would either become:

• too rigid (no evolution)
• or too chaotic (core drift)

17. Summary

Extension is the controlled evolution mechanism of COS.

It enables the protocol to grow across domains while preserving the stability of the Core Model.

Within COS, Extension is the boundary between core stability and ecosystem innovation.

Context Object Specification (COS)

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

1. Purpose

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

The Pipeline defines how a raw user selection is progressively enriched into a Context Object.

The Pipeline is the runtime mechanism responsible for transforming user attention into structured contextual information.

2. Definition

A Pipeline is a controlled process that transforms an initial Selection and source content into a Context Object.

Formally:

Selection + Source Content
            |
            ▼
Context Enrichment Pipeline
            |
            ▼
Context Object

3. Conceptual Role

The Pipeline connects the two fundamental layers of COS:

Input Layer

Defined by:

• Selection
• Source Content

Output Layer

Defined by:

• Context Object

The Pipeline itself does not define the meaning of the data.

It defines the process through which usable context is constructed.

4. Pipeline Model

A Pipeline operates on a mutable execution state called ContextState.

Each stage receives the current ContextState and produces an enriched ContextState.

Conceptually:

C(n+1) = Stage(n)(C(n))

Where:

• C(n) represents the current ContextState
• Stage(n) represents an enrichment operation
• C(n+1) represents the enriched state

5. ContextState

ContextState is the runtime representation of a Context Object during Pipeline execution.

It may contain:

• incomplete information
• intermediate enrichment results
• execution metadata
• stage results

ContextState is mutable only inside a single Pipeline execution.

A ContextState version becomes a finalized Context Object when it is emitted to Consumers.

After emission, a Context Object MUST be treated as immutable. Later enrichment MUST produce a new ContextState version and a new emitted Context Object version.

6. Pipeline Input

A Pipeline MUST start with:

interface PipelineInput {
  selection: Selection;
  source: SourceContext;
}

The Pipeline MUST NOT start from:

• raw text only
• isolated metadata
• AI-generated content

The initial state MUST preserve the original user selection.

7. Pipeline Output

A successfully completed Pipeline produces:

interface PipelineOutput {
  contextObject: ContextObject;
}

The resulting Context Object MUST conform to the Core Model defined in Part II.

8. Enrichment Principle

Pipeline execution follows the Incremental Enrichment Principle defined in Chapter 140.

Each stage:

MUST:

• add information
• refine existing information
• preserve existing meaning

MUST NOT:

• replace the original Selection
• invalidate source references
• overwrite unrelated enrichment results

9. Pipeline Architecture

COS v0.2 defines a lean context construction pipeline.

The Pipeline consists of two conceptual execution zones:

Selection
    |
Source
    |
Context Segments
    |
Relations
    |
Context Object

10. Structural Pipeline

The Pipeline is responsible for deterministic context construction.

Characteristics:

• fast execution
• deterministic output
• no AI dependency

Typical responsibilities:

• locating selection source
• extracting covered context segments
• preserving selected text within each segment
• attaching deterministic relations

11. Optional Enrichment

Implementations MAY perform optional enrichment after the lean Context Object has been produced.

Characteristics:

• semantic labeling beyond deterministic segment type
• product-specific recommendations
• debug metadata
• integrity checks

Optional enrichment MUST NOT be required for Consumers to understand the core Context Object.

12. Asynchronous Execution

Pipeline stages MAY execute asynchronously.

Asynchronous stages MUST:

• preserve ContextState integrity
• report execution status
• avoid corrupting previous enrichment results

A delayed or failed stage MUST NOT invalidate the entire Context Object.

13. Partial Completion

A Pipeline MAY produce a partially enriched Context Object.

Example:

source             ✓
selection          ✓
context.segments   ✓
context.relations  ✗
extensions.debug   ✗

The resulting Context Object remains valid if required core components are available.

14. Deterministic Execution

Pipeline execution SHOULD be deterministic.

Given:

• identical Selection
• identical source content
• identical Pipeline configuration

The resulting Context Object SHOULD be equivalent.

Non-deterministic stages MUST expose additional metadata.

15. Pipeline Isolation

A Pipeline execution represents an isolated enrichment process.

Each execution SHOULD maintain:

• independent ContextState
• independent stage results
• independent execution metadata

Pipeline executions MUST NOT implicitly modify each other.

16. Extension Support

Pipeline MAY support additional stages through Extension mechanisms.

Extensions:

• MAY introduce new enrichment capabilities
• MUST NOT modify existing stage semantics
• MUST NOT bypass Core Model rules

17. Relationship to Other Components

User Interaction
      |
      ▼
Selection
      |
      ▼
Pipeline
      |
      ▼
Context Object
      |
      ▼
Consumer

Pipeline is the runtime bridge between user attention and contextual understanding.

18. Summary

The Pipeline defines the execution model of COS.

It transforms Selection and Document context into a Context Object through controlled, incremental enrichment.

The Pipeline is intentionally independent from AI providers, frameworks, and implementations.

AI capabilities are treated as optional enrichment stages rather than the foundation of the protocol.

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.

Context Object Specification (COS)

Version: 0.2
Chapter: 320 — Lifecycle
Status: Normative — Runtime Profile
Category: Pipeline Model

1. Purpose

This chapter defines the lifecycle model of the Context Object Specification (COS).

The Lifecycle describes how a Context Object is:

• created
• initialized
• made available
• consumed
• updated
• invalidated

during its runtime existence.

2. Conceptual Role

Lifecycle defines the temporal behavior of COS.

If:

• Core Model defines what a Context Object contains
• Pipeline defines how a Context Object is generated

Then:

Lifecycle defines when and why Context Object states change.

3. Lifecycle Definition

A Context Object Lifecycle represents the sequence of states that a Context Object passes through during its existence.

Conceptually:

User Interaction

      ↓

Selection Created

      ↓

Context Initialized

      ↓

Pipeline Enrichment

      ↓

Context Available

      ↓

Context Updated / Invalidated

4. Lifecycle States

COS defines the following lifecycle states:

type ContextLifecycleState =
  | "created"
  | "initialized"
  | "processing"
  | "available"
  | "updated"
  | "invalidated";

5. State Definitions

5.1 Created

A Context Object lifecycle begins when a Selection event occurs.

Example:

• user highlights text
• user selects PDF region
• user selects code block

At this stage:

Available:

Selection

Not available:

Source
Context

5.2 Initialized

The system creates the initial ContextState.

The initialized state MUST contain:

• Selection
• Source

Example:

ContextState

├── Selection
└── Source

5.3 Processing

The Pipeline is executing enrichment stages.

During this phase:

• stages may execute sequentially
• stages may execute asynchronously
• ContextState may be partially enriched

5.4 Available

A Context Object becomes available when the required core components for a Consumer are present.

The minimum available Context Object SHOULD contain:

• Source
• Selection
• Context

Example:

Context Object

├── Source
├── Selection
└── Context

A Consumer MAY:

• display context actions
• send context to AI models
• store context
• trigger user interfaces

5.5 Updated

A Context Object enters Updated state when additional enrichment occurs.

Examples:

• additional context relations added
• extension data added
• meta stages updated

Update MUST preserve existing valid context.

An Updated state emits a new Context Object version.

5.6 Invalidated

A Context Object becomes invalid when its source context is no longer valid.

Examples:

• source document changed
• selection removed
• source content version changed

Invalidation MUST NOT silently delete historical information.

6. Lifecycle Flow

The default lifecycle:

Created

   ↓

Initialized

   ↓

Processing

   ↓

Available

   ↓

Updated*

   ↓

Invalidated*

* indicates optional transitions.

7. Selection Change Lifecycle

Selection is the primary lifecycle trigger.

When user attention changes:

Example:

Old Selection

      ↓

New Selection

The system SHOULD create a new Context Object lifecycle.

A Context Object MUST NOT silently change its Selection identity.

8. Incremental Enrichment

COS supports incremental enrichment.

Example:

Initial:

Context Object

Selection
Source
Context

Later:

Context Object

Selection
Source
Context
Extensions
Meta

The lifecycle remains continuous, but each externally visible update emits a new immutable Context Object version.

9. Async Enrichment Lifecycle

Optional enrichment stages MAY complete asynchronously.

Example:

User Selection

      ↓

Basic Context Available

      ↓

Optional Processing

      ↓

Extensions Updated

      ↓

Meta Updated

Consumers SHOULD be able to receive intermediate states.

10. Context Versioning

Each Context Object SHOULD maintain a version identifier.

Example:

interface ContextVersion {
  version: number;
  createdAt: number;
}

Version changes when:

• enrichment occurs
• extension data changes
• context structure changes

11. Context Persistence

COS does not require persistence.

A Context Object MAY exist as:

• temporary runtime state
• cached context
• persisted context record

Persistence behavior is implementation-specific.

12. Lifecycle Events

Implementations SHOULD expose lifecycle events.

Example:

type ContextEvent =
  | "context.created"
  | "context.initialized"
  | "context.processing"
  | "context.available"
  | "context.updated"
  | "context.invalidated";

13. Event Ordering

Lifecycle events MUST follow chronological ordering.

Example:

Valid:

created

↓

initialized

↓

processing

↓

available

Invalid:

updated

↓

created

14. Error Handling

Pipeline failures MUST produce lifecycle-aware results.

Example:

Processing

      ↓

Optional Enrichment Failed

      ↓

Available With Core Context

Failure MUST NOT automatically invalidate Context Object.

15. Relationship to Pipeline

Pipeline defines execution.

Lifecycle defines state transition.

Relationship:

Lifecycle

    controls

Pipeline Execution

    produces

Context Object

16. Relationship to Consumer

Consumers SHOULD react to lifecycle changes instead of polling Context Object state.

Example:

context.available

        ↓

Render AI Actions


context.updated

        ↓

Refresh Suggestions

17. Design Notes

Lifecycle is intentionally independent from:

• AI provider
• UI framework
• storage mechanism

It defines protocol behavior, not implementation details.

18. Summary

Lifecycle defines the temporal model of COS.

It describes how Context Objects are created, made available, consumed, updated, and invalidated.

Together with Pipeline and Pipeline Stages, Lifecycle completes the runtime model of the Context Object Specification.

Context Object Specification (COS)

Version: 0.2
Chapter: 400 — Plugin Specification
Status: Normative — Plugin Profile
Category: Plugin Model

1. Purpose

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

The Plugin System provides an extensibility mechanism that allows domain-specific capabilities to integrate with COS without modifying the Core Model.

Plugins enable COS to support different domains, environments, and processing capabilities while preserving protocol stability.

2. Definition

A Plugin is an optional capability provider that extends COS functionality through controlled integration points.

A Plugin MAY provide:

• new data capabilities
• new enrichment capabilities
• new adapters
• domain-specific processing logic

A Plugin MUST NOT modify the COS Core Model.

3. Core Principle

The Plugin System follows:

Stable Core, Extensible Capability

The Core Model remains fixed.

Plugins provide additional capabilities around the Core Model.

4. Plugin Relationship Model

The relationship between COS and Plugins:

Context Object
  ↑
Extension Data
  ↑
Plugin
  ↑
External Capability

A Plugin produces or enables additional capabilities that may enrich a Context Object.

5. Plugin Model

A Plugin MUST provide a unique identity.

interface Plugin {
  id: string;
  version: string;
  capabilities: string[];
}

6. Plugin Identity

Each Plugin MUST define:

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

Requirements:

id MUST be globally unique within an ecosystem version MUST follow semantic versioning

Example:

pdf-plugin@1.0.0

7. Plugin Capabilities

Capabilities describe what a Plugin provides.

interface PluginCapability {
  name: string;
  version?: string;
}

Examples:

pdf.page
pdf.annotation
code.ast
browser.dom

8. Capability Principle

Plugins SHOULD expose capabilities instead of implementation details.

Consumers SHOULD depend on:

Capability

rather than:

Plugin Implementation

Example:

Preferred:

requires:
pdf.annotation

Not:

requires:
PdfPluginV2

9. Plugin Lifecycle

A Plugin follows the lifecycle:

Register
    ↓
Initialize
    ↓
Available
    ↓
Execute
    ↓
Dispose

10. Registration

Registration makes a Plugin known to the COS runtime.

Example:

register(plugin);

During registration:

The runtime SHOULD verify:

• identity
• version
• capabilities

11. Initialization

Initialization prepares Plugin runtime resources.

A Plugin MAY:

• load configuration
• initialize services
• register stages
• register adapters

A Plugin MUST NOT modify existing Context Objects during initialization.

12. Available State

A Plugin enters Available state when:

• registration succeeds
• initialization succeeds
• required capabilities are satisfied

Available Plugins MAY participate in:

• Pipeline execution
• Adapter processing
• Context enrichment

13. Execution Model

A Plugin MAY contribute execution units.

Examples:

PDF Plugin

provides:

PDF Extraction Stage
PDF Annotation Adapter

Plugin execution MUST follow COS Pipeline rules.

13.1 Plugin and Stage Registration

A Plugin MAY register one or more Pipeline Stages.

Each registered Stage MUST:

• declare a unique Stage identifier
• declare the Plugin identifier that provides it
• declare provided and required capabilities
• follow Pipeline Stage isolation rules

If a Plugin registers multiple Stages, each Stage MUST be independently traceable.

A Plugin MUST NOT silently replace a built-in Stage or another Plugin’s Stage.

When multiple registered Stages provide the same capability, the Runtime MUST resolve the provider through explicit configuration, capability negotiation, or deterministic priority rules.

14. Plugin Output

Plugin-generated information MUST be represented through existing COS extension mechanisms.

Example:

Plugin
    ↓
Extension Data
    ↓
Context Object

Plugins MUST NOT introduce alternative Context Object structures.

15. Core Model Protection

Plugins MUST NOT modify:

• Selection
• Document
• Hierarchy
• Semantic
• Recommendation
• Metadata

Direct modification of Core Model fields is invalid.

16. Plugin Isolation

Each Plugin MUST operate independently.

A Plugin failure MUST NOT invalidate:

• COS Core
• Other Plugins
• Existing Context Objects

17. Plugin Categories

COS does not require a fixed Plugin taxonomy.

However, implementations MAY define categories:

17.1 Adapter Plugin

Connects external systems.

Examples:

Browser Adapter
PDF Adapter
Editor Adapter

17.2 Enrichment Plugin

Adds contextual information.

Examples:

Semantic Analyzer
Code Analyzer
Vision Processor

17.3 Capability Plugin

Provides reusable domain capabilities.

Examples:

Search Capability
Knowledge Capability
Storage Capability

18. Plugin Discovery

Plugin discovery is implementation-specific.

Possible mechanisms:

• static registration
• package discovery
• runtime loading
• service registry

COS does not mandate a discovery mechanism.

19. Plugin Security Boundary

Implementations SHOULD isolate Plugin execution.

Isolation MAY include:

• permission control
• sandboxing
• resource limits

20. Relationship to Other Specifications

Plugin Specification defines the plugin foundation.

Related specifications:

400 Plugin Specification
        ↓
410 Adapter
        ↓
420 Compatibility

21. Summary

The Plugin System provides a controlled extension mechanism for COS.

Plugins add capabilities without modifying the Core Model.

Through identity, capability declaration, lifecycle management, and isolation rules, COS enables ecosystem growth while maintaining protocol stability.

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:

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.

Context Object Specification (COS)

Version: 0.2
Chapter: 420 — Compatibility
Status: Normative — Plugin and Adapter Profiles
Category: Plugin Model

1. Purpose

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

The Compatibility Model specifies how COS implementations, Plugins, Adapters, and Extensions maintain interoperability across different versions and environments.

The goal of compatibility is to enable ecosystem evolution without breaking existing integrations.

2. Definition

Compatibility describes the ability of different COS components to work together while maintaining semantic correctness.

COS compatibility applies to:

• Core Model
• Pipeline
• Plugins
• Adapters
• Extensions
• Consumers

3. Core Principle

COS follows:

Capability-based Compatibility over Implementation-based Compatibility

Systems SHOULD depend on declared capabilities rather than specific implementations.

Example:

Preferred:

Requires:

pdf.annotation

Not:

Requires:

PDFPlugin v2.1

4. Compatibility Layers

COS v0.2 defines four compatibility layers:

Core Object Compatibility
        ↓
Plugin Compatibility
        ↓
Adapter Compatibility
        ↓
Extension Compatibility

Each layer has independent capability rules.

5. Core Object Compatibility

Core Object Compatibility means a system can consume the lean v0.2 Context Object shape.

Example:

source
selection
context
meta?
extensions?

Core compatibility MUST consider:

• data model changes
• interface changes
• lifecycle changes

6. Semantic Compatibility

Compatibility is not only structural.

Two systems are compatible only when they preserve the same meaning.

Example:

Compatible:

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

Incompatible:

{
 "selection": {
   "text":"hello",
   "meaning":"translated"
 }
}

if the original semantic meaning changed.

7. Plugin Compatibility

Plugins MUST declare compatibility information.

Example:

interface PluginCompatibility {
  cosVersion: string;
  capabilities: string[];
}

Example:

{
 "plugin":"pdf-plugin",
 "version":"1.2.0",
 "cosVersion":"0.2",
 "capabilities":[
   "pdf.annotation"
 ]
}

8. Capability Negotiation

COS uses capability negotiation.

Before activation:

Runtime

     asks

Plugin Capabilities

     compares

Required Capabilities

Example:

Required:

[
 "annotation",
 "coordinate"
]

Plugin:

[
 "annotation",
 "coordinate",
 "render"
]

Result:

Compatible.

9. Version Negotiation

COS protocol versions and component versions use different formats.

The Context Object version and cosVersion identify a two-part protocol line:

major.minor

Example:

0.2

Plugin, Adapter, and Extension versions MUST use semantic versioning:

major.minor.patch

Compatibility rules:

Major Version

May contain breaking changes.

1.x

≠

2.x

Minor Version

Should preserve declared capabilities.

1.1

compatible with

1.2

Patch Version

Should contain fixes only.

1.1.1

compatible with

1.1.2

10. Unknown Extension Handling

Unknown extensions SHOULD be ignored safely.

Core Context Object fields MUST remain usable when an implementation does not understand an extension.

Example:

Context Object
  ├── source
  ├── selection
  ├── context
  └── extensions.unknown

The Consumer SHOULD read the core object and ignore the unknown extension.

Example:

{
 "extensions":[
   {
     "namespace":"org.example.future-capability",
     "version":"1.0.0",
     "payload":{}
   }
 ]
}

11. Extension Compatibility

Extensions MUST be isolated.

Example:

{
 "extensions":[
   {
     "namespace":"org.example.pdf",
     "version":"1.0.0",
     "payload":{
       "annotation":{}
     }
   }
 ]
}

A system without PDF support SHOULD still process:

{
 "version":"0.2",
 "source":{"type":"pdf","title":"Report"},
 "selection":{"text":"Annotation"},
 "context":{
   "scope":"container",
   "segments":[{"type":"text","text":"Annotation"}]
 },
 "extensions":[{
   "namespace":"org.example.pdf",
   "version":"1.0.0",
   "payload":{"annotation":{}}
 }]
}

12. Adapter Compatibility

Adapters MUST declare:

source compatibility output compatibility capability support

Example:

{
 "source":"PDF.js",
 "supportedVersions":[
   "4.x",
   "5.x"
 ]
}

13. Deprecation Strategy

COS components SHOULD support controlled deprecation.

A deprecated capability SHOULD:

• remain available for a transition period
• provide replacement guidance when removing extension features
• announce removal version

Example:

Capability:

pdf.oldAnnotation

Status:

deprecated

Replacement:

pdf.annotation

14. Compatibility Checking

A COS Runtime SHOULD perform compatibility validation before execution.

Example:

Load Plugin
      ↓
Check Version
      ↓
Check Capability
      ↓
Activate

15. Compatibility Failure

Compatibility failures MUST be explicit.

Example:

{
 "status":"failed",
 "reason":"missing capability",
 "required":"pdf.annotation"
}

Failures SHOULD NOT silently degrade behavior.

16. Isolation Principle

A compatibility failure in one component MUST NOT affect unrelated components.

Example:

PDF Plugin incompatible
        ↓
PDF features unavailable
        ↓
Browser features continue working

17. Compatibility Matrix

Implementations MAY maintain compatibility matrices.

Example:

18. Relationship to Other Specifications

Compatibility completes the Plugin Model:

400 Plugin Specification
        ↓
410 Adapter
        ↓
420 Compatibility

19. Summary

Compatibility defines how COS evolves without breaking interoperability.

Through:

• capability negotiation
• semantic versioning
• isolation
• extension boundaries

COS enables a sustainable plugin ecosystem while preserving Core Model stability.

Context Object Specification (COS)

Version: 0.2
Chapter: 500 — Examples
Status: Informative
Category: Adoption & Evolution

1. Purpose

This chapter provides lean examples of COS v0.2 Context Objects.

The examples demonstrate the first principle of COS:

Selected text becomes useful when paired with source-grounded context.

2. General Flow

External Environment
    ↓
Adapter
    ↓
Selection + Source
    ↓
Context Construction
    ↓
Context Object
    ↓
Consumer

3. Example: Word in Paragraph

Scenario

A user selects the word nearby inside a paragraph.

Raw text alone is ambiguous.

COS preserves the local sentence context.

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Mixed Article",
    "uri": "about:srcdoc"
  },
  "selection": {
    "text": "nearby"
  },
  "context": {
    "scope": "inline",
    "segments": [
      {
        "id": "p1",
        "type": "paragraph",
        "text": "The adapter should preserve nearby context without turning the selection into a prompt.",
        "selectedText": "nearby",
        "beforeText": "The adapter should preserve ",
        "afterText": " context without turning the selection into a prompt."
      }
    ],
    "relations": [
      { "type": "section", "label": "Pricing Rules" }
    ]
  },
  "meta": {
    "adapter": "web-adapter"
  }
}

4. Example: Table Cell

Scenario

A user selects $19 inside a product table.

Raw text alone does not say what $19 means.

COS preserves table relationships.

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Product Table",
    "uri": "about:srcdoc"
  },
  "selection": {
    "text": "$19"
  },
  "context": {
    "scope": "container",
    "segments": [
      {
        "id": "cell-price-starter",
        "type": "table",
        "text": "$19",
        "selectedText": "$19",
        "relations": [
          { "type": "column_header", "label": "Base price" },
          { "type": "row_header", "label": "Starter" }
        ]
      }
    ],
    "relations": [
      { "type": "section", "label": "Quarterly Pricing Snapshot" }
    ]
  }
}

5. Example: Multi-Container Selection

Scenario

A user selects from the middle of a paragraph into a list.

Raw text loses the per-container boundaries.

COS preserves each covered segment.

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Mixed Article"
  },
  "selection": {
    "text": "adapter should preserve nearby context without turning the selection into a prompt.\n\nSelections can begin in ordinary prose.\nThey can cross list items and code "
  },
  "context": {
    "scope": "multi-container",
    "segments": [
      {
        "id": "p1",
        "type": "paragraph",
        "text": "The adapter should preserve nearby context without turning the selection into a prompt.",
        "selectedText": "adapter should preserve nearby context without turning the selection into a prompt.",
        "beforeText": "The "
      },
      {
        "id": "li1",
        "type": "list",
        "text": "Selections can begin in ordinary prose.",
        "selectedText": "Selections can begin in ordinary prose.",
        "relations": [
          { "type": "list_item", "label": "item 1" }
        ]
      },
      {
        "id": "li2",
        "type": "list",
        "text": "They can cross list items and code blocks.",
        "selectedText": "They can cross list items and code ",
        "afterText": "blocks.",
        "relations": [
          { "type": "list_item", "label": "item 2" }
        ]
      }
    ],
    "relations": [
      { "type": "section", "label": "Pricing Rules" }
    ]
  }
}

6. Example: Dashboard Value

Scenario

A user selects Degraded in a dashboard.

COS preserves the label that makes the value meaningful.

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Deployment Console"
  },
  "selection": {
    "text": "Degraded"
  },
  "context": {
    "scope": "container",
    "segments": [
      {
        "id": "health-value",
        "type": "text",
        "text": "Degraded",
        "selectedText": "Degraded",
        "relations": [
          { "type": "label", "label": "Health" }
        ]
      }
    ]
  }
}

7. Example: Code Selection

Scenario

A user selects a code expression.

COS preserves that the selected text comes from a code segment.

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Pricing Rules"
  },
  "selection": {
    "text": "return basePrice * (1 + taxRate);"
  },
  "context": {
    "scope": "container",
    "segments": [
      {
        "id": "code-1",
        "type": "code",
        "role": "code_snippet",
        "text": "return basePrice * (1 + taxRate);",
        "selectedText": "return basePrice * (1 + taxRate);"
      }
    ]
  }
}

8. Summary

Lean COS examples should be readable without knowing the whole protocol.

Consumers should understand the selected content by reading:

• source
• selection.text
• context.segments
• context.relations

Context Object Specification (COS)

Version: 0.2
Chapter: 510 — Best Practices
Status: Informative
Category: Adoption & Evolution

1. Purpose

This chapter defines recommended practices for implementing and extending the Context Object Specification (COS).

These practices help maintain:

• Core stability
• Semantic consistency
• Plugin interoperability
• Long-term ecosystem evolution

2. Core Philosophy

COS follows the principle:

Keep the Core minimal, keep Extensions flexible, keep Capabilities composable.

A healthy COS implementation should preserve:

• Stable Core
• Flexible Extensions
• Composable Plugins

3. Keep Core Model Stable

3.1 Principle

The Core Model represents universal concepts.

Core fields SHOULD only contain concepts shared across domains.

Good:

interface Selection {
  text: string;
  range?: Range;
}

Bad:

interface Selection {
  pdfPageNumber:number;
  domPath:string;
  codeSymbol:string;
}

3.2 Rule

Before adding a Core field, ask:

Does every COS implementation need this concept?

If the answer is no:

Use Extension.

4. Prefer Extension Over Core Modification

Domain-specific information SHOULD be placed in Extensions.

Example:

PDF:

{
  "extensions": [
    {
      "namespace": "org.example.pdf",
      "version": "1.0.0",
      "payload": {
        "page": 12
      }
    }
  ]
}

Code:

{
  "extensions": [
    {
      "namespace": "org.example.code",
      "version": "1.0.0",
      "payload": {
        "symbol": "calculate"
      }
    }
  ]
}

Do not introduce:

Document {
  pdfInfo;
  codeInfo;
}

5. Keep Plugin Boundaries Clear

A Plugin provides capabilities.

A Plugin SHOULD NOT become:

• application logic container
• business workflow engine
• AI orchestration layer

Correct:

Plugin
↓
Capability
↓
Context Enrichment

Incorrect:

Plugin
↓
Complete Application

6. Use Adapter for Translation

Adapters exist at system boundaries.

Their responsibility:

External Representation
        ↓
COS Representation

Adapters SHOULD:

• normalize data
• preserve source information
• translate events

Adapters SHOULD NOT:

• perform reasoning
• generate recommendations
• call AI models directly

7. Keep Pipeline Stages Focused

Each Pipeline Stage SHOULD have a single responsibility.

Good:

Selection Stage
↓
Source Stage
↓
Context Stage

Bad:

AI Stage

does:

- parsing
- analysis
- recommendation
- storage
- UI rendering

8. Progressive Context Enrichment

Context Objects SHOULD be enriched progressively.

Recommended:

Selection Created
        ↓
Source Attached
        ↓
Context Segments Added
        ↓
Relations Added

Avoid blocking the entire Context Object until all processing completes.

9. Preserve Original Context

The original user context SHOULD remain unchanged.

Example:

Original:

{
 "selection":{
   "text":"original text"
 }
}

AI result:

{
 "extensions":{
   "summary":"generated summary"
 }
}

Do not overwrite:

{
 "selection":{
   "text":"AI rewritten text"
 }
}

10. AI Should Be a Consumer

AI is a capability consumer, not the foundation of COS.

Relationship:

Context Object
        ↓
AI Consumer
        ↓
Result

COS SHOULD NOT depend on:

• specific LLM providers
• prompt formats
• model versions

11. Prefer Capability-Based Design

Consumers SHOULD request capabilities.

Preferred:

Requires:

semantic.analysis

Avoid:

Requires:

OpenAIPluginV3

Capabilities allow:

• multiple implementations
• easier replacement of implementation providers
• ecosystem growth

12. Design for Partial Availability

A Context Object does not need every field populated.

Example:

Available:

Selection

Source

context.segments

Later:

context.relations

extensions or meta

Systems SHOULD handle partial contexts gracefully.

13. Avoid Context Overloading

Context Object SHOULD represent:

User attention and relevant information.

It SHOULD NOT become:

• application state
• database model
• user profile
• workflow state

Bad:

{
 "context":{
   "userSettings":{},
   "shoppingCart":{},
   "permissions":{}
 }
}

14. Version Extensions Independently

Extensions SHOULD maintain independent evolution.

Example:

COS

v0.2


PDF Extension

v1.5

Do not require:

COS update

for every Extension change

15. Design for Observability

Implementations SHOULD provide visibility into:

• Context lifecycle
• Pipeline stages
• Plugin execution
• Extension generation

Example:

context.created
↓
context.relations.completed
↓
extensions.updated

16. Handle Failure Gracefully

A failed enrichment SHOULD NOT destroy existing context.

Example:

Optional Enrichment Failed
        ↓
Context remains usable

Prefer:

{
 "status":"partial",
 "available":[
   "selection",
   "source",
   "context.segments"
 ]
}

17. Security Considerations

Implementations SHOULD:

• validate external input
• isolate plugins
• control extension access
• protect sensitive context data
• minimize captured data to the active Selection and required surrounding context
• redact or omit sensitive source fields when transport does not require them
• preserve browser security boundaries, including Content Security Policy constraints
• avoid exposing raw DOM nodes, live editor objects, credentials, cookies, or authentication headers
• sandbox Plugin and Adapter execution when they process untrusted source content

Browser-based implementations SHOULD treat page URL, title, DOM path, selected text, and surrounding text as potentially sensitive.

Consumers SHOULD request only the Context Object fields and Extension namespaces required for their task.

18. Performance Guidance

Implementations SHOULD make basic context available quickly and defer expensive enrichment.

Recommended behavior:

• Structural Pipeline stages SHOULD run synchronously or with minimal delay when possible
• optional extension or product recommendation stages MAY run asynchronously
• large source documents SHOULD be represented by anchors and nearby context rather than full-document payloads
• Extensions SHOULD avoid duplicating core fields
• Meta SHOULD record minimal stages when useful

Implementations MAY define local size and latency budgets.

When a budget is exceeded, the Pipeline SHOULD emit a partial Context Object instead of blocking availability.

19. Recommended Architecture

A recommended COS implementation:

                 Consumer
                    ↑
             Context Object
                    ↑
               Pipeline
                    ↑
              Adapter
                    ↑
             External System

Plugins extend capabilities without breaking this structure.

20. Common Mistakes

Mistake 1

Putting domain fields into Core.

Solution:

Use Extension.

Mistake 2

Making Plugin responsible for everything.

Solution:

Separate Adapter, Pipeline, Consumer.

Mistake 3

Embedding AI concepts into protocol.

Solution:

Keep AI as Consumer.

Mistake 4

Treating Context as database storage.

Solution:

Keep Context focused on active user attention.

21. Summary

Best Practices ensure that COS remains:

• stable
• extensible
• interoperable
• AI-ready

The fundamental rule:

Preserve the Core, extend through Plugins, enrich through Pipeline, and consume through Context-aware systems.

Context Object Specification (COS)

Version: 0.2
Chapter: 520 — Future Work
Status: Informative
Category: Adoption & Evolution

1. Purpose

This chapter describes possible future directions of the Context Object Specification (COS).

Future Work defines potential evolution paths that may extend COS beyond its initial scope while preserving the core principles established in v0.2.

The directions described here are exploratory and do not represent mandatory requirements.

2. Evolution Vision

The long-term vision of COS is:

Transform user attention into a universal, structured, AI-ready context layer.

The evolution path:

User Selection
    ↓
Context Object
    ↓
AI Understanding
    ↓
Agent Action

3. From Selection Context to Universal Context

The initial COS model focuses on explicit user attention:

Examples:

• selected text
• selected document region
• selected code
• selected webpage content

Future versions may support broader context sources.

3.1 Explicit Context

Current model:

User selects something
    ↓
Create Context Object

Examples:

• highlighted paragraph
• selected function
• selected image region

3.2 Implicit Context

Future COS may support inferred user context.

Examples:

• current document
• current task
• working environment
• user workflow state

Example:

{
  "context": {
    "activeDocument": {},
    "activeApplication": {},
    "recentActions": {}
  }
}

4. Multimodal Context

Future COS may extend beyond text-based context.

Supported context types may include:

• text
• image
• audio
• video
• spatial information

4.1 Image Context

Example:

{
  "selection": {
    "type": "image-region"
  }
}

Possible applications:

• image explanation
• visual search
• design assistance

4.2 Audio Context

Example:

{
  "selection": {
    "type": "audio-segment"
  }
}

Possible applications:

• meeting assistant
• voice analysis
• transcription

4.3 Video Context

Example:

{
  "selection": {
    "type": "video-segment"
  }
}

Possible applications:

• video understanding
• education assistant
• content analysis

5. Agent Context Protocol

One future direction is enabling COS as a shared context layer for AI Agents.

Current:

User
 ↓
Context Object
 ↓
AI Assistant

Future:

User
 ↓
Context Object
 ↓
Multiple Agents

Example:

Research Agent
        ↓
Writing Agent
        ↓
Review Agent

All agents operate on the same contextual foundation.

6. Context Streaming

Current COS lifecycle is event-based.

Future COS may support continuous context streams.

Example:

context.created
        ↓
context.available
        ↓
context.updated
        ↓
context.refined

Streaming enables:

• real-time AI assistance
• collaborative systems
• continuous understanding

7. Shared Context Between Applications

Future COS may allow applications to share contextual information.

Example:

Browser
   ↓
Context Object
   ↓
Knowledge System
   ↓
Writing Assistant

Applications no longer need custom integrations.

They communicate through a shared context protocol.

8. Context Memory

Future versions may introduce persistent context memory.

Current:

Temporary Runtime Context

Future:

Temporary Context
        ↓
Context Memory
        ↓
Long-term Understanding

Possible applications:

• personal knowledge systems
• enterprise assistants
• workflow automation

9. Context Security Model

As context becomes more powerful, security becomes critical.

Future work may define:

• permission models
• context ownership
• access control
• privacy boundaries

Example:

{
  "contextPermission": {
    "read": true,
    "share": false
  }
}

10. Context Provenance

Future COS may track the origin and transformation history of context.

Example:

Original Selection
        ↓
Adapter Transformation
        ↓
Pipeline Enrichment
        ↓
AI Interpretation

Provenance enables:

• explainability
• auditing
• trust management

11. Standard Capability Registry

Future ecosystems may introduce a shared capability registry.

Example:

Capability Registry


pdf.annotation

code.analysis

semantic.search

vision.understanding

Applications can discover available capabilities dynamically.

12. Ecosystem Expansion

Potential COS ecosystem:

                 COS


        /          |          \


    PDF        Browser       Code


     |            |            |


  Plugin      Plugin       Plugin


        \          |          /


              AI Agents

13. Research Directions

Future research areas:

• Context compression
• Context ranking
• Context relevance scoring
• Context privacy
• Distributed context synchronization
• Agent interoperability

14. Compatibility Principle

Future evolution MUST preserve:

• Core Model stability
• Plugin isolation
• Extension compatibility
• Capability-based design

Future capabilities SHOULD extend COS without breaking existing implementations.

15. Final Vision

The long-term goal of COS is not to become another AI application framework.

COS aims to become:

A universal context layer connecting human attention, applications, and intelligent systems.

The evolution:

COS Web Adapter
        ↓
Context Ready for AI
        ↓
Context Infrastructure for Agents

16. Summary

Future Work defines the long-term evolution direction of COS.

The protocol may evolve from a selection-based context model into a universal context infrastructure supporting:

• multimodal understanding
• AI agents
• shared context
• context streaming
• intelligent applications

while maintaining the fundamental principle:

Context should be structured, extensible, and ready for intelligence.