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.