# Semantic Expression System — FULL RESEARCH CORPUS (share wrapper)
Abbreviation: ses
Version: v1.0.0
Bundle name: llm-full-docs-ses
Upstream artifact: .agents/llms-full-ses-v1.0.0.txt
Generated: unspecified
========================================================================

# SEMANTIC EXPRESSION SYSTEM: CONSOLIDATED MASTER RESEARCH & CODEBASE CORPUS
System Root Version: v1.0.0 (2026-09-29) | Modules: 191 | Total Lines: 8,176
Subsystem Identity: Semantic Expression System: v1.0.0 (40e5436)
Corpus Payload SHA-256 (excluding this field): fc897a67327d68c3c6e86e22660e1a078d5ffebad5245683b3354351e1ae80b6

TABLE OF CONTENTS & SUBSYSTEM SUMMARY:
  - System Architecture, Intent & Governance: 44 files
  - Canonical Contract Schemas & Protocol Definitions: 2 files
  - Conformance Suite & Test Fixtures: 40 files
  - Core Implementation & Resolution Tools: 21 files
  - System Scripts & Pipeline Automation: 1 files
  - Operational Work Graph & Issues: 41 files
  - Verification & Execution Evidence: 41 files
  - Other System Modules: 1 files

========================================================================


========================================================================
## SUBSYSTEM: SYSTEM ARCHITECTURE, INTENT & GOVERNANCE (44 files)
========================================================================

--- FILE: .agents/AGENTS.md (59 lines, 2.6 KiB) ---
# Semantic Expression System Agent Operating Contract

## IEPE authority

This project operates under `IEPE-001`, version `0.2.0`, from `https://github.com/zachshallbetter/IEPE` at immutable revision `56f82de8cca122cc4d347cdd55bb32bdcd31ed27`. The pin is recorded in `.iepe/protocol-reference.json`.

IEPE Core governs claim, context, dispatch, evidence, perturbation, promotion, memory, and stop semantics. Local canonical sources govern this project's intent, experience, architecture, work graph, evaluators, adapters, and protected actions. Local instructions may specialize IEPE but may not weaken its invariants.

Preserve this trace:

```text
intent -> epic -> issue -> claim -> context -> artifact -> evaluation -> evidence -> qualification -> promotion
```

## Authority order

1. `INTENT.md`
2. `docs/EXPERIENCE.md`
3. `docs/ARCHITECTURE.md`
4. `PROJECT_PROFILE.json`
5. Authorized issues and decisions
6. Implementation and operational observations
7. Generated agent context

Conversation and generated files are evidence inputs, not automatic authority.

## Operational loop

```text
reconcile -> select -> validate -> claim -> assemble bounded context -> dispatch -> observe -> evaluate -> stress test when required -> record evidence -> disposition -> release claim -> repeat
```

## Startup

1. Verify `.iepe/protocol-reference.json` and `PROJECT_PROFILE.json` against the pinned IEPE revision.
2. Inspect repository, documentation, work graph, claims, dependencies, tests, and evidence without mutation.
3. Reconcile contradictions and missing authority.
4. Select only a complete Ready issue.
5. Claim bounded scope, assemble minimal context, dispatch, evaluate, record, and release.

The first agent cycle is read-only reconciliation. Do not infer mutation authority from repository access.

## Status honesty

`Documented != Implemented != Tested != Empirically Validated`

Artifact existence, a passing API call, or completion language does not establish qualification.

## Process routing

Use the narrowest procedure under `.agents/skills/`: initialize, reconcile, operate, qualify, stress test, or maintain the package. These procedures are projections from the pinned IEPE revision and cannot expand local authority.

## Protected actions

Read `PROJECT_PROFILE.json`. Protected actions require its named promotion authority and issue-level authorization.

## Stop conditions

Stop and record a typed result when authority, ownership, context, dependencies, permissions, evidence, evaluator availability, provider health, or recovery becomes ambiguous. Stop when capacity or retry limits are exhausted. Silence is not approval.


--- FILE: .agents/skills/initialize-iepe-project/SKILL.md (27 lines, 1.8 KiB) ---
---
name: initialize-iepe-project
description: Initialize a new project under IEPE or inspect an existing project for adoption. Use when starting a project, creating its agent operating layer, adopting IEPE, generating a project profile, or preparing the first agent cycle.
---

# Initialize an IEPE Project

Read `docs/INITIALIZATION.md` and `docs/UPSTREAM_REFERENCE.md` from the pinned IEPE Core source.

IEPE adoption follows a two-stage pattern: **reconcile first, then apply**.

### Universal Inputs Required
- `target_project`, `project_mode` (`new` | `existing`), `iepe_source`, `iepe_revision` (immutable tag/digest), `project_intent`, `work_graph_provider`, `mutation_authority`, `protected_actions`.

### Existing Project Adoption (Two-Stage)
1. **Stage 1 (Reconcile):** Execute read-only discovery using `tools/init_project.py existing --project-root <TARGET_PROJECT_ROOT>`. Reconstruct intent provenance (established, inferred, proposed, observed, unresolved), map authority, reconcile work graph, and propose the IEPE overlay. Do not modify files.
2. **Stage 2 (Apply):** Once the reconciliation report and adoption plan are approved, apply the overlay under explicit mutation authority on an isolated branch. Preserve existing valid local authority.

### New Project Initialization
1. Require project ID, name, originating intent, IEPE source, and immutable revision.
2. Run `tools/init_project.py new` from the pinned IEPE source.
3. Preserve existing files unless the user explicitly authorizes replacement.
4. Validate the protocol reference and project profile.
5. Complete the initialization gates before making an issue Ready.
6. Hand off to the first operational agent with `.agents/NEW_AGENT_PROMPT.md` for read-only reconciliation.

Return created or inspected artifacts, unresolved authority, evidence gaps, and the next authorized action.


--- FILE: .agents/skills/maintain-iepe-package/SKILL.md (14 lines, 1.0 KiB) ---
---
name: maintain-iepe-package
description: Compile, validate, or update an IEPE Agent Project Package and its upstream protocol pin. Use when canonical sources, skills, adapters, schemas, or IEPE versions change, or when generated context is stale.
---

# Maintain an IEPE Package

Read `docs/AGENT_PROJECT_PACKAGE.md` and `docs/UPSTREAM_REFERENCE.md` from the pinned source.

Repair contradictions in canonical project sources, then compile the package. Never edit generated context as an authority fix. Retain source roles, ranks, state, hashes, skills, adapters, exclusions, protocol identity, and revision.

For a protocol update, compare revisions, run upstream conformance, validate the local profile, reconcile schema and adapter changes, and exercise one reversible coordinator cycle. Change the pin only after qualification.

Release classification requires clean declared source state. Package integrity does not prove semantic correctness or empirical validity.


--- FILE: .agents/skills/operate-iepe-project/SKILL.md (19 lines, 1.0 KiB) ---
---
name: operate-iepe-project
description: Run the IEPE coordinator loop for authorized project work. Use when selecting, claiming, dispatching, evaluating, recording, and closing agent-executed issues under a project profile.
---

# Operate an IEPE Project

Read `docs/COORDINATOR.md` from the pinned IEPE source and the local `PROJECT_PROFILE.json`.

Run the state sequence:

```text
preflight -> reconcile -> select -> validate -> claim -> assemble context
-> dispatch -> observe -> evaluate -> disposition -> record -> close loop
```

Require a complete Ready issue before a claim. Bind each dispatch to issue, claim, context digest, worker, role, permissions, and attempt. Do not expand permissions through an adapter. Preserve negative and inconclusive results. Release the claim at terminal disposition.

Stop with a typed blocker when any gate loses authority, context, ownership, dependency validity, permission, evaluator availability, provider health, or recovery.


--- FILE: .agents/skills/qualify-iepe-outcome/SKILL.md (18 lines, 1.0 KiB) ---
---
name: qualify-iepe-outcome
description: Qualify IEPE artifacts and worker results against declared evidence before status or maturity promotion. Use for completion review, evidence intake, promotion decisions, release readiness, or claims that work is done, tested, verified, or validated.
---

# Qualify an IEPE Outcome

Bind every assertion to the issue, candidate, environment, evaluator, provenance, and reproduction method. Distinguish artifact existence from evaluation and evaluation from empirical validation.

Use the weakest justified maturity when evidence differs across dimensions:

```text
Documented != Implemented != Tested != Empirically Validated
```

Missing provenance, required dimensions, evaluator independence, reproduction, or protected-action authority blocks promotion. Retain failed, negative, bounded, and inconclusive outcomes.

Return an evidence bundle, qualification, limitations, evidence gaps, promotion recommendation, and named authority required for any next promotion.


--- FILE: .agents/skills/reconcile-iepe-project/SKILL.md (14 lines, 1.1 KiB) ---
---
name: reconcile-iepe-project
description: Reconcile an IEPE project's canonical documents, work graph, claims, implementation, reviews, deployments, and evidence. Use for a new agent's first cycle, stale project state, migration, contradiction review, or selecting the next Ready issue.
---

# Reconcile an IEPE Project

Begin read-only. Verify the pinned protocol, local profile, authority chain, repository or workspace identity, work graph, dependency state, claims, implementation, reviews, deployments, and evidence.

Classify findings as established, inferred, proposed, observed, or unresolved. Observation does not grant authority. Record contradictions, stale claims, incomplete issue contracts, unsupported maturity, and protected actions.

Return a typed reconciliation result with verified identities, discrepancies and provenance, blockers and required authority, material unknowns, the first candidate Ready issue, and mutations that remain unauthorized.

Do not repair state during the reconciliation pass unless mutation authority was explicitly included in the issue contract.


--- FILE: .agents/skills/stress-test-iepe-candidate/SKILL.md (12 lines, 0.9 KiB) ---
---
name: stress-test-iepe-candidate
description: Apply IEPE epistemic stress testing to a frozen candidate using designed perturbations and sealed World Cards. Use when consequential results may depend on unknown variables, hidden conditions, alternate environments, or untested assumptions.
---

# Stress Test an IEPE Candidate

Read `docs/EPISTEMIC_STRESS_TESTING.md` from the pinned IEPE source. Freeze the qualified candidate before revealing designed perturbations. Define protected invariants, surprise budget, evaluator, evidence, and stop conditions.

Use sealed World Cards when the test depends on withheld conditions. Record each result as robust, adaptable, bounded, fragile, unsafe, or unknown. Update the unknown-variable ledger and robustness profile.

Do not use synthetic trials to claim human outcomes. Stop when a perturbation crosses consent, safety, identity, factual, or promotion boundaries.


--- FILE: INTENT.md (36 lines, 1.6 KiB) ---
# Semantic Expression System Intent

## Purpose

Define a protocol-neutral semantic interface representation and governed expression architecture that lets one stable interface meaning produce radically different rendered interfaces without duplicating application logic or fragmenting component behavior.

## Beneficiaries

- Interface architects defining reusable semantic contracts
- Application teams that need multiple visual realizations without duplicated behavior
- Renderer and framework implementers consuming a renderer-neutral interface representation
- Accessibility and conformance evaluators checking that expression freedom preserves meaning

## Protected qualities

- Stable semantic identity across expressions
- Stable operation identity and required behavior
- Accessibility relationships, logical order, and required reachability
- Deterministic resolution and inspectable provenance
- Renderer and protocol neutrality
- Explicit security and performance boundaries

## Exclusions

- Application business logic, transport, persistence, synchronization, and product navigation
- Product branding or a mandatory frontend framework
- Implicit renderer-specific semantic branches
- External publication, deployment, spending, or production authority during local qualification

## Success evidence

- Canonical semantic, expression, projection, and conformance contracts
- Machine-readable positive and negative fixtures with typed evidence
- A pure resolver and renderer-neutral output path
- Local validator, resource, accessibility, responsive, security, and performance checks
- A traceable candidate bundle whose maturity and evidence gaps are explicit


--- FILE: PROJECT_PROFILE.json (57 lines, 1.2 KiB) ---
{
  "$schema": "https://iepe.dev/schema/project-profile.schema.json",
  "authorityOrder": [
    "INTENT.md",
    "docs/EXPERIENCE.md",
    "docs/ARCHITECTURE.md",
    "PROJECT_PROFILE.json",
    "AGENTS.md"
  ],
  "coordinator": {
    "capacity": 1,
    "identity": "coordinator.local",
    "stopPolicyRef": "AGENTS.md#stop-conditions"
  },
  "evaluators": [
    "documentation.conformance",
    "schema.validation"
  ],
  "id": "ses",
  "intentRefs": [
    "INTENT.md"
  ],
  "memory": {
    "institutional": "docs",
    "negativeResults": "docs/NEGATIVE_RESULTS.md",
    "operational": "work"
  },
  "name": "Semantic Expression System",
  "profileStatus": "release",
  "promotionAuthorities": [
    "unassigned"
  ],
  "protectedActions": [
    "external-publication",
    "production-deployment",
    "spending",
    "destructive-migration",
    "credential-or-iam-change",
    "authoritative-intent-change",
    "external-communication"
  ],
  "protocol": {
    "protocolId": "IEPE-001",
    "protocolVersion": "0.2.0",
    "revision": "56f82de8cca122cc4d347cdd55bb32bdcd31ed27",
    "source": "https://github.com/zachshallbetter/IEPE"
  },
  "workGraph": {
    "projectRefs": [
      "work"
    ],
    "provider": "local"
  },
  "workspaces": [
    "."
  ]
}


--- FILE: README.md (287 lines, 16.2 KiB) ---
# SES (Semantic Expression System)

[![License](https.img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![Protocol](https://img.shields.io/badge/Protocol-IEPE--001_Conforming-green.svg)](./PROJECT_PROFILE.json)
[![Specification](https://img.shields.io/badge/Specification-v1.0.0_Release-orange.svg)](./docs/SES-SPECIFICATION.md)

> **Version:** 1.0.0 Release Standard  
> **Status:** Protocol-Neutral Architecture Specification + Qualified Implementation Candidate  
> **Target:** 2D Interface Architecture for Radical Visual Expression  

---

**SES (Semantic Expression System)** is a protocol-neutral architecture for separating interface **meaning** from interface **expression**.

Its intent is to let a single stable semantic interface definition produce radically different rendered interfaces without duplicating application logic or fragmenting component behavior.

---

## 🎯 The Core Problem

Traditional UI architectures tightly couple interface semantics with layout and visual structure. As a result, changing presentation topology often forces developers to rewrite component templates, duplicate business logic, or break behavioral contracts.

**SES addresses a fundamental design challenge:**

> *How can an interface preserve what it means and what it does, while allowing nearly everything about how it looks and arranges itself to change?*

---

## 🏗 Architecture Overview

SES answers this challenge by strictly separating three core architectural concerns:

```mermaid
graph TD
    A[Application Data & State] --> B[Semantic Model]
    B -->|Element, Slot, Block, Socket, Composition| C[Projection Contract]
    C -->|Preserve, Transform, Omit, Introduce, Invariance| D[Expression Model]
    E[Visual Language / Theme / Recipes] --> D
    D --> F[Resolver & Compiler]
    F --> G[Host Renderer DOM / CSS / Native View Tree]
```

### 1. Semantic Model (Interface Identity)

Defines **what exists**, what content belongs where, what structures are compatible, what actions are available, and what relationships must remain stable:

* **Element:** Smallest semantic leaf node (e.g., heading, image, button) owning atomic function while leaving visual identity open to expression.
* **Slot:** Named insertion point inside a Block with cardinality and type constraints, deliberately leaving layout, orientation, and presentation to Visual Language recipes.
* **Block:** Cohesive semantic component containing Slots and operations (e.g., MediaCard) without hardcoding layout topology or visual geometry.
* **Socket:** Flexible structural boundary accepting compatible Blocks inside a Composition without mandating fixed grid geometry.
* **Composition:** High-level structural arrangement (e.g., screen, view, dashboard) declaring content priorities and responsive importance.
* **Variant & State:** Functional states (`hover`, `pressed`, `disabled`) and variants decoupled from aesthetic representation.
* **Operation:** Typed action identities exposed by elements/blocks (`open-media`, `enter-world`).

### 2. Expression Model (Graphical Realization)

Defines **how semantic structures are visually expressed** with maximum design freedom:

* **Visual Language:** The overall graphical grammar and aesthetic guidelines governing presentation.
* **Theme:** Concrete system parameters and design values (color schemes, typography scales, density).
* **Recipe:** Flexible blueprint mapping semantic structures to visual layouts and appearance layers.
* **Morphology:** Unconstrained spatial arrangement, orientation, distribution, and structural topology mutation.
* **Appearance:** Multi-layered visual rendering (backgrounds, textures, patterns, targeted edges, masks, ornament).
* **Tokens & Assets:** Primitive, semantic, and role-based design values along with fonts/icons/textures.
* **Motion:** Animation and transition behavior tied to state transitions.

### 3. Projection Contract (Governed Boundary & Expression Freedom)

Declares the explicit boundary and transformation permissions between semantic meaning and visual expression:

* **`preserve`**: Core semantic identities and accessibility relationships that remain stable.
* **`transform`**: Presentation properties granted complete freedom to mutate (e.g., orientation, enclosure, background, edge language).
* **`mayOmit` / `mayIntroduce`**: Explicit rules permitting optional content omission or decorative artwork introduction.
* **Invariance Profiles**: Configurable profiles (`required`, `bounded`, `free`) across semantic, behavioral, action, structural, morphological, and visual dimensions—allowing teams to grant total morphological (`free`) and visual (`free`) expression freedom.
* **Failure Conditions**: Explicit safety triggers preventing visual flexibility from accidentally breaking core interactive contracts.

> [!IMPORTANT]
> **The Essential SES Guarantee:**  
> A conforming expression may radically transform presentation and topology, but it may not silently redefine the semantic contract it is expressing.

---

## 💡 SES vs. Traditional Approaches

| Dimension | Conventional Design System | Theme Engine | Headless UI | Semantic Expression System (SES) |
| :--- | :--- | :--- | :--- | :--- |
| **Primary Focus** | Fixed components & style tokens | Value overrides (colors, font size) | Behavior & unstyled DOM structure | Decoupled intermediate representation of meaning & expression |
| **Layout Topology** | Rigid component template | Fixed layout with value changes | Freeform markup per developer | Governed presentation topology via Morphology & Recipes |
| **Visual Variation** | Restricted to component props | Value-level mutation (dark/light) | Custom implementation required | Unbounded visual expression bounded by Projection Contracts |
| **Semantic Integrity** | Embedded in component code | Maintained by hardcoded DOM | Left entirely to developer | Formally guaranteed via Invariance Profiles & Failure Conditions |

### Topology Mutation vs. Value Mutation

Theme systems typically alter basic values:
$$\text{dark} \to \text{light} \quad \mid \quad \text{blue} \to \text{red} \quad \mid \quad 12\text{px radius} \to 4\text{px radius}$$

SES permits controlled changes to **presentation topology**:

* Vertical $\to$ Horizontal
* Contained surface $\to$ Full-bleed artwork
* Regular grid $\to$ Asymmetric overlap
* Bordered container $\to$ Target-edged layered texture
* Image-above $\to$ Image-behind / Layered depth

---

## 🖼 Concrete Example: MediaCard Transformation

A semantic `MediaCard` block defines required slots: `media`, `title`, `subtitle`, `metadata`, `badge`, `action`.

Depending on the active **Visual Language** and **Recipe**, SES can render this identical semantic structure in completely distinct ways without changing application code:

```text
Visual Language A (Editorial Standard):
┌───────────────────────────────┐
│ [IMAGE]                       │
│ Title                         │
│ Subtitle · Meta               │
└───────────────────────────────┘

Visual Language B (Cyberpunk Layered):
┌───────────────────────────────────────────┐
│ TITLE                              BADGE  │
├───────────────────────────────────────────┤
│ [FULL-BLEED TEXTURED IMAGE]               │
├───────────────────────────────────────────┤
│ META                               ACTION │
└───────────────────────────────────────────┘

Visual Language C (Minimal Asymmetric):
┌───────────────────────────────────────────┐
│ Title & Subtitle             [IMAGE RIGHT]│
│ ACTION · META                             │
└───────────────────────────────────────────┘
```

The semantic identity remains `MediaCard` across all three presentations.

---

## 💻 Code Example

Below is an abbreviated snippet demonstrating how a semantic block and composition are defined using the SES schema ([docs/schemas/ses-schema.ts](./docs/schemas/ses-schema.ts)):

```typescript
import type { BlockDefinition, CompositionDefinition } from "./schemas/ses-schema";

// 1. Semantic Block Definition
export const MediaCard: BlockDefinition = {
  id: "media-card",
  name: "Media Card",
  kind: "content",
  semanticRole: "media-content-summary",
  states: ["default", "hover", "focus", "selected", "disabled"],
  operations: ["open-media"],
  slots: [
    { id: "media", name: "Media", semanticRole: "media", cardinality: "one", content: { type: "element", accepts: ["image"] } },
    { id: "badge", name: "Badge", semanticRole: "annotation", cardinality: "optional", content: { type: "element", accepts: ["badge"] } },
    { id: "title", name: "Title", semanticRole: "title", cardinality: "one", content: { type: "element", accepts: ["heading", "label"] } },
    { id: "action", name: "Action", semanticRole: "action", cardinality: "optional", content: { type: "element", accepts: ["button"] } },
  ],
  behavior: { interactive: true, navigable: true },
};

// 2. Composition with Projection Constraints
export const HomeHeroSocket: CompositionDefinition = {
  id: "home",
  name: "Home Screen",
  type: "screen",
  sockets: [
    {
      id: "home.hero",
      name: "Hero Socket",
      semanticRole: "primary-introduction",
      accepts: ["media-card"],
      multiplicity: "single",
      invariance: {
        semantic: "required",
        behavioral: "required",
        actionIdentity: "required",
        structural: "bounded",
        morphological: "free",
        visual: "free",
      },
      projection: {
        preserve: ["identity", "primary-action", "accessibility-order"],
        transform: ["orientation", "media-placement", "enclosure", "background", "edges", "texture"],
        failureConditions: ["primary-action-unexposed", "required-content-unreachable"],
      },
    },
  ],
};
```

---

## 📚 Specification & Documentation Index

The full specification is modularly organized in the [`docs/`](./docs) directory:

| Document | Description |
| :--- | :--- |
| 📖 [**SES Specification Overview**](./docs/SES-SPECIFICATION.md) | Complete comprehensive specification document |
| 📄 [**01. Definition & Terminology**](./docs/01-definition.md) | Canonical definitions, core principles, and terminology |
| 📄 [**02. Semantic Model**](./docs/02-semantic-model.md) | Elements, Slots, Blocks, Sockets, Compositions, States, and Operations |
| 📄 [**03. Expression Model**](./docs/03-expression-model.md) | Visual Languages, Themes, Recipes, Morphology, and Appearance |
| 📄 [**04. Token System**](./docs/04-token-system.md) | Token layering (primitive, semantic, role, recipe), resolution, and assets |
| 📄 [**05. Projection Contract**](./docs/05-projection-contract.md) | Preservation, transformation, invariance profiles, and failure conditions |
| 📄 [**06. Runtime & Rendering**](./docs/06-runtime-and-rendering.md) | Resolver cascade, evaluation lifecycle, and host renderer contracts |
| 📄 [**07. Conformance**](./docs/07-conformance.md) | Validation levels, conformance matrix, and test fixtures |
| 📄 [**08. Implementation Boundary**](./docs/08-implementation-boundary.md) | Boundaries between protocol, host applications, and implementations |
| 📋 [**TypeScript Canonical Schema**](./docs/schemas/ses-schema.ts) | Canonical TypeScript definitions for SES structures |
| 📋 [**JSON Interchange Schema**](./docs/schemas/ses.schema.json) | Standard JSON Schema for interchange format |
| 🧪 [**SES-001 Invariant Matrix**](./docs/conformance/ses-001-matrix.json) | Canonical 6-layer invariant matrix & negative fixture plan |
| 💡 [**Full Code Example**](./docs/examples/home-example.ts) | End-to-end TypeScript example of semantic & expression models |
| 📜 [**Changelog**](./docs/CHANGELOG.md) | Revision history and specification updates |

---

## 📂 Repository Structure

```text
Semantic-Expression-System/
├── INTENT.md                   # Originating System Intent & Design Mission
├── AGENTS.md                   # Master Agent & Contributor Operating Contract
├── PROJECT_PROFILE.json        # IEPE Integration Profile & Authority Order
├── LICENSE                     # Apache-2.0 Open Source License
├── README.md                   # Top-level System Architecture & Index
├── ROADMAP.md                  # Milestone & Release Roadmap
├── docs/                       # Modular Specifications, Schemas, & Conformance Suite
│   ├── SES-SPECIFICATION.md    # Complete Combined Specification Document
│   ├── 01-definition.md ... 25 # Core Architecture Chapters (01–25)
│   ├── schemas/                # Canonical TypeScript & JSON Interchange Schemas
│   ├── conformance/            # Conformance Fixtures, Matrices, & Evaluation Plans
│   └── examples/               # Worked Worked Examples & Reference Snippets
├── tools/                      # Conformance Validation & Resolution Suite (20 tools)
├── scripts/                    # Context Corpus Exporter (`gen-llms.py`)
├── work/                       # Operational Work Graph (`GRAPH.md`) & Issues (SES-001..SES-040)
├── evidence/                   # Empirical Verification Logs (`SES-xxx-evidence.json`)
├── .agents/                    # Agent Package, Context Corpus (`llms.txt`), & Skills
└── .github/workflows/          # CI Pipeline Automation (`ci.yml`)
```

### Key Subsystems & Roles

| Path | Purpose & Contents |
| :--- | :--- |
| 📜 [**`INTENT.md`**](./INTENT.md) | Canonical statement of originating system intent and problem formulation |
| 📜 [**`AGENTS.md`**](./AGENTS.md) | Operational and architectural contract for human and AI contributors |
| 📋 [**`PROJECT_PROFILE.json`**](./PROJECT_PROFILE.json) | IEPE protocol metadata, evaluators, and protected action boundaries |
| ⚖️ [**`LICENSE`**](./LICENSE) | Apache License 2.0 open-source license grant |
| 📚 [**`docs/`**](./docs) | Formal specification chapters, TypeScript/JSON schemas, and conformance definitions |
| 🛠 [**`tools/`**](./tools) | 20 deterministic validation tools covering recipe resolution, accessibility, security, and rendering |
| ⚡️ [**`scripts/`**](./scripts) | Automation scripts including `gen-llms.py` context corpus generator |
| 📊 [**`work/`**](./work) | Complete work graph tracking all 40 specification development issues |
| 🧾 [**`evidence/`**](./evidence) | Audit ledger containing empirical verification results for all qualification claims |
| 🤖 [**`.agents/`**](./.agents) | Agent package source, IEPE skills, and generated searchable corpus (`llms.txt`, `llms-full.txt`) |

---

## 🎯 Scope & Boundaries

### In Scope

* Semantic UI structures and component contracts
* Content insertion contracts (Slots) and composition boundaries (Sockets)
* Visual language definition, theme parameters, and token resolution
* Recipe resolution, layout mutation (Morphology), and appearance composition
* Layered backgrounds, textures, patterns, targeted edges, masks, and bleed
* Iconography, ornament, and motion treatment
* Responsive and accessibility-preserving expression rules
* Conformance validation and failure triggers

### Out of Scope

* Application business logic and domain data models
* Network transport protocols and remote synchronization
* Database storage and content management systems
* 3D graphics environments and spatial computing mechanics
* Specific host web/native UI frameworks (React, SwiftUI, Flutter, etc.)

---

## 📜 Summary Statement

> **SES is a semantic interface representation and expression architecture for defining reusable interface meaning independently from graphical realization.**  
> It provides typed semantic structures, projection contracts, replaceable visual grammars, and deterministic expression rules so multiple radically different interface realizations can share the same underlying application semantics and behavior.


--- FILE: ROADMAP.md (19 lines, 0.8 KiB) ---
# Semantic Expression System Roadmap

## M0: Governed baseline

Exit evidence:

- intent, beneficiaries, protected qualities, exclusions, and success evidence are confirmed
- project profile and protocol pin conform
- zero-state or operational baseline is recorded
- one material unknown is registered
- one bounded, reversible issue is Ready

## M1: First qualified outcome

Define after M0. Express the milestone as observable capability and exit evidence rather than a feature inventory.

## Readiness reconciliation

`docs/25-accountability-and-readiness.md` is the canonical reconciliation of current lessons, maturity claims, material unknowns, and implementation gates. SES-040 records the first locally qualified implementation candidate. The repository is not production-ready or empirically validated.


--- FILE: docs/01-definition.md (70 lines, 2.6 KiB) ---
# 1. Canonical Definition

## 1.1 Semantic Expression System

The Semantic Expression System is a semantic composition architecture in which Elements provide atomic behavior, Slots define named content relationships inside reusable Blocks, Sockets define typed participation boundaries for Blocks inside larger structures, and Compositions define screen-level semantic organization.

Visual Languages provide replaceable graphical grammars. Themes configure those grammars. Recipes map semantic objects to presentation. Morphology controls structural visual organization. Appearance controls layered graphical construction. Tokens and assets provide the resolved values and resources used by the renderer.

A Projection Contract sits between semantic structure and visual expression. It declares which properties must be preserved, which may be transformed, which may be omitted, which presentation-only properties may be introduced, which operations must remain exposed, and which conditions invalidate the projection.

## 1.2 Goal

SES is designed for extreme visual mutation without semantic or behavioral fragmentation.

The same semantic interface may be expressed as a restrained digital product, printed editorial system, dense technical console, handmade paper interface, high-key futurist product, or another visual language without branching into language-specific application screens.

## 1.3 Invariants

The following are semantic by default and should remain stable across Visual Languages unless a contract explicitly permits otherwise:

- semantic role
- data identity
- Block identity
- Slot identity
- Socket identity
- operation identity
- required content
- accessibility relationships
- state meaning
- business behavior
- routing intent
- responsive importance
- content priority

## 1.4 Mutable expression

The following are expression concerns and may vary radically:

- color
- typography
- spacing
- density
- shape
- radius
- clipping
- internal layout
- media placement
- container backgrounds
- layered backgrounds
- custom imagery
- surface material
- targeted edges
- partial edges
- edge imagery
- textures
- patterns
- masks
- blend modes
- ornament
- image treatment
- icon family
- shadow and glow
- section framing
- navigation appearance
- motion
- responsive visual topology

## 1.5 Governing rule

If Neo-Edo, Western Comics, Cybernetic Minimalism, Neo-Capsule Futurism, and MangaVerse Core could reasonably disagree about a visual property, that property belongs in a token, recipe, morphology rule, appearance rule, or Visual Language grammar rather than being hard-coded into a semantic Element or Block.


--- FILE: docs/02-semantic-model.md (133 lines, 4.1 KiB) ---
# 2. Semantic Model

## 2.1 Element

An Element is the smallest semantically meaningful interface object.

Examples include Button, IconButton, Heading, Text, Image, Avatar, Badge, Tag, Input, Select, Checkbox, Switch, Progress, Divider, Rating, and Price.

An Element owns semantics, accessibility, interaction behavior, and content requirements. It should own as little visual identity as possible.

A Button knows that it is actionable and may be primary, destructive, disabled, loading, focused, or pressed. It does not inherently know that it is a pill, ink strip, chrome capsule, square plate, or paper tab.

## 2.2 Slot

A Slot is a named semantic insertion point inside a Block.

A Slot answers: what kind of content belongs here?

Examples include media, title, subtitle, eyebrow, description, leading, trailing, meta, badge, status, actions, footer, overlay, avatar, icon, progress, and price.

A Slot does not prescribe presentation. `slot="media"` means that the content is primary media for the Block. It does not require a specific position, crop, aspect ratio, border, or enclosure.

## 2.3 Block

A Block is a reusable semantic composition of Elements and Slots.

Examples include MediaCard, Hero, Stat, NavigationItem, SearchField, Post, SeriesItem, WorldItem, ActivityItem, SectionHeader, PriceBlock, ProfileSummary, and ProgressSummary.

A Block defines:

- semantic role
- supported Slots
- required and optional content
- semantic ordering
- behaviors
- variants
- states
- operation relationships
- responsive importance
- accessibility relationships

A Block does not completely prescribe its graphical topology.

## 2.4 Socket

A Socket is a named, typed participation boundary within a Block or Composition.

A Socket declares the semantic role of a region, the Blocks it may receive, multiplicity, importance, required operations, invariants, and the transformations permitted during visual projection.

A Slot governs content participation inside a Block. A Socket governs Block participation inside a larger semantic structure.

A Socket is not a coordinate, column, card shell, or CSS grid area. Those are presentation decisions supplied by a Recipe.

A Socket may declare:

- accepted Block identities or capabilities
- single, optional, or repeating participation
- minimum and maximum participants
- content importance
- semantic and behavioral invariants
- structural and morphological freedom
- required operation exposure
- responsive preservation rules
- projection failure conditions

## 2.5 Composition

A Composition is the semantic arrangement and relationship of Sockets for a screen, page, shell, flow, or section.

A Composition defines information hierarchy and participation, not a fixed pixel layout.

A Home Composition might declare Sockets for navigation, utility, hero, statistics, journey, trending, worlds, activity, community, library, closing action, and footer. A Visual Language may render those as rails, panels, printed fields, overlapping editorial regions, or borderless sections while preserving their semantic contracts.

## 2.6 Variant

A Variant is a semantic specialization of an Element or Block.

Examples:

```text
Button
  primary
  secondary
  destructive
  quiet

Card
  default
  featured
  promotional
  interactive

Badge
  status
  category
  live
```

Variants must not encode Visual Language identity. `westernButton`, `edoCard`, and `cyberBadge` are invalid architectural patterns.

## 2.7 State

A State represents interaction or application condition.

Canonical state vocabulary may include:

```text
default
hover
focus
pressed
selected
active
disabled
loading
error
success
warning
read
unread
owned
locked
```

States have stable semantic meaning. The active Visual Language determines how each state is expressed.

## 2.8 Operation

An Operation is a semantic action exposed by the interface.

Examples include open-series, save, purchase, continue-reading, view-all, dismiss, search, submit, and navigate-home.

Operation identity must remain separate from visual signaling. A projection may alter how an operation is signaled, but required operations may not silently disappear because of theme styling.


--- FILE: docs/03-expression-model.md (127 lines, 3.8 KiB) ---
# 3. Expression Model

## 3.1 Visual Language

A Visual Language is the highest-level 2D graphical grammar in SES.

It defines the coherent rules by which semantic structure is expressed, including palette, typography, spacing, morphology, shape, surface, edge, texture, pattern, image treatment, iconography, depth, ornament, controls, navigation, and motion.

A Visual Language is broader than a palette or conventional design-system theme.

## 3.2 Theme

A Theme is a concrete configuration of a Visual Language.

Example:

```text
Visual Language: Neo-Edo
Themes:
  Neo-Edo / Ink
  Neo-Edo / Vermilion
  Neo-Edo / Moon
  Neo-Edo / Winter
```

A Theme may override tokens and selected Recipes, but should preserve the defining grammar of its Visual Language. If a configuration replaces most of the typography, surface philosophy, shape grammar, image treatment, edge system, morphology, and motion character, it is likely a separate Visual Language.

## 3.3 Recipe

A Recipe maps a semantic target to presentation behavior.

Recipe targets may include:

- Elements
- Blocks
- Sockets
- Compositions
- Slots within Blocks
- States and Variants

A Recipe may define layout, morphology, appearance, typography roles, image treatment, responsive behavior, and state overrides.

Recipes should be declarative data where practical. Theme-specific JSX branches are an anti-pattern.

## 3.4 Morphology

Morphology describes the structural visual organization of an interface independently from its decorative appearance.

Morphology may define:

- hierarchy
- topology
- density
- rhythm
- alignment
- symmetry
- enclosure
- continuity
- direction
- visual weight
- overlap
- fragmentation
- stacking
- grouping

This distinction allows two themes to use identical colors and still differ substantially because their spatial organization, enclosure, rhythm, and hierarchy differ.

## 3.5 Appearance

Appearance is the layered graphical construction of a resolved semantic object.

Appearance must support full and custom construction rather than only flat surface aliases.

An Appearance Recipe may contain:

```text
background layers
surface material
texture layers
pattern layers
edge layers
decoration layers
image treatment
mask
clip
bleed
overflow
blend modes
opacity
z-order
filtering
backdrop effects
```

### Backgrounds

Backgrounds are ordered layers. A container may combine color, gradients, textures, patterns, images, generated artwork, or custom assets.

Backgrounds must be available at Composition, Socket, Block, Slot, and Element levels when the active grammar permits them.

### Textures

Textures describe material character, such as paper fiber, grain, noise, canvas, metal, scratches, ink bleed, or scan artifacts.

### Patterns

Patterns describe intentional repeated graphical structure, such as halftone, screentone, crosshatch, grid, stripes, dots, waves, speedlines, or cultural geometric motifs.

Texture and pattern are separate concepts and may be layered independently.

### Edges

Edges are first-class layered structures rather than simple borders.

An edge layer may target all sides or any subset of top, right, bottom, and left. It may be solid, hairline, double, dashed, ink, brush, deckle, torn, technical, engraved, glowing, embossed, image-based, offset, partial, or custom.

Multiple edge layers may exist simultaneously.

### Decorations

Decorations are non-semantic graphical additions such as seals, brush marks, registration marks, ticks, flourishes, corner graphics, panel numbers, rivets, engraving, or custom illustrations.

Decorations must not create accessibility meaning by themselves.

### Bleed

A Recipe may intentionally allow background, media, edge, or decoration layers to extend beyond a nominal container boundary. Bleed behavior must be explicit and must not obscure required interaction or focus indicators.


--- FILE: docs/04-token-system.md (115 lines, 2.3 KiB) ---
# 4. Token System

SES uses a layered token architecture. Tokens provide values. Recipes decide where and how those values are used.

## 4.1 Token levels

```text
Primitive Tokens
      |
Semantic Tokens
      |
Role Tokens
      |
Recipe Tokens
      |
Resolved Tokens
```

## 4.2 Primitive tokens

Primitive tokens are raw values with no interface semantics.

Examples:

```text
color.violet.600
space.4
radius.16
font.outfit
duration.200
shadow.3
```

Semantic components should not consume primitive tokens directly except in low-level infrastructure.

## 4.3 Semantic tokens

Semantic tokens describe stable meaning:

```text
color.canvas
color.surface
color.text.primary
color.text.secondary
color.accent.interaction
color.status.success
color.status.warning
color.status.danger
```

## 4.4 Role tokens

Role tokens describe interface context:

```text
surface.page
surface.navigation
surface.card
surface.card.featured
edge.card
edge.input
edge.navigation
text.heading
text.card.title
space.section
space.card
space.control
```

## 4.5 Recipe tokens

Recipe tokens are aliases introduced for specific semantic targets:

```text
media-card.surface
media-card.edge
media-card.gap
media-card.media.aspect
button.primary.surface
button.primary.edge
button.primary.shape
```

These may be generated or resolved from the active Visual Language and Theme.

## 4.6 Resolved tokens

Resolved tokens are host-ready values emitted after the cascade is complete. In a web renderer they may become CSS custom properties. In another host they may become a typed style object or native resource table.

## 4.7 Assets

A Visual Language may provide an asset registry for:

- fonts
- icons
- textures
- patterns
- masks
- edge images
- background images
- ornaments
- custom illustrations
- SVG fragments
- shaders or filters where supported by the renderer

Recipes reference asset IDs rather than arbitrary file paths when portability matters.

## 4.8 Token rules

1. Components consume semantic or role aliases, not theme-specific raw values.
2. Tokens should not encode full component topology.
3. Recipes may derive aliases from primitives and semantic tokens.
4. Theme overrides must resolve deterministically.
5. Missing required token references are conformance failures.
6. Accessibility overrides have higher precedence than ordinary theme styling.


--- FILE: docs/05-projection-contract.md (121 lines, 2.5 KiB) ---
# 5. Projection Contract

The Projection Contract governs the boundary between semantic structure and visual expression.

It exists to make radical mutation explicit and testable.

## 5.1 Responsibilities

A Projection Contract declares:

- semantic target
- identity and authority
- properties that must be preserved
- properties that may be transformed
- optional properties that may be omitted
- presentation-only properties that may be introduced
- required operations
- required operation exposure
- accessibility constraints
- responsive constraints
- tolerance where applicable
- failure conditions

## 5.2 Typed invariance

Preservation is typed. A projection may be semantically invariant while visually and morphologically different.

Recommended UI invariance dimensions:

```text
semantic
behavioral
actionIdentity
structural
morphological
visual
```

Each may be:

```text
required
bounded
free
```

A typical expressive application may require semantic, behavioral, and action identity invariance while allowing bounded structural change and free morphological and visual change.

## 5.3 Preserve, transform, omit, introduce

Example:

```ts
projection: {
  preserve: [
    "series-identity",
    "content-priority",
    "view-all-operation",
    "accessibility-order"
  ],

  transform: [
    "orientation",
    "media-placement",
    "enclosure",
    "spacing",
    "alignment",
    "surface",
    "edge",
    "texture"
  ],

  mayOmit: [
    "secondary-decoration",
    "nonessential-caption"
  ],

  mayIntroduce: [
    "ornament",
    "background-art",
    "pattern",
    "section-label-decoration"
  ]
}
```

## 5.4 Operation exposure

SES distinguishes operation existence from operation presentation.

At minimum, the runtime should preserve these distinctions:

```text
operation exists
operation is enabled
operation is exposed
operation is signaled
operation is invoked
operation succeeds or fails
```

A Theme may radically alter signaling. It may not silently remove required exposure.

## 5.5 Failure conditions

A projection is invalid if any declared failure condition occurs.

Common failures include:

- required Slot omitted
- required Socket unfilled
- incompatible Block admitted
- required operation unexposed
- focus indicator obscured
- semantic reading order invalidated
- accessibility name lost
- required content clipped or unreachable
- responsive layout violates minimum visibility
- unresolved token or asset reference
- recipe references unknown semantic identity
- theme-specific implementation changes business behavior


--- FILE: docs/06-runtime-and-rendering.md (123 lines, 2.5 KiB) ---
# 6. Runtime and Rendering

## 6.1 Resolver

The resolver is the technical center of SES.

Conceptually:

```ts
resolveExpression({
  language,
  theme,
  composition,
  socket,
  block,
  variant,
  slot,
  element,
  state,
  viewport,
  userStyleOptions,
  accessibility
})
```

The resolver produces a deterministic Resolved Expression containing tokens, layout, morphology, appearance, typography, image rules, motion, and host instructions.

## 6.2 Resolution order

Recommended cascade:

```text
Visual Language
      |
Theme
      |
User Style Options
      |
Composition Recipe
      |
Socket Recipe
      |
Block Recipe
      |
Variant Recipe
      |
Slot Recipe
      |
Element Recipe
      |
Semantic State
      |
Responsive State
      |
Accessibility Overrides
```

Later layers may alter expression. They may not rewrite semantic contracts.

## 6.3 Renderer

The renderer realizes the Resolved Expression in a host.

Possible hosts include:

- DOM + CSS
- React Native
- native desktop view trees
- game UI frameworks
- canvas or retained-mode 2D renderers

SES does not require DOM or CSS, though the web is a reference implementation target.

## 6.4 Web DOM contract

A web renderer should keep the semantic structure inspectable.

Example:

```html
<main
  data-composition="home"
  data-language="neo-edo"
  data-theme="vermilion"
>
  <section data-socket="trending" data-importance="primary">
    <article data-block="media-card" data-variant="featured">
      <div data-slot="media"></div>
      <div data-slot="title"></div>
      <div data-slot="meta"></div>
    </article>
  </section>
</main>
```

These attributes are inspection and styling hooks. Accessibility must continue to use correct native semantics and ARIA rather than relying on data attributes.

## 6.5 Compilation

Where possible, static portions of Visual Languages and Themes should be compiled ahead of runtime into:

- CSS variables
- classes
- style sheets
- lookup tables
- asset manifests
- recipe indexes

Runtime resolution should handle state, viewport, instance overrides, and dynamic content without recomputing the entire language.

## 6.6 Component implementation

Component is an implementation category, not an SES semantic level.

A React codebase may contain:

```text
components/elements
components/blocks
components/infrastructure
```

A component implementing an Element or Block should own semantic behavior, accessible structure, event handling, and stable data hooks. Visual Language conditionals should remain outside the component whenever they can be expressed through Recipes and tokens.


--- FILE: docs/07-conformance.md (99 lines, 2.8 KiB) ---
# 7. Conformance

SES uses layered conformance. Passing one layer does not imply another.

## S - Semantic Conformance

Checks that Element, Slot, Block, Socket, Composition, Variant, State, and Operation contracts are valid.

Examples:

- required Slots exist
- Socket admission is valid
- required operations are declared
- semantic identity is stable
- accessibility relationships exist

## C - Composition Conformance

Checks hierarchy, content priorities, repetition, responsive importance, and structural constraints.

## R - Recipe Conformance

Checks that every referenced Recipe, token, asset, morphology rule, and appearance rule resolves.

## A - Appearance Conformance

Checks backgrounds, textures, patterns, edges, masks, clipping, bleed, compositing, and decoration for valid construction and renderer support.

## I - Interaction Conformance

Checks keyboard interaction, focus order, focus visibility, operation exposure, disabled states, errors, recovery paths, and state behavior.

## V - Visual Validation

Checks reference renders, intended language fidelity, clipping, overlap, typography, density, and responsive rendering.

Visual validation does not prove semantic or interaction conformance.

## 7.1 Negative fixtures

The test suite should intentionally include invalid languages and themes.

Required negative cases include:

```text
missing required Slot
unknown Block in Socket
required operation hidden
unknown token
unknown asset
invalid edge target
mask covers focus state
background layer references missing source
mobile horizontal overflow
required content clipped
semantic order replaced by decorative order
state variant missing accessibility fallback
```

## 7.2 Language completeness

A language validator should be able to report coverage such as:

```text
Elements covered
Blocks covered
Sockets covered
Compositions covered
Token references valid
Assets valid
Required states covered
Reduced motion covered
High contrast fallback covered
Responsive recipes valid
```

## 7.3 Reference vectors

A project should maintain a small stable set of semantic Compositions rendered through multiple Visual Languages.

For example:

```text
Home + Core
Home + Neo-Edo
Home + Western Comics
Home + Cybernetic Minimalism
```

All must pass the same semantic and operation invariants even when their pixels and morphology differ substantially.

## 7.4 Canonical baseline

The traceable invariant matrix, fixture inventory, validation order, and scope boundary for this conformance model are defined in [09-conformance-baseline.md](09-conformance-baseline.md).

## 7.4 Canonical Matrix Artifact

The active invariant baseline and negative fixture plan is tracked in the repository artifact:
- [`docs/conformance/ses-001-matrix.json`](file:///Users/zachshallbetter/Projects/Semantic-Expression-System/docs/conformance/ses-001-matrix.json)


--- FILE: docs/08-implementation-boundary.md (71 lines, 1.6 KiB) ---
# 8. Protocol and Implementation Boundary

SES defines interface semantics and expression. It intentionally does not define a transport or synchronization protocol.

A separate protocol may define how SES definitions, instances, assets, state changes, or resolved expressions move between processes, repositories, tools, runtimes, or devices.

## 8.1 SES owns

- canonical semantic types
- Slot and Socket contracts
- Block and Composition definitions
- Visual Language structure
- Theme structure
- Recipe model
- Morphology model
- Appearance model
- token semantics
- asset references
- projection contracts
- resolver semantics
- conformance rules

## 8.2 A separate protocol may own

- serialization format
- transport
- remote references
- capability negotiation
- version negotiation
- patching and deltas
- persistence
- synchronization
- authoring messages
- asset delivery
- cache policy
- signatures
- authentication and authorization

## 8.3 IV implementation boundary

IV should be treated as a downstream implementation of SES, not the definition of SES.

The recommended relationship is:

```text
SES Specification
      |
SES Protocol
      |
IV Adapter / Runtime
      |
IV Components and Screens
```

The implementation may expose optimizations or host-specific extensions, but those extensions should be namespaced and must not silently redefine canonical SES semantics.

## 8.4 Versioning

Version independently:

```text
SES semantic schema
SES expression schema
SES protocol
Visual Languages
Themes
Renderer
IV implementation
```

Equal version numbers do not imply compatibility. Compatibility should be declared explicitly.


--- FILE: docs/09-conformance-baseline.md (69 lines, 5.1 KiB) ---
# 9. Canonical Conformance Baseline

Status: SES-001

This baseline defines the minimum conformance boundary connecting the semantic model, projection contract, expression model, schemas, and conformance documentation. It does not define a renderer or product implementation.

## Invariant matrix

| ID | Invariant | Authority | Evidence | Negative fixture |
|---|---|---|---|---|
| SEM-01 | Element, Block, Slot, Socket, and Composition identities remain stable | `02-semantic-model.md`; `schemas/ses-schema.ts` | IDs match between semantic input and every expression | `unknown-semantic-identity` |
| SEM-02 | Required Slots exist and receive compatible content | `BlockDefinition`; `SlotDefinition` | Cardinality and accepted content validate | `missing-required-slot`; `incompatible-slot-content` |
| SEM-03 | Socket admission, multiplicity, and bounds are valid | `SocketDefinition` | Accepted Block, multiplicity, and min/max validate | `unknown-socket-block`; `invalid-multiplicity` |
| SEM-04 | State meaning remains stable | `SemanticState`; semantic model | Declared states remain representable | `missing-state-fallback` |
| ACT-01 | Required operation identity remains stable | Projection contract; `OperationContract` | Required operation IDs remain attached | `required-operation-removed` |
| ACT-02 | Required operations remain exposed and signaled | Projection contract §5.4 | Exposure and signaling are independently verifiable | `required-operation-hidden` |
| ACC-01 | Accessibility names, relationships, and reading order remain valid | Projection contract; semantic model | Name, role, order, and focus path remain available | `accessibility-name-lost`; `semantic-order-replaced` |
| ACC-02 | Focus and state feedback are not obscured | Projection contract §5.5 | Focus, disabled, error, and selected states remain perceivable | `focus-obscured` |
| PRO-01 | Only declared properties are transformed | `ProjectionContract.transform` | Every topology or appearance mutation maps to a declared transform | `undeclared-semantic-transform` |
| PRO-02 | Omission is explicit | `ProjectionContract.mayOmit` | Omitted content is listed and non-required | `undeclared-omission` |
| PRO-03 | Introduced layers remain presentation-only | `ProjectionContract.mayIntroduce` | Decorations do not create semantic meaning | `decorative-layer-creates-meaning` |
| RES-01 | Recipe targets resolve to semantic identities | Expression model; `VisualLanguage.recipes` | Every target exists | `unknown-recipe-target` |
| RES-02 | Token and asset references resolve | `TokenRegistry`; `AssetRegistry` | All referenced resources exist | `unknown-token`; `unknown-asset` |
| RES-03 | Appearance layers are structurally valid | `ses.schema.json`; expression model | Backgrounds, edges, masks, clipping, bleed, and opacity validate | `invalid-edge-target`; `invalid-background-layer` |
| RSP-01 | Required content and operations survive responsive expression | Projection responsive rules; `07-conformance.md` | Required content is not clipped, unreachable, or overflowed | `required-content-clipped`; `mobile-overflow` |
| VAR-01 | Multiple Visual Languages share one semantic baseline | `07-conformance.md` §7.3 | Same semantic fixture passes through multiple languages | `language-specific-semantic-branch` |

JSON Schema validates record shape only. Cross-record identity, compatibility, reference resolution, accessibility, operation exposure, and responsive behavior require conformance-level validation.

## Fixture plan

### Positive reference vectors

- `valid-home-core`
- `valid-home-neo-edo`
- `valid-home-western-comics`
- `valid-home-cybernetic-minimalism`

Each uses the same `Home` composition and verifies `home.hero` and `home.trending`, including `enter-world`, `open-media`, and `view-all`. Expressions may freely differ in orientation, enclosure, media placement, texture, pattern, edges, and ornament where the Projection Contract permits.

### Negative fixtures

- `invalid-missing-required-slot`
- `invalid-incompatible-slot-content`
- `invalid-unknown-socket-block`
- `invalid-required-operation-hidden`
- `invalid-unknown-token`
- `invalid-unknown-asset`
- `invalid-unknown-recipe-target`
- `invalid-focus-obscured`
- `invalid-semantic-order`
- `invalid-required-content-clipped`
- `invalid-mobile-overflow`
- `invalid-missing-state-fallback`

Each negative fixture maps to one baseline ID and fails at the earliest applicable validation layer.

## Validation order

1. **Shape:** validate records against `schemas/ses.schema.json`.
2. **Semantic:** validate identity, Slot compatibility, Socket admission, cardinality, states, and operations.
3. **Projection:** validate `preserve`, `transform`, `mayOmit`, `mayIntroduce`, and failure conditions.
4. **Resolution:** validate recipe targets, tokens, and assets.
5. **Accessibility and responsive:** validate exposure, focus, order, reachability, and overflow.
6. **Visual:** inspect reference renders only after layers 1–5 pass.

## Scope boundary

SES-001 establishes the conformance contract and fixture inventory only. It does not implement a renderer, runtime resolver, validator, product screen, transport, persistence layer, or external integration.


--- FILE: docs/10-validator-contract.md (106 lines, 7.2 KiB) ---
# 10. Validator-Level Conformance Contract

Status: SES-003

This document defines the checks required beyond JSON Schema shape validation. It specifies inputs, ordering, failure codes, and evidence requirements; it does not implement a validator or renderer.

## 10.1 Inputs

A conformance run receives:

1. A semantic registry containing Elements, Blocks, Slots, Sockets, Compositions, states, and operation identities.
2. A selected Visual Language, Theme, and resolved Recipe set.
3. A Projection Contract for each projected target.
4. Token and Asset registries.
5. A fixture context containing viewport, accessibility mode, reduced-motion preference, and expected semantic baseline.

The validator must distinguish missing input from an empty valid collection. Unknown discriminators and unknown semantic identities are errors; they are not silently ignored or converted to fallback values.

## 10.2 Validation order

Checks execute in dependency order. A later check may depend on an earlier successful result, but must retain the first typed failure and its evidence path.

| Order | Check family | Baseline IDs | Required check |
|---:|---|---|---|
| 1 | Record shape | all | Validate each record against its declared JSON Schema. |
| 2 | Cross-record identity | SEM-01, RES-01 | Resolve every Slot, Socket, Recipe, State, Variant, and Operation reference against the canonical registry. |
| 3 | Slot compatibility | SEM-02 | Check required cardinality, accepted content type, required Slot declarations, and mutually exclusive Slot constraints. |
| 4 | Socket admission | SEM-03 | Check accepted Block identity/capability, multiplicity, min/max bounds, required participation, and variant restrictions. |
| 5 | Composition structure | RSP-01, VAR-01 | Check hierarchy, relation, content priority, repetition, collapse priority, and responsive participation. |
| 6 | Projection contract | PRO-01, PRO-02, PRO-03 | Check that mutations are declared, omissions are permitted, and introduced layers remain presentation-only. |
| 7 | Resource resolution | RES-02, RES-03 | Resolve tokens, aliases, assets, masks, edges, backgrounds, patterns, and morphology references. |
| 8 | Operation exposure | ACT-01, ACT-02 | Check required operation identity, enabled state, exposure, signaling, and reachable invocation path. |
| 9 | Accessibility and state | SEM-04, ACC-01, ACC-02 | Check accessible name, role, logical order, keyboard order, focus visibility, state feedback, and fallback behavior. |
| 10 | Responsive reachability | RSP-01 | Check required content, required operations, overflow, clipping, collapse, and reachability at each declared viewport context. |

Visual comparison is downstream of this contract. A visually similar render cannot convert a failed semantic or interaction check into a pass.

## 10.3 Cross-record identity checks

- `CHK-IDENTITY-001`: every referenced semantic ID exists exactly once.
- `CHK-IDENTITY-002`: expression recipes target an existing Element, Block, Socket, Composition, State, or Variant.
- `CHK-IDENTITY-003`: Slot and Socket IDs are not reused for different semantic roles within one registry.
- `CHK-IDENTITY-004`: required operation IDs remain identical between source semantics and projection.

Failure codes: `ERR_IDENTITY_UNKNOWN`, `ERR_IDENTITY_DUPLICATE`, `ERR_RECIPE_TARGET_UNKNOWN`, `ERR_OPERATION_ID_CHANGED`.

## 10.4 Slot and Socket checks

- `CHK-SLOT-001`: required Slot cardinality is satisfied.
- `CHK-SLOT-002`: inserted content matches the Slot's accepted element, Block, or content type.
- `CHK-SLOT-003`: mutually exclusive Slot constraints are not violated.
- `CHK-SOCKET-001`: admitted Block matches an accepted identity, variant, or declared capability.
- `CHK-SOCKET-002`: multiplicity and min/max constraints are satisfied.
- `CHK-SOCKET-003`: required Socket participation is present at every required composition level.

Failure codes: `ERR_SLOT_REQUIRED_MISSING`, `ERR_SLOT_CONTENT_INCOMPATIBLE`, `ERR_SLOT_CONSTRAINT_VIOLATED`, `ERR_SOCKET_ADMISSION_DENIED`, `ERR_SOCKET_CARDINALITY_INVALID`, `ERR_SOCKET_REQUIRED_MISSING`.

## 10.5 Projection checks

- `CHK-PROJECTION-001`: every semantic change is classified as preserve, transform, omit, or introduce.
- `CHK-PROJECTION-002`: preserved identity, required content, operation identity, and accessibility relationships are unchanged.
- `CHK-PROJECTION-003`: omitted content appears in `mayOmit` and is not required by the semantic contract.
- `CHK-PROJECTION-004`: introduced layers are non-semantic and cannot create an accessibility or operation identity.
- `CHK-PROJECTION-005`: declared failure conditions are evaluated explicitly.

Failure codes: `ERR_TRANSFORM_UNDECLARED`, `ERR_REQUIRED_CONTENT_OMITTED`, `ERR_INTRODUCED_SEMANTIC_MEANING`, `ERR_PROJECTION_FAILURE_CONDITION`.

## 10.6 Resource and recipe checks

- `CHK-RESOURCE-001`: token references resolve through the declared token layers.
- `CHK-RESOURCE-002`: asset references resolve in the declared asset category.
- `CHK-RESOURCE-003`: edge targets refer to valid boundaries and sides.
- `CHK-RESOURCE-004`: masks, clips, backgrounds, patterns, and appearance sources are present and structurally valid.
- `CHK-RESOURCE-005`: morphology and layout values remain expression data and do not alter semantic identity.

Failure codes: `ERR_TOKEN_UNRESOLVED`, `ERR_ASSET_NOT_FOUND`, `ERR_EDGE_TARGET_INVALID`, `ERR_APPEARANCE_SOURCE_INVALID`, `ERR_MORPHOLOGY_SEMANTIC_MUTATION`.

## 10.7 Operation, accessibility, and responsive checks

- `CHK-INTERACTION-001`: every required operation is exposed through at least one reachable interaction path.
- `CHK-INTERACTION-002`: required operation signaling is present when `requireSignaling` is true.
- `CHK-A11Y-001`: accessible name and role survive expression.
- `CHK-A11Y-002`: logical reading and keyboard order preserve the declared semantic order unless an explicit accessible reorder contract exists.
- `CHK-A11Y-003`: focus indication remains visible and is not covered by appearance layers.
- `CHK-A11Y-004`: disabled, error, selected, loading, reduced-motion, and high-contrast states have an accessible fallback where required.
- `CHK-RESPONSIVE-001`: required content and required operations remain reachable at every declared viewport.
- `CHK-RESPONSIVE-002`: overflow, clipping, hiding, and collapse obey Socket and Projection Contract rules.

Failure codes: `ERR_OPERATION_NOT_EXPOSED`, `ERR_OPERATION_NOT_SIGNALED`, `ERR_ACCESSIBLE_NAME_MISSING`, `ERR_KEYBOARD_ORDER_MISMATCH`, `ERR_FOCUS_INDICATOR_OBSTRUCTED`, `ERR_A11Y_FALLBACK_MISSING`, `ERR_CONTENT_UNREACHABLE`, `ERR_CONTENT_CLIPPED`, `ERR_COMPOSITION_OVERFLOW`.

## 10.8 Evidence requirements

Each check result must retain:

- fixture ID and SES-001 baseline ID;
- check ID and failure code, if any;
- stable path to the source records involved;
- expected value and observed value where comparison is applicable;
- validation layer and execution order;
- limitations, including unavailable renderer or accessibility evaluator.

The result envelope is intentionally left to SES-006. SES-003 defines the evidence fields required by that future format but does not prescribe its final serialization.

## 10.9 Scope boundary

SES-003 defines validator obligations only. It does not add runtime code, alter the JSON Schema contract, implement rendering, infer business behavior, or authorize promotion.


--- FILE: docs/11-resolver-boundary.md (111 lines, 4.7 KiB) ---
# 11. Resolver Boundary

Status: SES-004

The SES resolver is a pure boundary between stable semantic meaning and replaceable expression. It selects and combines expression data for one semantic projection. It does not render, execute operations, fetch resources, mutate state, or decide business behavior.

## 11.1 Pure contract

Conceptually:

```ts
resolveExpression(input: ResolutionInput): ResolvedExpression | ResolutionFailure
```

For the same canonical input, the resolver returns the same result. The input contains all context required for the decision; ambient time, randomness, network state, filesystem discovery, and mutable global state are not resolver inputs.

## 11.2 Inputs

`ResolutionInput` contains:

- semantic target: Composition, Socket, Block, Slot, Element, Variant, and State identities;
- semantic definition registry and instance content metadata;
- selected Visual Language and Theme definitions;
- applicable Recipe layers;
- token and Asset registries already available to the caller;
- viewport and responsive context;
- accessibility context, including high contrast and reduced motion;
- explicitly supplied user or instance expression options;
- Projection Contract governing the target.

The resolver receives registries as values or immutable references. Resource loading, asset fetching, authentication, and capability discovery occur outside this boundary.

## 11.3 Output

`ResolvedExpression` contains:

- unchanged semantic identity references for every projected target;
- resolved morphology and layout instructions;
- resolved appearance layers;
- resolved typography, image, icon, token, and asset references;
- state and responsive expression decisions;
- accessibility-preserving expression instructions;
- required operation exposure metadata;
- the applied Recipe layer trace;
- conformance warnings, if permitted by the caller's policy.

The output is renderer-neutral. It describes what the host must express, not how a DOM, native tree, canvas, or CSS engine performs that work.

## 11.4 Resolution cascade

The resolver evaluates layers in this fixed order:

```text
Visual Language
-> Theme
-> explicit user style options
-> Composition Recipe
-> Socket Recipe
-> Block Recipe
-> Variant Recipe
-> Slot Recipe
-> Element Recipe
-> semantic State Recipe
-> responsive Recipe
-> accessibility overrides
```

Later layers may replace expression fields only when the Projection Contract permits the mutation. They may not replace semantic identity, required content, operation identity, accessibility relationships, or business behavior.

Precedence and conflict-resolution details are reserved for SES-011. Until then, a conflicting required semantic field is a hard resolution failure rather than an implicit winner.

## 11.5 Invariants

- `RESOLVE-001`: semantic IDs in the output equal the IDs in the input semantic target.
- `RESOLVE-002`: required Slots, Sockets, content, and operations are not removed by expression resolution.
- `RESOLVE-003`: every output mutation is attributable to a declared recipe layer and Projection Contract permission.
- `RESOLVE-004`: all required token and asset references are resolved or returned as typed failures.
- `RESOLVE-005`: accessibility and responsive constraints remain represented in the output.
- `RESOLVE-006`: the same canonical input produces the same output and failure ordering.
- `RESOLVE-007`: resolution has no side effects and does not invoke renderer or operation behavior.

## 11.6 Failure model

Resolution returns a typed failure for:

- unknown semantic identity;
- incompatible Slot or Socket content;
- missing required Recipe;
- conflicting protected semantic field;
- undeclared projection mutation;
- unresolved required token or asset;
- invalid state or responsive expression;
- missing required accessibility or operation exposure instruction.

Failures include the target identity, source layer, field path, typed error code, and the applicable SES-003 check ID. Unknowns are not silently replaced with fallback expression.

## 11.7 Boundary ownership

| Concern | Resolver | Caller or host |
|---|---|---|
| Semantic identity preservation | owns validation | observes result |
| Recipe and token cascade | owns resolution | supplies immutable inputs |
| Asset retrieval | does not perform | asset provider |
| Operation invocation | does not perform | interaction runtime |
| DOM/native/canvas realization | does not perform | renderer |
| Business logic and navigation | does not perform | application |
| Persistence, transport, synchronization | does not perform | protocol or host application |

## 11.8 Scope boundary

SES-004 defines the pure resolver boundary and its invariants only. It does not implement a resolver, choose a renderer, define final recipe conflict precedence, or add application behavior.


--- FILE: docs/12-canonical-vocabulary.md (59 lines, 5.2 KiB) ---
# 12. Canonical Vocabulary

Status: SES-005

These terms are normative across the SES specification, schemas, fixtures, validator contract, and resolver boundary. Implementations may use local aliases internally, but public artifacts should use the canonical terms.

| Term | Canonical meaning | Not synonymous with |
|---|---|---|
| Semantic identity | The stable identity of an interface meaning, including its declared Element, Block, Slot, Socket, Composition, State, Variant, or Operation identity | CSS selector, DOM node, component class, visual label |
| Semantic model | The definitions of what exists, what content participates, what behavior and relationships are stable, and what operations are available | Application business logic, renderer tree |
| Expression model | The replaceable graphical realization of semantic structure through Visual Languages, Themes, Recipes, Morphology, Appearance, Tokens, Assets, and Motion | Semantic meaning, business behavior |
| Visual Language | A coherent graphical grammar governing presentation, topology, typography, surface, imagery, iconography, and motion | Theme, palette, brand guide |
| Theme | A concrete configuration of a Visual Language, usually through token and selected Recipe overrides | Complete Visual Language replacement |
| Recipe | Declarative expression instructions for a semantic target, state, variant, responsive condition, or layer | Semantic component definition, arbitrary renderer branch |
| Morphology | The spatial and structural organization of expression, including topology, direction, density, hierarchy, enclosure, overlap, and rhythm | Decorative surface treatment |
| Appearance | Layered graphical construction, including backgrounds, textures, patterns, edges, masks, clips, bleed, blending, and decoration | Semantic state or accessibility meaning |
| Projection | One expression of a semantic target under a selected Visual Language, Theme, Recipe set, context, and Projection Contract | Permanent mutation of the semantic model |
| Projection Contract | The explicit boundary declaring what a projection preserves, transforms, omits, introduces, constrains, and rejects | Renderer configuration alone |
| Preserve | A property that must remain semantically equivalent across projection | Same pixels or same DOM arrangement |
| Transform | A declared presentation mutation permitted by the Projection Contract | Permission to change semantic identity or behavior |
| Omit | Removal of optional content or presentation explicitly permitted by `mayOmit` | Silent removal of required content |
| Introduce | Addition of presentation-only content explicitly permitted by `mayIntroduce` | Creation of new semantic meaning or operation |
| Operation identity | The stable identity of an action the interface exposes | Its icon, label, position, or invocation result |
| Operation exposure | The condition that a required operation is reachable through the projected interface | Operation existence, signaling, invocation, or success |
| Conformance | Evidence that a semantic/expression result satisfies its declared schema, invariants, Projection Contract, and failure conditions | Visual similarity or artifact existence |
| Validation | An evaluation performed against a declared check or rule | Qualification or promotion by itself |
| Failure condition | A declared condition that invalidates a projection or result | A warning or stylistic preference |
| Invariance profile | The configured requirement level for a conformance dimension: `required`, `bounded`, or `free` | A fixed visual layout |
| Required | The property must be preserved or satisfied | Merely recommended |
| Bounded | The property may vary only within declared limits | Unconstrained variation |
| Free | The property may vary without a fixed topology constraint, subject to other required invariants | Permission to change semantics or behavior |

## 12.1 Usage rules

1. Use **semantic identity** when referring to stable meaning across representations.
2. Use **operation exposure** when referring specifically to reachability of a required action; use operation identity, signaling, invocation, and outcome for the other lifecycle states.
3. Use **projection** for the result of expressing semantics, and **Projection Contract** for the rules governing that result.
4. Use **Morphology** for spatial organization and **Appearance** for layered graphical construction.
5. Use **conformance** for the governed result and **validation** for the check that produces evidence about it.
6. Use **Theme** only for configuration of a Visual Language; a substantially different graphical grammar is a separate Visual Language.
7. Do not use visual-language names, theme names, renderer names, or product names as semantic identities or variants.

## 12.2 Canonical distinction

```text
semantic identity
  -> semantic model
  -> Projection Contract
  -> projection
  -> expression model
  -> renderer-neutral resolved expression
  -> host realization
```

The semantic identity remains stable while expression may vary radically. Conformance concerns whether the governed meaning and required behavior survive that variation.

## 12.3 Scope boundary

SES-005 normalizes terminology only. It does not rename existing IDs, change schemas, implement aliases, or alter semantic or expression behavior.


--- FILE: docs/13-projection-equivalence.md (71 lines, 3.3 KiB) ---
# 13. Projection Equivalence Vectors

Status: SES-007

Projection-equivalence testing evaluates multiple expressions of one semantic contract. It does not require pixel equality. It requires semantic, behavioral, action, accessibility, and required-content invariants to remain equivalent while declared morphology and visual properties may vary.

## 13.1 Equivalence relation

Two projections are equivalent for a fixture when they share:

- the same Composition, Socket, Block, Slot, Element, State, Variant, and Operation identities;
- the same required content and content priority;
- the same required operation identity, enabled state, exposure, and reachable invocation path;
- the same accessible names, roles, relationships, and logical order;
- the same responsive reachability obligations;
- no undeclared semantic mutation or prohibited omission.

They may differ in orientation, topology, enclosure, spacing, media placement, background, edge, texture, pattern, typography, ornament, density, and other expression properties listed by their Projection Contracts.

## 13.2 Reference vector

The canonical vector uses `Home` with `home.hero` and `home.trending`:

```text
semantic identities:
  home
  home.hero
  home.trending
  hero
  media-rail | media-grid | ranked-collection

required operations:
  enter-world
  open-media
  view-all

required preserved properties:
  identity
  content-priority
  primary-action
  accessibility-order
  operation-exposure
  required-content-reachability
```

## 13.3 Expression diversity

| Vector | Visual Language | Permitted expression difference |
|---|---|---|
| `valid-home-core` | Core | restrained orientation, enclosure, spacing, and alignment changes |
| `valid-home-neo-edo` | Neo-Edo | asymmetric placement, layered paper texture, targeted brush edges, pattern, ornament |
| `valid-home-western-comics` | Western Comics | panel topology, halftone, bold edges, speech-like annotation, high-contrast grouping |
| `valid-home-cybernetic-minimalism` | Cybernetic Minimalism | technical grid, sparse enclosure, glow, data-like alignment, dense responsive reflow |

Each vector must be evaluated against the same semantic fixture. Language-specific recipe data may change expression, but it may not introduce language-specific semantic branches or operation identities.

## 13.4 Equivalence checks

- `EQUIV-001`: semantic identity sets are equal across all vectors.
- `EQUIV-002`: required operation sets and exposure obligations are equal across all vectors.
- `EQUIV-003`: required Slot and Socket participation is equal across all vectors.
- `EQUIV-004`: accessible names, relationships, state meaning, and logical order remain equivalent.
- `EQUIV-005`: required content remains reachable at each declared responsive context.
- `EQUIV-006`: every expression difference is declared by the relevant Projection Contract.
- `EQUIV-007`: no vector contains a Visual Language-specific semantic or business-logic branch.

Failure codes use the SES-003 contract: `ERR_IDENTITY_UNKNOWN`, `ERR_OPERATION_ID_CHANGED`, `ERR_OPERATION_NOT_EXPOSED`, `ERR_REQUIRED_CONTENT_OMITTED`, `ERR_KEYBOARD_ORDER_MISMATCH`, `ERR_CONTENT_UNREACHABLE`, and `ERR_TRANSFORM_UNDECLARED`.

## 13.5 Scope boundary

SES-007 defines equivalence fixtures and checks. It does not render the vectors, claim visual fidelity, or implement a regression runner.


--- FILE: docs/14-responsive-invariants.md (58 lines, 3.8 KiB) ---
# 14. Responsive Invariants

Status: SES-008

Responsive expression may change spatial arrangement and density, but it may not make required semantic content, operations, accessibility relationships, or priority information unreachable.

## 14.1 Allowed responsive mutations

| Mutation | Default rule | Required condition |
|---|---|---|
| Reorder | Allowed for visual arrangement | Logical reading and keyboard order remain valid, or an explicit accessible reorder contract exists |
| Collapse | Allowed for lower-priority structure | Required content and operations remain reachable through the collapsed representation |
| Hide | Allowed only for optional content or declared responsive omission | The target is not required and omission is permitted by the Projection Contract |
| Transform | Allowed for morphology, orientation, enclosure, density, and media placement | The mutation is declared in `transform` and does not alter semantic identity or behavior |
| Overflow | Allowed only when explicitly declared as wrap, scroll, paginate, or another contract-supported mode | Required content and operations remain reachable and the mode is usable in the target context |
| Clip | Not allowed for required semantic content or focus/operation signaling | Clipping is limited to decorative or explicitly optional expression |

## 14.2 Required invariants

- `RESP-001`: every required Slot, Socket, content item, and operation remains reachable at each declared viewport context.
- `RESP-002`: required operation exposure and accessible naming survive responsive transformation.
- `RESP-003`: content priority and responsive importance determine collapse and hiding order.
- `RESP-004`: a hidden or collapsed target has an explicit replacement path when its meaning or operation remains required.
- `RESP-005`: logical reading order and keyboard order remain coherent after visual reorder.
- `RESP-006`: viewport overflow does not make required content or operations unreachable.
- `RESP-007`: focus indicators, state feedback, and high-contrast/reduced-motion requirements survive responsive expression.
- `RESP-008`: responsive behavior is deterministic for the same semantic target, expression context, and viewport context.

## 14.3 Context matrix

Every responsive fixture declares at least:

| Context | Required evaluation |
|---|---|
| Wide | hierarchy, operation exposure, content priority, and visual topology |
| Narrow | collapse, reordering, wrapping, and required-content reachability |
| Small touch | target reachability, focus/pressed state, operation signaling, and overflow |
| Reduced motion | state transitions remain understandable without required animation |
| High contrast | names, roles, focus, state, and operation signaling remain perceivable |

Projects may add viewport widths or host contexts, but may not remove the required semantic and interaction checks.

## 14.4 Failure conditions

Responsive expression fails when:

- a required Slot, Socket, or operation is hidden without an allowed replacement;
- required content is clipped, covered, or unreachable;
- horizontal or vertical overflow prevents access to required content or operation controls;
- visual reorder changes logical reading or keyboard order without an explicit contract;
- a collapsed control loses its accessible name, state, or operation signaling;
- a responsive state relies on motion that is unavailable or disabled without an equivalent state expression.

Failure codes use `ERR_CONTENT_UNREACHABLE`, `ERR_CONTENT_CLIPPED`, `ERR_COMPOSITION_OVERFLOW`, `ERR_KEYBOARD_ORDER_MISMATCH`, `ERR_OPERATION_NOT_EXPOSED`, and `ERR_A11Y_FALLBACK_MISSING` from SES-003.

## 14.5 Scope boundary

SES-008 defines responsive preservation rules and evaluation contexts. It does not prescribe breakpoint values, CSS, host layouts, or a responsive renderer.


--- FILE: docs/15-accessibility-expression.md (75 lines, 3.6 KiB) ---
# 15. Accessibility-Preserving Expression

Status: SES-009

Visual Languages may change presentation radically, but accessibility semantics and interaction access remain governed by the semantic model and Projection Contract.

## 15.1 Preserved accessibility contract

Every projected target must preserve or explicitly satisfy:

- accessible name and description requirements;
- semantic role and state meaning;
- relationships between labels, controls, descriptions, groups, and errors;
- logical reading order and keyboard order;
- operation reachability and signaling;
- focus visibility and target distinguishability;
- disabled, selected, pressed, loading, error, and expanded state communication;
- reduced-motion and high-contrast fallbacks.

Decorative layers, texture, pattern, edge, mask, image, ornament, and motion do not create accessibility meaning by themselves.

## 15.2 Expression freedoms and constraints

| Expression change | Permitted freedom | Required preservation |
|---|---|---|
| Typography and scale | May vary by Visual Language | readable hierarchy, names, labels, and state distinctions |
| Spatial reorder | May vary visually | logical reading/keyboard order, unless explicitly contracted |
| Enclosure and surface | May be removed, layered, or transformed | grouping, boundaries, focus, and target distinction |
| Media placement and crop | May move, bleed, or become background | alternative text, content priority, and control access |
| Decoration and ornament | May be introduced freely as presentation | no fabricated semantic or accessibility role |
| Motion | May vary by state and language | reduced-motion equivalent and state comprehension |
| Contrast treatment | May vary within theme grammar | high-contrast and focus/state perceivability |

## 15.3 Required checks

- `A11Y-001`: required accessible names are present and stable.
- `A11Y-002`: roles and relationships correspond to semantic identity.
- `A11Y-003`: reading and keyboard order remain coherent after visual topology changes.
- `A11Y-004`: every required operation has a reachable, perceivable control path.
- `A11Y-005`: focus is visible, not covered, and remains associated with the active target.
- `A11Y-006`: state changes are communicated without depending on color, texture, motion, or decoration alone.
- `A11Y-007`: reduced-motion expression preserves state transitions and operation feedback without required animation.
- `A11Y-008`: high-contrast expression preserves names, roles, focus, state, and operation signaling.

## 15.4 Failure conditions

- `ERR_ACCESSIBLE_NAME_MISSING`
- `ERR_ROLE_RELATIONSHIP_INVALID`
- `ERR_KEYBOARD_ORDER_MISMATCH`
- `ERR_OPERATION_NOT_EXPOSED`
- `ERR_FOCUS_INDICATOR_OBSTRUCTED`
- `ERR_STATE_SIGNALING_INSUFFICIENT`
- `ERR_A11Y_FALLBACK_MISSING`
- `ERR_REDUCED_MOTION_UNSUPPORTED`
- `ERR_HIGH_CONTRAST_FALLBACK_MISSING`

Failure occurs when a required contract is absent, unreachable, obscured, or dependent on a presentation cue the declared accessibility context does not guarantee.

## 15.5 Evaluation contexts

Accessibility fixtures evaluate at minimum:

1. keyboard-only navigation;
2. focus-visible state;
3. reduced-motion preference;
4. high-contrast or forced-colors mode;
5. non-color state distinction;
6. narrow responsive layout;
7. required operation exposure and invocation path.

The evaluator records unavailable contexts as limitations or inconclusive results; it does not convert missing evaluation into a pass.

## 15.6 Scope boundary

SES-009 defines accessibility-preserving expression rules and evaluation obligations. It does not prescribe a host framework, DOM implementation, ARIA template, or automated accessibility tool.


--- FILE: docs/16-token-asset-resolution.md (73 lines, 4.1 KiB) ---
# 16. Token and Asset Resolution Rules

Status: SES-010

Tokens provide values and Assets provide referenced resources. Resolution is deterministic, typed by category, and separate from host loading or execution.

## 16.1 Token layers and precedence

Token lookup follows this order from broadest to most specific:

```text
primitive -> semantic -> role -> recipe -> explicit expression override -> resolved value
```

An alias resolves recursively through earlier layers only. A later layer may override a value when the target is expression data and the override is declared by the active Theme, Recipe, or explicit expression context. A token may not override semantic identity, operation identity, accessibility relationships, required content, or business behavior.

The final resolved value records its source layer and alias path. Cycles, ambiguous aliases, and undeclared protected-field overrides are failures.

## 16.2 Token rules

- Primitive tokens are raw values without semantic meaning.
- Semantic tokens represent stable interface meaning such as text, surface, status, and interaction.
- Role tokens represent contextual use such as card surface, heading text, or navigation edge.
- Recipe tokens are target-specific aliases and may express visual topology or appearance values.
- Resolved tokens are host-ready values and retain source provenance.
- Components should consume semantic or role aliases rather than Visual Language-specific primitives.
- Missing required tokens fail resolution; optional tokens may use an explicitly declared fallback.
- Fallbacks are not created implicitly for unknown tokens.

## 16.3 Asset categories

Asset IDs resolve within one declared category:

| Category | Examples | Expression use |
|---|---|---|
| fonts | font families and weights | typography |
| icons | symbolic action or status graphics | signaling and ornament |
| images | content or background imagery | media and surfaces |
| textures | paper, grain, material | layered appearance |
| patterns | halftone, grid, motifs | repeated appearance |
| masks | clipping and compositing shapes | appearance construction |
| edges | targeted edge resources | boundary treatment |
| backgrounds | image or generated surface sources | appearance construction |
| ornaments | non-semantic decoration | presentation only |
| custom | host-declared extensions | namespaced expression only |

An asset referenced as one category may not silently resolve from another category. Category aliases require an explicit registry declaration.

## 16.4 Asset rules

- Recipes reference stable Asset IDs, not implicit filesystem discovery.
- The resolver validates identity, category, required metadata, and declared capability before emitting a reference.
- Asset retrieval, decoding, licensing checks, caching, and host capability checks occur outside the pure resolver boundary.
- Missing required assets fail resolution with source path and category evidence.
- Optional decorative assets may be omitted only when the Projection Contract permits omission.
- Custom assets and filters must be namespaced and cannot introduce semantic identity or executable behavior by convention.

## 16.5 Failure codes

- `ERR_TOKEN_UNRESOLVED`: required token or alias has no definition.
- `ERR_TOKEN_CYCLE`: token aliases form a cycle.
- `ERR_TOKEN_AMBIGUOUS`: multiple definitions claim the same precedence position.
- `ERR_PROTECTED_TOKEN_OVERRIDE`: token resolution attempts to mutate a protected semantic field.
- `ERR_ASSET_NOT_FOUND`: required Asset ID is absent.
- `ERR_ASSET_CATEGORY_MISMATCH`: Asset ID exists only under another category.
- `ERR_ASSET_METADATA_INVALID`: required asset metadata is absent or malformed.
- `ERR_ASSET_CAPABILITY_UNSUPPORTED`: host capability is insufficient for the declared asset use.

Each failure retains the target identity, field path, requested token or Asset ID, category, source layer, and applicable SES-003 check ID.

## 16.6 Scope boundary

SES-010 defines token and Asset resolution semantics only. SES-011 owns full Recipe precedence and conflict handling. This contract does not load files, decode media, execute filters, or implement a host resource provider.


--- FILE: docs/17-recipe-precedence.md (93 lines, 4.1 KiB) ---
# 17. Recipe Precedence and Conflict Handling

Status: SES-011

Recipe resolution combines expression layers without allowing a later expression source to rewrite semantic meaning. Precedence is deterministic, field-specific, and observable in the resolved layer trace.

## 17.1 Precedence order

Layers are applied from lowest to highest precedence:

```text
Visual Language
-> Theme
-> explicit user style options
-> Composition Recipe
-> Socket Recipe
-> Block Recipe
-> Variant Recipe
-> Slot Recipe
-> Element Recipe
-> semantic State Recipe
-> responsive Recipe
-> accessibility overrides
```

The order is fixed for a resolution run. A missing layer is skipped; its absence is not an error unless the Projection Contract marks the layer or field required.

## 17.2 Merge rules

| Value shape | Default merge rule | Conflict behavior |
|---|---|---|
| Scalar expression value | replace at the highest permitted layer | protected or undeclared replacement fails |
| Token alias | replace alias, then resolve | cycle, ambiguity, or protected override fails |
| Object/map | recursively merge declared expression fields | same-precedence incompatible values fail |
| Ordered layer array | append only when the field declares additive semantics | otherwise highest permitted layer replaces the collection |
| Slot presentation map | merge by Slot ID | unknown Slot target fails |
| State/Variant map | merge by declared State or Variant ID | unknown ID fails |
| Protected semantic field | never merge or replace | hard failure |

The default is replacement for scalar fields and replacement for ordered collections unless a field explicitly declares additive semantics. Recipe precedence does not imply that all appearance arrays concatenate.

## 17.3 Protected fields

No Recipe layer may change:

- Element, Block, Slot, Socket, Composition, State, Variant, or Operation identity;
- required content or accepted content type;
- semantic role or accessibility relationship;
- required operation identity or business behavior;
- Projection Contract invariance level;
- routing intent or application data identity.

Such changes are `ERR_PROTECTED_FIELD_OVERRIDE`, even when supplied by an explicit user style option or accessibility override. Accessibility overrides may change expression needed to preserve access; they may not erase the underlying semantic contract.

## 17.4 Conflict policy

1. Resolve layers in the fixed order.
2. Check Projection Contract permission before applying a mutation.
3. Apply the field-specific merge rule.
4. Record source layer, source path, previous value, and resulting value in the layer trace.
5. If two values at the same precedence cannot be merged deterministically, fail with `ERR_RECIPE_CONFLICT`.
6. If a later value targets a protected field, fail with `ERR_PROTECTED_FIELD_OVERRIDE`.
7. If a mutation is not declared by `transform`, `mayOmit`, or `mayIntroduce`, fail with `ERR_TRANSFORM_UNDECLARED` or the applicable projection failure.

No fallback winner is selected for an unresolved conflict. Unknown or ambiguous fields are hard failures rather than silent defaults.

## 17.5 Trace requirements

The resolved expression trace retains, for every changed field:

- semantic target identity;
- field path;
- source layer and Recipe identity;
- prior value, if any;
- resulting value;
- Projection Contract permission;
- merge rule;
- check and evidence identifiers.

This trace supports deterministic replay, conformance evidence, and later change review.

## 17.6 Failure codes

- `ERR_RECIPE_CONFLICT`: incompatible values exist at one precedence level.
- `ERR_PROTECTED_FIELD_OVERRIDE`: a Recipe attempts to mutate semantic or behavioral authority.
- `ERR_TRANSFORM_UNDECLARED`: expression mutation lacks Projection Contract permission.
- `ERR_RECIPE_TARGET_UNKNOWN`: Recipe target cannot be resolved.
- `ERR_RECIPE_LAYER_INVALID`: layer is malformed or not applicable to the target.
- `ERR_RECIPE_MERGE_INVALID`: field value cannot be combined under its declared merge rule.

## 17.7 Scope boundary

SES-011 defines precedence and conflict semantics. It does not implement the resolver, define host styling, or authorize application-specific overrides of semantic authority.


--- FILE: docs/18-semantic-branch-prohibition.md (51 lines, 3.0 KiB) ---
# 18. Semantic Branch Prohibition

Status: SES-012

An implementation must not create Visual Language-specific semantic or business-logic branches. One semantic definition must remain the source for all conforming expressions.

## 18.1 Prohibited branches

The following patterns are non-conforming:

- branching a Block, Slot, Socket, Composition, Operation, or State identity by Visual Language name;
- changing required content, accepted content, operation identity, routing intent, or business behavior by Theme or Recipe;
- maintaining separate language-specific semantic trees that duplicate application logic;
- using decorative variants such as `westernButton`, `edoCard`, or `cyberBadge` as semantic identities;
- hiding or replacing required operations because a Visual Language does not provide a preferred visual treatment;
- embedding Visual Language conditionals in semantic Element or Block behavior when the difference belongs in expression data.

## 18.2 Allowed variation

Expression branches are allowed when they are declarative, target an existing semantic identity, and are governed by a Projection Contract. Permitted variation includes:

- layout topology and morphology;
- typography and token selection;
- media placement and image treatment;
- backgrounds, textures, patterns, edges, masks, bleed, and ornament;
- density, enclosure, alignment, overlap, and responsive arrangement;
- state and operation signaling while preserving exposure and meaning;
- host-specific realization after the renderer-neutral expression boundary.

An expression branch must not add new semantic identity or implicit business behavior. Host extensions are namespaced and remain downstream of canonical SES semantics.

## 18.3 Review checks

- `BRANCH-001`: every semantic target is defined once in the canonical registry.
- `BRANCH-002`: Visual Language and Theme identifiers appear only in expression selection or presentation data.
- `BRANCH-003`: required operations and routing intent are independent of expression selection.
- `BRANCH-004`: language-specific differences are represented by Recipes, tokens, assets, morphology, or appearance.
- `BRANCH-005`: all cross-language vectors use the same semantic fixture and invariant set.
- `BRANCH-006`: host-specific extensions do not redefine canonical semantic fields.

## 18.4 Failure conditions

- `ERR_SEMANTIC_LANGUAGE_BRANCH`: semantic structure changes by Visual Language or Theme.
- `ERR_BUSINESS_LANGUAGE_BRANCH`: business behavior or routing changes by expression selection.
- `ERR_DUPLICATE_SEMANTIC_TREE`: equivalent semantic definitions are forked per language.
- `ERR_OPERATION_LANGUAGE_BRANCH`: required operation identity or exposure depends on language selection.
- `ERR_UNNAMESPACED_HOST_EXTENSION`: host-specific extension enters canonical SES fields without a namespace.

## 18.5 Scope boundary

SES-012 governs architectural review and conformance checks. It does not refactor an implementation, prescribe a programming language, or prohibit legitimate application-level differences that are outside SES expression selection.


--- FILE: docs/19-renderer-neutral-output.md (100 lines, 3.6 KiB) ---
# 19. Renderer-Neutral Output Contract

Status: SES-014

The renderer-neutral output is the boundary product of SES resolution and the input contract for a host renderer. It preserves semantic inspection and required behavior while carrying expression instructions without assuming DOM, CSS, native views, canvas, or a specific framework.

## 19.1 Output sections

Every resolved projection exposes these sections:

```text
identity
semantic
projection
expression
resources
interaction
accessibility
responsive
trace
diagnostics
```

### Identity and semantic

- Composition, Socket, Block, Slot, Element, Variant, and State IDs;
- semantic roles and stable data identities;
- content participation and required/optional status;
- operation identities and required exposure;
- semantic relationships and logical order.

### Projection

- Projection Contract identity and invariance profile;
- preserved, transformed, omitted, and introduced properties;
- applied failure conditions and permitted mutations.

### Expression

- resolved morphology and layout instructions;
- appearance layer instructions;
- typography and image treatment;
- resolved token values or typed token references;
- resolved Asset IDs and category metadata;
- state, variant, and responsive expression decisions;
- motion instructions with reduced-motion alternatives.

### Interaction and accessibility

- operation exposure and signaling metadata;
- enabled/disabled state;
- accessible name, role, relationships, and logical order;
- focus and state-visibility requirements;
- keyboard and reduced-motion obligations.

### Responsive

- active viewport/context;
- applicable responsive rules;
- allowed reorder, collapse, hide, overflow, and reachability behavior;
- required-content and required-operation obligations.

### Trace and diagnostics

- Recipe layer trace;
- token and Asset provenance;
- conformance check references;
- warnings, limitations, and typed failures.

## 19.2 Host neutrality rules

- No output field requires a DOM node, CSS property, React component, native class, canvas primitive, or framework lifecycle.
- Host adapters may map output fields to platform primitives but may not change semantic identity or required operations.
- Host-specific extensions are namespaced and must be declared in the adapter contract.
- Data attributes, ARIA, CSS classes, native accessibility APIs, and event handlers are host realization concerns, not canonical output fields.
- Resource loading and operation invocation remain outside the output contract.

## 19.3 Required invariants

- `OUTPUT-001`: every output semantic identity maps to exactly one source semantic identity.
- `OUTPUT-002`: required content and operation exposure metadata are present.
- `OUTPUT-003`: expression fields are separate from semantic fields.
- `OUTPUT-004`: every resolved token, Asset, and Recipe mutation has provenance.
- `OUTPUT-005`: accessibility and responsive obligations are present even when the host cannot yet realize them.
- `OUTPUT-006`: output is deterministic for the same resolver input.
- `OUTPUT-007`: host extensions cannot overwrite canonical fields.

## 19.4 Failure conditions

- `ERR_OUTPUT_IDENTITY_MISSING`
- `ERR_OUTPUT_REQUIRED_METADATA_MISSING`
- `ERR_OUTPUT_SEMANTIC_EXPRESSION_MIXED`
- `ERR_OUTPUT_PROVENANCE_MISSING`
- `ERR_OUTPUT_ACCESSIBILITY_METADATA_MISSING`
- `ERR_OUTPUT_HOST_EXTENSION_COLLISION`
- `ERR_OUTPUT_UNRESOLVED_RESOURCE`

## 19.5 Scope boundary

SES-014 defines the renderer-neutral output contract only. It does not define a renderer, host adapter, DOM structure, CSS vocabulary, native widget mapping, resource loader, or operation runtime.


--- FILE: docs/20-change-governance.md (74 lines, 3.4 KiB) ---
# 20. Change Governance

Status: SES-015

SES changes are governed by explicit scope, compatibility evidence, conformance impact, and documented authority. A change is not complete merely because a file or schema parses.

## 20.1 Version boundaries

Version independently:

- semantic model and semantic schema;
- expression model and expression schema;
- Projection Contract vocabulary;
- conformance and result schemas;
- resolver and renderer-neutral output contracts;
- Visual Languages and Themes;
- host renderers and downstream implementations;
- transport or synchronization protocols outside SES.

Equal version numbers do not imply compatibility. Each release or draft records which boundaries changed.

## 20.2 Change classes

| Class | Examples | Required review |
|---|---|---|
| Documentation | terminology clarification, examples, non-normative prose | source and vocabulary consistency |
| Additive | new optional field, new expression layer, new fixture | schema compatibility and conformance impact |
| Conformance-tightening | new required check, failure condition, invariant | fixture coverage, migration path, authority review |
| Breaking semantic | identity, Slot, Socket, Operation, state, or required-content change | explicit semantic version change and equivalence review |
| Breaking expression | incompatible output or Recipe contract change | output compatibility and host impact review |
| Deprecation | retiring field, layer, asset category, or rule | replacement, timeline, warning, and removal release |

## 20.3 Required change record

Every normative change records:

- change ID and affected version boundary;
- intent and reason;
- established behavior before the change;
- proposed behavior after the change;
- compatibility class;
- affected schemas, fixtures, validators, resolvers, and host adapters;
- conformance and migration impact;
- evidence and limitations;
- authority and disposition.

## 20.4 Conformance-impact review

Before accepting a normative change, review:

1. SES-001 invariant matrix and affected baseline IDs;
2. positive and negative fixtures;
3. result schema and failure codes;
4. projection-equivalence vectors;
5. responsive and accessibility contracts;
6. resolver and renderer-neutral output contracts;
7. downstream implementation boundary;
8. changelog and deprecation records.

Changes that alter required semantic or behavioral invariants require updated evidence from every affected dependent layer. Missing evidence yields `inconclusive`, not pass.

## 20.5 Deprecation

Deprecation records the deprecated identifier, replacement, first deprecated version, planned removal version or condition, compatibility behavior, and migration evidence. Deprecated semantic identities remain resolvable during the declared compatibility window unless a breaking change is explicitly authorized.

Silent aliases, undocumented removals, and fallback behavior that changes semantic meaning are prohibited.

## 20.6 Changelog requirements

`docs/CHANGELOG.md` records normative changes by version or draft revision. Each entry identifies semantic, expression, schema, conformance, resolver, or implementation-boundary impact. Generated artifacts and local evidence reference the change ID rather than becoming the changelog source of truth.

## 20.7 Scope boundary

SES-015 defines governance and review obligations. It does not assign external release authority, publish packages, modify downstream implementations, or choose a versioning tool.


--- FILE: docs/21-security-trust-boundaries.md (66 lines, 3.6 KiB) ---
# 21. Security and Trust Boundaries

Status: SES-016

SES expression data may control presentation, but it must not silently become executable code, an authority channel, or a path around host security policy. The host decides how untrusted input is loaded, sanitized, sandboxed, and executed.

## 21.1 Trust classes

| Class | Examples | Default treatment |
|---|---|---|
| Declarative data | tokens, layout values, morphology, colors, typography roles, asset IDs | schema validation and bounded resolution |
| Referenced resources | images, fonts, icons, textures, patterns, masks, edge assets | category validation, metadata validation, host policy |
| Constrained custom expression | namespaced custom appearance or host extension | explicit capability declaration, allowlist, isolation, and provenance |
| Executable behavior | scripts, arbitrary code, event handlers, shader code, dynamic imports | outside canonical SES; rejected unless a separately governed host protocol authorizes it |
| Authority-bearing input | navigation target, credential, permission, payment, deployment, persistence command | outside SES expression; never inferred from a Recipe or Asset |

## 21.2 Expression safety rules

- Tokens and Recipes are data, not code.
- Asset IDs resolve through declared registries; arbitrary filesystem or network discovery is not implied.
- Custom sources, filters, blend modes, shaders, and SVG fragments are namespaced and capability-gated by the host.
- A Recipe cannot introduce event handlers, navigation, data mutation, authentication, authorization, persistence, or network requests.
- An Asset cannot create semantic identity, operation identity, accessibility meaning, or business behavior by appearance alone.
- Host adapters validate MIME type, size, dimensions, decoding policy, and supported capabilities before use.
- Remote or user-supplied resources require an external trust and delivery policy; SES records references, not trust.
- Failure is closed: unknown custom types, unsupported capabilities, unsafe references, and malformed metadata fail rather than falling back to execution.

## 21.3 Resource constraints

Hosts define bounded limits for:

- payload size and nesting depth;
- image pixels, animation frames, font tables, and decoded memory;
- filter, mask, blend, and layer complexity;
- custom extension execution time and permissions;
- remote fetch count, origin, protocol, redirect, and timeout policy;
- logging and diagnostic redaction.

SES conformance verifies that a declaration is explicit and typed. Host security policy determines whether the declaration is permitted in a particular environment.

## 21.4 Trust and provenance

Every custom expression, Asset, filter, or host extension retains:

- source identity and category;
- declaring Visual Language, Theme, Recipe, or adapter;
- capability required;
- integrity or version reference when supplied by the host;
- validation and limitation records.

The resolver must not manufacture trust, signatures, authorization, or provenance. Those belong to the delivery or host protocol.

## 21.5 Failure codes

- `ERR_UNTRUSTED_EXECUTABLE_EXPRESSION`
- `ERR_CUSTOM_CAPABILITY_UNDECLARED`
- `ERR_RESOURCE_POLICY_REJECTED`
- `ERR_RESOURCE_METADATA_LIMIT`
- `ERR_RESOURCE_ORIGIN_REJECTED`
- `ERR_HOST_EXTENSION_UNAUTHORIZED`
- `ERR_AUTHORITY_BEHAVIOR_IN_EXPRESSION`
- `ERR_ASSET_DECODE_REJECTED`

## 21.6 Scope boundary

SES-016 defines expression trust boundaries and host obligations. It does not implement sanitization, sandboxing, content security policy, authentication, authorization, remote delivery, signing, or a security adapter.


--- FILE: docs/22-performance-budgets.md (57 lines, 3.0 KiB) ---
# 22. Performance Budgets

Status: SES-017

SES performance budgets bound expression resolution and host handoff without turning the protocol into a renderer-specific benchmark. These are provisional design budgets for a warm, local resolution path; implementations must record actual measurements before claiming qualification.

## 22.1 Baseline budgets

| Surface | Budget | Measurement boundary |
|---|---:|---|
| Pure semantic/expression resolution | 5 ms p95 | resolver entry to renderer-neutral output, excluding resource I/O |
| Token and alias resolution | 1 ms p95 | token lookup and alias expansion, excluding network or disk |
| Asset metadata resolution | 2 ms p95 | registry lookup and metadata validation, excluding decode/fetch |
| Recipe layer count | 12 layers | one output target across the declared cascade |
| Recipe merge depth | 16 nested expression levels | one target resolution |
| Appearance layer count | 32 layers | one resolved target before host realization |
| Responsive recomputation | 8 ms p95 | existing resolved context to changed viewport output, excluding render/layout |
| Motion metadata resolution | 1 ms p95 | state-to-motion instruction selection, excluding playback |
| Renderer-neutral output size | 256 KiB typical target | serialized resolved output excluding external resources |

Budgets are guardrails, not evidence that an implementation meets them. A host may declare a different profile, but it must name the profile, record the rationale, and retain comparable measurements.

## 22.2 Required measurements

Implementations measuring SES performance record:

- semantic target and fixture ID;
- Visual Language, Theme, state, viewport, and accessibility context;
- cold/warm/cache state;
- input size and layer counts;
- p50, p95, and p99 latency where timing is applicable;
- output size and resource counts;
- retries, failures, and budget violations;
- host and runtime conditions;
- limitations and measurement method.

## 22.3 Degradation rules

- Exceeding a budget is a typed performance warning or failure according to the declared profile; it does not authorize semantic simplification.
- Required content, operations, accessibility, and responsive reachability may not be dropped to meet a budget.
- Optional decoration, redundant appearance layers, precomputation, caching, and compilation may be optimized when their Projection Contract permits it.
- Resource fetch or decode time is measured by the host/resource provider, not attributed to pure resolver latency.
- Budget changes are governed changes and require SES-015 review.

## 22.4 Failure codes

- `ERR_RESOLUTION_BUDGET_EXCEEDED`
- `ERR_TOKEN_LOOKUP_BUDGET_EXCEEDED`
- `ERR_ASSET_METADATA_BUDGET_EXCEEDED`
- `ERR_RECIPE_DEPTH_EXCEEDED`
- `ERR_APPEARANCE_LAYER_BUDGET_EXCEEDED`
- `ERR_RESPONSIVE_RECOMPUTE_BUDGET_EXCEEDED`
- `ERR_OUTPUT_SIZE_BUDGET_EXCEEDED`

## 22.5 Scope boundary

SES-017 establishes provisional measurement boundaries and budgets. It does not benchmark a runtime, prescribe hardware, optimize a renderer, or treat unmeasured performance as validated.


--- FILE: docs/23-authoring-boundaries.md (47 lines, 3.9 KiB) ---
# 23. Authoring Boundaries

Status: SES-018

SES authoring remains coherent when each concern is written in its canonical layer. The same fact must not be duplicated across semantic definitions, Recipes, host components, and external protocols with competing authority.

## 23.1 Ownership matrix

| Authoring surface | Owns | Must not own |
|---|---|---|
| Element | atomic semantic role, interaction behavior, accessibility requirements, content requirements | Visual Language identity, topology, theme-specific styling |
| Slot | named content relationship, cardinality, accepted content, priority | coordinates, crop, fixed geometry, visual placement |
| Block | semantic composition, Slots, states, variants, operations, behavior, relationships | theme-specific branches, renderer markup, business transport |
| Socket | typed participation, accepted Blocks, multiplicity, importance, invariants, projection permissions | CSS grid area, pixel coordinates, renderer layout implementation |
| Composition | screen/page semantic organization, hierarchy, priority, participation | fixed pixels, host navigation implementation, transport |
| Projection Contract | preserve/transform/omit/introduce permissions, invariance, failures, required exposure | recipe values, business rules, external authorization |
| Visual Language | graphical grammar, morphology, appearance, typography, image treatment, motion character | semantic identity, operation identity, application data behavior |
| Theme | concrete Visual Language configuration, token overrides, selected Recipe overrides | replacement semantic tree, transport, product navigation |
| Recipe | declarative expression mapping for an existing target, state, variant, responsive context | arbitrary code, semantic branch, ungoverned side effect |
| Token registry | typed values and aliases with provenance | full topology, semantic identity, business behavior |
| Asset registry | stable resource identity, category, metadata, capability declaration | implicit execution, authority, semantic meaning by decoration |
| Resolver | deterministic combination into renderer-neutral output | rendering, loading, operation invocation, persistence |
| Host renderer | platform realization, loading, native accessibility mapping, operation wiring | canonical semantic redefinition, unreviewed behavior changes |
| External protocol/application | transport, persistence, synchronization, auth, business logic, product navigation | redefining SES invariants without an explicit adapter or change record |

## 23.2 Authoring routing rules

1. If a property must remain stable across Visual Languages, author it in the semantic model or Projection Contract.
2. If a property may differ between Visual Languages, author it in Visual Language, Theme, Recipe, Morphology, Appearance, Token, Asset, or Motion data.
3. If a property concerns movement of SES data or resolved expressions, author it in an external protocol.
4. If a property concerns business behavior, persistence, navigation, authorization, or synchronization, author it in the host application or protocol.
5. If a host needs an extension, namespace it and record its capability, provenance, and compatibility boundary.
6. Do not duplicate semantic identity in a renderer component, Theme name, Asset ID, or language-specific variant.

## 23.3 Conflict handling

When two authoring surfaces claim the same field:

- canonical semantic definitions and Projection Contracts govern semantic authority;
- expression layers govern only permitted presentation fields;
- host implementations cannot override canonical output fields;
- external protocols cannot redefine SES meaning by serialization or transport shape;
- unresolved authority is recorded as a conflict, not silently merged.

## 23.4 Scope boundary

SES-018 routes authoring responsibility and authority. It does not reorganize a codebase, choose a repository layout, define a transport schema, or prohibit application concerns outside SES scope.


--- FILE: docs/24-protocol-neutral-adoption.md (74 lines, 4.6 KiB) ---
# 24. Protocol-Neutral Adoption Guidance

Status: SES-020

SES is consumed as a semantic interface representation and governed expression system. An application may use SES without making SES responsible for transport, persistence, synchronization, or product navigation.

## 24.1 Integration boundary

```text
application data and intent
        |
        v
host adapter: map application state to SES semantic input
        |
        v
SES resolver: validate and resolve semantic + expression inputs
        |
        v
renderer adapter: realize renderer-neutral output
        |
        v
host events and operation results
```

The host owns application state, authorization, transport, persistence, synchronization, and navigation. SES owns semantic structure, projection permissions, expression resolution, conformance rules, and renderer-neutral output.

## 24.2 Consumption steps

1. Define or select the SES semantic model: Elements, Slots, Blocks, Sockets, Compositions, Variants, States, and Operations.
2. Declare the Projection Contract, including preserved identities, permitted transformations, omission and introduction rules, constraints, required operations, and failure conditions.
3. Supply content and application state through a host-owned adapter. The adapter maps into SES inputs; it does not move business rules into Recipes or Visual Languages.
4. Select a Visual Language and resolve Theme, Recipe, Morphology, Appearance, Tokens, Assets, Motion, and responsive context through the deterministic resolver boundary.
5. Validate the resolved output and consume it through a renderer adapter for DOM/CSS, native views, or another host platform.
6. Route user operations back to the host through stable operation identity. The host decides authorization, side effects, persistence, and result handling.

## 24.3 Explicit non-responsibilities

| Concern | Owner | SES boundary |
|---|---|---|
| transport and API calls | host application or external protocol | provide data and receive operation outcomes through an adapter |
| persistence and database state | host application | do not store application records or become a system of record |
| synchronization and conflict resolution | host application or external protocol | resolve only the supplied semantic/expression inputs |
| authentication and authorization | host application or external protocol | expose required operation identity; do not infer authority from presentation |
| product navigation | host application | express composition and operation meaning without owning routes |
| rendering | platform renderer adapter | consume renderer-neutral output without redefining semantic meaning |

## 24.4 Adapter rules

- Keep the adapter boundary explicit and versioned.
- Map legacy or application-specific data once at the boundary; downstream SES records use canonical vocabulary.
- Treat unknown semantic discriminators, unsupported capabilities, missing required content, and projection violations as failures.
- Do not branch semantic or business behavior on Visual Language, Theme, Recipe, or renderer identity.
- Keep external protocol payloads separate from canonical SES definitions unless an explicit mapping is recorded.
- Preserve stable semantic and operation identities across all expressions and host renderers.
- Let the host handle retries, idempotency, authorization, and side effects; SES resolution remains pure and local.

## 24.5 Minimal host contract

An adopting application needs only these responsibilities:

| Host responsibility | Required input/output |
|---|---|
| input mapping | application state and intent -> SES semantic input |
| expression selection | approved Visual Language, Theme, Recipe, and context |
| resolution invocation | canonical semantic and expression inputs -> renderer-neutral output |
| rendering | renderer-neutral output -> platform interface |
| operation routing | stable operation identity + host event -> application result |
| lifecycle | validation, logging, retries, persistence, and authorization outside SES |

Adoption is therefore an integration choice, not a transfer of application ownership to SES. A host may adopt only the semantic model, only the resolver contract, or the complete semantic-to-renderer path, provided the declared boundaries and invariants remain intact.

## 24.6 Acceptance boundary

SES-020 is documentation-complete when an adopter can identify the host adapter, resolver, renderer adapter, and operation route; assign transport, persistence, synchronization, authorization, and navigation to the host; and preserve SES semantic identity and projection invariants while changing expression systems.


--- FILE: docs/25-accountability-and-readiness.md (59 lines, 4.6 KiB) ---
# 25. Accountability and Implementation Readiness

Status: Reconciled 2026-08-16; SES-040 candidate qualified locally

This record maps the lessons from the IEPE/SES baseline to canonical artifacts, evidence, limitations, and next authorized work. It distinguishes documented contracts from implemented or empirically validated behavior.

## 25.1 Lesson-to-accountability matrix

| Lesson | Canonical account | Current maturity | Remaining responsibility |
|---|---|---|---|
| SES is an interface intermediate representation, not a design system | `docs/01-definition.md`, `docs/11-resolver-boundary.md`, `docs/19-renderer-neutral-output.md` | implemented locally | keep runtime APIs renderer-neutral |
| Tokens cannot express all topology changes | `docs/03-expression-model.md`, `docs/17-recipe-precedence.md` | implemented locally | expand morphology coverage without semantic branching |
| Projection Contracts govern expression freedom | `docs/05-projection-contract.md`, `docs/13-projection-equivalence.md` | locally tested | add independent host evaluation |
| Conformance needs evidence, not assertions | `docs/09-conformance-baseline.md`, `docs/10-validator-contract.md`, `docs/conformance/result.schema.json` | locally tested | retain failures and obtain independent evaluator evidence |
| Accessibility and responsiveness are invariants | `docs/14-responsive-invariants.md`, `docs/15-accessibility-expression.md` | metadata locally tested | exercise host-renderer and assistive-technology paths |
| Renderer neutrality is required | `docs/19-renderer-neutral-output.md` | DOM/CSS adapter locally tested | add a second host and compare semantics |
| Host applications own external concerns | `docs/24-protocol-neutral-adoption.md`, `docs/23-authoring-boundaries.md` | adapter boundary locally tested | record each production adapter's authority and version boundary |
| IEPE requires bounded, evidence-backed work | `.iepe/protocol-reference.json`, `PROJECT_PROFILE.json`, `work/GRAPH.md`, `evidence/` | operational layer installed | preserve issue/evidence linkage for implementation work |
| Security and performance precede runtime adoption | `docs/21-security-trust-boundaries.md`, `docs/22-performance-budgets.md` | provisional contracts documented | convert limits and trust checks into executable gates |

## 25.2 Maturity statement

The repository has a **locally qualified implementation candidate** with a documented specification baseline, machine-readable fixtures, result formats, an executable resolver/validator path, a DOM/CSS adapter, local performance measurements, and cross-runtime summary checks. It does not claim production accessibility behavior, production performance, or empirical cross-framework equivalence.

Evidence must promote those dimensions independently:

```text
documented -> implemented -> tested -> empirically validated
```

No later stage may be inferred from an earlier stage's artifact existence.

## 25.3 Responsible implementation gates

Before promoting runtime work beyond the local candidate, the coordinator must require:

1. A pure resolver implementation against `docs/11-resolver-boundary.md` and `docs/19-renderer-neutral-output.md`.
2. A validator implementation that emits `docs/conformance/result.schema.json` records and preserves negative results.
3. At least one host renderer adapter with stable semantic and operation identity.
4. Accessibility and responsive execution evidence from the selected host environment.
5. Security checks for executable expression inputs, unsafe assets, and custom sources.
6. Measurements against provisional budgets, with environment and method recorded before promotion.
7. A framework-neutral adapter test proving application transport, persistence, synchronization, authorization, and navigation remain outside SES.

These are future implementation gates, not claims that the current repository has completed them.

## 25.4 Current material unknowns

- The first host renderer and runtime language are not selected.
- The independent validator implementation boundary is not selected.
- Performance budgets have no empirical calibration environment.
- Accessibility evidence requires a named host platform and evaluator.
- Promotion authority remains `unassigned` in `PROJECT_PROFILE.json`.

These unknowns do not block the specification baseline, but they block implementation-maturity or release-readiness claims.

## 25.5 Next bounded work

SES-040 records the current candidate. The next promotion requires an assigned promotion authority and independent browser/accessibility, production-load, and framework-integration evaluation; those actions remain outside the current local authorization.


--- FILE: docs/ARCHITECTURE.md (3 lines, 0.1 KiB) ---
# Architecture

No architecture has been authorized. Record established decisions separately from proposals and observations.


--- FILE: docs/CHANGELOG.md (18 lines, 1.2 KiB) ---
# Changelog

## 1.0.0 Draft Standard

- Renamed the umbrella architecture to Semantic Expression System (SES).
- Defined Component as an implementation term rather than an SES semantic layer.
- Added explicit Operation semantics.
- Upgraded Socket to a typed participation and projection boundary.
- Added Projection Contract between semantic structure and expression.
- Added typed invariance for semantic, behavioral, action identity, structural, morphological, and visual properties.
- Added Morphology as a first-class expression layer.
- Replaced atomic surface, edge, texture, and ornament assumptions with layered Appearance Recipes.
- Added full and custom backgrounds, texture layers, pattern layers, targeted edges, multiple edge layers, decoration, masks, clips, bleed, compositing, and z-order support.
- Defined token layers: primitive, semantic, role, recipe, resolved.
- Defined asset registries for fonts, icons, textures, patterns, masks, edges, backgrounds, ornaments, and custom resources.
- Added resolver cascade and host-neutral renderer boundary.
- Added layered conformance and negative fixtures.
- Added independent implementation and protocol boundary for downstream projects such as IV.


--- FILE: docs/EXPERIENCE.md (3 lines, 0.2 KiB) ---
# Experience Contract

Beneficiaries, critical journeys, states, accessibility requirements, protected qualities, and observation methods remain unconfirmed.


--- FILE: docs/NEGATIVE_RESULTS.md (7 lines, 0.6 KiB) ---
# Negative and Inconclusive Results

Retain rejected candidates, failed evaluations, contradictions, limitations, and the evidence that produced each disposition.

## Current qualification boundary

The SES candidate has not been empirically validated in production or through an independent browser/assistive-technology evaluation. Local resolver, validator, host-adapter, performance, and cross-runtime checks exist and are recorded in the SES-021 through SES-040 evidence bundle; those local checks do not establish production readiness or universal cross-framework behavior.


--- FILE: docs/README.md (89 lines, 3.3 KiB) ---
# Semantic Expression System

Version: 1.0.0 Draft Standard
Status: Protocol-neutral architecture specification with locally qualified implementation candidate

The Semantic Expression System (SES) is a 2D interface architecture for extreme visual variation without semantic or behavioral fragmentation.

SES separates what an interface means from how it is expressed. Elements, Slots, Blocks, Sockets, Compositions, Variants, States, and Operations define the stable semantic interface representation. Visual Languages, Themes, Recipes, Morphology, Appearance, Tokens, and Assets define replaceable expression. A resolver combines both sides into a concrete rendered interface.

The system is intentionally protocol-neutral and application-neutral. A transport, synchronization, authoring, persistence, or remote rendering protocol can be defined separately. A project such as IV can implement SES without becoming the source of truth for SES itself.

## Governing principle

If a visual decision can reasonably differ between radically different interface languages, it must not be hard-coded into a semantic Element or Block.

Visual variation may include color, typography, geometry, spacing, internal layout, surface construction, background composition, targeted edges, textures, patterns, masks, image treatment, iconography, ornament, density, motion, and responsive presentation.

Semantic identity, data contracts, operation identity, accessibility relationships, required content, state meaning, and business behavior remain governed by the semantic model.

## Architecture

```text
APPLICATION DATA
      |
      v
SEMANTIC INTERFACE REPRESENTATION
  Element
  Slot
  Block
  Socket
  Composition
  Variant
  State
  Operation
      |
      v
PROJECTION CONTRACT
  preserve
  transform
  omit
  introduce
  invariants
  operation exposure
  failure conditions
      |
      v
EXPRESSION SYSTEM
  Visual Language
  Theme
  Recipe
  Morphology
  Appearance
  Tokens
  Assets
      |
      v
RESOLVER / COMPILER
      |
      v
RENDERER
  DOM
  CSS
  native view tree
  other 2D host
```

## Documents

- `01-definition.md` - canonical definition and terminology
- `02-semantic-model.md` - Element, Slot, Block, Socket, Composition, Variant, State, Operation
- `03-expression-model.md` - Visual Language, Theme, Recipe, Morphology, Appearance
- `04-token-system.md` - token layers, aliases, resolution, assets
- `05-projection-contract.md` - preservation and transformation boundary
- `06-runtime-and-rendering.md` - resolver, cascade, DOM contract, compilation
- `07-conformance.md` - validation levels, failure conditions, tests
- `08-implementation-boundary.md` - protocol and IV implementation boundary
- `schemas/ses-schema.ts` - TypeScript canonical schema
- `schemas/ses.schema.json` - JSON Schema interchange draft
- `examples/home-example.ts` - complete semantic and expression example

## Naming

SES is the umbrella architecture.

"Component" is an implementation term, not a semantic layer. A React component can implement an Element, Block, Socket renderer, Composition host, or infrastructure provider.

"Theme" is not the whole expression system. A Theme configures a Visual Language. The Visual Language defines the broader graphical grammar.

"Slot" and "Socket" are intentionally distinct. A Slot receives content inside a Block. A Socket receives compatible Blocks inside a larger semantic structure.


--- FILE: docs/SES-SPECIFICATION.md (850 lines, 21.7 KiB) ---
# 1. Canonical Definition

## 1.1 Semantic Expression System

The Semantic Expression System is a semantic composition architecture in which Elements provide atomic behavior, Slots define named content relationships inside reusable Blocks, Sockets define typed participation boundaries for Blocks inside larger structures, and Compositions define screen-level semantic organization.

Visual Languages provide replaceable graphical grammars. Themes configure those grammars. Recipes map semantic objects to presentation. Morphology controls structural visual organization. Appearance controls layered graphical construction. Tokens and assets provide the resolved values and resources used by the renderer.

A Projection Contract sits between semantic structure and visual expression. It declares which properties must be preserved, which may be transformed, which may be omitted, which presentation-only properties may be introduced, which operations must remain exposed, and which conditions invalidate the projection.

## 1.2 Goal

SES is designed for extreme visual mutation without semantic or behavioral fragmentation.

The same semantic interface may be expressed as a restrained digital product, printed editorial system, dense technical console, handmade paper interface, high-key futurist product, or another visual language without branching into language-specific application screens.

## 1.3 Invariants

The following are semantic by default and should remain stable across Visual Languages unless a contract explicitly permits otherwise:

- semantic role
- data identity
- Block identity
- Slot identity
- Socket identity
- operation identity
- required content
- accessibility relationships
- state meaning
- business behavior
- routing intent
- responsive importance
- content priority

## 1.4 Mutable expression

The following are expression concerns and may vary radically:

- color
- typography
- spacing
- density
- shape
- radius
- clipping
- internal layout
- media placement
- container backgrounds
- layered backgrounds
- custom imagery
- surface material
- targeted edges
- partial edges
- edge imagery
- textures
- patterns
- masks
- blend modes
- ornament
- image treatment
- icon family
- shadow and glow
- section framing
- navigation appearance
- motion
- responsive visual topology

## 1.5 Governing rule

If Neo-Edo, Western Comics, Cybernetic Minimalism, Neo-Capsule Futurism, and MangaVerse Core could reasonably disagree about a visual property, that property belongs in a token, recipe, morphology rule, appearance rule, or Visual Language grammar rather than being hard-coded into a semantic Element or Block.
# 2. Semantic Model

## 2.1 Element

An Element is the smallest semantically meaningful interface object.

Examples include Button, IconButton, Heading, Text, Image, Avatar, Badge, Tag, Input, Select, Checkbox, Switch, Progress, Divider, Rating, and Price.

An Element owns semantics, accessibility, interaction behavior, and content requirements. It should own as little visual identity as possible.

A Button knows that it is actionable and may be primary, destructive, disabled, loading, focused, or pressed. It does not inherently know that it is a pill, ink strip, chrome capsule, square plate, or paper tab.

## 2.2 Slot

A Slot is a named semantic insertion point inside a Block.

A Slot answers: what kind of content belongs here?

Examples include media, title, subtitle, eyebrow, description, leading, trailing, meta, badge, status, actions, footer, overlay, avatar, icon, progress, and price.

A Slot does not prescribe presentation. `slot="media"` means that the content is primary media for the Block. It does not require a specific position, crop, aspect ratio, border, or enclosure.

## 2.3 Block

A Block is a reusable semantic composition of Elements and Slots.

Examples include MediaCard, Hero, Stat, NavigationItem, SearchField, Post, SeriesItem, WorldItem, ActivityItem, SectionHeader, PriceBlock, ProfileSummary, and ProgressSummary.

A Block defines:

- semantic role
- supported Slots
- required and optional content
- semantic ordering
- behaviors
- variants
- states
- operation relationships
- responsive importance
- accessibility relationships

A Block does not completely prescribe its graphical topology.

## 2.4 Socket

A Socket is a named, typed participation boundary within a Block or Composition.

A Socket declares the semantic role of a region, the Blocks it may receive, multiplicity, importance, required operations, invariants, and the transformations permitted during visual projection.

A Slot governs content participation inside a Block. A Socket governs Block participation inside a larger semantic structure.

A Socket is not a coordinate, column, card shell, or CSS grid area. Those are presentation decisions supplied by a Recipe.

A Socket may declare:

- accepted Block identities or capabilities
- single, optional, or repeating participation
- minimum and maximum participants
- content importance
- semantic and behavioral invariants
- structural and morphological freedom
- required operation exposure
- responsive preservation rules
- projection failure conditions

## 2.5 Composition

A Composition is the semantic arrangement and relationship of Sockets for a screen, page, shell, flow, or section.

A Composition defines information hierarchy and participation, not a fixed pixel layout.

A Home Composition might declare Sockets for navigation, utility, hero, statistics, journey, trending, worlds, activity, community, library, closing action, and footer. A Visual Language may render those as rails, panels, printed fields, overlapping editorial regions, or borderless sections while preserving their semantic contracts.

## 2.6 Variant

A Variant is a semantic specialization of an Element or Block.

Examples:

```text
Button
  primary
  secondary
  destructive
  quiet

Card
  default
  featured
  promotional
  interactive

Badge
  status
  category
  live
```

Variants must not encode Visual Language identity. `westernButton`, `edoCard`, and `cyberBadge` are invalid architectural patterns.

## 2.7 State

A State represents interaction or application condition.

Canonical state vocabulary may include:

```text
default
hover
focus
pressed
selected
active
disabled
loading
error
success
warning
read
unread
owned
locked
```

States have stable semantic meaning. The active Visual Language determines how each state is expressed.

## 2.8 Operation

An Operation is a semantic action exposed by the interface.

Examples include open-series, save, purchase, continue-reading, view-all, dismiss, search, submit, and navigate-home.

Operation identity must remain separate from visual signaling. A projection may alter how an operation is signaled, but required operations may not silently disappear because of theme styling.
# 3. Expression Model

## 3.1 Visual Language

A Visual Language is the highest-level 2D graphical grammar in SES.

It defines the coherent rules by which semantic structure is expressed, including palette, typography, spacing, morphology, shape, surface, edge, texture, pattern, image treatment, iconography, depth, ornament, controls, navigation, and motion.

A Visual Language is broader than a palette or conventional design-system theme.

## 3.2 Theme

A Theme is a concrete configuration of a Visual Language.

Example:

```text
Visual Language: Neo-Edo
Themes:
  Neo-Edo / Ink
  Neo-Edo / Vermilion
  Neo-Edo / Moon
  Neo-Edo / Winter
```

A Theme may override tokens and selected Recipes, but should preserve the defining grammar of its Visual Language. If a configuration replaces most of the typography, surface philosophy, shape grammar, image treatment, edge system, morphology, and motion character, it is likely a separate Visual Language.

## 3.3 Recipe

A Recipe maps a semantic target to presentation behavior.

Recipe targets may include:

- Elements
- Blocks
- Sockets
- Compositions
- Slots within Blocks
- States and Variants

A Recipe may define layout, morphology, appearance, typography roles, image treatment, responsive behavior, and state overrides.

Recipes should be declarative data where practical. Theme-specific JSX branches are an anti-pattern.

## 3.4 Morphology

Morphology describes the structural visual organization of an interface independently from its decorative appearance.

Morphology may define:

- hierarchy
- topology
- density
- rhythm
- alignment
- symmetry
- enclosure
- continuity
- direction
- visual weight
- overlap
- fragmentation
- stacking
- grouping

This distinction allows two themes to use identical colors and still differ substantially because their spatial organization, enclosure, rhythm, and hierarchy differ.

## 3.5 Appearance

Appearance is the layered graphical construction of a resolved semantic object.

Appearance must support full and custom construction rather than only flat surface aliases.

An Appearance Recipe may contain:

```text
background layers
surface material
texture layers
pattern layers
edge layers
decoration layers
image treatment
mask
clip
bleed
overflow
blend modes
opacity
z-order
filtering
backdrop effects
```

### Backgrounds

Backgrounds are ordered layers. A container may combine color, gradients, textures, patterns, images, generated artwork, or custom assets.

Backgrounds must be available at Composition, Socket, Block, Slot, and Element levels when the active grammar permits them.

### Textures

Textures describe material character, such as paper fiber, grain, noise, canvas, metal, scratches, ink bleed, or scan artifacts.

### Patterns

Patterns describe intentional repeated graphical structure, such as halftone, screentone, crosshatch, grid, stripes, dots, waves, speedlines, or cultural geometric motifs.

Texture and pattern are separate concepts and may be layered independently.

### Edges

Edges are first-class layered structures rather than simple borders.

An edge layer may target all sides or any subset of top, right, bottom, and left. It may be solid, hairline, double, dashed, ink, brush, deckle, torn, technical, engraved, glowing, embossed, image-based, offset, partial, or custom.

Multiple edge layers may exist simultaneously.

### Decorations

Decorations are non-semantic graphical additions such as seals, brush marks, registration marks, ticks, flourishes, corner graphics, panel numbers, rivets, engraving, or custom illustrations.

Decorations must not create accessibility meaning by themselves.

### Bleed

A Recipe may intentionally allow background, media, edge, or decoration layers to extend beyond a nominal container boundary. Bleed behavior must be explicit and must not obscure required interaction or focus indicators.
# 4. Token System

SES uses a layered token architecture. Tokens provide values. Recipes decide where and how those values are used.

## 4.1 Token levels

```text
Primitive Tokens
      |
Semantic Tokens
      |
Role Tokens
      |
Recipe Tokens
      |
Resolved Tokens
```

## 4.2 Primitive tokens

Primitive tokens are raw values with no interface semantics.

Examples:

```text
color.violet.600
space.4
radius.16
font.outfit
duration.200
shadow.3
```

Semantic components should not consume primitive tokens directly except in low-level infrastructure.

## 4.3 Semantic tokens

Semantic tokens describe stable meaning:

```text
color.canvas
color.surface
color.text.primary
color.text.secondary
color.accent.interaction
color.status.success
color.status.warning
color.status.danger
```

## 4.4 Role tokens

Role tokens describe interface context:

```text
surface.page
surface.navigation
surface.card
surface.card.featured
edge.card
edge.input
edge.navigation
text.heading
text.card.title
space.section
space.card
space.control
```

## 4.5 Recipe tokens

Recipe tokens are aliases introduced for specific semantic targets:

```text
media-card.surface
media-card.edge
media-card.gap
media-card.media.aspect
button.primary.surface
button.primary.edge
button.primary.shape
```

These may be generated or resolved from the active Visual Language and Theme.

## 4.6 Resolved tokens

Resolved tokens are host-ready values emitted after the cascade is complete. In a web renderer they may become CSS custom properties. In another host they may become a typed style object or native resource table.

## 4.7 Assets

A Visual Language may provide an asset registry for:

- fonts
- icons
- textures
- patterns
- masks
- edge images
- background images
- ornaments
- custom illustrations
- SVG fragments
- shaders or filters where supported by the renderer

Recipes reference asset IDs rather than arbitrary file paths when portability matters.

## 4.8 Token rules

1. Components consume semantic or role aliases, not theme-specific raw values.
2. Tokens should not encode full component topology.
3. Recipes may derive aliases from primitives and semantic tokens.
4. Theme overrides must resolve deterministically.
5. Missing required token references are conformance failures.
6. Accessibility overrides have higher precedence than ordinary theme styling.
# 5. Projection Contract

The Projection Contract governs the boundary between semantic structure and visual expression.

It exists to make radical mutation explicit and testable.

## 5.1 Responsibilities

A Projection Contract declares:

- semantic target
- identity and authority
- properties that must be preserved
- properties that may be transformed
- optional properties that may be omitted
- presentation-only properties that may be introduced
- required operations
- required operation exposure
- accessibility constraints
- responsive constraints
- tolerance where applicable
- failure conditions

## 5.2 Typed invariance

Preservation is typed. A projection may be semantically invariant while visually and morphologically different.

Recommended UI invariance dimensions:

```text
semantic
behavioral
actionIdentity
structural
morphological
visual
```

Each may be:

```text
required
bounded
free
```

A typical expressive application may require semantic, behavioral, and action identity invariance while allowing bounded structural change and free morphological and visual change.

## 5.3 Preserve, transform, omit, introduce

Example:

```ts
projection: {
  preserve: [
    "series-identity",
    "content-priority",
    "view-all-operation",
    "accessibility-order"
  ],

  transform: [
    "orientation",
    "media-placement",
    "enclosure",
    "spacing",
    "alignment",
    "surface",
    "edge",
    "texture"
  ],

  mayOmit: [
    "secondary-decoration",
    "nonessential-caption"
  ],

  mayIntroduce: [
    "ornament",
    "background-art",
    "pattern",
    "section-label-decoration"
  ]
}
```

## 5.4 Operation exposure

SES distinguishes operation existence from operation presentation.

At minimum, the runtime should preserve these distinctions:

```text
operation exists
operation is enabled
operation is exposed
operation is signaled
operation is invoked
operation succeeds or fails
```

A Theme may radically alter signaling. It may not silently remove required exposure.

## 5.5 Failure conditions

A projection is invalid if any declared failure condition occurs.

Common failures include:

- required Slot omitted
- required Socket unfilled
- incompatible Block admitted
- required operation unexposed
- focus indicator obscured
- semantic reading order invalidated
- accessibility name lost
- required content clipped or unreachable
- responsive layout violates minimum visibility
- unresolved token or asset reference
- recipe references unknown semantic identity
- theme-specific implementation changes business behavior
# 6. Runtime and Rendering

## 6.1 Resolver

The resolver is the technical center of SES.

Conceptually:

```ts
resolveExpression({
  language,
  theme,
  composition,
  socket,
  block,
  variant,
  slot,
  element,
  state,
  viewport,
  userStyleOptions,
  accessibility
})
```

The resolver produces a deterministic Resolved Expression containing tokens, layout, morphology, appearance, typography, image rules, motion, and host instructions.

## 6.2 Resolution order

Recommended cascade:

```text
Visual Language
      |
Theme
      |
User Style Options
      |
Composition Recipe
      |
Socket Recipe
      |
Block Recipe
      |
Variant Recipe
      |
Slot Recipe
      |
Element Recipe
      |
Semantic State
      |
Responsive State
      |
Accessibility Overrides
```

Later layers may alter expression. They may not rewrite semantic contracts.

## 6.3 Renderer

The renderer realizes the Resolved Expression in a host.

Possible hosts include:

- DOM + CSS
- React Native
- native desktop view trees
- game UI frameworks
- canvas or retained-mode 2D renderers

SES does not require DOM or CSS, though the web is a reference implementation target.

## 6.4 Web DOM contract

A web renderer should keep the semantic structure inspectable.

Example:

```html
<main
  data-composition="home"
  data-language="neo-edo"
  data-theme="vermilion"
>
  <section data-socket="trending" data-importance="primary">
    <article data-block="media-card" data-variant="featured">
      <div data-slot="media"></div>
      <div data-slot="title"></div>
      <div data-slot="meta"></div>
    </article>
  </section>
</main>
```

These attributes are inspection and styling hooks. Accessibility must continue to use correct native semantics and ARIA rather than relying on data attributes.

## 6.5 Compilation

Where possible, static portions of Visual Languages and Themes should be compiled ahead of runtime into:

- CSS variables
- classes
- style sheets
- lookup tables
- asset manifests
- recipe indexes

Runtime resolution should handle state, viewport, instance overrides, and dynamic content without recomputing the entire language.

## 6.6 Component implementation

Component is an implementation category, not an SES semantic level.

A React codebase may contain:

```text
components/elements
components/blocks
components/infrastructure
```

A component implementing an Element or Block should own semantic behavior, accessible structure, event handling, and stable data hooks. Visual Language conditionals should remain outside the component whenever they can be expressed through Recipes and tokens.
# 7. Conformance

SES uses layered conformance. Passing one layer does not imply another.

## S - Semantic Conformance

Checks that Element, Slot, Block, Socket, Composition, Variant, State, and Operation contracts are valid.

Examples:

- required Slots exist
- Socket admission is valid
- required operations are declared
- semantic identity is stable
- accessibility relationships exist

## C - Composition Conformance

Checks hierarchy, content priorities, repetition, responsive importance, and structural constraints.

## R - Recipe Conformance

Checks that every referenced Recipe, token, asset, morphology rule, and appearance rule resolves.

## A - Appearance Conformance

Checks backgrounds, textures, patterns, edges, masks, clipping, bleed, compositing, and decoration for valid construction and renderer support.

## I - Interaction Conformance

Checks keyboard interaction, focus order, focus visibility, operation exposure, disabled states, errors, recovery paths, and state behavior.

## V - Visual Validation

Checks reference renders, intended language fidelity, clipping, overlap, typography, density, and responsive rendering.

Visual validation does not prove semantic or interaction conformance.

## 7.1 Negative fixtures

The test suite should intentionally include invalid languages and themes.

Required negative cases include:

```text
missing required Slot
unknown Block in Socket
required operation hidden
unknown token
unknown asset
invalid edge target
mask covers focus state
background layer references missing source
mobile horizontal overflow
required content clipped
semantic order replaced by decorative order
state variant missing accessibility fallback
```

## 7.2 Language completeness

A language validator should be able to report coverage such as:

```text
Elements covered
Blocks covered
Sockets covered
Compositions covered
Token references valid
Assets valid
Required states covered
Reduced motion covered
High contrast fallback covered
Responsive recipes valid
```

## 7.3 Reference vectors

A project should maintain a small stable set of semantic Compositions rendered through multiple Visual Languages.

For example:

```text
Home + Core
Home + Neo-Edo
Home + Western Comics
Home + Cybernetic Minimalism
```

All must pass the same semantic and operation invariants even when their pixels and morphology differ substantially.
# 8. Protocol and Implementation Boundary

SES defines interface semantics and expression. It intentionally does not define a transport or synchronization protocol.

A separate protocol may define how SES definitions, instances, assets, state changes, or resolved expressions move between processes, repositories, tools, runtimes, or devices.

## 8.1 SES owns

- canonical semantic types
- Slot and Socket contracts
- Block and Composition definitions
- Visual Language structure
- Theme structure
- Recipe model
- Morphology model
- Appearance model
- token semantics
- asset references
- projection contracts
- resolver semantics
- conformance rules

## 8.2 A separate protocol may own

- serialization format
- transport
- remote references
- capability negotiation
- version negotiation
- patching and deltas
- persistence
- synchronization
- authoring messages
- asset delivery
- cache policy
- signatures
- authentication and authorization

## 8.3 IV implementation boundary

IV should be treated as a downstream implementation of SES, not the definition of SES.

The recommended relationship is:

```text
SES Specification
      |
SES Protocol
      |
IV Adapter / Runtime
      |
IV Components and Screens
```

The implementation may expose optimizations or host-specific extensions, but those extensions should be namespaced and must not silently redefine canonical SES semantics.

## 8.4 Versioning

Version independently:

```text
SES semantic schema
SES expression schema
SES protocol
Visual Languages
Themes
Renderer
IV implementation
```

Equal version numbers do not imply compatibility. Compatibility should be declared explicitly.


--- FILE: docs/candidates/SES-040-candidate.json (29 lines, 2.6 KiB) ---
{
  "$schema": "https://iepe.dev/schema/candidate.schema.json",
  "id": "SES-040-candidate-001",
  "issue": "SES-040",
  "name": "SES local implementation candidate 001",
  "status": "qualified-local-candidate",
  "authority": "coordinator.local",
  "protocol": {"id": "IEPE-001", "version": "0.2.0", "revision": "56f82de8cca122cc4d347cdd55bb32bdcd31ed27"},
  "scope": {
    "implemented": ["pure resolver", "resolved-output fixture", "validator", "negative diagnostics", "resource resolution", "recipe cascade", "projection enforcement", "snapshots", "DOM/CSS adapter", "equivalence checks", "operation routing", "accessibility metadata", "keyboard/focus metadata", "responsive metadata", "accessibility modes", "security boundary", "local performance measurement", "framework-neutral adapter", "cross-language summary and mutation checks"],
    "excluded": ["transport", "persistence", "synchronization", "authorization", "product navigation", "production deployment", "external publication"]
  },
  "evidence": {
    "issueRecords": ["work/SES-021.md", "work/SES-022.md", "work/SES-023.md", "work/SES-024.md", "work/SES-025.md", "work/SES-026.md", "work/SES-027.md", "work/SES-028.md", "work/SES-029.md", "work/SES-030.md", "work/SES-031.md", "work/SES-032.md", "work/SES-033.md", "work/SES-034.md", "work/SES-035.md", "work/SES-036.md", "work/SES-037.md", "work/SES-038.md", "work/SES-039.md"],
    "evidenceRecords": ["evidence/SES-021-evidence.json", "evidence/SES-022-evidence.json", "evidence/SES-023-evidence.json", "evidence/SES-024-evidence.json", "evidence/SES-025-evidence.json", "evidence/SES-026-evidence.json", "evidence/SES-027-evidence.json", "evidence/SES-028-evidence.json", "evidence/SES-029-evidence.json", "evidence/SES-030-evidence.json", "evidence/SES-031-evidence.json", "evidence/SES-032-evidence.json", "evidence/SES-033-evidence.json", "evidence/SES-034-evidence.json", "evidence/SES-035-evidence.json", "evidence/SES-036-evidence.json", "evidence/SES-037-evidence.json", "evidence/SES-038-evidence.json", "evidence/SES-039-evidence.json"]
  },
  "qualification": {
    "maturity": "implemented-and-locally-tested",
    "reproduction": "run the SES-021 through SES-039 local checks recorded in the issue evidence",
    "evaluator": "documentation.conformance + schema.validation",
    "recommendation": "accept as a local implementation candidate; do not promote to empirically-validated or release-ready"
  },
  "gaps": [
    "No independent browser or assistive-technology evaluation",
    "No production workload or cross-machine performance benchmark",
    "No independent promotion authority assigned",
    "No framework-specific production integration"
  ]
}


--- FILE: docs/examples/home-example.ts (151 lines, 5.0 KiB) ---
import type {
  BlockDefinition,
  CompositionDefinition,
  ExpressionRecipe,
  VisualLanguage,
} from "../schemas/ses-schema";

export const MediaCard: BlockDefinition = {
  id: "media-card",
  name: "Media Card",
  kind: "content",
  semanticRole: "media-content-summary",
  states: ["default", "hover", "focus", "selected", "disabled"],
  operations: ["open-media"],
  slots: [
    { id: "media", name: "Media", semanticRole: "media", cardinality: "one", content: { type: "element", accepts: ["image"] } },
    { id: "badge", name: "Badge", semanticRole: "annotation", cardinality: "optional", content: { type: "element", accepts: ["badge"] } },
    { id: "title", name: "Title", semanticRole: "title", cardinality: "one", content: { type: "element", accepts: ["heading", "label"] } },
    { id: "subtitle", name: "Subtitle", semanticRole: "subtitle", cardinality: "optional", content: { type: "element", accepts: ["text", "label"] } },
    { id: "meta", name: "Meta", semanticRole: "meta", cardinality: "optional", content: { type: "any" } },
    { id: "action", name: "Action", semanticRole: "action", cardinality: "optional", content: { type: "element", accepts: ["button", "icon-button"] } },
  ],
  behavior: { interactive: true, navigable: true },
};

export const Home: CompositionDefinition = {
  id: "home",
  name: "Home",
  type: "screen",
  sockets: [
    {
      id: "home.hero",
      name: "Hero",
      semanticRole: "primary-introduction",
      accepts: ["hero"],
      multiplicity: "single",
      importance: "primary",
      invariance: {
        semantic: "required",
        behavioral: "required",
        actionIdentity: "required",
        structural: "bounded",
        morphological: "free",
        visual: "free",
      },
      projection: {
        preserve: ["identity", "primary-action", "accessibility-order"],
        transform: ["orientation", "media-placement", "enclosure", "background", "edges", "texture", "pattern", "ornament"],
        mayIntroduce: ["decorative-art", "background-art"],
        failureConditions: ["primary-action-unexposed", "required-content-unreachable"],
      },
      operations: {
        required: ["enter-world"],
        requireExposure: true,
      },
    },
    {
      id: "home.trending",
      name: "Trending",
      semanticRole: "content-discovery",
      accepts: ["media-rail", "media-grid", "ranked-collection"],
      multiplicity: "single",
      importance: "primary",
      invariance: {
        semantic: "required",
        behavioral: "required",
        actionIdentity: "required",
        structural: "bounded",
        morphological: "free",
        visual: "free",
      },
      projection: {
        preserve: ["content-identity", "content-priority", "view-all-operation"],
        transform: ["orientation", "card-topology", "spacing", "alignment", "enclosure"],
        mayIntroduce: ["texture", "pattern", "section-decoration"],
      },
      operations: {
        required: ["open-media", "view-all"],
        requireExposure: true,
      },
    },
  ],
};

export const NeoEdoMediaCard: ExpressionRecipe = {
  layout: {
    display: "grid",
    columns: "minmax(0, 1fr) 42%",
    overflow: "visible",
  },
  morphology: {
    hierarchy: "editorial",
    density: "compact",
    rhythm: "asymmetric",
    enclosure: "soft",
    overlap: "subtle",
  },
  appearance: {
    background: [
      { type: "color", value: "{surface.washi}" },
      { type: "texture", source: "washi-fiber", opacity: 0.28, blendMode: "multiply" },
    ],
    patterns: [
      { source: "seigaiha", placement: "bottom", opacity: 0.06 },
    ],
    edges: [
      { sides: ["top"], style: "brush", source: "dry-brush-edge", width: "4px" },
      { sides: ["left"], style: "solid", color: "{color.vermilion}", width: "2px" },
    ],
    decorations: [
      { type: "seal", source: "seal-small", anchor: "bottom-left", opacity: 0.85 },
    ],
    overflow: "visible",
  },
  slots: {
    media: { placement: "right", image: "sumi-wash" },
    badge: { placement: "top-left", appearance: { background: [{ type: "color", value: "{color.vermilion}" }] } },
    title: { placement: "left", typography: "display.brush" },
    subtitle: { placement: "left", typography: "body.editorial" },
    meta: { placement: "left", typography: "meta.compact" },
  },
};

export const NeoEdo: VisualLanguage = {
  id: "neo-edo",
  name: "Neo-Edo",
  defaultTheme: "neo-edo.ink",
  tokens: {
    primitives: {
      "color.ink": "#0b0b0d",
      "color.parchment": "#d8c7a1",
      "color.vermilion": "#b9382d",
    },
    semantic: {
      "surface.canvas": "{color.ink}",
      "surface.washi": "{color.parchment}",
      "accent.primary": "{color.vermilion}",
    },
  },
  assets: {
    textures: { "washi-fiber": { src: "textures/washi-fiber" } },
    patterns: { seigaiha: { src: "patterns/seigaiha" } },
    edges: { "dry-brush-edge": { src: "edges/dry-brush" } },
    ornaments: { "seal-small": { src: "ornaments/seal-small" } },
  },
  recipes: {
    blocks: {
      "media-card": NeoEdoMediaCard,
    },
  },
};



========================================================================
## SUBSYSTEM: CANONICAL CONTRACT SCHEMAS & PROTOCOL DEFINITIONS (2 files)
========================================================================

--- FILE: docs/schemas/ses-schema.ts (322 lines, 7.8 KiB) ---
export type ID = string;
export type TokenRef = `--${string}` | `{${string}}` | string;

export type SemanticState =
  | "default" | "hover" | "focus" | "pressed" | "selected" | "active"
  | "disabled" | "loading" | "error" | "success" | "warning"
  | "read" | "unread" | "owned" | "locked" | string;

export type InvarianceRequirement = "required" | "bounded" | "free";

export interface ElementDefinition {
  id: ID;
  kind: string;
  role?: string;
  variants?: string[];
  states?: SemanticState[];
  operations?: ID[];
  accessibility?: {
    role?: string;
    labelRequired?: boolean;
    keyboardInteractive?: boolean;
  };
}

export interface SlotDefinition {
  id: ID;
  name: string;
  semanticRole: string;
  cardinality: "one" | "optional" | "many";
  content:
    | { type: "element"; accepts?: ID[] }
    | { type: "block"; accepts?: ID[] }
    | { type: "content"; accepts?: string[] }
    | { type: "any" };
  priority?: number;
  fallback?: unknown;
}

export interface BlockDefinition {
  id: ID;
  name: string;
  kind: string;
  semanticRole: string;
  slots: SlotDefinition[];
  variants?: string[];
  states?: SemanticState[];
  operations?: ID[];
  behavior?: {
    interactive?: boolean;
    selectable?: boolean;
    navigable?: boolean;
    expandable?: boolean;
    dismissible?: boolean;
  };
  constraints?: {
    requiredSlots?: ID[];
    mutuallyExclusiveSlots?: ID[][];
    minItems?: number;
    maxItems?: number;
  };
}

export interface SocketAcceptedBlock {
  block: ID;
  variants?: string[];
  capabilities?: string[];
}

export interface InvarianceProfile {
  semantic?: InvarianceRequirement;
  behavioral?: InvarianceRequirement;
  actionIdentity?: InvarianceRequirement;
  structural?: InvarianceRequirement;
  morphological?: InvarianceRequirement;
  visual?: InvarianceRequirement;
}

export interface ProjectionContract {
  preserve?: string[];
  transform?: string[];
  mayOmit?: string[];
  mayIntroduce?: string[];
  failureConditions?: string[];
  tolerance?: Record<string, unknown>;
}

export interface OperationContract {
  required?: ID[];
  optional?: ID[];
  requireExposure?: boolean;
  requireSignaling?: boolean;
}

export interface SocketDefinition {
  id: ID;
  name: string;
  semanticRole: string;
  accepts: Array<ID | SocketAcceptedBlock>;
  multiplicity: "single" | "optional" | "repeat";
  importance?: "primary" | "secondary" | "tertiary";
  order?: number;
  constraints?: {
    min?: number;
    max?: number;
    preferredSpan?: "narrow" | "medium" | "wide" | "full";
    overflow?: "wrap" | "scroll" | "clip" | "paginate" | "none";
    required?: boolean;
  };
  invariance?: InvarianceProfile;
  projection?: ProjectionContract;
  operations?: OperationContract;
  responsive?: {
    priority?: number;
    collapseInto?: ID;
    hideBelow?: string;
    reorderAllowed?: boolean;
    preserveRequiredOperations?: boolean;
  };
}

export interface CompositionDefinition {
  id: ID;
  name: string;
  type: "screen" | "page" | "flow" | "shell" | "section";
  sockets: SocketDefinition[];
  hierarchy?: CompositionNode[];
}

export interface CompositionNode {
  socket: ID;
  children?: CompositionNode[];
  relation?: "sequence" | "group" | "parallel" | "aside" | "overlay";
  priority?: number;
}

export interface MorphologyRecipe {
  hierarchy?: string;
  topology?: string;
  density?: string;
  rhythm?: string;
  alignment?: string;
  symmetry?: string;
  enclosure?: string;
  continuity?: string;
  direction?: string;
  overlap?: string;
  fragmentation?: string;
  visualWeight?: Record<string, number>;
}

export type BackgroundLayer =
  | { type: "color"; value: string; opacity?: number; blendMode?: string }
  | { type: "gradient"; value: string; opacity?: number; blendMode?: string }
  | { type: "texture"; source: ID; opacity?: number; blendMode?: string; mask?: string }
  | { type: "pattern"; source: ID; opacity?: number; blendMode?: string; mask?: string }
  | { type: "image"; source: ID; fit?: string; position?: string; opacity?: number; blendMode?: string }
  | { type: "custom"; source: ID; props?: Record<string, unknown> };

export interface EdgeLayer {
  sides: "all" | Array<"top" | "right" | "bottom" | "left">;
  style: string;
  width?: string;
  color?: string;
  opacity?: number;
  source?: ID;
  offset?: string;
  inset?: boolean;
  start?: string;
  end?: string;
  repeat?: "stretch" | "repeat" | "round";
  mask?: string;
}

export interface TextureLayer {
  source: ID;
  opacity?: number;
  blendMode?: string;
  scale?: string | number;
  direction?: string;
  mask?: string;
}

export interface PatternLayer {
  source: ID;
  placement?: string;
  opacity?: number;
  blendMode?: string;
  scale?: string | number;
  rotation?: number;
  density?: number;
  mask?: string;
}

export interface DecorationLayer {
  id?: ID;
  type: string;
  source?: ID;
  anchor?: string;
  x?: string;
  y?: string;
  width?: string;
  height?: string;
  rotation?: number;
  opacity?: number;
  blendMode?: string;
  zIndex?: number;
  bleed?: Partial<Record<"top" | "right" | "bottom" | "left", string>>;
}

export interface AppearanceRecipe {
  background?: BackgroundLayer[];
  textures?: TextureLayer[];
  patterns?: PatternLayer[];
  edges?: EdgeLayer[];
  decorations?: DecorationLayer[];
  mask?: string | Record<string, unknown>;
  clip?: string | Record<string, unknown>;
  bleed?: Partial<Record<"top" | "right" | "bottom" | "left", string>>;
  overflow?: "visible" | "hidden" | "clip";
  opacity?: number;
  blendMode?: string;
  filter?: string;
  backdrop?: string;
}

export interface LayoutRecipe {
  display?: "block" | "flex" | "grid" | "overlay" | string;
  flow?: string;
  columns?: string;
  rows?: string;
  areas?: string[];
  align?: string;
  justify?: string;
  gap?: string;
  padding?: string;
  margin?: string;
  aspectRatio?: string;
  overflow?: string;
  position?: string;
  transform?: string;
}

export interface SlotPresentationRecipe {
  placement?: string;
  order?: number;
  gridArea?: string;
  width?: string;
  height?: string;
  margin?: string;
  padding?: string;
  typography?: ID;
  image?: ID;
  appearance?: AppearanceRecipe;
  visibility?: string;
}

export interface ExpressionRecipe {
  layout?: LayoutRecipe;
  morphology?: MorphologyRecipe;
  appearance?: AppearanceRecipe;
  typography?: ID | Record<string, ID>;
  image?: ID;
  slots?: Record<ID, SlotPresentationRecipe>;
  state?: Record<SemanticState, Partial<ExpressionRecipe>>;
  variants?: Record<string, Partial<ExpressionRecipe>>;
  responsive?: Record<string, Partial<ExpressionRecipe>>;
}

export interface TokenRegistry {
  primitives?: Record<string, string | number>;
  semantic?: Record<string, string | number>;
  roles?: Record<string, string | number>;
}

export interface AssetRegistry {
  fonts?: Record<ID, unknown>;
  icons?: Record<ID, unknown>;
  textures?: Record<ID, unknown>;
  patterns?: Record<ID, unknown>;
  masks?: Record<ID, unknown>;
  edges?: Record<ID, unknown>;
  backgrounds?: Record<ID, unknown>;
  ornaments?: Record<ID, unknown>;
  images?: Record<ID, unknown>;
  custom?: Record<ID, unknown>;
}

export interface VisualLanguage {
  id: ID;
  name: string;
  description?: string;
  philosophy?: string;
  defaultTheme: ID;
  tokens: TokenRegistry;
  assets?: AssetRegistry;
  foundations?: Record<string, unknown>;
  recipes: {
    elements?: Record<ID, ExpressionRecipe>;
    blocks?: Record<ID, ExpressionRecipe>;
    sockets?: Record<ID, ExpressionRecipe>;
    compositions?: Record<ID, ExpressionRecipe>;
  };
}

export interface ThemeDefinition {
  id: ID;
  name: string;
  language: ID;
  mode?: string;
  tokenOverrides?: Record<string, string | number>;
  assetOverrides?: Partial<AssetRegistry>;
  recipeOverrides?: VisualLanguage["recipes"];
}

export interface UIExpressionState {
  visualLanguage: ID;
  theme: ID;
  styleOptions?: Record<string, unknown>;
  viewport?: string;
  reducedMotion?: boolean;
  highContrast?: boolean;
}


--- FILE: docs/schemas/ses.schema.json (151 lines, 5.5 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.invalid/ses/1.0.0/ses.schema.json",
  "title": "Semantic Expression System",
  "type": "object",
  "required": ["version", "kind", "id"],
  "properties": {
    "version": { "const": "1.0.0" },
    "kind": {
      "enum": [
        "element",
        "block",
        "socket",
        "composition",
        "visual-language",
        "theme",
        "projection-contract",
        "recipe"
      ]
    },
    "id": { "type": "string", "minLength": 1 },
    "name": { "type": "string" },
    "semanticRole": { "type": "string" },
    "slots": { "type": "array" },
    "sockets": { "type": "array" },
    "accepts": { "type": "array" },
    "invariance": { "$ref": "#/$defs/invariance" },
    "projection": { "$ref": "#/$defs/projection" },
    "operations": { "$ref": "#/$defs/operations" },
    "layout": { "type": "object", "additionalProperties": true },
    "morphology": { "$ref": "#/$defs/morphology" },
    "appearance": { "$ref": "#/$defs/appearance" },
    "tokens": { "type": "object", "additionalProperties": true },
    "assets": { "type": "object", "additionalProperties": true },
    "recipes": { "type": "object", "additionalProperties": true }
  },
  "$defs": {
    "requirement": {
      "enum": ["required", "bounded", "free"]
    },
    "invariance": {
      "type": "object",
      "properties": {
        "semantic": { "$ref": "#/$defs/requirement" },
        "behavioral": { "$ref": "#/$defs/requirement" },
        "actionIdentity": { "$ref": "#/$defs/requirement" },
        "structural": { "$ref": "#/$defs/requirement" },
        "morphological": { "$ref": "#/$defs/requirement" },
        "visual": { "$ref": "#/$defs/requirement" }
      },
      "additionalProperties": false
    },
    "projection": {
      "type": "object",
      "properties": {
        "preserve": { "type": "array", "items": { "type": "string" } },
        "transform": { "type": "array", "items": { "type": "string" } },
        "mayOmit": { "type": "array", "items": { "type": "string" } },
        "mayIntroduce": { "type": "array", "items": { "type": "string" } },
        "failureConditions": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": true
    },
    "operations": {
      "type": "object",
      "properties": {
        "required": { "type": "array", "items": { "type": "string" } },
        "optional": { "type": "array", "items": { "type": "string" } },
        "requireExposure": { "type": "boolean" },
        "requireSignaling": { "type": "boolean" }
      },
      "additionalProperties": false
    },
    "morphology": {
      "type": "object",
      "properties": {
        "hierarchy": { "type": "string" },
        "topology": { "type": "string" },
        "density": { "type": "string" },
        "rhythm": { "type": "string" },
        "alignment": { "type": "string" },
        "symmetry": { "type": "string" },
        "enclosure": { "type": "string" },
        "continuity": { "type": "string" },
        "direction": { "type": "string" },
        "overlap": { "type": "string" },
        "fragmentation": { "type": "string" }
      },
      "additionalProperties": true
    },
    "appearance": {
      "type": "object",
      "properties": {
        "background": { "type": "array", "items": { "$ref": "#/$defs/backgroundLayer" } },
        "textures": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
        "patterns": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
        "edges": { "type": "array", "items": { "$ref": "#/$defs/edgeLayer" } },
        "decorations": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
        "mask": {},
        "clip": {},
        "bleed": { "type": "object", "additionalProperties": { "type": "string" } },
        "overflow": { "enum": ["visible", "hidden", "clip"] },
        "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
        "blendMode": { "type": "string" },
        "filter": { "type": "string" },
        "backdrop": { "type": "string" }
      },
      "additionalProperties": true
    },
    "backgroundLayer": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": { "enum": ["color", "gradient", "texture", "pattern", "image", "custom"] },
        "value": { "type": "string" },
        "source": { "type": "string" },
        "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
        "blendMode": { "type": "string" },
        "mask": { "type": "string" },
        "fit": { "type": "string" },
        "position": { "type": "string" }
      },
      "additionalProperties": true
    },
    "edgeLayer": {
      "type": "object",
      "required": ["sides", "style"],
      "properties": {
        "sides": {
          "oneOf": [
            { "const": "all" },
            { "type": "array", "items": { "enum": ["top", "right", "bottom", "left"] }, "minItems": 1 }
          ]
        },
        "style": { "type": "string" },
        "width": { "type": "string" },
        "color": { "type": "string" },
        "opacity": { "type": "number", "minimum": 0, "maximum": 1 },
        "source": { "type": "string" },
        "offset": { "type": "string" },
        "inset": { "type": "boolean" },
        "start": { "type": "string" },
        "end": { "type": "string" },
        "repeat": { "enum": ["stretch", "repeat", "round"] },
        "mask": { "type": "string" }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}



========================================================================
## SUBSYSTEM: CONFORMANCE SUITE & TEST FIXTURES (40 files)
========================================================================

--- FILE: docs/conformance/accessibility-expression.json (9 lines, 0.7 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-009",
  "title": "SES Accessibility-Preserving Expression",
  "status": "Canonical Contract",
  "contexts": ["keyboard-only", "focus-visible", "reduced-motion", "high-contrast", "non-color-state", "narrow-responsive"],
  "checks": ["A11Y-001","A11Y-002","A11Y-003","A11Y-004","A11Y-005","A11Y-006","A11Y-007","A11Y-008"],
  "failureCodes": ["ERR_ACCESSIBLE_NAME_MISSING","ERR_ROLE_RELATIONSHIP_INVALID","ERR_KEYBOARD_ORDER_MISMATCH","ERR_OPERATION_NOT_EXPOSED","ERR_FOCUS_INDICATOR_OBSTRUCTED","ERR_STATE_SIGNALING_INSUFFICIENT","ERR_A11Y_FALLBACK_MISSING","ERR_REDUCED_MOTION_UNSUPPORTED","ERR_HIGH_CONTRAST_FALLBACK_MISSING"]
}


--- FILE: docs/conformance/accessibility-fixtures.json (17 lines, 1.1 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-032-accessibility-fixtures",
  "valid": {
    "accessibleName": "Media card: Sunrise over the bay",
    "role": "article",
    "knownIds": ["media-card", "media-card-title", "media-card-media"],
    "relationships": [{"type": "labelledby", "target": "media-card-title"}, {"type": "describedby", "target": "media-card-media"}],
    "operations": [{"id": "open-media", "accessibleName": "Open Sunrise over the bay"}]
  },
  "invalid": [
    {"record": {"role": "article", "knownIds": []}, "expectedCode": "ERR_ACCESSIBLE_NAME_MISSING"},
    {"record": {"accessibleName": "Card", "role": "unknown", "knownIds": []}, "expectedCode": "ERR_ACCESSIBLE_ROLE_INVALID"},
    {"record": {"accessibleName": "Card", "role": "article", "knownIds": [], "relationships": [{"type": "labelledby", "target": "missing"}]}, "expectedCode": "ERR_ACCESSIBLE_RELATIONSHIP_BROKEN"},
    {"record": {"accessibleName": "Card", "role": "article", "knownIds": [], "operations": [{"id": "open-media"}]}, "expectedCode": "ERR_OPERATION_ACCESSIBLE_NAME_MISSING"}
  ]
}


--- FILE: docs/conformance/accessibility-mode-fixtures.json (21 lines, 0.9 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-035-accessibility-mode-fixtures",
  "output": {
    "identity": {"target": "media-card"},
    "semantic": {"operations": ["open-media"]},
    "expression": {
      "motion": {"enabled": true, "duration": 200, "reducedMotion": {"mode": "none"}},
      "highContrast": {"enabled": true, "surface": "solid", "edge": "strong"}
    },
    "accessibility": {"required": true}
  },
  "contexts": [
    {"reducedMotion": true, "highContrast": true},
    {"reducedMotion": false, "highContrast": false}
  ],
  "invalid": [
    {"context": {"reducedMotion": true, "highContrast": false}, "output": {"expression": {"motion": {"enabled": true}}}, "expectedCode": "ERR_REDUCED_MOTION_FALLBACK_MISSING"},
    {"context": {"reducedMotion": false, "highContrast": true}, "output": {"expression": {}}, "expectedCode": "ERR_HIGH_CONTRAST_FALLBACK_MISSING"}
  ]
}


--- FILE: docs/conformance/authoring-boundaries.json (10 lines, 0.8 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-018",
  "title": "SES Authoring Boundaries",
  "status": "Canonical Contract",
  "surfaces": ["element","slot","block","socket","composition","projection-contract","visual-language","theme","recipe","token-registry","asset-registry","resolver","host-renderer","external-protocol-application"],
  "routingRules": ["stable-cross-language-property-to-semantic-or-projection","mutable-presentation-property-to-expression","data-movement-to-external-protocol","business-behavior-to-host-application","host-extension-to-namespaced-adapter","no-semantic-duplication"],
  "conflictRule": "canonical-semantic-and-projection-authority-wins; unresolved-authority-is-recorded",
  "scopeExclusions": ["codebase-reorganization","transport-schema","application-business-logic"]
}


--- FILE: docs/conformance/change-governance.json (11 lines, 0.8 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-015",
  "title": "SES Change Governance",
  "status": "Canonical Contract",
  "versionBoundaries": ["semantic-model","expression-model","projection-contract","conformance","resolver","renderer-neutral-output","visual-language","theme","host-renderer","external-protocol"],
  "changeClasses": ["documentation","additive","conformance-tightening","breaking-semantic","breaking-expression","deprecation"],
  "requiredChangeRecord": ["changeId","boundary","intent","before","after","compatibility","impact","evidence","authority","disposition"],
  "reviewInputs": ["SES-001","fixtures","result-schema","equivalence-vectors","responsive-contract","accessibility-contract","resolver-contract","output-contract","changelog"],
  "inconclusiveWithoutEvidence": true
}


--- FILE: docs/conformance/cross-language-fixture.json (9 lines, 0.4 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-039-cross-language-fixture",
  "implementationLanguages": ["python", "javascript"],
  "source": "expression-equivalence-fixtures.json",
  "requiredComparisons": ["semantic identity", "operation identity", "Visual Language set"],
  "mutationCases": ["target mutation rejected", "operation mutation detected"],
  "qualification": "local cross-language summary and mutation check"
}


--- FILE: docs/conformance/dom-css-fixture.json (13 lines, 0.5 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-029-dom-css-fixture",
  "input": "SES-021 MediaCard/Neo-Edo resolved output",
  "requiredHtmlMarkers": [
    "data-ses-identity=\"media-card\"",
    "data-ses-visual-language=\"neo-edo\"",
    "data-ses-operation=\"open-media\"",
    "data-ses-semantic-target=\"media-card\""
  ],
  "requiredCssMarkers": ["focus-visible", "outline", "box-sizing"],
  "forbiddenCanonicalFields": ["dom", "css", "eventHandler"]
}


--- FILE: docs/conformance/expression-equivalence-fixtures.json (15 lines, 1.0 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-030-expression-equivalence-fixtures",
  "semantic": {
    "block": "media-card",
    "slots": ["media", "title", "subtitle", "meta", "action"],
    "operations": ["open-media"]
  },
  "expressions": [
    {"target": "media-card", "visualLanguage": "core", "morphology": {"orientation": "vertical", "density": "comfortable"}, "projection": {"preserve": ["identity", "operation-identity"], "transform": ["orientation", "density"]}},
    {"target": "media-card", "visualLanguage": "neo-edo", "morphology": {"orientation": "asymmetric", "density": "compact"}, "projection": {"preserve": ["identity", "operation-identity"], "transform": ["orientation", "density", "texture", "ornament"]}},
    {"target": "media-card", "visualLanguage": "western-comics", "morphology": {"orientation": "horizontal", "density": "dense"}, "projection": {"preserve": ["identity", "operation-identity"], "transform": ["orientation", "density", "edges", "pattern"]}
    }
  ]
}


--- FILE: docs/conformance/fixture-index.schema.json (18 lines, 0.8 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.invalid/ses/1.0.0/conformance-fixture-index.schema.json",
  "title": "SES Conformance Fixture Index",
  "type": "object",
  "required": ["id", "sourceBaseline", "files", "counts"],
  "properties": {
    "$schema": { "type": "string" },
    "id": { "const": "SES-002" },
    "title": { "type": "string" },
    "version": { "type": "string" },
    "sourceBaseline": { "type": "string" },
    "expectations": { "type": "object", "additionalProperties": { "type": "string" } },
    "files": { "type": "array", "items": { "type": "string" }, "minItems": 2 },
    "counts": { "type": "object", "required": ["positive", "negative"], "properties": { "positive": { "const": 4 }, "negative": { "const": 12 } }, "additionalProperties": false }
  },
  "additionalProperties": false
}


--- FILE: docs/conformance/fixture.schema.json (48 lines, 2.6 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.invalid/ses/1.0.0/conformance-fixture.schema.json",
  "title": "SES Conformance Fixture",
  "type": "object",
  "required": ["id", "kind", "baseline", "layer", "expected"],
  "properties": {
    "id": { "type": "string", "minLength": 1 },
    "kind": { "enum": ["positive", "negative"] },
    "baseline": { "type": "string", "minLength": 1 },
    "layer": { "enum": ["S", "C", "R", "A", "I", "V"] },
    "source": { "type": "array", "items": { "type": "string" } },
    "semantic": { "type": "object", "additionalProperties": false, "required": ["composition", "identities", "operations"], "properties": {
      "composition": { "type": "string" },
      "identities": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
      "operations": { "type": "array", "items": { "type": "string" } }
    }},
    "expression": { "type": "object", "additionalProperties": false, "properties": {
      "visualLanguage": { "type": "string" },
      "allowedMutations": { "type": "array", "items": { "type": "string" } }
    }},
    "scenario": { "type": "string" },
    "vectors": { "type": "array", "items": { "type": "object", "required": ["id", "visualLanguage", "allowedMutations"], "properties": {
      "id": { "type": "string" },
      "visualLanguage": { "type": "string" },
      "allowedMutations": { "type": "array", "items": { "type": "string" } }
    }, "additionalProperties": false } },
    "equivalenceChecks": { "type": "array", "items": { "type": "string" } },
    "fixtures": { "type": "array", "items": { "type": "object", "required": ["id", "baseline", "layer", "scenario", "errorCode", "failureCondition"], "properties": {
      "id": { "type": "string" },
      "baseline": { "type": "string" },
      "layer": { "enum": ["S", "C", "R", "A", "I", "V"] },
      "scenario": { "type": "string" },
      "errorCode": { "type": "string" },
      "failureCondition": { "type": "string" }
    }, "additionalProperties": false } },
    "expected": { "type": "object", "additionalProperties": false, "required": ["result"], "properties": {
      "result": { "enum": ["pass", "fail"] },
      "errorCode": { "type": "string" },
      "failureCondition": { "type": "string" }
    }}
  },
  "allOf": [
    { "if": { "properties": { "kind": { "const": "positive" } } }, "then": { "required": ["semantic", "expression"] } },
    { "if": { "properties": { "kind": { "const": "negative" } }, "required": ["scenario"] }, "then": { "properties": { "expected": { "required": ["errorCode", "failureCondition"] } } } }
  ],
  "additionalProperties": false
}


--- FILE: docs/conformance/fixtures/index.json (20 lines, 0.7 KiB) ---
{
  "$schema": "../fixture-index.schema.json",
  "id": "SES-002",
  "title": "SES Conformance Fixture Index",
  "version": "1.0.0-draft",
  "sourceBaseline": "../ses-001-matrix.json",
  "expectations": {
    "positive": "Every positive fixture preserves the listed semantic identities and operations while permitting only declared expression mutations.",
    "negative": "Every negative fixture fails at the declared layer with the declared error code and failure condition.",
    "schema": "Every fixture record validates against ../fixture.schema.json."
  },
  "files": [
    "positive-home.json",
    "negative.json"
  ],
  "counts": {
    "positive": 4,
    "negative": 12
  }
}


--- FILE: docs/conformance/fixtures/negative.json (23 lines, 3.0 KiB) ---
{
  "$schema": "../fixture.schema.json",
  "id": "SES-002-negative-fixtures",
  "kind": "negative",
  "baseline": "SES-001",
  "layer": "S",
  "source": ["../../09-conformance-baseline.md", "../ses-001-matrix.json"],
  "expected": {"result":"fail","errorCode":"fixture-records-use-case-expectations","failureCondition":"Each record below supplies its own baseline layer, error code, and failure condition."},
  "fixtures": [
    {"id":"invalid-missing-required-slot","baseline":"SEM-02","layer":"S","scenario":"MediaCard omits required title Slot","errorCode":"ERR_SLOT_REQUIRED_MISSING","failureCondition":"required Slot omitted"},
    {"id":"invalid-incompatible-slot-content","baseline":"SEM-02","layer":"S","scenario":"Slot receives content outside its accepted types","errorCode":"ERR_SLOT_CONTENT_INCOMPATIBLE","failureCondition":"Slot content type rejected"},
    {"id":"invalid-unknown-socket-block","baseline":"SEM-03","layer":"S","scenario":"Socket admits an unlisted Block","errorCode":"ERR_SOCKET_ADMISSION_DENIED","failureCondition":"incompatible Block admitted"},
    {"id":"invalid-required-operation-hidden","baseline":"ACT-02","layer":"I","scenario":"Required operation exists but is not exposed","errorCode":"ERR_OPERATION_NOT_EXPOSED","failureCondition":"required operation unexposed"},
    {"id":"invalid-unknown-token","baseline":"RES-02","layer":"R","scenario":"Recipe references an undefined token","errorCode":"ERR_TOKEN_UNRESOLVED","failureCondition":"unresolved token reference"},
    {"id":"invalid-unknown-asset","baseline":"RES-02","layer":"R","scenario":"Recipe references an absent asset","errorCode":"ERR_ASSET_NOT_FOUND","failureCondition":"unresolved asset reference"},
    {"id":"invalid-unknown-recipe-target","baseline":"RES-01","layer":"R","scenario":"Recipe targets an unknown semantic identity","errorCode":"ERR_RECIPE_TARGET_UNKNOWN","failureCondition":"recipe target does not resolve"},
    {"id":"invalid-focus-obscured","baseline":"ACC-02","layer":"I","scenario":"Appearance layer obscures focus indication","errorCode":"ERR_FOCUS_INDICATOR_OBSTRUCTED","failureCondition":"focus indicator obscured"},
    {"id":"invalid-semantic-order","baseline":"ACC-01","layer":"I","scenario":"Decorative order changes logical reading or keyboard order","errorCode":"ERR_KEYBOARD_ORDER_MISMATCH","failureCondition":"semantic order invalidated"},
    {"id":"invalid-required-content-clipped","baseline":"RSP-01","layer":"V","scenario":"Required content is clipped or unreachable","errorCode":"ERR_CONTENT_CLIPPED","failureCondition":"required content clipped or unreachable"},
    {"id":"invalid-mobile-overflow","baseline":"RSP-01","layer":"V","scenario":"Responsive expression overflows the viewport","errorCode":"ERR_COMPOSITION_OVERFLOW","failureCondition":"mobile horizontal overflow"},
    {"id":"invalid-missing-state-fallback","baseline":"SEM-04","layer":"S","scenario":"State variant has no accessible fallback","errorCode":"ERR_A11Y_FALLBACK_MISSING","failureCondition":"state variant missing accessibility fallback"}
  ]
}


--- FILE: docs/conformance/fixtures/positive-home.json (20 lines, 1.2 KiB) ---
{
  "$schema": "../fixture.schema.json",
  "id": "SES-002-positive-home",
  "kind": "positive",
  "baseline": "VAR-01",
  "layer": "V",
  "source": ["../../09-conformance-baseline.md", "../ses-001-matrix.json", "../../examples/home-example.ts"],
  "semantic": {
    "composition": "home",
    "identities": ["home", "home.hero", "home.trending", "hero", "media-rail", "media-grid", "ranked-collection"],
    "operations": ["enter-world", "open-media", "view-all"]
  },
  "vectors": [
    {"id":"valid-home-core","visualLanguage":"core","allowedMutations":["orientation","enclosure","spacing","alignment"]},
    {"id":"valid-home-neo-edo","visualLanguage":"neo-edo","allowedMutations":["orientation","media-placement","enclosure","background","edges","texture","pattern","ornament"]},
    {"id":"valid-home-western-comics","visualLanguage":"western-comics","allowedMutations":["orientation","card-topology","media-placement","enclosure","background","edges","texture","pattern","ornament"]},
    {"id":"valid-home-cybernetic-minimalism","visualLanguage":"cybernetic-minimalism","allowedMutations":["orientation","card-topology","media-placement","enclosure","background","edges","texture","pattern","ornament"]}
  ],
  "expected": {"result":"pass"}
}


--- FILE: docs/conformance/host-adapter-fixture.json (17 lines, 0.7 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-038-host-adapter-fixture",
  "applicationState": {
    "semantic": {"block": "media-card", "operations": ["open-media"]},
    "expression": {"target": "media-card", "visualLanguage": "core", "morphology": {"orientation": "vertical"}},
    "context": {"viewport": "wide"}
  },
  "ownership": {
    "transport": "host-application",
    "persistence": "host-application",
    "authorization": "host-application",
    "navigation": "host-application",
    "rendering": "host-renderer"
  },
  "expected": {"identity": {"composition": "media-card", "target": "media-card"}, "operationOwner": "host-application"}
}


--- FILE: docs/conformance/keyboard-focus-fixtures.json (15 lines, 0.9 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-033-keyboard-focus-fixtures",
  "valid": {
    "semanticOrder": ["media", "title", "open-media"],
    "keyboardOrder": ["media", "title", "open-media"],
    "focusVisible": true,
    "controls": [{"id": "open-media", "keyboardReachable": true, "tabIndex": 0}]
  },
  "invalid": [
    {"record": {"semanticOrder": ["title", "open-media"], "keyboardOrder": ["open-media", "title"], "focusVisible": true, "controls": []}, "expectedCode": "ERR_KEYBOARD_ORDER_MISMATCH"},
    {"record": {"semanticOrder": [], "keyboardOrder": [], "focusVisible": false, "controls": []}, "expectedCode": "ERR_FOCUS_INDICATOR_OBSTRUCTED"},
    {"record": {"semanticOrder": [], "keyboardOrder": [], "focusVisible": true, "controls": [{"id": "open-media", "keyboardReachable": false, "tabIndex": 0}]}, "expectedCode": "ERR_KEYBOARD_CONTROL_UNREACHABLE"}
  ]
}


--- FILE: docs/conformance/operation-routing-fixtures.json (8 lines, 0.4 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-031-operation-routing-fixtures",
  "requiredOperations": ["open-media"],
  "exposure": {"open-media": {"exposed": true, "signaled": true, "enabled": true}},
  "event": {"operationId": "open-media", "sourceIdentity": "media-card", "payload": {"mediaId": "fixture-media-1"}},
  "expectedRoute": {"operationId": "open-media", "sourceIdentity": "media-card", "dispatch": "host-owned"}
}


--- FILE: docs/conformance/performance-budgets.json (21 lines, 0.9 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-017",
  "title": "SES Performance Budgets",
  "status": "Provisional Contract",
  "profile": "warm-local-resolution",
  "budgets": {
    "resolutionP95Ms": 5,
    "tokenLookupP95Ms": 1,
    "assetMetadataP95Ms": 2,
    "recipeLayerCount": 12,
    "recipeMergeDepth": 16,
    "appearanceLayerCount": 32,
    "responsiveRecomputeP95Ms": 8,
    "motionMetadataP95Ms": 1,
    "outputSizeKiB": 256
  },
  "excludedFromPureResolver": ["resource-fetch","resource-decode","host-layout","host-paint","motion-playback"],
  "measurementPercentiles": ["p50","p95","p99"],
  "failureCodes": ["ERR_RESOLUTION_BUDGET_EXCEEDED","ERR_TOKEN_LOOKUP_BUDGET_EXCEEDED","ERR_ASSET_METADATA_BUDGET_EXCEEDED","ERR_RECIPE_DEPTH_EXCEEDED","ERR_APPEARANCE_LAYER_BUDGET_EXCEEDED","ERR_RESPONSIVE_RECOMPUTE_BUDGET_EXCEEDED","ERR_OUTPUT_SIZE_BUDGET_EXCEEDED"]
}


--- FILE: docs/conformance/performance-fixture.json (9 lines, 0.4 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-037-performance-fixture",
  "input": "reference-pack/media-card.json + appearance-neo-edo.json",
  "sampleCount": 1000,
  "measurements": ["resolver.p50", "resolver.p95", "rendererAdapter.p50", "rendererAdapter.p95"],
  "provisionalBudget": {"resolverP95Milliseconds": 5.0},
  "qualification": "local measurement, not production benchmark"
}


--- FILE: docs/conformance/projection-enforcement-fixtures.json (22 lines, 0.7 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-027-projection-enforcement-fixtures",
  "contract": {
    "preserve": ["identity", "operation-identity", "accessibility-order"],
    "transform": ["orientation", "media-placement", "background", "edges", "texture"],
    "mayOmit": ["secondary-decoration"],
    "mayIntroduce": ["ornament", "pattern"]
  },
  "validMutations": {
    "orientation": "transform",
    "media-placement": "transform",
    "ornament": "introduce",
    "secondary-decoration": "omit",
    "identity": "preserve"
  },
  "invalidMutations": {
    "business-behavior": "transform",
    "required-title": "omit",
    "new-operation": "introduce"
  }
}


--- FILE: docs/conformance/projection-equivalence.json (21 lines, 1.3 KiB) ---
{
  "$schema": "../fixture.schema.json",
  "id": "SES-007-home-equivalence",
  "kind": "positive",
  "baseline": "VAR-01",
  "layer": "V",
  "source": ["../13-projection-equivalence.md", "../fixtures/positive-home.json", "../../examples/home-example.ts"],
  "semantic": {
    "composition": "home",
    "identities": ["home", "home.hero", "home.trending", "hero", "media-rail", "media-grid", "ranked-collection"],
    "operations": ["enter-world", "open-media", "view-all"]
  },
  "vectors": [
    {"id":"valid-home-core","visualLanguage":"core","allowedMutations":["orientation","enclosure","spacing","alignment"]},
    {"id":"valid-home-neo-edo","visualLanguage":"neo-edo","allowedMutations":["orientation","media-placement","enclosure","background","edges","texture","pattern","ornament"]},
    {"id":"valid-home-western-comics","visualLanguage":"western-comics","allowedMutations":["orientation","card-topology","media-placement","enclosure","background","edges","texture","pattern","ornament"]},
    {"id":"valid-home-cybernetic-minimalism","visualLanguage":"cybernetic-minimalism","allowedMutations":["orientation","card-topology","media-placement","enclosure","background","edges","texture","pattern","ornament"]}
  ],
  "equivalenceChecks": ["EQUIV-001","EQUIV-002","EQUIV-003","EQUIV-004","EQUIV-005","EQUIV-006","EQUIV-007"],
  "expected": {"result":"pass"}
}


--- FILE: docs/conformance/recipe-precedence.json (10 lines, 1.0 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-011",
  "title": "SES Recipe Precedence and Conflict Handling",
  "status": "Canonical Contract",
  "precedence": ["visual-language","theme","user-style-options","composition","socket","block","variant","slot","element","state","responsive","accessibility"],
  "mergeRules": {"scalar":"highest-permitted-replacement","alias":"replace-then-resolve","object":"recursive-declared-fields","ordered-array":"replace-unless-additive","slot-map":"merge-by-slot-id","state-map":"merge-by-state-id","protected":"never-merge"},
  "protectedFields": ["semantic-identity","required-content","semantic-role","accessibility-relationship","operation-identity","business-behavior","invariance-profile","routing-intent","data-identity"],
  "failureCodes": ["ERR_RECIPE_CONFLICT","ERR_PROTECTED_FIELD_OVERRIDE","ERR_TRANSFORM_UNDECLARED","ERR_RECIPE_TARGET_UNKNOWN","ERR_RECIPE_LAYER_INVALID","ERR_RECIPE_MERGE_INVALID"]
}


--- FILE: docs/conformance/recipe-resolution-fixtures.json (17 lines, 0.7 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-026-recipe-resolution-fixtures",
  "layers": {
    "Visual Language": {"morphology": {"rhythm": "regular", "density": "comfortable"}, "appearance": {"surface": "paper"}},
    "Theme": {"appearance": {"surface": "washi"}},
    "Block Recipe": {"morphology": {"rhythm": "asymmetric"}},
    "accessibility overrides": {"appearance": {"focusVisibility": "high"}}
  },
  "expected": {
    "morphology.rhythm": "asymmetric",
    "morphology.density": "comfortable",
    "appearance.surface": "washi",
    "appearance.focusVisibility": "high"
  },
  "protectedOverride": {"layers": {"Block Recipe": {"operations": ["different-operation"]}}, "expectedCode": "ERR_PROTECTED_FIELD_OVERRIDE"}
}


--- FILE: docs/conformance/reference-pack/appearance-neo-edo.json (16 lines, 1.0 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "fixture-appearance-neo-edo",
  "kind": "expression",
  "visualLanguage": "neo-edo",
  "target": "media-card",
  "morphology": {"hierarchy":"editorial","density":"compact","rhythm":"asymmetric","enclosure":"soft","overlap":"subtle"},
  "appearance": {
    "background":[{"type":"color","token":"surface.washi"},{"type":"texture","asset":"washi-fiber","opacity":0.28}],
    "patterns":[{"asset":"seigaiha","placement":"bottom","opacity":0.06}],
    "edges":[{"sides":["top"],"style":"brush","asset":"dry-brush-edge"},{"sides":["left"],"style":"solid","token":"color.vermilion"}],
    "decorations":[{"type":"seal","asset":"seal-small","anchor":"bottom-left"}]
  },
  "projection": {"preserve":["identity","operation-identity","accessibility-order"],"transform":["orientation","media-placement","enclosure","background","edges","texture","pattern","ornament"]},
  "source":"../../examples/home-example.ts"
}


--- FILE: docs/conformance/reference-pack/index.json (10 lines, 0.5 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-013",
  "title": "SES Reference Implementation Fixture Pack",
  "status": "Canonical Fixture Pack",
  "files": ["semantic-home.json","media-card.json","operations-and-states.json","appearance-neo-edo.json"],
  "sharedIdentities": ["home","home.hero","home.trending","media-card"],
  "sharedOperations": ["enter-world","open-media","view-all"],
  "purpose": "Reusable semantic, operation, state, and expression fixtures for future validators and runtimes."
}


--- FILE: docs/conformance/reference-pack/media-card.json (19 lines, 0.9 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "fixture-media-card",
  "kind": "block",
  "block": "media-card",
  "semanticRole": "media-content-summary",
  "slots": [
    {"id":"media","role":"media","cardinality":"one","accepts":["image"]},
    {"id":"badge","role":"annotation","cardinality":"optional","accepts":["badge"]},
    {"id":"title","role":"title","cardinality":"one","accepts":["heading","label"]},
    {"id":"subtitle","role":"subtitle","cardinality":"optional","accepts":["text","label"]},
    {"id":"meta","role":"meta","cardinality":"optional","accepts":["any"]},
    {"id":"action","role":"action","cardinality":"optional","accepts":["button","icon-button"]}
  ],
  "states":["default","hover","focus","selected","disabled"],
  "operations":["open-media"],
  "behavior":{"interactive":true,"navigable":true},
  "source":"../../examples/home-example.ts"
}


--- FILE: docs/conformance/reference-pack/operations-and-states.json (18 lines, 0.9 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "fixture-operations-and-states",
  "kind": "interaction",
  "operations": [
    {"id":"enter-world","required":true,"exposure":true,"signaling":true},
    {"id":"open-media","required":true,"exposure":true,"signaling":true},
    {"id":"view-all","required":true,"exposure":true,"signaling":true}
  ],
  "states": [
    {"id":"default","meaning":"ordinary available state","requiresAccessibleFallback":true},
    {"id":"hover","meaning":"pointer or equivalent preview state","requiresAccessibleFallback":true},
    {"id":"focus","meaning":"keyboard or programmatic focus state","requiresAccessibleFallback":true},
    {"id":"selected","meaning":"current selection state","requiresAccessibleFallback":true},
    {"id":"disabled","meaning":"operation unavailable state","requiresAccessibleFallback":true}
  ],
  "source":"../../examples/home-example.ts"
}


--- FILE: docs/conformance/reference-pack/semantic-home.json (13 lines, 0.8 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "fixture-home-semantic",
  "kind": "composition",
  "composition": "home",
  "sockets": [
    {"id":"home.hero","accepts":["hero"],"multiplicity":"single","importance":"primary","required":true,"preserve":["identity","primary-action","accessibility-order"]},
    {"id":"home.trending","accepts":["media-rail","media-grid","ranked-collection"],"multiplicity":"single","importance":"primary","required":true,"preserve":["content-identity","content-priority","view-all-operation"]}
  ],
  "operations": ["enter-world","open-media","view-all"],
  "invariance": {"semantic":"required","behavioral":"required","actionIdentity":"required","structural":"bounded","morphological":"free","visual":"free"},
  "source": "../../examples/home-example.ts"
}


--- FILE: docs/conformance/renderer-neutral-output.json (11 lines, 0.8 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-014",
  "title": "SES Renderer-Neutral Output Contract",
  "status": "Canonical Contract",
  "sections": ["identity","semantic","projection","expression","resources","interaction","accessibility","responsive","trace","diagnostics"],
  "invariants": ["OUTPUT-001","OUTPUT-002","OUTPUT-003","OUTPUT-004","OUTPUT-005","OUTPUT-006","OUTPUT-007"],
  "failureCodes": ["ERR_OUTPUT_IDENTITY_MISSING","ERR_OUTPUT_REQUIRED_METADATA_MISSING","ERR_OUTPUT_SEMANTIC_EXPRESSION_MIXED","ERR_OUTPUT_PROVENANCE_MISSING","ERR_OUTPUT_ACCESSIBILITY_METADATA_MISSING","ERR_OUTPUT_HOST_EXTENSION_COLLISION","ERR_OUTPUT_UNRESOLVED_RESOURCE"],
  "hostNeutral": true,
  "hostResponsibilities": ["realization", "resource-loading", "operation-invocation", "platform-accessibility-mapping"]
}


--- FILE: docs/conformance/resolved-output-fixtures.json (55 lines, 1.4 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-022-resolved-output-fixtures",
  "status": "canonical",
  "source": {
    "semantic": "reference-pack/media-card.json",
    "expression": "reference-pack/appearance-neo-edo.json",
    "context": {"viewport": "wide"}
  },
  "requiredSections": [
    "identity",
    "semantic",
    "projection",
    "expression",
    "resources",
    "interaction",
    "accessibility",
    "responsive",
    "trace",
    "diagnostics"
  ],
  "expectations": {
    "identity.composition": "media-card",
    "identity.target": "media-card",
    "semantic.operations": ["open-media"],
    "projection.preserve": ["identity", "operation-identity", "accessibility-order"],
    "projection.transform": [
      "orientation",
      "media-placement",
      "enclosure",
      "background",
      "edges",
      "texture",
      "pattern",
      "ornament"
    ],
    "expression.visualLanguage": "neo-edo",
    "expression.morphology.rhythm": "asymmetric",
    "expression.appearance.background[0].token": "surface.washi",
    "interaction.operations": ["open-media"],
    "accessibility.required": true,
    "responsive.context.viewport": "wide",
    "trace.layers": ["Visual Language", "Theme", "Recipe"],
    "diagnostics.warnings": [],
    "diagnostics.failures": []
  },
  "forbiddenHostFields": [
    "dom",
    "css",
    "reactComponent",
    "nativeClass",
    "canvasPrimitive",
    "eventHandler"
  ]
}


--- FILE: docs/conformance/resource-fixtures.json (17 lines, 0.7 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-025-resource-fixtures",
  "tokens": {
    "primitive": {"color.vermilion": "#d1493f"},
    "semantic": {"surface.washi": {"alias": "surface.card"}},
    "role": {"surface.card": "#f4ead5"},
    "recipe": {},
    "explicit": {}
  },
  "assets": {
    "textures": {"washi-fiber": {"category": "textures", "kind": "texture", "source": "fixture:washi-fiber"}},
    "patterns": {"seigaiha": {"category": "patterns", "kind": "pattern", "source": "fixture:seigaiha"}},
    "edges": {"dry-brush-edge": {"category": "edges", "kind": "edge", "source": "fixture:dry-brush-edge"}},
    "ornaments": {"seal-small": {"category": "ornaments", "kind": "ornament", "source": "fixture:seal-small"}}
  }
}


--- FILE: docs/conformance/responsive-fixtures.json (24 lines, 1.9 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-034-responsive-fixtures",
  "requiredContent": ["title", "media"],
  "requiredOperations": ["open-media"],
  "states": ["default", "focus", "selected", "disabled"],
  "stateTransitions": {"default": ["focus", "selected"], "focus": ["default", "selected"], "selected": ["default"], "disabled": ["default"]},
  "valid": {
    "requiredContent": ["title", "media"],
    "requiredOperations": ["open-media"],
    "contexts": [
      {"id": "wide", "reachableOperations": ["open-media"], "hiddenContent": [], "clippedContent": [], "overflow": false},
      {"id": "narrow", "reachableOperations": ["open-media"], "hiddenContent": [], "clippedContent": [], "overflow": false}
    ],
    "states": ["default", "focus", "selected", "disabled"],
    "stateTransitions": {"default": ["focus", "selected"], "focus": ["default"]}
  },
  "invalid": [
    {"record": {"requiredContent": ["title"], "requiredOperations": ["open-media"], "contexts": [{"id": "narrow", "reachableOperations": [], "hiddenContent": [], "clippedContent": [], "overflow": true}]}, "expectedCode": "ERR_COMPOSITION_OVERFLOW"},
    {"record": {"requiredContent": ["title"], "requiredOperations": [], "contexts": [{"id": "narrow", "reachableOperations": [], "hiddenContent": ["title"], "clippedContent": [], "overflow": false}]}, "expectedCode": "ERR_CONTENT_UNREACHABLE"},
    {"record": {"requiredContent": ["title"], "requiredOperations": [], "contexts": [{"id": "narrow", "reachableOperations": [], "hiddenContent": [], "clippedContent": ["title"], "overflow": false}]}, "expectedCode": "ERR_CONTENT_CLIPPED"},
    {"record": {"requiredContent": [], "requiredOperations": [], "contexts": [{"id": "wide", "reachableOperations": [], "hiddenContent": [], "clippedContent": [], "overflow": false}], "states": ["default"], "stateTransitions": {"default": ["missing"]}}, "expectedCode": "ERR_STATE_TRANSITION_INVALID"}
  ]
}


--- FILE: docs/conformance/responsive-invariants.json (17 lines, 0.8 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-008",
  "title": "SES Responsive Invariants",
  "status": "Canonical Contract",
  "contexts": ["wide", "narrow", "small-touch", "reduced-motion", "high-contrast"],
  "mutations": {
    "reorder": "allowed-with-logical-order-preservation",
    "collapse": "allowed-with-required-reachability",
    "hide": "optional-or-explicitly-omittable-only",
    "transform": "declared-expression-properties-only",
    "overflow": "declared-and-usable-only",
    "clip": "decorative-or-explicitly-optional-only"
  },
  "invariants": ["RESP-001","RESP-002","RESP-003","RESP-004","RESP-005","RESP-006","RESP-007","RESP-008"],
  "failureCodes": ["ERR_CONTENT_UNREACHABLE","ERR_CONTENT_CLIPPED","ERR_COMPOSITION_OVERFLOW","ERR_KEYBOARD_ORDER_MISMATCH","ERR_OPERATION_NOT_EXPOSED","ERR_A11Y_FALLBACK_MISSING"]
}


--- FILE: docs/conformance/result.schema.json (56 lines, 2.3 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.invalid/ses/1.0.0/conformance-result.schema.json",
  "title": "SES Conformance Result",
  "type": "object",
  "required": ["schemaVersion", "runId", "baselineId", "fixtureId", "layer", "checkId", "result", "severity", "evidence"],
  "properties": {
    "schemaVersion": { "const": "1.0.0-draft" },
    "runId": { "type": "string", "minLength": 1 },
    "baselineId": { "type": "string", "minLength": 1 },
    "fixtureId": { "type": "string", "minLength": 1 },
    "layer": { "enum": ["S", "C", "R", "A", "I", "V"] },
    "checkId": { "type": "string", "pattern": "^CHK-[A-Z0-9-]+$" },
    "result": { "enum": ["pass", "fail", "blocked", "inconclusive"] },
    "severity": { "enum": ["info", "warning", "error", "blocker"] },
    "summary": { "type": "string" },
    "failure": {
      "type": "object",
      "required": ["code", "condition"],
      "properties": {
        "code": { "type": "string", "pattern": "^ERR_[A-Z0-9_]+$" },
        "condition": { "type": "string" },
        "expected": {},
        "observed": {},
        "paths": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "evidence": {
      "type": "object",
      "required": ["sources", "method"],
      "properties": {
        "sources": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
        "method": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
        "observations": { "type": "array", "items": { "type": "string" } },
        "limitations": { "type": "array", "items": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "execution": {
      "type": "object",
      "properties": {
        "order": { "type": "integer", "minimum": 1 },
        "validator": { "type": "string" },
        "context": { "type": "object", "additionalProperties": true }
      },
      "additionalProperties": false
    }
  },
  "allOf": [
    { "if": { "properties": { "result": { "const": "fail" } } }, "then": { "required": ["failure"] } },
    { "if": { "properties": { "result": { "const": "blocked" } } }, "then": { "required": ["failure"] } },
    { "if": { "properties": { "result": { "const": "inconclusive" } } }, "then": { "required": ["summary"] } }
  ],
  "additionalProperties": false
}


--- FILE: docs/conformance/results/SES-002-structural.json (25 lines, 0.9 KiB) ---
{
  "$schema": "../result.schema.json",
  "schemaVersion": "1.0.0-draft",
  "runId": "SES-002-structural-001",
  "baselineId": "SES-001",
  "fixtureId": "SES-002-fixture-pack",
  "layer": "S",
  "checkId": "CHK-RECORD-SHAPE-001",
  "result": "inconclusive",
  "severity": "warning",
  "summary": "Fixture files parse as JSON and satisfy count assertions; JSON Schema execution is pending.",
  "evidence": {
    "sources": [
      "../fixture.schema.json",
      "../fixture-index.schema.json",
      "../fixtures/index.json",
      "../fixtures/positive-home.json",
      "../fixtures/negative.json"
    ],
    "method": ["JSON parsing", "fixture count assertions", "stable ID assertions"],
    "observations": ["4 positive vectors", "12 negative fixtures"],
    "limitations": ["jsonschema Python package unavailable", "runtime validator not implemented"]
  },
  "execution": {"order": 1, "validator": "manual.structural-check"}
}


--- FILE: docs/conformance/security-fixtures.json (16 lines, 0.7 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-036-security-fixtures",
  "valid": {
    "visualLanguage": "neo-edo",
    "source": "fixture:appearance-neo-edo",
    "assets": [{"id": "washi-fiber", "source": "fixture:washi-fiber"}],
    "customSource": "custom:vendor:ornament"
  },
  "invalid": [
    {"expression": {"script": "alert(1)"}, "expectedCode": "ERR_EXECUTABLE_EXPRESSION_INPUT"},
    {"expression": {"source": "javascript:alert(1)"}, "expectedCode": "ERR_ASSET_SOURCE_UNSAFE"},
    {"expression": {"source": "/tmp/asset.svg"}, "expectedCode": "ERR_ASSET_SOURCE_UNSAFE"},
    {"expression": {"customSource": "vendor-ornament"}, "expectedCode": "ERR_CUSTOM_SOURCE_UNNAMESPACED"}
  ]
}


--- FILE: docs/conformance/security-trust-boundaries.json (11 lines, 0.8 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-016",
  "title": "SES Security and Trust Boundaries",
  "status": "Canonical Contract",
  "trustClasses": ["declarative-data","referenced-resource","constrained-custom-expression","executable-behavior","authority-bearing-input"],
  "hostResponsibilities": ["sanitization","sandboxing","capability-policy","mime-validation","size-limits","origin-policy","logging-redaction"],
  "failureCodes": ["ERR_UNTRUSTED_EXECUTABLE_EXPRESSION","ERR_CUSTOM_CAPABILITY_UNDECLARED","ERR_RESOURCE_POLICY_REJECTED","ERR_RESOURCE_METADATA_LIMIT","ERR_RESOURCE_ORIGIN_REJECTED","ERR_HOST_EXTENSION_UNAUTHORIZED","ERR_AUTHORITY_BEHAVIOR_IN_EXPRESSION","ERR_ASSET_DECODE_REJECTED"],
  "executableExpressionCanonical": false,
  "authorityInputCanonical": false
}


--- FILE: docs/conformance/semantic-branch-prohibition.json (9 lines, 0.6 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-012",
  "title": "SES Semantic Branch Prohibition",
  "status": "Canonical Contract",
  "checks": ["BRANCH-001","BRANCH-002","BRANCH-003","BRANCH-004","BRANCH-005","BRANCH-006"],
  "failureCodes": ["ERR_SEMANTIC_LANGUAGE_BRANCH","ERR_BUSINESS_LANGUAGE_BRANCH","ERR_DUPLICATE_SEMANTIC_TREE","ERR_OPERATION_LANGUAGE_BRANCH","ERR_UNNAMESPACED_HOST_EXTENSION"],
  "allowedExpressionSurfaces": ["recipe","token","asset","morphology","appearance","responsive","state-signaling","renderer-neutral-host-extension"]
}


--- FILE: docs/conformance/ses-001-matrix.json (160 lines, 4.5 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-001",
  "title": "SES-001 Conformance Invariant Matrix & Fixture Plan",
  "status": "Canonical Baseline",
  "version": "1.0.0-draft",
  "governance": {
    "principle": "Expression topology is free where the Projection Contract permits it, while semantic, behavioral, action, accessibility, and responsive invariants remain testable.",
    "invarianceLevels": ["required", "bounded", "free"]
  },
  "layers": [
    {
      "id": "S",
      "name": "Semantic Conformance",
      "target": "Interface Identity",
      "invariants": [
        "stable-identities",
        "slot-compatibility",
        "socket-admission",
        "cardinality-bounds",
        "state-meaning"
      ]
    },
    {
      "id": "C",
      "name": "Composition Conformance",
      "target": "Hierarchy & Structure",
      "invariants": [
        "structural-hierarchy",
        "content-priority",
        "repetition-bounds",
        "collapse-priority"
      ]
    },
    {
      "id": "R",
      "name": "Recipe Conformance",
      "target": "Symbol & Asset Resolution",
      "invariants": [
        "recipe-target-resolution",
        "token-resolution",
        "asset-path-validity",
        "morphology-rule-validity"
      ]
    },
    {
      "id": "A",
      "name": "Appearance Conformance",
      "target": "Surface & Edge Composition",
      "invariants": [
        "background-composition-validity",
        "texture-mask-pipeline",
        "targeted-edge-rules",
        "z-order-compositing"
      ]
    },
    {
      "id": "I",
      "name": "Interaction Conformance",
      "target": "Behavior & Accessibility",
      "invariants": [
        "operation-exposure",
        "focus-ring-visibility",
        "accessible-naming",
        "logical-reading-order",
        "disabled-state-handling"
      ]
    },
    {
      "id": "V",
      "name": "Visual Validation",
      "target": "Rendering Fidelity & Reflow",
      "invariants": [
        "responsive-content-reachability",
        "no-viewport-overflow",
        "cross-language-fidelity"
      ]
    }
  ],
  "referenceVectors": [
    "Home + Core",
    "Home + Neo-Edo",
    "Home + Western Comics",
    "Home + Cybernetic Minimalism"
  ],
  "negativeFixtures": [
    {
      "id": "FIX-NEG-01",
      "layer": "S",
      "scenario": "Missing required Slot (e.g. MediaCard missing title slot)",
      "expectedErrorCode": "ERR_SLOT_REQUIRED_MISSING"
    },
    {
      "id": "FIX-NEG-02",
      "layer": "S",
      "scenario": "Unknown or inadmissible Block inserted into Socket",
      "expectedErrorCode": "ERR_SOCKET_ADMISSION_DENIED"
    },
    {
      "id": "FIX-NEG-03",
      "layer": "S",
      "scenario": "Required operation hidden or unexposed by expression recipe",
      "expectedErrorCode": "ERR_OPERATION_NOT_EXPOSED"
    },
    {
      "id": "FIX-NEG-04",
      "layer": "R",
      "scenario": "Expression recipe references undefined token",
      "expectedErrorCode": "ERR_TOKEN_UNRESOLVED"
    },
    {
      "id": "FIX-NEG-05",
      "layer": "R",
      "scenario": "Recipe references missing asset URI",
      "expectedErrorCode": "ERR_ASSET_NOT_FOUND"
    },
    {
      "id": "FIX-NEG-06",
      "layer": "A",
      "scenario": "Edge rule assigned to non-existent target boundary",
      "expectedErrorCode": "ERR_EDGE_TARGET_INVALID"
    },
    {
      "id": "FIX-NEG-07",
      "layer": "A",
      "scenario": "Decorative background texture mask completely covers focus ring",
      "expectedErrorCode": "ERR_FOCUS_INDICATOR_OBSTRUCTED"
    },
    {
      "id": "FIX-NEG-08",
      "layer": "A",
      "scenario": "Background layer references non-existent image/pattern source",
      "expectedErrorCode": "ERR_BACKGROUND_SOURCE_NULL"
    },
    {
      "id": "FIX-NEG-09",
      "layer": "C",
      "scenario": "Mobile breakpoint forces horizontal layout overflow beyond viewport",
      "expectedErrorCode": "ERR_COMPOSITION_OVERFLOW"
    },
    {
      "id": "FIX-NEG-10",
      "layer": "C",
      "scenario": "Required semantic slot content clipped or unreachable",
      "expectedErrorCode": "ERR_CONTENT_CLIPPED"
    },
    {
      "id": "FIX-NEG-11",
      "layer": "I",
      "scenario": "Decorative visual ordering alters logical DOM keyboard focus order",
      "expectedErrorCode": "ERR_KEYBOARD_ORDER_MISMATCH"
    },
    {
      "id": "FIX-NEG-12",
      "layer": "I",
      "scenario": "State variant missing ARIA/accessibility fallback",
      "expectedErrorCode": "ERR_A11Y_FALLBACK_MISSING"
    }
  ]
}


--- FILE: docs/conformance/snapshot-fixtures.json (19 lines, 0.9 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-028-snapshot-fixtures",
  "value": {
    "identity": {"target": "media-card", "composition": "media-card"},
    "semantic": {"operations": ["open-media"], "invariance": {"visual": "free", "semantic": "required"}},
    "expression": {"visualLanguage": "neo-edo", "morphology": {"rhythm": "asymmetric"}}
  },
  "equivalentValue": {
    "expression": {"morphology": {"rhythm": "asymmetric"}, "visualLanguage": "neo-edo"},
    "semantic": {"invariance": {"semantic": "required", "visual": "free"}, "operations": ["open-media"]},
    "identity": {"composition": "media-card", "target": "media-card"}
  },
  "changedValue": {
    "identity": {"target": "media-card", "composition": "media-card"},
    "semantic": {"operations": ["open-media"], "invariance": {"visual": "free", "semantic": "required"}},
    "expression": {"visualLanguage": "neo-edo", "morphology": {"rhythm": "regular"}}
  }
}


--- FILE: docs/conformance/token-asset-resolution.json (10 lines, 0.7 KiB) ---
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "id": "SES-010",
  "title": "SES Token and Asset Resolution",
  "status": "Canonical Contract",
  "tokenLayers": ["primitive", "semantic", "role", "recipe", "explicit-expression-override", "resolved"],
  "assetCategories": ["fonts", "icons", "images", "textures", "patterns", "masks", "edges", "backgrounds", "ornaments", "custom"],
  "failureCodes": ["ERR_TOKEN_UNRESOLVED","ERR_TOKEN_CYCLE","ERR_TOKEN_AMBIGUOUS","ERR_PROTECTED_TOKEN_OVERRIDE","ERR_ASSET_NOT_FOUND","ERR_ASSET_CATEGORY_MISMATCH","ERR_ASSET_METADATA_INVALID","ERR_ASSET_CAPABILITY_UNSUPPORTED"],
  "externalResponsibilities": ["retrieval", "decoding", "licensing", "caching", "host-capability-check"]
}



========================================================================
## SUBSYSTEM: CORE IMPLEMENTATION & RESOLUTION TOOLS (21 files)
========================================================================

--- FILE: tools/accessibility_modes.py (33 lines, 1.8 KiB) ---
"""Pure SES-035 reduced-motion and high-contrast expression handling."""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Mapping


class AccessibilityModeError(ValueError):
    def __init__(self, code: str, field_path: str, message: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


def apply_accessibility_modes(output: Mapping[str, Any], context: Mapping[str, Any]) -> dict[str, Any]:
    result = deepcopy(dict(output))
    expression = result.setdefault("expression", {})
    motion = expression.get("motion", {})
    if context.get("reducedMotion", False):
        if not isinstance(motion, Mapping):
            raise AccessibilityModeError("ERR_MOTION_METADATA_INVALID", "expression.motion", "motion metadata must be an object")
        fallback = motion.get("reducedMotion")
        if fallback is None and motion.get("enabled", False):
            raise AccessibilityModeError("ERR_REDUCED_MOTION_FALLBACK_MISSING", "expression.motion.reducedMotion", "motion lacks reduced-motion fallback")
        expression["motion"] = {"enabled": False, "mode": "reduced", "fallback": deepcopy(fallback)}
    if context.get("highContrast", False):
        contrast = expression.get("highContrast")
        if not isinstance(contrast, Mapping) or not contrast.get("enabled", False):
            raise AccessibilityModeError("ERR_HIGH_CONTRAST_FALLBACK_MISSING", "expression.highContrast", "high-contrast expression is missing")
        expression["highContrast"] = deepcopy(dict(contrast))
    result["accessibility"] = {**dict(result.get("accessibility", {})), "reducedMotion": bool(context.get("reducedMotion", False)), "highContrast": bool(context.get("highContrast", False))}
    return result


--- FILE: tools/accessibility_validation.py (43 lines, 2.0 KiB) ---
"""Pure SES-032 accessible-name, role, and relationship validation."""

from __future__ import annotations

from typing import Any, Mapping


class AccessibilityError(ValueError):
    def __init__(self, code: str, field_path: str, message: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


ALLOWED_ROLES = {"article", "button", "heading", "img", "group", "region", "text"}


def validate_accessibility(record: Mapping[str, Any]) -> dict[str, Any]:
    name = record.get("accessibleName")
    if not isinstance(name, str) or not name.strip():
        raise AccessibilityError("ERR_ACCESSIBLE_NAME_MISSING", "accessibleName", "accessible name is required")
    role = record.get("role")
    if role not in ALLOWED_ROLES:
        raise AccessibilityError("ERR_ACCESSIBLE_ROLE_INVALID", "role", f"unsupported role {role!r}")
    relationships = record.get("relationships", [])
    if not isinstance(relationships, list):
        raise AccessibilityError("ERR_ACCESSIBLE_RELATIONSHIP_INVALID", "relationships", "relationships must be a list")
    ids = set(record.get("knownIds", []))
    for index, relationship in enumerate(relationships):
        target = relationship.get("target") if isinstance(relationship, Mapping) else None
        if not isinstance(target, str) or target not in ids:
            raise AccessibilityError("ERR_ACCESSIBLE_RELATIONSHIP_BROKEN", f"relationships[{index}].target", f"unknown relationship target {target!r}")
    operations = record.get("operations", [])
    for index, operation in enumerate(operations):
        if not isinstance(operation, Mapping) or not operation.get("id") or not operation.get("accessibleName"):
            raise AccessibilityError("ERR_OPERATION_ACCESSIBLE_NAME_MISSING", f"operations[{index}]", "operation needs stable ID and accessible name")
    return {
        "result": "pass",
        "accessibleName": name,
        "role": role,
        "relationshipCount": len(relationships),
        "operationCount": len(operations),
    }


--- FILE: tools/cross_language_equivalence.py (54 lines, 2.4 KiB) ---
#!/usr/bin/env python3
"""Compare Python and JavaScript semantic projection summaries and mutations."""

from __future__ import annotations

import json
from pathlib import Path
import subprocess
import sys

from ses_resolver import ResolutionError, resolve_projection


ROOT = Path(__file__).resolve().parents[1]
FIXTURE = ROOT / "docs/conformance/expression-equivalence-fixtures.json"
JS_CHECK = ROOT / "tools/cross_language_projection.mjs"


def main() -> int:
    fixture = json.loads(FIXTURE.read_text(encoding="utf-8"))
    python_outputs = [resolve_projection(fixture["semantic"], expression) for expression in fixture["expressions"]]
    js_output = json.loads(subprocess.run(["node", str(JS_CHECK), str(FIXTURE)], check=True, capture_output=True, text=True).stdout)
    python_summary = {
        "identity": python_outputs[0]["identity"],
        "operations": python_outputs[0]["interaction"]["operations"],
        "visualLanguages": sorted(output["expression"]["visualLanguage"] for output in python_outputs),
    }
    js_summary = {"identity": js_output["identity"], "operations": js_output["operations"], "visualLanguages": sorted(vector["visualLanguage"] for vector in js_output["vectors"])}
    if python_summary != js_summary:
        raise ValueError("Python and JavaScript projection summaries differ")

    mutation = dict(fixture["expressions"][0])
    mutation["target"] = "mutated-target"
    try:
        resolve_projection(fixture["semantic"], mutation)
    except ResolutionError as error:
        if error.code != "ERR_RESOLVE_TARGET_MISMATCH":
            raise
    else:
        raise ValueError("target mutation was accepted")
    operation_mutation = dict(fixture["semantic"])
    operation_mutation["operations"] = ["mutated-operation"]
    if operation_mutation["operations"] == fixture["semantic"]["operations"]:
        raise ValueError("operation mutation was not applied")
    print(json.dumps({"fixture": fixture["id"], "result": "pass", "languages": python_summary["visualLanguages"], "mutationChecks": ["target-rejected", "operation-change-detected"]}, indent=2, sort_keys=True))
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, KeyError, TypeError, ValueError, subprocess.SubprocessError, json.JSONDecodeError) as error:
        print(f"cross-language-equivalence: fail: {error}", file=sys.stderr)
        raise SystemExit(1)


--- FILE: tools/cross_language_projection.mjs (11 lines, 0.4 KiB) ---
import { readFileSync } from "node:fs";

const fixture = JSON.parse(readFileSync(process.argv[2], "utf8"));
const identity = { composition: fixture.semantic.block, target: fixture.semantic.block };
const operations = fixture.semantic.operations;
const vectors = fixture.expressions.map((expression) => ({
  identity,
  operations,
  visualLanguage: expression.visualLanguage,
}));
process.stdout.write(JSON.stringify({ identity, operations, vectors }));


--- FILE: tools/deterministic_snapshot.py (42 lines, 1.4 KiB) ---
"""Deterministic SES output serialization and snapshot comparison."""

from __future__ import annotations

import hashlib
import json
from typing import Any


def canonical_value(value: Any) -> Any:
    """Return a JSON-compatible value with explicitly ordered object fields."""
    if isinstance(value, dict):
        return {key: canonical_value(value[key]) for key in sorted(value)}
    if isinstance(value, list):
        return [canonical_value(item) for item in value]
    if isinstance(value, (str, int, float, bool)) or value is None:
        return value
    raise TypeError(f"unsupported snapshot value: {type(value).__name__}")


def canonical_serialize(value: Any) -> str:
    """Serialize a value with stable object order and no ambient formatting."""
    return json.dumps(canonical_value(value), ensure_ascii=False, separators=(",", ":"))


def snapshot(value: Any) -> dict[str, str]:
    serialized = canonical_serialize(value)
    return {
        "algorithm": "sha256",
        "encoding": "utf-8",
        "serialized": serialized,
        "digest": hashlib.sha256(serialized.encode("utf-8")).hexdigest(),
    }


def compare_snapshots(expected: dict[str, str], value: Any) -> dict[str, Any]:
    actual = snapshot(value)
    return {
        "result": "pass" if expected["digest"] == actual["digest"] else "fail",
        "expectedDigest": expected["digest"],
        "actualDigest": actual["digest"],
    }


--- FILE: tools/dom_css_renderer.py (49 lines, 1.7 KiB) ---
"""Minimal DOM/CSS host adapter for renderer-neutral SES output."""

from __future__ import annotations

from html import escape
from typing import Any, Mapping


class RenderError(ValueError):
    pass


def render_dom_css(output: Mapping[str, Any]) -> dict[str, str]:
    """Map resolved SES output to escaped HTML and CSS host artifacts."""
    identity = output.get("identity", {})
    semantic = output.get("semantic", {})
    expression = output.get("expression", {})
    if not identity.get("target"):
        raise RenderError("ERR_OUTPUT_IDENTITY_MISSING")
    operations = semantic.get("operations", [])
    if not isinstance(operations, list):
        raise RenderError("ERR_OUTPUT_REQUIRED_METADATA_MISSING")

    target = escape(str(identity["target"]), quote=True)
    visual_language = escape(str(expression.get("visualLanguage", "default")), quote=True)
    operation_markup = "".join(
        f'<button type="button" data-ses-operation="{escape(str(operation), quote=True)}">{escape(str(operation))}</button>'
        for operation in operations
    )
    html = (
        f'<article class="ses-{target}" data-ses-identity="{target}" '
        f'data-ses-visual-language="{visual_language}" aria-busy="false">'
        f'<div data-ses-semantic-target="{target}">{operation_markup}</div>'
        "</article>"
    )
    css = (
        f'.ses-{target} {{\n'
        "  display: block;\n"
        "  box-sizing: border-box;\n"
        "}\n"
        f'.ses-{target} [data-ses-operation] {{\n'
        "  cursor: pointer;\n"
        "}\n"
        f'.ses-{target} [data-ses-operation]:focus-visible {{\n'
        "  outline: 3px solid currentColor;\n"
        "  outline-offset: 2px;\n"
        "}\n"
    )
    return {"html": html, "css": css}


--- FILE: tools/execute_negative_fixtures.py (66 lines, 2.2 KiB) ---
#!/usr/bin/env python3
"""Execute the declarative negative-fixture contract with typed diagnostics."""

from __future__ import annotations

import json
from pathlib import Path
import sys


ROOT = Path(__file__).resolve().parents[1]
FIXTURE = ROOT / "docs/conformance/fixtures/negative.json"


def execute(record: dict) -> dict:
    required = ("id", "baseline", "layer", "scenario", "errorCode", "failureCondition")
    missing = [field for field in required if not record.get(field)]
    if missing:
        return {
            "fixtureId": record.get("id", "unknown"),
            "result": "blocked",
            "diagnostic": {
                "code": "ERR_NEGATIVE_FIXTURE_MALFORMED",
                "path": "fixture",
                "message": f"missing required fields: {', '.join(missing)}",
            },
        }
    return {
        "fixtureId": record["id"],
        "baselineId": record["baseline"],
        "layer": record["layer"],
        "result": "fail",
        "diagnostic": {
            "code": record["errorCode"],
            "path": record["id"],
            "message": record["failureCondition"],
        },
    }


def main() -> int:
    fixture = json.loads(FIXTURE.read_text(encoding="utf-8"))
    records = fixture["fixtures"]
    ids = [record.get("id") for record in records]
    if len(ids) != len(set(ids)):
        raise ValueError("negative fixture IDs must be unique")
    results = [execute(record) for record in records]
    blocked = [result for result in results if result["result"] == "blocked"]
    output = {
        "fixture": fixture["id"],
        "result": "pass" if not blocked else "blocked",
        "expectedFailureCount": len(results),
        "typedFailureCount": sum(result["result"] == "fail" for result in results),
        "blockedCount": len(blocked),
        "results": results,
    }
    print(json.dumps(output, indent=2, sort_keys=True))
    return 0 if not blocked else 1


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as error:
        print(f"execute-negative-fixtures: fail: {error}", file=sys.stderr)
        raise SystemExit(1)


--- FILE: tools/framework_neutral_adapter.py (35 lines, 1.5 KiB) ---
"""Framework-neutral SES host adapter example.

The adapter maps host state to SES inputs and returns resolved output. It does
not own transport, persistence, authorization, navigation, or rendering.
"""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Mapping

from ses_resolver import resolve_projection


def adapt_application_state(application_state: Mapping[str, Any]) -> dict[str, Any]:
    """Map host-owned state to explicit SES semantic and expression inputs."""
    return {
        "semantic": deepcopy(application_state["semantic"]),
        "expression": deepcopy(application_state["expression"]),
        "context": deepcopy(application_state.get("context", {})),
    }


def resolve_for_host(application_state: Mapping[str, Any]) -> dict[str, Any]:
    """Resolve host input; the returned output is still renderer-neutral."""
    inputs = adapt_application_state(application_state)
    return resolve_projection(inputs["semantic"], inputs["expression"], context=inputs["context"])


def host_operation_envelope(output: Mapping[str, Any], operation_id: str, payload: Mapping[str, Any]) -> dict[str, Any]:
    """Create an explicit host handoff; invocation remains outside this adapter."""
    operations = output.get("interaction", {}).get("operations", [])
    if operation_id not in operations:
        raise ValueError(f"operation not exposed: {operation_id}")
    return {"operationId": operation_id, "payload": deepcopy(dict(payload)), "owner": "host-application"}


--- FILE: tools/keyboard_focus_validation.py (30 lines, 1.6 KiB) ---
"""Pure SES-033 keyboard order and focus validation."""

from __future__ import annotations

from typing import Any, Mapping


class KeyboardFocusError(ValueError):
    def __init__(self, code: str, field_path: str, message: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


def validate_keyboard_focus(record: Mapping[str, Any]) -> dict[str, Any]:
    semantic_order = record.get("semanticOrder", [])
    keyboard_order = record.get("keyboardOrder", [])
    if semantic_order != keyboard_order:
        raise KeyboardFocusError("ERR_KEYBOARD_ORDER_MISMATCH", "keyboardOrder", "keyboard order differs from semantic order")
    if not record.get("focusVisible", False):
        raise KeyboardFocusError("ERR_FOCUS_INDICATOR_OBSTRUCTED", "focusVisible", "focus indication is not visible")
    controls = record.get("controls", [])
    for index, control in enumerate(controls):
        if not isinstance(control, Mapping) or not control.get("id"):
            raise KeyboardFocusError("ERR_KEYBOARD_CONTROL_ID_MISSING", f"controls[{index}]", "keyboard control needs stable ID")
        if not control.get("keyboardReachable", False):
            raise KeyboardFocusError("ERR_KEYBOARD_CONTROL_UNREACHABLE", f"controls[{index}]", "keyboard control is unreachable")
        if control.get("tabIndex", 0) < 0:
            raise KeyboardFocusError("ERR_KEYBOARD_CONTROL_UNREACHABLE", f"controls[{index}].tabIndex", "control is removed from keyboard order")
    return {"result": "pass", "order": list(keyboard_order), "focusVisible": True, "controlCount": len(controls)}


--- FILE: tools/measure_pipeline.py (59 lines, 2.2 KiB) ---
#!/usr/bin/env python3
"""Measure the local SES resolver and DOM/CSS adapter."""

from __future__ import annotations

import json
import platform
from pathlib import Path
import statistics
import sys
import time

from dom_css_renderer import render_dom_css
from ses_resolver import resolve_projection


ROOT = Path(__file__).resolve().parents[1]
REFERENCE = ROOT / "docs/conformance/reference-pack"


def percentile(values: list[float], fraction: float) -> float:
    ordered = sorted(values)
    index = min(len(ordered) - 1, int((len(ordered) - 1) * fraction))
    return ordered[index]


def main() -> int:
    semantic = json.loads((REFERENCE / "media-card.json").read_text(encoding="utf-8"))
    expression = json.loads((REFERENCE / "appearance-neo-edo.json").read_text(encoding="utf-8"))
    sample_count = 1000
    resolver_times: list[float] = []
    renderer_times: list[float] = []
    for _ in range(sample_count):
        start = time.perf_counter_ns()
        output = resolve_projection(semantic, expression, context={"viewport": "wide"})
        resolver_times.append((time.perf_counter_ns() - start) / 1_000_000)
        start = time.perf_counter_ns()
        render_dom_css(output)
        renderer_times.append((time.perf_counter_ns() - start) / 1_000_000)
    result = {
        "fixture": "media-card/neo-edo",
        "sampleCount": sample_count,
        "environment": {"python": platform.python_version(), "platform": platform.platform()},
        "units": "milliseconds",
        "resolver": {"p50": statistics.median(resolver_times), "p95": percentile(resolver_times, 0.95), "budgetP95": 5.0},
        "rendererAdapter": {"p50": statistics.median(renderer_times), "p95": percentile(renderer_times, 0.95)},
        "method": "perf_counter_ns around pure local calls; process warm-up not separately discarded",
    }
    result["result"] = "pass" if result["resolver"]["p95"] <= result["resolver"]["budgetP95"] else "inconclusive"
    print(json.dumps(result, indent=2, sort_keys=True))
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as error:
        print(f"measure-pipeline: fail: {error}", file=sys.stderr)
        raise SystemExit(1)


--- FILE: tools/operation_routing.py (46 lines, 2.1 KiB) ---
"""Pure SES operation exposure validation and event routing."""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Mapping


class OperationRoutingError(ValueError):
    def __init__(self, code: str, message: str, operation_id: str) -> None:
        super().__init__(message)
        self.code = code
        self.operation_id = operation_id


def validate_operation_exposure(
    required_operations: list[str],
    exposure: Mapping[str, Mapping[str, Any]],
) -> dict[str, Any]:
    results = []
    for operation_id in required_operations:
        record = exposure.get(operation_id)
        if record is None or not record.get("exposed", False):
            raise OperationRoutingError("ERR_OPERATION_NOT_EXPOSED", f"operation {operation_id} is not exposed", operation_id)
        if not record.get("signaled", False):
            raise OperationRoutingError("ERR_OPERATION_NOT_SIGNALED", f"operation {operation_id} is not signaled", operation_id)
        results.append({"id": operation_id, "exposed": True, "signaled": True, "enabled": bool(record.get("enabled", True))})
    return {"result": "pass", "operations": results}


def route_event(event: Mapping[str, Any], exposure: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
    """Return a host-routable operation envelope; never invoke the operation."""
    operation_id = event.get("operationId")
    if not isinstance(operation_id, str) or not operation_id:
        raise OperationRoutingError("ERR_OPERATION_ID_MISSING", "event has no operation identity", "")
    record = exposure.get(operation_id)
    if record is None or not record.get("exposed", False):
        raise OperationRoutingError("ERR_OPERATION_NOT_EXPOSED", f"operation {operation_id} is not exposed", operation_id)
    if not record.get("enabled", True):
        raise OperationRoutingError("ERR_OPERATION_DISABLED", f"operation {operation_id} is disabled", operation_id)
    return {
        "operationId": operation_id,
        "sourceIdentity": deepcopy(event.get("sourceIdentity")),
        "payload": deepcopy(event.get("payload", {})),
        "dispatch": "host-owned",
    }


--- FILE: tools/projection_enforcement.py (53 lines, 2.5 KiB) ---
"""Pure SES-027 Projection Contract enforcement."""

from __future__ import annotations

from typing import Any, Mapping


class ProjectionViolation(ValueError):
    def __init__(self, code: str, field_path: str, message: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


def enforce_projection(
    contract: Mapping[str, Any],
    mutations: Mapping[str, Any],
    *,
    semantic_before: Mapping[str, Any] | None = None,
    semantic_after: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
    """Check declared projection permissions and required semantic invariants."""
    preserve = set(contract.get("preserve", []))
    transform = set(contract.get("transform", []))
    may_omit = set(contract.get("mayOmit", contract.get("omit", [])))
    may_introduce = set(contract.get("mayIntroduce", contract.get("introduce", [])))
    classifications: list[dict[str, str]] = []
    for field, kind in mutations.items():
        if kind == "preserve":
            if field not in preserve:
                raise ProjectionViolation("ERR_PROJECTION_CLASSIFICATION_MISSING", field, f"{field} is not declared preserve")
            classifications.append({"field": field, "classification": kind})
        elif kind == "transform":
            if field not in transform:
                raise ProjectionViolation("ERR_TRANSFORM_UNDECLARED", field, f"{field} is not declared transform")
            classifications.append({"field": field, "classification": kind})
        elif kind == "omit":
            if field not in may_omit:
                raise ProjectionViolation("ERR_REQUIRED_CONTENT_OMITTED", field, f"{field} is not permitted to omit")
            classifications.append({"field": field, "classification": kind})
        elif kind == "introduce":
            if field not in may_introduce:
                raise ProjectionViolation("ERR_INTRODUCED_SEMANTIC_MEANING", field, f"{field} is not presentation-only")
            classifications.append({"field": field, "classification": kind})
        else:
            raise ProjectionViolation("ERR_PROJECTION_CLASSIFICATION_UNKNOWN", field, f"unknown classification {kind}")

    before = semantic_before or {}
    after = semantic_after or before
    for field in sorted(preserve):
        if field in before and field in after and before[field] != after[field]:
            raise ProjectionViolation("ERR_PRESERVED_SEMANTIC_CHANGED", field, f"preserved field {field} changed")
    return {"result": "pass", "classifications": classifications, "preserved": sorted(preserve)}


--- FILE: tools/recipe_resolution.py (65 lines, 2.5 KiB) ---
"""Pure SES-026 recipe cascade and conflict detection."""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Mapping


class RecipeResolutionError(ValueError):
    def __init__(self, code: str, message: str, field_path: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


LAYER_ORDER = (
    "Visual Language",
    "Theme",
    "explicit user style options",
    "Composition Recipe",
    "Socket Recipe",
    "Block Recipe",
    "Variant Recipe",
    "Slot Recipe",
    "Element Recipe",
    "semantic State Recipe",
    "responsive Recipe",
    "accessibility overrides",
)

PROTECTED_FIELDS = {
    "identity", "composition", "socket", "block", "slot", "element", "variant", "state",
    "operations", "operationIdentity", "semanticRole", "accessibilityRelationship",
    "requiredContent", "acceptedContent", "invariance", "businessBehavior", "routingIntent",
}


def _merge(target: dict[str, Any], source: Mapping[str, Any], layer: str, path: str, trace: list[dict[str, Any]]) -> None:
    for key, value in source.items():
        field_path = f"{path}.{key}" if path else key
        if key in PROTECTED_FIELDS:
            raise RecipeResolutionError("ERR_PROTECTED_FIELD_OVERRIDE", f"protected field {field_path}", field_path)
        if isinstance(value, Mapping) and isinstance(target.get(key), Mapping):
            _merge(target[key], value, layer, field_path, trace)
            continue
        previous = deepcopy(target[key]) if key in target else None
        target[key] = deepcopy(value)
        trace.append({"layer": layer, "fieldPath": field_path, "previous": previous, "result": deepcopy(value), "mergeRule": "replace"})


def resolve_recipe_layers(layers: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
    """Apply the fixed cascade and return expression data plus provenance."""
    unknown = sorted(set(layers) - set(LAYER_ORDER))
    if unknown:
        raise RecipeResolutionError("ERR_RECIPE_LAYER_INVALID", f"unknown recipe layer {unknown[0]}", unknown[0])
    resolved: dict[str, Any] = {}
    trace: list[dict[str, Any]] = []
    for layer in LAYER_ORDER:
        value = layers.get(layer)
        if value is None:
            continue
        if not isinstance(value, Mapping):
            raise RecipeResolutionError("ERR_RECIPE_LAYER_INVALID", f"layer {layer} is not an object", layer)
        _merge(resolved, value, layer, "", trace)
    return {"resolved": resolved, "trace": trace}


--- FILE: tools/resolve_reference_fixture.py (30 lines, 1.0 KiB) ---
#!/usr/bin/env python3
"""Resolve the canonical SES reference fixture without rendering."""

from __future__ import annotations

import json
from pathlib import Path
import sys

from ses_resolver import ResolutionError, resolve_projection


ROOT = Path(__file__).resolve().parents[1]
REFERENCE = ROOT / "docs/conformance/reference-pack"


def main() -> int:
    semantic = json.loads((REFERENCE / "media-card.json").read_text(encoding="utf-8"))
    expression = json.loads((REFERENCE / "appearance-neo-edo.json").read_text(encoding="utf-8"))
    resolved = resolve_projection(semantic, expression, context={"viewport": "wide"})
    print(json.dumps(resolved, indent=2, sort_keys=True))
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError, ResolutionError) as error:
        print(f"resolve-reference-fixture: fail: {error}", file=sys.stderr)
        raise SystemExit(1)


--- FILE: tools/resource_resolution.py (50 lines, 2.4 KiB) ---
"""Pure token and asset resolution for SES-025."""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Mapping


class ResourceResolutionError(ValueError):
    def __init__(self, code: str, message: str, field_path: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


TOKEN_LAYERS = ("primitive", "semantic", "role", "recipe", "explicit")


def resolve_token(name: str, registry: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
    """Resolve one token through the fixed SES layer order with alias tracing."""
    visited: list[str] = []

    def visit(token_name: str) -> dict[str, Any]:
        if token_name in visited:
            raise ResourceResolutionError("ERR_TOKEN_CYCLE", f"token cycle at {token_name}", token_name)
        visited.append(token_name)
        matches = [(layer, registry.get(layer, {}).get(token_name)) for layer in TOKEN_LAYERS]
        matches = [(layer, value) for layer, value in matches if value is not None]
        if not matches:
            raise ResourceResolutionError("ERR_TOKEN_UNRESOLVED", f"unknown token {token_name}", token_name)
        layer, value = matches[-1]
        if isinstance(value, Mapping) and "alias" in value:
            resolved = visit(str(value["alias"]))
            return {"id": token_name, "value": resolved["value"], "sourceLayer": layer, "aliasPath": [token_name] + resolved["aliasPath"]}
        return {"id": token_name, "value": deepcopy(value), "sourceLayer": layer, "aliasPath": [token_name]}

    return visit(name)


def resolve_asset(asset_id: str, category: str, registry: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
    """Resolve an asset ID within its declared category without loading it."""
    category_records = registry.get(category, {})
    record = category_records.get(asset_id)
    if record is None:
        if any(asset_id in records for records in registry.values()):
            raise ResourceResolutionError("ERR_ASSET_CATEGORY_MISMATCH", f"{asset_id} is not a {category} asset", asset_id)
        raise ResourceResolutionError("ERR_ASSET_NOT_FOUND", f"unknown asset {asset_id}", asset_id)
    if not isinstance(record, Mapping) or record.get("category") != category:
        raise ResourceResolutionError("ERR_ASSET_METADATA_INVALID", f"invalid metadata for {asset_id}", asset_id)
    return {"id": asset_id, "category": category, "metadata": deepcopy(dict(record))}


--- FILE: tools/responsive_validation.py (37 lines, 2.0 KiB) ---
"""Pure SES-034 responsive reachability and state-transition validation."""

from __future__ import annotations

from typing import Any, Mapping


class ResponsiveError(ValueError):
    def __init__(self, code: str, field_path: str, message: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


def validate_responsive(record: Mapping[str, Any]) -> dict[str, Any]:
    required_content = set(record.get("requiredContent", []))
    required_operations = set(record.get("requiredOperations", []))
    contexts = record.get("contexts", [])
    if not contexts:
        raise ResponsiveError("ERR_RESPONSIVE_CONTEXT_MISSING", "contexts", "at least one responsive context is required")
    checked = []
    for index, context in enumerate(contexts):
        path = f"contexts[{index}]"
        if context.get("overflow", False):
            raise ResponsiveError("ERR_COMPOSITION_OVERFLOW", path, "responsive context overflows")
        if set(context.get("clippedContent", [])) & required_content:
            raise ResponsiveError("ERR_CONTENT_CLIPPED", path, "required content is clipped")
        if set(context.get("hiddenContent", [])) & required_content:
            raise ResponsiveError("ERR_CONTENT_UNREACHABLE", path, "required content is hidden")
        if not required_operations.issubset(set(context.get("reachableOperations", []))):
            raise ResponsiveError("ERR_CONTENT_UNREACHABLE", path, "required operation is unreachable")
        checked.append(context.get("id", path))
    transitions = record.get("stateTransitions", {})
    for source, targets in transitions.items():
        if not isinstance(targets, list) or any(target not in record.get("states", []) for target in targets):
            raise ResponsiveError("ERR_STATE_TRANSITION_INVALID", f"stateTransitions.{source}", "transition target is not a declared state")
    return {"result": "pass", "contexts": checked, "transitionCount": sum(len(targets) for targets in transitions.values())}


--- FILE: tools/security_validation.py (41 lines, 2.0 KiB) ---
"""Pure SES-036 security and trust-boundary validation."""

from __future__ import annotations

from typing import Any, Mapping
from urllib.parse import urlparse


class SecurityValidationError(ValueError):
    def __init__(self, code: str, field_path: str, message: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


EXECUTABLE_KEYS = {"code", "script", "eval", "function", "handler", "onClick", "shader", "expression"}
UNSAFE_SCHEMES = {"javascript", "data", "file", "vbscript"}
SAFE_SCHEMES = {"fixture", "https"}
CUSTOM_KEYS = {"customSource", "customFilter", "customAsset"}


def validate_expression_security(expression: Mapping[str, Any]) -> dict[str, Any]:
    def walk(value: Any, path: str) -> None:
        if isinstance(value, Mapping):
            for key, child in value.items():
                child_path = f"{path}.{key}" if path else str(key)
                if key in EXECUTABLE_KEYS:
                    raise SecurityValidationError("ERR_EXECUTABLE_EXPRESSION_INPUT", child_path, f"executable input {key} is not accepted")
                if key in CUSTOM_KEYS:
                    if not isinstance(child, str) or not child.startswith("custom:") or ":" not in child[7:]:
                        raise SecurityValidationError("ERR_CUSTOM_SOURCE_UNNAMESPACED", child_path, "custom source must use a namespaced custom: value")
                if key == "source" and isinstance(child, str):
                    scheme = urlparse(child).scheme.lower()
                    if scheme in UNSAFE_SCHEMES or scheme not in SAFE_SCHEMES:
                        raise SecurityValidationError("ERR_ASSET_SOURCE_UNSAFE", child_path, f"source scheme {scheme or 'missing'} is not allowed")
                walk(child, child_path)
        elif isinstance(value, list):
            for index, child in enumerate(value):
                walk(child, f"{path}[{index}]")
    walk(expression, "")
    return {"result": "pass", "trust": "data-only", "executableInputs": False}


--- FILE: tools/ses_resolver.py (106 lines, 4.8 KiB) ---
"""Minimal pure SES semantic-to-expression resolver.

The resolver accepts already-loaded immutable records. It does not read files,
load assets, render, invoke operations, or mutate application state.
"""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Mapping

from resource_resolution import resolve_asset, resolve_token


class ResolutionError(ValueError):
    """Typed failure for an invalid minimal resolution input."""

    def __init__(self, code: str, message: str, field_path: str) -> None:
        super().__init__(message)
        self.code = code
        self.field_path = field_path


def _require(record: Mapping[str, Any], key: str, field_path: str) -> Any:
    if key not in record:
        raise ResolutionError("ERR_RESOLVE_REQUIRED_INPUT", f"missing {field_path}", field_path)
    return record[key]


def resolve_projection(
    semantic: Mapping[str, Any],
    expression: Mapping[str, Any],
    *,
    context: Mapping[str, Any] | None = None,
    token_registry: Mapping[str, Mapping[str, Any]] | None = None,
    asset_registry: Mapping[str, Mapping[str, Any]] | None = None,
) -> dict[str, Any]:
    """Resolve one reference projection into renderer-neutral output.

    The minimal implementation resolves the canonical semantic identity,
    operations, invariance, expression layers, and context. Expression data
    cannot replace semantic identity or operations.
    """
    semantic_id = semantic.get("composition") or _require(semantic, "block", "semantic.block")
    expression_target = _require(expression, "target", "expression.target")
    if expression_target != semantic_id and expression_target != semantic.get("block"):
        raise ResolutionError(
            "ERR_RESOLVE_TARGET_MISMATCH",
            f"expression target {expression_target!r} does not match {semantic_id!r}",
            "expression.target",
        )

    operations = list(_require(semantic, "operations", "semantic.operations"))
    projection = deepcopy(expression.get("projection", {}))
    morphology = deepcopy(expression.get("morphology", {}))
    appearance = deepcopy(expression.get("appearance", {}))
    active_context = deepcopy(dict(context or {}))
    tokens: list[dict[str, Any]] = []
    assets: list[dict[str, Any]] = []
    if token_registry is not None:
        for token_name in sorted({item["token"] for group in appearance.values() if isinstance(group, list) for item in group if isinstance(item, Mapping) and "token" in item}):
            tokens.append(resolve_token(token_name, token_registry))
    if asset_registry is not None:
        group_categories = {"background": "backgrounds", "patterns": "patterns", "edges": "edges", "decorations": "ornaments"}
        type_categories = {"texture": "textures", "pattern": "patterns", "seal": "ornaments", "edge": "edges"}
        asset_requests = sorted({(item["asset"], item.get("category", "") or type_categories.get(item.get("type"), group_categories.get(group_name, ""))) for group_name, group in appearance.items() if isinstance(group, list) for item in group if isinstance(item, Mapping) and "asset" in item})
        category_by_type = {"texture": "textures", "pattern": "patterns", "seal": "ornaments", "edge": "edges"}
        for asset_name, declared_category in asset_requests:
            category = declared_category or next((category_by_type.get(item.get("type"), "") for group in appearance.values() if isinstance(group, list) for item in group if isinstance(item, Mapping) and item.get("asset") == asset_name), "")
            assets.append(resolve_asset(asset_name, category, asset_registry))

    return {
        "identity": {
            "composition": semantic_id,
            "target": expression_target,
        },
        "semantic": {
            "sockets": deepcopy(semantic.get("sockets", [])),
            "operations": operations,
            "invariance": deepcopy(semantic.get("invariance", {})),
        },
        "projection": {
            "preserve": list(projection.get("preserve", [])),
            "transform": list(projection.get("transform", [])),
            "omit": list(projection.get("omit", [])),
            "introduce": list(projection.get("introduce", [])),
        },
        "expression": {
            "visualLanguage": expression.get("visualLanguage"),
            "morphology": morphology,
            "appearance": appearance,
        },
        "resources": {
            "tokens": tokens,
            "assets": assets,
            "resolution": "caller-supplied registries",
        },
        "interaction": {"operations": operations},
        "accessibility": {"required": True, "source": "semantic-contract"},
        "responsive": {"context": active_context, "rules": []},
        "trace": {
            "layers": ["Visual Language", "Theme", "Recipe"],
            "source": expression.get("source"),
        },
        "diagnostics": {"warnings": [], "failures": []},
    }


--- FILE: tools/validate_projection_equivalence.py (54 lines, 1.7 KiB) ---
#!/usr/bin/env python3
"""Validate the renderer-neutral invariants of the SES-007 vectors."""

from __future__ import annotations

import json
from pathlib import Path
import sys


ROOT = Path(__file__).resolve().parents[1]
FIXTURE = ROOT / "docs/conformance/projection-equivalence.json"


def main() -> int:
    fixture = json.loads(FIXTURE.read_text(encoding="utf-8"))
    vectors = fixture["vectors"]
    semantic = fixture["semantic"]

    if len(vectors) != 4:
        raise ValueError(f"expected 4 projection vectors, found {len(vectors)}")

    vector_ids = [vector["id"] for vector in vectors]
    if len(set(vector_ids)) != len(vector_ids):
        raise ValueError("projection vector IDs must be unique")

    if not semantic["identities"]:
        raise ValueError("shared semantic identity set must not be empty")
    if not semantic["operations"]:
        raise ValueError("shared operation set must not be empty")

    for vector in vectors:
        if not vector["visualLanguage"]:
            raise ValueError(f"{vector['id']} has no Visual Language")
        if not vector["allowedMutations"]:
            raise ValueError(f"{vector['id']} has no declared expression mutations")

    print(json.dumps({
        "fixture": fixture["id"],
        "result": "pass",
        "vectorCount": len(vectors),
        "sharedIdentityCount": len(semantic["identities"]),
        "sharedOperationCount": len(semantic["operations"]),
        "vectors": vector_ids,
    }, sort_keys=True))
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as error:
        print(f"projection-equivalence: fail: {error}", file=sys.stderr)
        raise SystemExit(1)


--- FILE: tools/validate_resolved_output.py (74 lines, 2.5 KiB) ---
#!/usr/bin/env python3
"""Validate SES-021 output against the SES-022 canonical fixture."""

from __future__ import annotations

import json
from pathlib import Path
import re
import sys
from typing import Any


ROOT = Path(__file__).resolve().parents[1]
FIXTURE = ROOT / "docs/conformance/resolved-output-fixtures.json"


class ValidationFailure(ValueError):
    def __init__(self, code: str, path: str, message: str) -> None:
        super().__init__(message)
        self.code = code
        self.path = path


def _read_path(value: Any, path: str) -> Any:
    matches = re.finditer(r"([^.\[\]]+)|\[(\d+)\]", path)
    tokens = [match.group(1) if match.group(1) is not None else int(match.group(2)) for match in matches]
    current = value
    for token in tokens:
        key: Any = token if isinstance(token, int) else token
        try:
            current = current[key]
        except (KeyError, IndexError, TypeError) as error:
            raise ValidationFailure("ERR_OUTPUT_PATH_MISSING", path, str(error)) from error
    return current


def validate(output: dict[str, Any], fixture: dict[str, Any]) -> dict[str, Any]:
    failures: list[dict[str, str]] = []
    for section in fixture["requiredSections"]:
        if section not in output:
            failures.append({"code": "ERR_OUTPUT_SECTION_MISSING", "path": section})
    for path, expected in fixture["expectations"].items():
        try:
            actual = _read_path(output, path)
        except ValidationFailure as error:
            failures.append({"code": error.code, "path": error.path})
            continue
        if actual != expected:
            failures.append({"code": "ERR_OUTPUT_EXPECTATION_MISMATCH", "path": path})
    for field in fixture["forbiddenHostFields"]:
        if field in output:
            failures.append({"code": "ERR_OUTPUT_HOST_FIELD_PRESENT", "path": field})
    return {
        "fixture": fixture["id"],
        "result": "pass" if not failures else "fail",
        "failureCount": len(failures),
        "failures": failures,
    }


def main() -> int:
    fixture = json.loads(FIXTURE.read_text(encoding="utf-8"))
    output = json.loads(sys.stdin.read())
    result = validate(output, fixture)
    print(json.dumps(result, indent=2, sort_keys=True))
    return 0 if result["result"] == "pass" else 1


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, TypeError, ValueError, json.JSONDecodeError) as error:
        print(f"validate-resolved-output: fail: {error}", file=sys.stderr)
        raise SystemExit(1)


--- FILE: tools/verify_expression_equivalence.py (46 lines, 1.7 KiB) ---
#!/usr/bin/env python3
"""Verify semantic identity across multiple SES expression records."""

from __future__ import annotations

import json
from pathlib import Path
import sys

from ses_resolver import resolve_projection


ROOT = Path(__file__).resolve().parents[1]
FIXTURE = ROOT / "docs/conformance/expression-equivalence-fixtures.json"


def main() -> int:
    fixture = json.loads(FIXTURE.read_text(encoding="utf-8"))
    semantic = fixture["semantic"]
    outputs = [resolve_projection(semantic, expression, context={"viewport": "wide"}) for expression in fixture["expressions"]]
    identities = {json.dumps(output["identity"], sort_keys=True) for output in outputs}
    operations = {json.dumps(output["interaction"]["operations"], sort_keys=True) for output in outputs}
    languages = {output["expression"]["visualLanguage"] for output in outputs}
    if len(identities) != 1:
        raise ValueError("semantic identity changed across expressions")
    if len(operations) != 1:
        raise ValueError("operation identity changed across expressions")
    if len(languages) != len(outputs):
        raise ValueError("expressions must use distinct Visual Languages")
    print(json.dumps({
        "fixture": fixture["id"],
        "result": "pass",
        "expressionCount": len(outputs),
        "sharedIdentity": outputs[0]["identity"],
        "sharedOperations": outputs[0]["interaction"]["operations"],
        "visualLanguages": sorted(languages),
    }, indent=2, sort_keys=True))
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as error:
        print(f"verify-expression-equivalence: fail: {error}", file=sys.stderr)
        raise SystemExit(1)



========================================================================
## SUBSYSTEM: SYSTEM SCRIPTS & PIPELINE AUTOMATION (1 files)
========================================================================

--- FILE: scripts/gen-llms.py (381 lines, 13.8 KiB) ---
#!/usr/bin/env python3
"""
gen-llms.py — Master Agent-First Publishing Architecture & Context Corpus Exporter for Semantic Expression System.

Generates versioned llms index and full codebase corpus files in the top-level `.agents/` directory:
  .agents/llms.txt
  .agents/llms-ses-v<version>.txt
  .agents/llms-full.txt
  .agents/llms-full-ses-v<version>.txt
"""

import os
import sys
import re
import json
import glob
import hashlib
import subprocess
from datetime import datetime

ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
AGENTS_DIR = os.path.join(ROOT_DIR, ".agents")
PKG_PATH = os.path.join(ROOT_DIR, "package.json")
PKG_SRC_PATH = os.path.join(AGENTS_DIR, "package-source.json")
PROFILE_PATH = os.path.join(ROOT_DIR, "PROJECT_PROFILE.json")

def get_root_version():
    """Returns the SES project version from git tags, package-source.json, PROJECT_PROFILE.json, or package.json."""
    # 1. Try git describe --tags
    try:
        tag = subprocess.check_output(
            ["git", "describe", "--tags", "--abbrev=0"],
            cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True
        ).strip()
        if tag:
            return tag.lstrip("v")
    except Exception:
        pass

    # 2. Check .agents/package-source.json
    if os.path.exists(PKG_SRC_PATH):
        try:
            with open(PKG_SRC_PATH, "r", encoding="utf-8") as f:
                data = json.load(f)
                if data.get("packageVersion"):
                    return data["packageVersion"].lstrip("v")
        except Exception:
            pass

    # 3. Check PROJECT_PROFILE.json
    if os.path.exists(PROFILE_PATH):
        try:
            with open(PROFILE_PATH, "r", encoding="utf-8") as f:
                prof = json.load(f)
                if prof.get("protocol", {}).get("protocolVersion"):
                    return prof["protocol"]["protocolVersion"].lstrip("v")
        except Exception:
            pass

    # 4. Check package.json
    if os.path.exists(PKG_PATH):
        try:
            with open(PKG_PATH, "r", encoding="utf-8") as f:
                pkg = json.load(f)
                if pkg.get("version"):
                    return pkg["version"].lstrip("v")
        except Exception:
            pass

    return "0.1.0"

def get_repo_identity():
    """Collects git commit SHA, tag, and dirty state for Semantic Expression System."""
    info = {}
    try:
        sha = subprocess.check_output(
            ["git", "rev-parse", "--short", "HEAD"],
            cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True
        ).strip()
        info["sha"] = sha
        
        status = subprocess.check_output(
            ["git", "status", "--porcelain"],
            cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True
        ).strip()
        if status:
            info["sha"] += " (dirty)"
    except Exception:
        info["sha"] = "unknown"
        
    try:
        tag = subprocess.check_output(
            ["git", "describe", "--tags", "--always"],
            cwd=ROOT_DIR, stderr=subprocess.DEVNULL, text=True
        ).strip()
        info["tag"] = tag
    except Exception:
        info["tag"] = "untagged"

    return f"Semantic Expression System: v{VERSION} ({info['sha']})"

VERSION = get_root_version()
ABBR = "ses"
DATE = datetime.now().strftime("%Y-%m-%d")

EXCLUDED_DIRS = {
    "_scripts",
    "scratch",
    "node_modules",
    "target",
    "worktrees",
    ".worktrees",
    ".git",
    ".github",
    ".vscode",
    ".cache",
    "dist",
    "build",
    "coverage",
    "tmp",
    "temp",
    "out",
    "__pycache__",
}

EXCLUDED_FILE_SUBSTRINGS = {
    "-lock.json",
    ".lock",
    "pnpm-lock.yaml",
    "yarn.lock",
    ".DS_Store",
    ".map",
    ".min.js",
    ".min.css",
}

ALLOWED_EXTS = {
    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".json", ".md", ".py", ".sh", ".css", ".scss", ".yaml", ".yml", ".toml", ".sql"
}

def is_excluded_dir(dir_name):
    lower = dir_name.lower()
    if dir_name in EXCLUDED_DIRS or lower in EXCLUDED_DIRS:
        return True
    if dir_name.startswith(".") and dir_name != ".agents":
        return True
    if dir_name.startswith("__") or "__" in dir_name:
        return True
    if "worktree" in lower:
        return True
    return False

def read_file(file_path, rel_path):
    """Reads UTF-8 source byte-faithfully, rejects binary input, and raises on I/O errors."""
    try:
        with open(file_path, "rb") as f:
            raw_bytes = f.read()
    except OSError as e:
        raise RuntimeError(f"Failed to read file {rel_path}: {e}")

    if b"\x00" in raw_bytes:
        print(f"[gen-llms] skipping binary file containing NUL bytes: {rel_path}")
        return None, raw_bytes

    try:
        return raw_bytes.decode("utf-8"), raw_bytes
    except UnicodeDecodeError:
        print(f"[gen-llms] skipping non-utf8 encoded file: {rel_path}")
        return None, raw_bytes

def is_excluded_file(file_name):
    lower = file_name.lower()
    if (
        file_name.endswith(".lock")
        or file_name.endswith("-lock.json")
        or file_name.endswith("-lock.yaml")
        or file_name.endswith("-lock.yml")
        or lower in {"cargo.lock", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb"}
    ):
        return True

    if file_name.startswith("._") or file_name.endswith(".pyc"):
        return True

    for sub in EXCLUDED_FILE_SUBSTRINGS:
        if sub in file_name:
            return True

    return False

def read_agents_dir_files():
    """Reads doctrine files from .agents/ surface (AGENTS.md and skills/*/SKILL.md)."""
    entries = []

    agents_md_path = os.path.join(AGENTS_DIR, "AGENTS.md")
    if os.path.exists(agents_md_path):
        rel_path = ".agents/AGENTS.md"
        content, _ = read_file(agents_md_path, rel_path)
        if content is not None:
            entries.append((rel_path, content))

    skills_dir = os.path.join(AGENTS_DIR, "skills")
    if os.path.exists(skills_dir):
        for root, dirs, files in os.walk(skills_dir):
            dirs[:] = [d for d in dirs if not is_excluded_dir(d)]
            for f in sorted(files):
                if f != "SKILL.md" or is_excluded_file(f):
                    continue
                full_path = os.path.join(root, f)
                rel_path = os.path.relpath(full_path, ROOT_DIR)
                content, _ = read_file(full_path, rel_path)
                if content is not None:
                    entries.append((rel_path, content))

    return entries

def read_source_files():
    entries = read_agents_dir_files()
    agents_rel_paths = {rel for rel, _ in entries}

    for root, dirs, files in os.walk(ROOT_DIR):
        if root == ROOT_DIR:
            dirs[:] = [d for d in dirs if d != ".agents" and not is_excluded_dir(d)]
        else:
            dirs[:] = [d for d in dirs if not is_excluded_dir(d)]
            
        for f in files:
            ext = os.path.splitext(f)[1]
            if (ext in ALLOWED_EXTS or f in {"package-source.json", "PROJECT_PROFILE.json"}) and not is_excluded_file(f):
                full_path = os.path.join(root, f)
                rel_path = os.path.relpath(full_path, ROOT_DIR)
                
                if rel_path in agents_rel_paths:
                    continue

                content, _ = read_file(full_path, rel_path)
                if content is not None:
                    entries.append((rel_path, content))
                    
    sorted_entries = sorted(entries, key=lambda x: x[0])
    return sorted_entries

def categorize_files(source_files):
    categories = {
        "System Architecture, Intent & Governance": [],
        "Canonical Contract Schemas & Protocol Definitions": [],
        "Conformance Suite & Test Fixtures": [],
        "Core Implementation & Resolution Tools": [],
        "System Scripts & Pipeline Automation": [],
        "Operational Work Graph & Issues": [],
        "Verification & Execution Evidence": [],
        "Other System Modules": []
    }
    for rel, src in source_files:
        line_count = len(src.splitlines())
        size_kib = round(len(src.encode('utf-8')) / 1024, 1)
        item = (rel, line_count, size_kib)

        if rel in {"INTENT.md", "AGENTS.md", "PROJECT_PROFILE.json", "README.md", "ROADMAP.md"} \
           or rel == ".agents/AGENTS.md" \
           or rel.startswith(".agents/skills/") \
           or (rel.startswith("docs/") and not rel.startswith("docs/schemas/") and not rel.startswith("docs/conformance/")):
            categories["System Architecture, Intent & Governance"].append(item)
        elif rel.startswith("docs/schemas/") or rel.startswith(".iepe/"):
            categories["Canonical Contract Schemas & Protocol Definitions"].append(item)
        elif rel.startswith("docs/conformance/"):
            categories["Conformance Suite & Test Fixtures"].append(item)
        elif rel.startswith("tools/"):
            categories["Core Implementation & Resolution Tools"].append(item)
        elif rel.startswith("scripts/"):
            categories["System Scripts & Pipeline Automation"].append(item)
        elif rel.startswith("work/"):
            categories["Operational Work Graph & Issues"].append(item)
        elif rel.startswith("evidence/"):
            categories["Verification & Execution Evidence"].append(item)
        else:
            categories["Other System Modules"].append(item)
            
    return categories

def make_agent_rel_link(rel_path):
    if rel_path.startswith(".agents/"):
        return os.path.relpath(rel_path, ".agents")
    return "../" + rel_path

def main():
    os.makedirs(AGENTS_DIR, exist_ok=True)

    # Clean up stale/previous llms artifacts in .agents/
    for pattern in ["llms*.txt"]:
        for p in glob.glob(os.path.join(AGENTS_DIR, pattern)):
            try:
                os.remove(p)
            except Exception:
                pass

    ident_summary = get_repo_identity()
    source_files = read_source_files()
    categorized = categorize_files(source_files)

    total_lines = sum(len(src.splitlines()) for _, src in source_files)

    manifest_lines = [
        "# Semantic Expression System Master Index",
        f"> System Root Version: v{VERSION} | Generated: {DATE} | Total Modules: {len(source_files)} files | Total Lines: {total_lines:,} lines",
        f"> Subsystem Identity: {ident_summary}",
        "",
        "## Core Authority & Governance",
        f"- [INTENT.md]({make_agent_rel_link('INTENT.md')}): Originating System Intent",
        f"- [AGENTS.md]({make_agent_rel_link('AGENTS.md')}): Master AI Agent Operating Contract",
        f"- [PROJECT_PROFILE.json]({make_agent_rel_link('PROJECT_PROFILE.json')}): IEPE Project Profile & Authority Order",
        f"- [README.md]({make_agent_rel_link('README.md')}): System Architecture Overview",
        f"- [ROADMAP.md]({make_agent_rel_link('ROADMAP.md')}): System Execution Roadmap",
        f"- [docs/ARCHITECTURE.md]({make_agent_rel_link('docs/ARCHITECTURE.md')}): Technical Architecture Specification",
        f"- [docs/EXPERIENCE.md]({make_agent_rel_link('docs/EXPERIENCE.md')}): Target Developer & User Experience",
        "",
    ]

    for cat, items in categorized.items():
        if items:
            manifest_lines.append(f"## {cat} ({len(items)} files)")
            for rel, lcnt, size in items:
                link = make_agent_rel_link(rel)
                manifest_lines.append(f"- [{rel}]({link}) ({lcnt} lines, {size} KiB)")
            manifest_lines.append("")

    manifest_content = "\n".join(manifest_lines) + "\n"

    sep = "=" * 72
    def banner(title, info=""):
        extra = f" [{info}]" if info else ""
        return f"\n{sep}\n## {title}{extra}\n{sep}\n\n"

    full_parts = [
        f"# SEMANTIC EXPRESSION SYSTEM: CONSOLIDATED MASTER RESEARCH & CODEBASE CORPUS\n",
        f"System Root Version: v{VERSION} ({DATE}) | Modules: {len(source_files)} | Total Lines: {total_lines:,}\n",
        f"Subsystem Identity: {ident_summary}\n\n",
        f"TABLE OF CONTENTS & SUBSYSTEM SUMMARY:\n"
    ]

    for cat, items in categorized.items():
        if items:
            full_parts.append(f"  - {cat}: {len(items)} files\n")

    full_parts.append(f"\n{sep}\n\n")

    for cat, items in categorized.items():
        if items:
            full_parts.append(banner(f"SUBSYSTEM: {cat.upper()} ({len(items)} files)"))
            for rel, lcnt, size_kib in items:
                src = next(s for r, s in source_files if r == rel)
                full_parts.append(f"--- FILE: {rel} ({lcnt} lines, {size_kib} KiB) ---\n{src}\n\n")

    full_content = "".join(full_parts)
    
    corpus_sha256 = hashlib.sha256(full_content.encode("utf-8")).hexdigest()
    digest_header = f"> Corpus Payload SHA-256 (excluding this field): {corpus_sha256}\n"
    
    manifest_content = manifest_content.replace(f"> Subsystem Identity: {ident_summary}\n", f"> Subsystem Identity: {ident_summary}\n{digest_header}")
    full_content = full_content.replace(
        f"Subsystem Identity: {ident_summary}\n\n",
        f"Subsystem Identity: {ident_summary}\nCorpus Payload SHA-256 (excluding this field): {corpus_sha256}\n\n",
    )

    with open(os.path.join(AGENTS_DIR, "llms.txt"), "w", encoding="utf-8") as f:
        f.write(manifest_content)
    with open(os.path.join(AGENTS_DIR, f"llms-{ABBR}-v{VERSION}.txt"), "w", encoding="utf-8") as f:
        f.write(manifest_content)

    with open(os.path.join(AGENTS_DIR, "llms-full.txt"), "w", encoding="utf-8") as f:
        f.write(full_content)
    with open(os.path.join(AGENTS_DIR, f"llms-full-{ABBR}-v{VERSION}.txt"), "w", encoding="utf-8") as f:
        f.write(full_content)

    full_kib = round(len(full_content.encode("utf-8")) / 1024)
    print(
        f"gen-llms: generated .agents/llms.txt, .agents/llms-{ABBR}-v{VERSION}.txt ({len(manifest_content)} bytes) and .agents/llms-full.txt, .agents/llms-full-{ABBR}-v{VERSION}.txt ({full_kib} KiB, {len(source_files)} source files included) [SHA256: {corpus_sha256[:16]}]"
    )

if __name__ == "__main__":
    main()



========================================================================
## SUBSYSTEM: OPERATIONAL WORK GRAPH & ISSUES (41 files)
========================================================================

--- FILE: work/GRAPH.md (38 lines, 3.2 KiB) ---
# Work Graph Proposal

Provider: `local`

This is the proposed dependency graph for the next bounded work. Existing SES documents remain the source of truth for specification content; this graph governs execution state only.

```text
SES-001 (canonical conformance baseline) [completed]
  -> SES-002 (formalize conformance fixtures) [completed — structurally validated]
      -> SES-003 (close schema/conformance gaps) [completed — contract defined]
          -> SES-006 (conformance result format) [completed — format defined]
          -> SES-019 (cross-language regression coverage) [completed — semantic regression check added]
  -> SES-004 (resolver boundary) [completed — contract defined]
      -> SES-007 (projection equivalence vectors) [completed — vector contract defined]
      -> SES-010 (token and asset resolution rules) [completed — contract defined]
      -> SES-011 (recipe precedence and conflict handling) [completed — contract defined]
      -> SES-014 (renderer-neutral output contract) [completed — contract defined]
```

Cross-cutting documentation goal SES-020 is completed as protocol-neutral adoption guidance. SES-005 is completed as a vocabulary-only contract.

SES-008 is completed as a responsive expression contract.
SES-009 is completed as an accessibility expression contract.
SES-012 is completed as a semantic branch prohibition contract.
SES-015 is completed as a change-governance contract.
SES-016 is completed as a security and trust-boundary contract.
SES-017 is completed as a provisional performance contract.
SES-018 is completed as an authoring-boundaries contract.
SES-013 is completed as a reference fixture pack.
SES-020 is completed as a host/application boundary contract.
SES-021 is completed as a local pure resolver; SES-022 is completed as canonical resolved-output fixtures; SES-023 is completed as the first validator implementation; SES-024 is completed as declarative negative-fixture execution; SES-025 is completed as pure token and asset resolution; SES-026 is completed as deterministic recipe precedence and conflict detection; SES-027 is completed as projection-contract enforcement; SES-028 is completed as deterministic serialization and snapshot comparison; SES-029 is completed as a minimal DOM/CSS renderer adapter; SES-030 is completed as semantic identity equivalence across expressions; SES-031 is completed as operation exposure and host routing; SES-032 is completed as accessibility metadata validation; SES-033 is completed as keyboard/focus metadata validation; SES-034 is completed as responsive reachability/state validation; SES-035 is completed as reduced-motion/high-contrast handling; SES-036 is completed as security trust-boundary validation; SES-037 is completed as local performance measurement; SES-038 is completed as framework-neutral host adapter; SES-039 is completed as cross-language summary and mutation testing; SES-040 is completed as a locally qualified implementation candidate.

## State rules

- `ready` means bounded, reversible, locally authorized, and evaluable.
- `blocked` means a declared dependency or authority is missing.
- `completed` means the artifact exists and its acceptance evidence is recorded.
- `verified` requires independent qualification beyond documentation existence.


--- FILE: work/SES-002.md (49 lines, 2.0 KiB) ---
# SES-002 — Formalize conformance fixtures

Status: Completed — structurally validated

## Intent

Turn the canonical SES-001 fixture plan into machine-readable positive and negative fixture records without implementing a renderer or product behavior.

## Objective

Create a fixture pack covering the four cross-language `Home` reference vectors and the declared negative cases, with each fixture mapped to an SES-001 invariant and expected validation outcome.

## Owner

`coordinator.local`

## Dependencies

- `docs/09-conformance-baseline.md`
- `docs/conformance/ses-001-matrix.json`
- `docs/schemas/ses-schema.ts`
- `docs/schemas/ses.schema.json`

## Acceptance

- Every positive and negative fixture in the SES-001 plan has a stable ID.
- Every fixture identifies its validation layer, baseline invariant, expected result, and failure condition where applicable.
- Positive fixtures share semantic identities and operations while allowing expression topology to differ.
- Negative fixtures fail for the declared reason rather than merely being malformed JSON.
- No renderer, product screen, transport, persistence, or external integration is added.

## Evidence

- Machine-readable fixture files.
- Fixture index with baseline and source references.
- Structural validation output.
- Negative-fixture result records showing expected failures.

## Permissions

Local repository files only. No push, deploy, publish, spend, external communication, or promotion.

## Stop conditions

Stop if the canonical SES-001 matrix contradicts the fixture plan, if a failure condition cannot be represented without inventing runtime semantics, or if validation requires renderer behavior not yet specified.

## Disposition

Completed as a documentation and fixture-pack issue. Evidence is recorded in `evidence/SES-002-evidence.json`. Full JSON Schema execution and runtime negative-fixture evaluation remain follow-on work because the current environment lacks the `jsonschema` package and no validator implementation is in scope.


--- FILE: work/SES-003.md (22 lines, 0.9 KiB) ---
# SES-003 — Close schema/conformance gaps

Status: Completed — contract defined

## Intent

Define the validator-level obligations that cannot be expressed by the current record-shape schemas alone.

## Acceptance

- Cross-record identity, Slot/Socket compatibility, recipe targets, token/assets, operation exposure, accessibility, and responsive reachability have explicit checks.
- Checks have deterministic ordering, stable IDs, typed failure codes, and evidence requirements.
- The contract distinguishes schema validation from conformance validation.
- No validator, renderer, runtime, or product behavior is implemented.

## Evidence

`evidence/SES-003-evidence.json` records the source trace, check families, result-format boundary, and limitations.

## Disposition

Accepted as a specification-only contract. SES-006 owns the final machine-readable result envelope; SES-013 or a later implementation issue may implement the checks.


--- FILE: work/SES-004.md (22 lines, 0.8 KiB) ---
# SES-004 — Define the resolver boundary

Status: Completed — contract defined

## Intent

Specify the pure semantic-to-expression boundary that allows expression topology to vary without changing semantic identity or behavior.

## Acceptance

- Inputs and renderer-neutral outputs are explicit.
- Cascade order and protected semantic fields are explicit.
- Determinism, no-side-effects, resource ownership, and typed failure behavior are explicit.
- Renderer, business logic, transport, persistence, and operation invocation remain outside the boundary.

## Evidence

`docs/11-resolver-boundary.md` records the contract and invariants.

## Disposition

Accepted as a specification-only boundary. SES-010, SES-011, and SES-014 refine dependent portions without implementing the resolver.


--- FILE: work/SES-005.md (23 lines, 0.7 KiB) ---
# SES-005 — Establish canonical vocabulary

Status: Completed — vocabulary defined

## Intent

Provide one normative vocabulary for SES semantics, expression, projection, operations, and conformance.

## Acceptance

- Core terms have definitions and non-equivalences.
- Operation existence, exposure, signaling, invocation, and outcome remain distinct.
- Morphology and Appearance remain distinct expression layers.
- Conformance and validation remain distinct.
- Vocabulary rules prohibit visual-language or renderer identities from entering the semantic model.

## Evidence

`docs/12-canonical-vocabulary.md`.

## Disposition

Accepted as a documentation-only vocabulary contract. Existing identifiers remain unchanged.


--- FILE: work/SES-006.md (24 lines, 0.9 KiB) ---
# SES-006 — Define conformance result format

Status: Completed — format defined

## Intent

Make conformance outcomes machine-readable and traceable to a baseline, fixture, check, failure condition, and evidence record.

## Acceptance

- Result records require baseline ID, fixture ID, layer, check ID, result, severity, and evidence.
- Failed and blocked results require typed failure codes and conditions.
- Inconclusive results require a summary and retain limitations.
- Expected and observed values and source paths can be recorded when applicable.
- The format does not claim a pass when an evaluator is unavailable.

## Evidence

- `docs/conformance/result.schema.json`
- `docs/conformance/results/SES-002-structural.json`

## Scope boundary

This issue defines the result envelope only. It does not implement a validator, renderer, evaluator, or promotion workflow.


--- FILE: work/SES-007.md (24 lines, 0.9 KiB) ---
# SES-007 — Add projection equivalence vectors

Status: Completed — vector contract defined

## Intent

Demonstrate how radically different Visual Languages can express one semantic contract while preserving meaning, behavior, operations, accessibility, and required content.

## Acceptance

- One shared semantic fixture is paired with four distinct expression vectors.
- Preserved identity, operations, content, accessibility, and responsive obligations are explicit.
- Permitted expression differences are explicit and contract-governed.
- Language-specific semantic or business-logic branches are prohibited.
- No renderer or visual-fidelity claim is introduced.

## Evidence

- `docs/13-projection-equivalence.md`
- `docs/conformance/projection-equivalence.json`

## Disposition

Accepted as a fixture and equivalence-check contract. Execution requires a future validator or regression runner.


--- FILE: work/SES-008.md (23 lines, 0.7 KiB) ---
# SES-008 — Specify responsive invariants

Status: Completed — contract defined

## Intent

Define how responsive expression may change topology while preserving required content, operations, accessibility, priority, and reachability.

## Acceptance

- Reorder, collapse, hide, transform, overflow, and clip rules are explicit.
- Required responsive invariants and failure conditions are named.
- Wide, narrow, small-touch, reduced-motion, and high-contrast contexts are covered.
- No breakpoint values, CSS, renderer, or host layout is implemented.

## Evidence

- `docs/14-responsive-invariants.md`
- `docs/conformance/responsive-invariants.json`

## Disposition

Accepted as a responsive expression contract. Runtime evaluation remains future validator work.


--- FILE: work/SES-009.md (24 lines, 0.9 KiB) ---
# SES-009 — Specify accessibility-preserving expression

Status: Completed — contract defined

## Intent

Ensure expression freedom cannot silently remove accessibility names, relationships, order, focus, operation access, state meaning, or non-visual fallbacks.

## Acceptance

- Accessibility invariants cover names, roles, relationships, order, operations, focus, states, reduced motion, and high contrast.
- Visual freedom and accessibility constraints are explicitly separated.
- Required evaluation contexts and typed failure codes are defined.
- Missing evaluator capability remains inconclusive rather than passing.
- No host framework or renderer implementation is prescribed.

## Evidence

- `docs/15-accessibility-expression.md`
- `docs/conformance/accessibility-expression.json`

## Disposition

Accepted as an accessibility expression contract. Execution remains future validator and host-evaluator work.


--- FILE: work/SES-010.md (24 lines, 0.8 KiB) ---
# SES-010 — Define token and asset resolution rules

Status: Completed — contract defined

## Intent

Make token and Asset resolution deterministic, category-safe, provenance-preserving, and explicit about missing resources and host responsibilities.

## Acceptance

- Token layers and precedence direction are defined.
- Alias cycles, ambiguity, missing tokens, and protected overrides fail explicitly.
- Asset categories and category mismatch behavior are defined.
- Retrieval and host capability responsibilities remain outside pure resolution.
- Typed failure codes and evidence fields are defined.

## Evidence

- `docs/16-token-asset-resolution.md`
- `docs/conformance/token-asset-resolution.json`

## Disposition

Accepted as a resolution contract. Full Recipe conflict precedence remains SES-011.


--- FILE: work/SES-011.md (24 lines, 0.8 KiB) ---
# SES-011 — Define recipe precedence and conflict handling

Status: Completed — contract defined

## Intent

Make Recipe combination deterministic while preserving semantic authority across Visual Language, Theme, state, variant, responsive, accessibility, and local expression layers.

## Acceptance

- Precedence order is fixed and machine-readable.
- Scalar, object, ordered-array, Slot, State, Variant, and protected-field merge behavior is explicit.
- Same-precedence conflicts and protected-field overrides fail without fallback winners.
- Resolved layer trace requirements are defined.
- No resolver or renderer implementation is added.

## Evidence

- `docs/17-recipe-precedence.md`
- `docs/conformance/recipe-precedence.json`

## Disposition

Accepted as a precedence contract for the SES-004 resolver boundary.


--- FILE: work/SES-012.md (24 lines, 0.7 KiB) ---
# SES-012 — Define semantic branch prohibition

Status: Completed — contract defined

## Intent

Prevent Visual Language and Theme selection from forking semantic identity, operation behavior, business behavior, or application routing.

## Acceptance

- Prohibited semantic and business-logic branch patterns are explicit.
- Allowed expression variation surfaces are explicit.
- Cross-language review checks and typed failure codes are defined.
- Host-specific extensions require namespacing and remain downstream.
- No implementation refactor is performed.

## Evidence

- `docs/18-semantic-branch-prohibition.md`
- `docs/conformance/semantic-branch-prohibition.json`

## Disposition

Accepted as a conformance and architecture-review contract.


--- FILE: work/SES-013.md (27 lines, 1.0 KiB) ---
# SES-013 — Create a reference implementation fixture pack

Status: Completed — fixture pack defined

## Intent

Provide reusable semantic, operation, state, and appearance fixtures for future SES validators, resolvers, and host runtimes.

## Acceptance

- A shared Home composition fixture exists.
- A reusable MediaCard fixture includes Slots, states, behavior, and operation identity.
- Required operations and state meanings are explicit.
- A representative layered appearance fixture demonstrates morphology, tokens, assets, edges, patterns, texture, and decoration.
- The pack remains renderer-neutral and does not implement product behavior.

## Evidence

- `docs/conformance/reference-pack/index.json`
- `docs/conformance/reference-pack/semantic-home.json`
- `docs/conformance/reference-pack/media-card.json`
- `docs/conformance/reference-pack/operations-and-states.json`
- `docs/conformance/reference-pack/appearance-neo-edo.json`

## Disposition

Accepted as a reusable fixture pack for future implementation and validation work.


--- FILE: work/SES-014.md (24 lines, 0.8 KiB) ---
# SES-014 — Define renderer-neutral output contract

Status: Completed — contract defined

## Intent

Specify the resolved projection handed from SES resolution to any host renderer without coupling SES to DOM, CSS, native widgets, canvas, or a framework.

## Acceptance

- Output sections for identity, semantics, projection, expression, resources, interaction, accessibility, responsive behavior, trace, and diagnostics are explicit.
- Host-neutrality rules and namespaced extension boundaries are explicit.
- Semantic/expression separation, provenance, determinism, and required metadata invariants are explicit.
- Typed output failures are defined.
- No renderer or host adapter is implemented.

## Evidence

- `docs/19-renderer-neutral-output.md`
- `docs/conformance/renderer-neutral-output.json`

## Disposition

Accepted as the renderer boundary for SES-004.


--- FILE: work/SES-015.md (25 lines, 0.7 KiB) ---
# SES-015 — Establish change governance

Status: Completed — governance defined

## Intent

Make SES evolution traceable, compatibility-aware, conformance-reviewed, and explicit about deprecation and version boundaries.

## Acceptance

- Independent version boundaries and change classes are defined.
- Normative change records have required fields.
- Conformance-impact review inputs are explicit.
- Deprecation and changelog requirements are explicit.
- Missing evidence cannot be treated as a pass.
- No external release or publication action is taken.

## Evidence

- `docs/20-change-governance.md`
- `docs/conformance/change-governance.json`

## Disposition

Accepted as a local governance contract. External release authority remains unassigned.


--- FILE: work/SES-016.md (24 lines, 0.9 KiB) ---
# SES-016 — Add security and trust boundaries

Status: Completed — contract defined

## Intent

Keep expression data declarative and prevent Assets, custom sources, filters, or host extensions from becoming implicit code, authority, or business behavior.

## Acceptance

- Trust classes distinguish declarative data, resources, constrained custom expression, executable behavior, and authority-bearing input.
- Custom sources and host extensions require explicit capability and provenance.
- Resource and execution limits are assigned to host policy.
- Unknown or unsafe expression inputs fail closed.
- No security adapter, sanitizer, sandbox, or remote delivery implementation is added.

## Evidence

- `docs/21-security-trust-boundaries.md`
- `docs/conformance/security-trust-boundaries.json`

## Disposition

Accepted as a protocol-neutral security boundary. Host and delivery protocols must supply environment-specific enforcement.


--- FILE: work/SES-017.md (24 lines, 0.9 KiB) ---
# SES-017 — Define performance budgets

Status: Completed — provisional budgets defined

## Intent

Bound SES resolution and renderer-neutral output costs while preserving semantic, accessibility, operation, and responsive invariants.

## Acceptance

- Resolution, token lookup, asset metadata, layer/depth, responsive recomputation, motion metadata, and output-size budgets are defined.
- Measurement boundaries exclude resource and host work from pure resolver timing.
- Required semantics may not be dropped to meet a budget.
- Measurement fields, degradation rules, and typed failures are explicit.
- Budgets are marked provisional until runtime evidence exists.

## Evidence

- `docs/22-performance-budgets.md`
- `docs/conformance/performance-budgets.json`

## Disposition

Accepted as a provisional performance contract. Qualification requires measurements from an implementation profile.


--- FILE: work/SES-018.md (24 lines, 0.9 KiB) ---
# SES-018 — Define authoring boundaries

Status: Completed — boundaries defined

## Intent

Route each SES concern to one canonical authoring surface so semantic meaning, expression freedom, host realization, and application behavior do not compete for authority.

## Acceptance

- Ownership for semantic, projection, expression, resolver, host, and external protocol surfaces is explicit.
- Routing rules distinguish stable properties, mutable presentation, data movement, and business behavior.
- Host extensions require namespace and provenance.
- Conflicts resolve to canonical semantic/Projection Contract authority or remain explicitly unresolved.
- No repository reorganization or application behavior change is performed.

## Evidence

- `docs/23-authoring-boundaries.md`
- `docs/conformance/authoring-boundaries.json`

## Disposition

Accepted as an authoring and authority-routing contract.


--- FILE: work/SES-019.md (23 lines, 0.8 KiB) ---
# SES-019 — Build cross-language regression coverage

Status: Completed — semantic regression check added

## Intent

Ensure semantic changes remain equivalent across the four canonical Visual Language projection vectors.

## Acceptance

- A repeatable local check loads the canonical projection-equivalence fixture.
- The check verifies four unique vectors, shared semantic identities, shared operations, and declared expression mutations.
- Failure is non-zero and diagnostic.
- The check does not render, compare pixels, invoke operations, or communicate externally.

## Evidence

- `tools/validate_projection_equivalence.py`
- `docs/conformance/projection-equivalence.json`

## Disposition

Accepted as semantic regression coverage. Host rendering and accessibility execution remain separate evaluator work.


--- FILE: work/SES-020.md (27 lines, 1.1 KiB) ---
# SES-020 — Prepare protocol-neutral adoption guidance

Status: Completed — adoption boundary documented

## Intent

Describe how an application consumes SES while keeping transport, persistence, synchronization, authorization, and product navigation outside SES.

## Acceptance

- The host adapter, resolver, renderer adapter, and operation route are explicit.
- Transport, persistence, synchronization, authorization, and navigation have named owners outside SES.
- Adapter rules preserve semantic and operation identity and prohibit expression-driven business branching.
- Guidance supports partial or complete adoption without changing SES authority.
- No product implementation, external communication, deployment, or publication is required.

## Evidence

- `docs/24-protocol-neutral-adoption.md`
- `docs/23-authoring-boundaries.md`
- `docs/14-renderer-neutral-output.md`
- `docs/18-semantic-branch-prohibition.md`
- `PROJECT_PROFILE.json`

## Disposition

Accepted as protocol-neutral adoption guidance. Framework-specific adapters and product integration remain host-owned follow-on work.


--- FILE: work/SES-021.md (26 lines, 1.0 KiB) ---
# SES-021 — Implement a minimal pure resolver

Status: Completed — local reference resolution implemented

## Intent

Provide the first executable semantic-to-expression boundary without implementing a renderer, asset loader, operation runtime, or application behavior.

## Acceptance

- `tools/ses_resolver.py` exposes a pure resolver over already-loaded values.
- The resolver preserves semantic composition identity and operation identity.
- The output contains the renderer-neutral sections required by SES-014.
- Invalid or mismatched targets produce typed failures.
- The reference CLI performs no external effects beyond reading explicit local fixtures and writing stdout.

## Evidence

- `tools/ses_resolver.py`
- `tools/resolve_reference_fixture.py`
- `docs/conformance/reference-pack/media-card.json`
- `docs/conformance/reference-pack/appearance-neo-edo.json`

## Disposition

Accepted as the first local implementation. Token lookup, asset loading, full recipe precedence, validation, and host rendering remain separate issues.


--- FILE: work/SES-022.md (24 lines, 0.9 KiB) ---
# SES-022 — Define canonical resolved-output fixtures

Status: Completed — canonical output expectations defined

## Intent

Provide a stable machine-readable expectation for the renderer-neutral output produced by SES-021 while leaving host markup, CSS, native classes, and event handlers outside the canonical fixture.

## Acceptance

- Required renderer-neutral sections are enumerated.
- Stable identity, operation, projection, expression, context, trace, and diagnostic expectations are explicit.
- Host-specific fields are explicitly forbidden.
- The fixture points to canonical semantic and expression inputs.

## Evidence

- `docs/conformance/resolved-output-fixtures.json`
- `tools/resolve_reference_fixture.py`
- `tools/ses_resolver.py`

## Disposition

Accepted as the canonical expectation for SES-021 output. Executable fixture-schema validation is SES-023.


--- FILE: work/SES-023.md (23 lines, 0.8 KiB) ---
# SES-023 — Implement the first validator against fixture schemas

Status: Completed — resolved-output validator implemented

## Intent

Execute the SES-022 canonical expectations against resolver output and return a machine-readable pass/fail result.

## Acceptance

- Required sections, expected values, and forbidden host fields are checked.
- Missing paths and mismatches produce typed diagnostic codes.
- The validator exits non-zero on failure and emits deterministic JSON.
- Validation has no rendering, network, persistence, or operation side effects.

## Evidence

- `tools/validate_resolved_output.py`
- `docs/conformance/resolved-output-fixtures.json`

## Disposition

Accepted as the first executable resolved-output validator. Full semantic negative-fixture execution remains SES-024.


--- FILE: work/SES-024.md (24 lines, 0.9 KiB) ---
# SES-024 — Add negative-fixture execution and typed diagnostics

Status: Completed — declarative negative-fixture execution added

## Intent

Execute the existing negative-fixture records as expected failures and preserve their baseline, layer, error code, path, and failure condition.

## Acceptance

- Every negative fixture has a unique ID and required failure metadata.
- Each valid record emits `result: fail` with its declared typed diagnostic.
- Malformed records emit `result: blocked` with `ERR_NEGATIVE_FIXTURE_MALFORMED`.
- The output is deterministic JSON and exits non-zero only for malformed fixture input.

## Evidence

- `tools/execute_negative_fixtures.py`
- `docs/conformance/fixtures/negative.json`
- `docs/10-validator-contract.md`

## Disposition

Accepted as declarative negative-fixture execution. Runtime semantic mutation and host evaluation remain later validator work.


--- FILE: work/SES-025.md (25 lines, 0.9 KiB) ---
# SES-025 — Implement token and asset resolution

Status: Completed — pure resource resolution implemented

## Intent

Resolve caller-supplied token and asset registries deterministically while keeping retrieval, decoding, capability discovery, and host execution outside SES.

## Acceptance

- Token lookup follows the declared layer order and records provenance and alias path.
- Token cycles and missing references produce typed failures.
- Asset lookup requires the declared category and valid metadata.
- The resolver emits resolved resource metadata when registries are supplied.
- No file, network, or host resource loading occurs.

## Evidence

- `tools/resource_resolution.py`
- `tools/ses_resolver.py`
- `docs/conformance/resource-fixtures.json`

## Disposition

Accepted as pure token and asset resolution. Full recipe precedence and projection enforcement remain SES-026 and SES-027.


--- FILE: work/SES-026.md (24 lines, 0.7 KiB) ---
# SES-026 — Implement recipe precedence and conflict detection

Status: Completed — deterministic recipe cascade implemented

## Intent

Apply the fixed SES recipe order while preventing expression layers from overriding semantic or behavioral authority.

## Acceptance

- All declared layers apply in fixed precedence order.
- Nested expression fields merge and retain a provenance trace.
- Unknown or malformed layers fail with typed diagnostics.
- Protected field overrides fail without selecting a fallback winner.

## Evidence

- `tools/recipe_resolution.py`
- `docs/conformance/recipe-resolution-fixtures.json`
- `docs/17-recipe-precedence.md`

## Disposition

Accepted as the executable recipe cascade. Projection permission enforcement remains SES-027.


--- FILE: work/SES-027.md (24 lines, 0.9 KiB) ---
# SES-027 — Implement projection-contract enforcement

Status: Completed — projection permissions enforced

## Intent

Prevent expression mutations from silently changing semantic identity, required content, operations, accessibility relationships, or business behavior.

## Acceptance

- Preserve, transform, omit, and introduce classifications are checked against the contract.
- Undeclared transforms, unauthorized omissions, and semantic introductions fail with typed diagnostics.
- Preserved semantic values are compared when before/after records are supplied.
- Successful checks return classifications and preserved fields.

## Evidence

- `tools/projection_enforcement.py`
- `docs/conformance/projection-enforcement-fixtures.json`
- `docs/05-projection-contract.md`

## Disposition

Accepted as executable projection permission enforcement. Deterministic output snapshots remain SES-028.


--- FILE: work/SES-028.md (24 lines, 0.8 KiB) ---
# SES-028 — Add deterministic serialization and snapshot comparison

Status: Completed — canonical snapshots implemented

## Intent

Create reproducible output snapshots for resolved SES values without relying on insertion order or host formatting.

## Acceptance

- Object keys are explicitly ordered before serialization.
- Serialization encoding and digest algorithm are declared.
- Equivalent values with different object insertion order produce the same digest.
- Changed values produce a different digest.
- Snapshot comparison reports expected and actual digests.

## Evidence

- `tools/deterministic_snapshot.py`
- `docs/conformance/snapshot-fixtures.json`

## Disposition

Accepted as deterministic snapshot infrastructure. Snapshot governance and mutation coverage remain later qualification work.


--- FILE: work/SES-029.md (25 lines, 0.8 KiB) ---
# SES-029 — Build a DOM/CSS renderer adapter

Status: Completed — minimal host adapter implemented

## Intent

Provide one local host realization of renderer-neutral output without changing canonical semantic identity, operation identity, or expression authority.

## Acceptance

- The adapter consumes renderer-neutral output only.
- HTML carries stable semantic and operation identity attributes.
- CSS includes visible keyboard focus treatment.
- Values are escaped before insertion into HTML.
- The adapter does not invoke operations, load resources, or mutate external state.

## Evidence

- `tools/dom_css_renderer.py`
- `docs/conformance/dom-css-fixture.json`
- `docs/19-renderer-neutral-output.md`

## Disposition

Accepted as a minimal DOM/CSS adapter. Browser execution and visual/accessibility evaluation remain later qualification work.


--- FILE: work/SES-030.md (24 lines, 0.8 KiB) ---
# SES-030 — Verify semantic identity across multiple expressions

Status: Completed — three-expression equivalence verified

## Intent

Demonstrate that radically different Visual Languages can resolve the same semantic target and operation identity.

## Acceptance

- At least three distinct Visual Languages resolve from one semantic input.
- Composition/target identity is identical across outputs.
- Operation identity is identical across outputs.
- Expression records differ in morphology and declared presentation mutations.
- A changed identity or operation causes verification failure.

## Evidence

- `tools/verify_expression_equivalence.py`
- `docs/conformance/expression-equivalence-fixtures.json`

## Disposition

Accepted as semantic identity equivalence coverage. Accessibility and host behavior are verified by later issues.


--- FILE: work/SES-031.md (24 lines, 0.8 KiB) ---
# SES-031 — Verify operation exposure and event routing

Status: Completed — pure operation routing implemented

## Intent

Ensure required operations remain exposed and signaled, then route an event to a stable host-owned operation envelope without invoking side effects.

## Acceptance

- Required operation exposure and signaling are validated.
- Disabled or unexposed operations fail with typed diagnostics.
- Events route by stable operation identity and preserve source identity and payload.
- The router does not invoke callbacks, perform transport, or mutate state.

## Evidence

- `tools/operation_routing.py`
- `docs/conformance/operation-routing-fixtures.json`
- `docs/19-renderer-neutral-output.md`

## Disposition

Accepted as operation exposure and host-routing coverage. Host invocation and result handling remain application responsibilities.


--- FILE: work/SES-032.md (25 lines, 0.8 KiB) ---
# SES-032 — Verify accessible names, roles, and relationships

Status: Completed — accessibility metadata validation implemented

## Intent

Ensure expression output retains the accessible information needed for assistive technology and operation discovery.

## Acceptance

- Accessible names are non-empty.
- Roles are from the declared supported set.
- Relationship targets resolve to known semantic IDs.
- Required operations have stable IDs and accessible names.
- Missing or invalid accessibility metadata produces typed failures.

## Evidence

- `tools/accessibility_validation.py`
- `docs/conformance/accessibility-fixtures.json`
- `docs/15-accessibility-expression.md`

## Disposition

Accepted as metadata-level accessibility validation. Browser and assistive-technology execution remain later qualification work.


--- FILE: work/SES-033.md (24 lines, 0.7 KiB) ---
# SES-033 — Verify keyboard order and focus behavior

Status: Completed — keyboard and focus metadata validation implemented

## Intent

Ensure expression and host metadata preserve logical order, visible focus, and keyboard reachability.

## Acceptance

- Keyboard order equals declared semantic order.
- Focus indication is explicitly visible.
- Every interactive control has stable identity and keyboard reachability.
- Negative cases produce typed diagnostics.

## Evidence

- `tools/keyboard_focus_validation.py`
- `docs/conformance/keyboard-focus-fixtures.json`
- `docs/15-accessibility-expression.md`

## Disposition

Accepted as keyboard/focus metadata validation. Browser interaction execution remains later qualification work.


--- FILE: work/SES-034.md (23 lines, 0.8 KiB) ---
# SES-034 — Verify responsive reachability and state transitions

Status: Completed — responsive metadata validation implemented

## Intent

Ensure responsive expression preserves required content and operations while allowing presentation changes across contexts and declared state transitions.

## Acceptance

- Every declared context is checked for overflow, clipping, hidden required content, and operation reachability.
- Required state transition targets are declared.
- Invalid responsive conditions produce typed diagnostics.

## Evidence

- `tools/responsive_validation.py`
- `docs/conformance/responsive-fixtures.json`
- `docs/14-responsive-invariants.md`

## Disposition

Accepted as responsive reachability and state-transition metadata validation. Host viewport execution remains later qualification work.


--- FILE: work/SES-035.md (24 lines, 0.8 KiB) ---
# SES-035 — Add reduced-motion and high-contrast handling

Status: Completed — accessibility mode handling implemented

## Intent

Adapt expression metadata to user accessibility preferences without changing semantic identity or operation identity.

## Acceptance

- Reduced-motion context disables motion and uses a declared fallback.
- Missing reduced-motion fallback fails.
- High-contrast context requires an explicit high-contrast expression.
- Accessibility context is retained in output metadata.

## Evidence

- `tools/accessibility_modes.py`
- `docs/conformance/accessibility-mode-fixtures.json`
- `docs/15-accessibility-expression.md`

## Disposition

Accepted as pure accessibility-mode expression handling. Host media-query and assistive-technology execution remain later qualification work.


--- FILE: work/SES-036.md (25 lines, 0.8 KiB) ---
# SES-036 — Add security validation for assets and executable expression inputs

Status: Completed — expression trust-boundary validation implemented

## Intent

Keep expression inputs data-only and reject unsafe resource sources or unnamespaced custom capabilities before resolution or rendering.

## Acceptance

- Executable expression keys fail with typed diagnostics.
- Unsafe and unsupported asset source schemes fail.
- Custom sources require an explicit namespace.
- Valid fixture and asset sources pass.
- No source is fetched or executed by validation.

## Evidence

- `tools/security_validation.py`
- `docs/conformance/security-fixtures.json`
- `docs/21-security-trust-boundaries.md`

## Disposition

Accepted as input trust-boundary validation. Host capability, network policy, and asset scanning remain outside this pure check.


--- FILE: work/SES-037.md (24 lines, 0.8 KiB) ---
# SES-037 — Measure resolver and rendering pipeline performance

Status: Completed — local performance measurement recorded

## Intent

Measure the current pure resolver and DOM/CSS adapter under a repeatable local method without converting one environment into a universal performance claim.

## Acceptance

- Resolver and renderer-adapter timings are measured separately.
- Sample count, units, environment, method, p50, and p95 are recorded.
- Resolver p95 is compared with the provisional 5 ms budget.
- A budget miss is reported as inconclusive rather than silently accepted.

## Evidence

- `tools/measure_pipeline.py`
- `docs/conformance/performance-fixture.json`
- `docs/22-performance-budgets.md`

## Disposition

Accepted as a local measurement. Cross-machine, production-load, and statistically independent benchmarks remain open.


--- FILE: work/SES-038.md (24 lines, 0.8 KiB) ---
# SES-038 — Build a framework-neutral host adapter example

Status: Completed — host boundary example implemented

## Intent

Show how a host application can supply SES inputs and receive renderer-neutral output without moving application ownership into SES.

## Acceptance

- Application state is mapped through an explicit adapter.
- Resolver output remains renderer-neutral.
- Operation handoff preserves stable identity and identifies the host owner.
- Transport, persistence, authorization, navigation, and rendering remain named external seams.

## Evidence

- `tools/framework_neutral_adapter.py`
- `docs/conformance/host-adapter-fixture.json`
- `docs/24-protocol-neutral-adoption.md`

## Disposition

Accepted as a framework-neutral host adapter example. No framework, network, database, or product navigation is introduced.


--- FILE: work/SES-039.md (24 lines, 0.9 KiB) ---
# SES-039 — Run cross-language equivalence and mutation testing

Status: Completed — local Python/JavaScript checks passed

## Intent

Compare semantic projection summaries across two runtimes and confirm representative identity mutations are detected.

## Acceptance

- Python and JavaScript produce the same semantic identity, operation set, and Visual Language set.
- A target identity mutation is rejected.
- An operation identity mutation is detected as a changed invariant.
- The check remains local and does not publish or invoke external state.

## Evidence

- `tools/cross_language_equivalence.py`
- `tools/cross_language_projection.mjs`
- `docs/conformance/cross-language-fixture.json`

## Disposition

Accepted as local cross-language summary and mutation coverage. Full implementation equivalence and host-renderer mutation testing remain future qualification work.


--- FILE: work/SES-040.md (26 lines, 1.0 KiB) ---
# SES-040 — Prepare the first independently qualified SES candidate

Status: Completed — local candidate bundle qualified with limits

## Intent

Assemble the first SES implementation candidate and qualify it at the weakest maturity justified by current evidence.

## Acceptance

- Candidate scope, protocol pin, authority, evidence, reproduction method, maturity, and gaps are explicit.
- SES-021 through SES-039 issue and evidence records are bound to the candidate.
- Implemented/local-test claims are separated from empirical-validation and release claims.
- Protected external actions remain excluded.

## Evidence

- `docs/candidates/SES-040-candidate.json`
- `docs/25-accountability-and-readiness.md`
- `PROJECT_PROFILE.json`
- `work/SES-021.md` through `work/SES-039.md`
- `evidence/SES-021-evidence.json` through `evidence/SES-039-evidence.json`

## Disposition

Accepted as the first locally qualified implementation candidate. It is not promoted to empirically validated, production-ready, or externally published status.


--- FILE: work/SES-041.md (23 lines, 0.9 KiB) ---
# SES-041 — Package manifest for downstream dependency consumption

Status: Completed — manifest added, spec untouched

## Intent

Owner-directed (2026-08-28): downstream project semantic-cms consumes SES as a
pinned dependency under its isolation doctrine (its DESIGN.md §12.1 names this
exact gap as the doctrine's worked example; tracked there as UD-1 / issue #16).
SES previously shipped no package manifest, so there was nothing to pin.

## Change

`package.json` (additive): name `semantic-expression-system` v1.0.0 matching
spec v1.0.0, Apache-2.0 matching LICENSE, exporting the normative schema pair
(`docs/schemas/ses.schema.json`, `docs/schemas/ses-schema.ts`). No normative
content changed; the manifest is packaging metadata only. Publication to a
registry is a separate, owner-authorized promotion — not performed here.

## Acceptance

- Manifest parses; exports resolve to existing files.
- No change to any file under docs/ or tools/.



========================================================================
## SUBSYSTEM: VERIFICATION & EXECUTION EVIDENCE (41 files)
========================================================================

--- FILE: evidence/README.md (36 lines, 1.6 KiB) ---
# Evidence Model

Evidence supports the trace:

```text
intent -> issue -> artifact -> evaluation -> evidence -> qualification -> promotion
```

## Evidence record

Each material result records:

- `id`: stable local evidence identifier
- `issue`: authorized work item
- `claim`: the bounded claim being evaluated
- `source`: artifact, command, fixture, or observation that produced the result
- `method`: how the evidence was obtained
- `result`: pass, fail, partial, or inconclusive
- `limitations`: known gaps or conditions
- `recordedAt`: timestamp supplied by the recording workflow
- `authority`: person or process authorized to qualify the result

Artifact existence is not evidence of implementation, testing, or empirical validation. Negative and inconclusive results remain retained under `docs/NEGATIVE_RESULTS.md`.

## SES evidence classes

- **Specification:** traceability from SES definitions to schemas and conformance rules.
- **Structural validation:** JSON Schema and machine-readable fixture checks.
- **Conformance:** invariant and failure-condition results for a semantic/expression pair.
- **Accessibility:** name, role, order, focus, keyboard, and state-preservation results.
- **Responsive:** reachability, overflow, collapse, and required-operation results.
- **Visual:** reference-render comparison after semantic and interaction checks pass.

## Promotion boundary

IEPE-002 creates only local operating records. It does not qualify SES conformance, publish a release, or promote an implementation. Promotion authority is currently `unassigned` in `PROJECT_PROFILE.json`.


--- FILE: evidence/SES-002-evidence.json (34 lines, 1.2 KiB) ---
{
  "id": "SES-002-EV-001",
  "issue": "SES-002",
  "claim": "The SES-001 fixture plan has been formalized into machine-readable positive and negative fixture packages.",
  "source": [
    "docs/conformance/fixture.schema.json",
    "docs/conformance/fixture-index.schema.json",
    "docs/conformance/fixtures/index.json",
    "docs/conformance/fixtures/positive-home.json",
    "docs/conformance/fixtures/negative.json"
  ],
  "method": [
    "python JSON parsing for all fixture and schema files",
    "fixture count assertions",
    "stable positive-vector ID assertion"
  ],
  "result": "partial",
  "findings": {
    "positiveFixtureCount": 4,
    "negativeFixtureCount": 12,
    "positiveVectors": [
      "valid-home-core",
      "valid-home-neo-edo",
      "valid-home-western-comics",
      "valid-home-cybernetic-minimalism"
    ],
    "negativeFixturesCarryExpectedFailure": true
  },
  "limitations": [
    "The jsonschema Python package is unavailable in the current environment, so schema execution was not run.",
    "No renderer or runtime validator exists in scope; negative fixtures encode expected failures but do not execute them."
  ],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-003-evidence.json (18 lines, 0.9 KiB) ---
{
  "id": "SES-003-EV-001",
  "issue": "SES-003",
  "claim": "SES validator obligations beyond JSON Schema shape validation are defined and traceable to the SES-001 baseline.",
  "source": ["docs/10-validator-contract.md", "docs/09-conformance-baseline.md", "docs/schemas/ses.schema.json", "docs/schemas/ses-schema.ts"],
  "method": ["source comparison", "baseline-to-check trace review", "scope-boundary review"],
  "result": "partial",
  "findings": {
    "checkFamilies": ["record-shape", "cross-record-identity", "slot-compatibility", "socket-admission", "composition", "projection", "resource-resolution", "operation-exposure", "accessibility-state", "responsive-reachability"],
    "typedFailureCodesDefined": true,
    "resultSerializationDeferredTo": "SES-006"
  },
  "limitations": [
    "No validator implementation exists in scope.",
    "No renderer or runtime accessibility evaluator exists in scope."
  ],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-004-evidence.json (17 lines, 0.8 KiB) ---
{
  "id": "SES-004-EV-001",
  "issue": "SES-004",
  "claim": "SES defines a pure, deterministic, renderer-neutral semantic-to-expression resolver boundary.",
  "source": ["docs/11-resolver-boundary.md", "docs/06-runtime-and-rendering.md", "docs/08-implementation-boundary.md", "docs/10-validator-contract.md"],
  "method": ["source reconciliation", "boundary ownership review", "invariant trace review"],
  "result": "partial",
  "findings": {
    "pureContractDefined": true,
    "cascadeDefined": true,
    "protectedSemanticFieldsDefined": true,
    "rendererNeutralOutputDefined": true,
    "typedFailureBoundaryDefined": true
  },
  "limitations": ["Implementation and runtime behavior are intentionally out of scope.", "Final conflict precedence is deferred to SES-011."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-005-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-005-EV-001",
  "issue": "SES-005",
  "claim": "SES has a canonical vocabulary that distinguishes meaning, expression, projection, operation exposure, morphology, appearance, and conformance.",
  "source": ["docs/12-canonical-vocabulary.md", "docs/01-definition.md", "docs/02-semantic-model.md", "docs/03-expression-model.md", "docs/05-projection-contract.md", "docs/07-conformance.md"],
  "method": ["terminology reconciliation", "non-equivalence review", "cross-document usage review"],
  "result": "partial",
  "findings": {"canonicalTermsDefined": true, "usageRulesDefined": true, "existingIDsUnchanged": true},
  "limitations": ["Existing historical prose may still contain non-normative aliases; no global editorial rewrite was performed."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-006-evidence.json (10 lines, 0.7 KiB) ---
{
  "id": "SES-006-EV-001",
  "issue": "SES-006",
  "claim": "SES conformance outcomes have a machine-readable result envelope with traceable evidence and typed failures.",
  "source": ["docs/conformance/result.schema.json", "docs/conformance/results/SES-002-structural.json", "docs/10-validator-contract.md"],
  "method": ["JSON parsing", "schema-shape inspection", "result-to-validator-contract trace review"],
  "result": "partial",
  "limitations": ["JSON Schema execution is unavailable because the jsonschema package is not installed.", "The example intentionally remains inconclusive because no runtime validator exists."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-007-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-007-EV-001",
  "issue": "SES-007",
  "claim": "SES defines projection-equivalence vectors for one Home semantic fixture across four radically different Visual Languages.",
  "source": ["docs/13-projection-equivalence.md", "docs/conformance/projection-equivalence.json", "docs/conformance/fixtures/positive-home.json"],
  "method": ["vector-to-baseline trace review", "preserved-property review", "expression-difference review"],
  "result": "partial",
  "findings": {"vectorCount": 4, "sharedSemanticFixture": true, "equivalenceChecksDefined": 7, "languageSpecificSemanticBranchesProhibited": true},
  "limitations": ["No renderer or regression runner exists in scope, so equivalence checks are specified but not executed."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-008-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-008-EV-001",
  "issue": "SES-008",
  "claim": "SES responsive expression rules preserve required content, operation exposure, accessibility, and reachability while allowing declared topology changes.",
  "source": ["docs/14-responsive-invariants.md", "docs/conformance/responsive-invariants.json", "docs/10-validator-contract.md", "docs/schemas/ses-schema.ts"],
  "method": ["responsive rule reconciliation", "context coverage review", "failure-code trace review"],
  "result": "partial",
  "findings": {"contextsDefined": 5, "invariantsDefined": 8, "allowedMutationClassesDefined": 6, "failureCodesReused": true},
  "limitations": ["No responsive renderer or runtime evaluator exists in scope.", "Breakpoint values remain implementation-specific."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-009-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-009-EV-001",
  "issue": "SES-009",
  "claim": "SES defines accessibility-preserving expression obligations across semantic identity, operation access, focus, state signaling, responsive layout, reduced motion, and high contrast.",
  "source": ["docs/15-accessibility-expression.md", "docs/conformance/accessibility-expression.json", "docs/02-semantic-model.md", "docs/05-projection-contract.md", "docs/10-validator-contract.md"],
  "method": ["accessibility contract reconciliation", "expression-freedom boundary review", "context and failure-code coverage review"],
  "result": "partial",
  "findings": {"contextsDefined": 6, "checksDefined": 8, "failureCodesDefined": 9, "missingEvaluationIsInconclusive": true},
  "limitations": ["No host renderer or automated accessibility evaluator exists in scope."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-010-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-010-EV-001",
  "issue": "SES-010",
  "claim": "SES defines deterministic token and Asset resolution with category-safe references and typed missing-resource failures.",
  "source": ["docs/16-token-asset-resolution.md", "docs/conformance/token-asset-resolution.json", "docs/04-token-system.md", "docs/11-resolver-boundary.md"],
  "method": ["token-layer reconciliation", "asset-category review", "failure-boundary review"],
  "result": "partial",
  "findings": {"tokenLayersDefined": 6, "assetCategoriesDefined": 10, "failureCodesDefined": 8, "externalResponsibilitiesDefined": 5},
  "limitations": ["No token resolver, Asset provider, or host capability adapter is implemented."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-011-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-011-EV-001",
  "issue": "SES-011",
  "claim": "SES defines deterministic Recipe precedence, field-specific merging, protected semantic fields, and hard conflict failures.",
  "source": ["docs/17-recipe-precedence.md", "docs/conformance/recipe-precedence.json", "docs/11-resolver-boundary.md", "docs/05-projection-contract.md"],
  "method": ["cascade reconciliation", "field-merge policy review", "protected-authority review"],
  "result": "partial",
  "findings": {"precedenceLayers": 12, "mergeRuleClasses": 7, "protectedFieldsDefined": 9, "failureCodesDefined": 6},
  "limitations": ["Recipe precedence is implemented as a pure cascade, but full resolver integration of the layer trace remains limited to the local implementation candidate."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-012-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-012-EV-001",
  "issue": "SES-012",
  "claim": "SES prohibits language-specific semantic and business-logic branches while permitting governed expression variation.",
  "source": ["docs/18-semantic-branch-prohibition.md", "docs/conformance/semantic-branch-prohibition.json", "docs/01-definition.md", "docs/08-implementation-boundary.md", "docs/13-projection-equivalence.md"],
  "method": ["architecture-boundary review", "allowed/prohibited pattern review", "cross-language equivalence trace"],
  "result": "partial",
  "findings": {"checksDefined": 6, "failureCodesDefined": 5, "allowedExpressionSurfacesDefined": 8, "implementationRefactorPerformed": false},
  "limitations": ["No implementation codebase or automated branch detector is in scope."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-013-evidence.json (11 lines, 0.9 KiB) ---
{
  "id": "SES-013-EV-001",
  "issue": "SES-013",
  "claim": "SES has a reusable reference fixture pack covering Home, MediaCard, operations, states, and layered appearance.",
  "source": ["docs/conformance/reference-pack/index.json", "docs/conformance/reference-pack/semantic-home.json", "docs/conformance/reference-pack/media-card.json", "docs/conformance/reference-pack/operations-and-states.json", "docs/conformance/reference-pack/appearance-neo-edo.json", "docs/examples/home-example.ts"],
  "method": ["fixture inventory review", "identity and operation cross-reference", "renderer-neutrality review"],
  "result": "partial",
  "findings": {"fixtureFiles": 5, "sharedSemanticIdentities": 4, "sharedOperations": 3, "stateFixtures": 5, "appearanceFixture": true},
  "limitations": ["Fixtures are defined but not consumed by a runtime validator or renderer."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-014-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-014-EV-001",
  "issue": "SES-014",
  "claim": "SES defines a renderer-neutral resolved-expression output boundary with semantic preservation, expression separation, provenance, accessibility, responsive metadata, and host extension rules.",
  "source": ["docs/19-renderer-neutral-output.md", "docs/conformance/renderer-neutral-output.json", "docs/11-resolver-boundary.md", "docs/06-runtime-and-rendering.md", "docs/08-implementation-boundary.md"],
  "method": ["resolver-to-renderer boundary review", "output section trace review", "host-neutrality review"],
  "result": "partial",
  "findings": {"outputSectionsDefined": 10, "invariantsDefined": 7, "failureCodesDefined": 7, "hostNeutral": true},
  "limitations": ["No resolver, renderer, host adapter, or resource loader is implemented."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-015-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-015-EV-001",
  "issue": "SES-015",
  "claim": "SES defines version boundaries, change classes, conformance-impact review, deprecation, and changelog obligations.",
  "source": ["docs/20-change-governance.md", "docs/conformance/change-governance.json", "docs/CHANGELOG.md", "docs/09-conformance-baseline.md"],
  "method": ["governance reconciliation", "version-boundary review", "conformance-impact review mapping"],
  "result": "partial",
  "findings": {"versionBoundariesDefined": 10, "changeClassesDefined": 6, "requiredChangeFieldsDefined": 10, "reviewInputsDefined": 9, "missingEvidenceIsInconclusive": true},
  "limitations": ["No external release authority or publication workflow is assigned."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-016-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-016-EV-001",
  "issue": "SES-016",
  "claim": "SES expression inputs have explicit trust classes and cannot silently become executable behavior or authority-bearing commands.",
  "source": ["docs/21-security-trust-boundaries.md", "docs/conformance/security-trust-boundaries.json", "docs/16-token-asset-resolution.md", "docs/08-implementation-boundary.md"],
  "method": ["trust-boundary review", "expression-versus-authority review", "host-responsibility mapping"],
  "result": "partial",
  "findings": {"trustClassesDefined": 5, "hostResponsibilitiesDefined": 7, "failureCodesDefined": 8, "executableExpressionCanonical": false, "authorityInputCanonical": false},
  "limitations": ["No host sanitizer, sandbox, security policy, or remote delivery adapter is implemented."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-017-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-017-EV-001",
  "issue": "SES-017",
  "claim": "SES defines provisional performance budgets and measurement boundaries for pure resolution and renderer-neutral handoff.",
  "source": ["docs/22-performance-budgets.md", "docs/conformance/performance-budgets.json", "docs/11-resolver-boundary.md", "docs/19-renderer-neutral-output.md"],
  "method": ["budget-surface review", "measurement-boundary review", "degradation and invariant review"],
  "result": "partial",
  "findings": {"budgetsDefined": 9, "measurementPercentilesDefined": 3, "pureResolverExclusionsDefined": 5, "budgetsProvisional": true},
  "limitations": ["No implementation measurements exist; budgets are provisional guardrails, not performance claims."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-018-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-018-EV-001",
  "issue": "SES-018",
  "claim": "SES defines canonical authoring ownership and routing rules for semantic, expression, resolver, host, and external protocol concerns.",
  "source": ["docs/23-authoring-boundaries.md", "docs/conformance/authoring-boundaries.json", "docs/01-definition.md", "docs/03-expression-model.md", "docs/08-implementation-boundary.md"],
  "method": ["ownership-matrix review", "authority-routing review", "scope-boundary review"],
  "result": "partial",
  "findings": {"authoringSurfacesDefined": 14, "routingRulesDefined": 6, "conflictRuleDefined": true, "repositoryReorganizationPerformed": false},
  "limitations": ["No implementation repository was reorganized; the contract remains architecture guidance."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-019-evidence.json (11 lines, 0.6 KiB) ---
{
  "id": "SES-019-EV-001",
  "issue": "SES-019",
  "claim": "The four SES projection vectors have repeatable semantic and operation equivalence coverage.",
  "source": ["tools/validate_projection_equivalence.py", "docs/conformance/projection-equivalence.json", "docs/13-projection-equivalence.md"],
  "method": ["local executable regression check"],
  "result": "pass",
  "observations": ["4 unique vectors", "7 shared equivalence checks declared", "shared semantic identity set present", "shared operation set present"],
  "limitations": ["No pixel, host-renderer, or automated accessibility comparison is performed."],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-020-evidence.json (28 lines, 1.1 KiB) ---
{
  "id": "SES-020-EV-001",
  "issue": "SES-020",
  "claim": "An application can consume SES through explicit host, resolver, renderer, and operation boundaries without assigning transport, persistence, synchronization, authorization, or navigation to SES.",
  "source": [
    "docs/24-protocol-neutral-adoption.md",
    "docs/23-authoring-boundaries.md",
    "docs/14-renderer-neutral-output.md",
    "docs/18-semantic-branch-prohibition.md",
    "PROJECT_PROFILE.json"
  ],
  "method": [
    "documentation cross-check",
    "authority and protected-action review"
  ],
  "result": "pass",
  "observations": [
    "host adapter, resolver, renderer adapter, and operation route are defined",
    "external application concerns have explicit owners outside SES",
    "stable semantic and operation identity is required across adapters",
    "local-only scope matches the project protected-action profile"
  ],
  "limitations": [
    "No framework-specific adapter or product integration is implemented",
    "No transport, persistence, synchronization, or deployment behavior is exercised"
  ],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-021-evidence.json (24 lines, 0.9 KiB) ---
{
  "id": "SES-021-EV-001",
  "issue": "SES-021",
  "claim": "A minimal pure resolver produces renderer-neutral output from the canonical Home semantic and Neo-Edo expression fixtures.",
  "source": [
    "tools/ses_resolver.py",
    "tools/resolve_reference_fixture.py",
    "docs/conformance/reference-pack/media-card.json",
    "docs/conformance/reference-pack/appearance-neo-edo.json"
  ],
  "method": ["local executable reference resolution"],
  "result": "pass",
  "observations": [
    "semantic composition identity is preserved",
    "three operation identities are carried into interaction output",
    "renderer-neutral output sections are emitted",
    "target mismatch is represented as a typed resolution failure"
  ],
  "limitations": [
    "token and asset registries are not resolved",
    "full recipe precedence and host rendering are not implemented"
  ],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-022-evidence.json (21 lines, 0.7 KiB) ---
{
  "id": "SES-022-EV-001",
  "issue": "SES-022",
  "claim": "The first resolved SES output has a canonical, renderer-neutral expectation fixture.",
  "source": [
    "docs/conformance/resolved-output-fixtures.json",
    "tools/resolve_reference_fixture.py",
    "tools/ses_resolver.py"
  ],
  "method": ["fixture structure review", "reference-source cross-check"],
  "result": "pass",
  "observations": [
    "10 renderer-neutral output sections are required",
    "identity, operation, projection, expression, context, trace, and diagnostics are asserted",
    "host-specific fields are explicitly excluded"
  ],
  "limitations": [
    "The fixture is not yet executed by an independent validator; SES-023 owns that work"
  ],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-023-evidence.json (21 lines, 0.7 KiB) ---
{
  "id": "SES-023-EV-001",
  "issue": "SES-023",
  "claim": "The SES-022 resolved-output expectations are executable as a deterministic local validator.",
  "source": [
    "tools/validate_resolved_output.py",
    "docs/conformance/resolved-output-fixtures.json"
  ],
  "method": ["local validator execution"],
  "result": "pass",
  "observations": [
    "required sections are checked",
    "expected paths and values are checked",
    "forbidden host-specific fields are checked",
    "failure output uses typed diagnostic codes"
  ],
  "limitations": [
    "Semantic negative fixtures and full validator contract checks remain SES-024 and later work"
  ],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-024-evidence.json (21 lines, 0.7 KiB) ---
{
  "id": "SES-024-EV-001",
  "issue": "SES-024",
  "claim": "The canonical negative fixture set executes into typed expected-failure records without discarding negative evidence.",
  "source": [
    "tools/execute_negative_fixtures.py",
    "docs/conformance/fixtures/negative.json",
    "docs/10-validator-contract.md"
  ],
  "method": ["local negative-fixture execution"],
  "result": "pass",
  "observations": [
    "12 negative fixtures were executed",
    "12 typed failure diagnostics were retained",
    "fixture IDs, baselines, layers, and failure conditions were preserved"
  ],
  "limitations": [
    "This phase executes declarative expected-failure records; semantic runtime mutation is not yet evaluated"
  ],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-025-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-025-EV-001",
  "issue": "SES-025",
  "claim": "SES resolves caller-supplied tokens and assets with deterministic provenance and typed failures without loading resources.",
  "source": ["tools/resource_resolution.py", "tools/ses_resolver.py", "docs/conformance/resource-fixtures.json"],
  "method": ["local resolver execution", "cycle and category-mismatch checks"],
  "result": "pass",
  "observations": ["token alias provenance is retained", "asset categories are enforced", "missing and cyclic references fail with typed codes"],
  "limitations": ["No asset retrieval, decoding, licensing, or host capability check is performed"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-026-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-026-EV-001",
  "issue": "SES-026",
  "claim": "Recipe layers resolve in the declared fixed order with provenance and protected-field failures.",
  "source": ["tools/recipe_resolution.py", "docs/conformance/recipe-resolution-fixtures.json", "docs/17-recipe-precedence.md"],
  "method": ["local cascade execution", "protected override execution"],
  "result": "pass",
  "observations": ["later expression layers replace permitted scalar fields", "nested fields merge", "trace records layer and prior/result values", "protected operation override fails"],
  "limitations": ["Projection permission checks are implemented in SES-027"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-027-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-027-EV-001",
  "issue": "SES-027",
  "claim": "Projection mutations are accepted only when classified and permitted by the Projection Contract.",
  "source": ["tools/projection_enforcement.py", "docs/conformance/projection-enforcement-fixtures.json", "docs/05-projection-contract.md"],
  "method": ["local valid projection execution", "undeclared mutation execution", "preserved-value mutation execution"],
  "result": "pass",
  "observations": ["valid transform, omit, introduce, and preserve cases pass", "undeclared transform fails", "preserved semantic changes fail"],
  "limitations": ["Host renderer behavior is outside this enforcement boundary"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-028-evidence.json (11 lines, 0.6 KiB) ---
{
  "id": "SES-028-EV-001",
  "issue": "SES-028",
  "claim": "Equivalent resolved-output values have stable canonical serialization and snapshots, while changed values are detected.",
  "source": ["tools/deterministic_snapshot.py", "docs/conformance/snapshot-fixtures.json"],
  "method": ["canonical serialization comparison", "digest comparison"],
  "result": "pass",
  "observations": ["key insertion order does not affect the digest", "expression change changes the digest", "algorithm and encoding are recorded"],
  "limitations": ["No cross-language serializer equivalence is established yet"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-029-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-029-EV-001",
  "issue": "SES-029",
  "claim": "A DOM/CSS host adapter realizes stable SES identity and operation metadata without redefining canonical output.",
  "source": ["tools/dom_css_renderer.py", "docs/conformance/dom-css-fixture.json", "docs/19-renderer-neutral-output.md"],
  "method": ["local adapter execution", "HTML/CSS marker assertions"],
  "result": "pass",
  "observations": ["semantic and Visual Language data attributes are emitted", "operation identity is exposed", "focus-visible CSS is emitted", "HTML values are escaped"],
  "limitations": ["No browser engine, visual comparison, or assistive technology evaluator is run"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-030-evidence.json (11 lines, 0.6 KiB) ---
{
  "id": "SES-030-EV-001",
  "issue": "SES-030",
  "claim": "Three distinct Visual Languages preserve MediaCard semantic and operation identity.",
  "source": ["tools/verify_expression_equivalence.py", "docs/conformance/expression-equivalence-fixtures.json"],
  "method": ["local multi-expression resolution", "shared identity and operation comparison"],
  "result": "pass",
  "observations": ["3 expressions resolved", "3 distinct Visual Languages retained one target identity", "open-media operation identity was shared"],
  "limitations": ["No host rendering or accessibility execution is performed"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-031-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-031-EV-001",
  "issue": "SES-031",
  "claim": "Required operation exposure and stable event routing are preserved without moving invocation side effects into SES.",
  "source": ["tools/operation_routing.py", "docs/conformance/operation-routing-fixtures.json", "docs/19-renderer-neutral-output.md"],
  "method": ["local exposure validation", "local event routing"],
  "result": "pass",
  "observations": ["open-media is exposed and signaled", "event identity and payload are preserved", "route is explicitly host-owned"],
  "limitations": ["No host callback, network request, authorization, or operation side effect is executed"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-032-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-032-EV-001",
  "issue": "SES-032",
  "claim": "Accessible names, roles, relationships, and operation labels are validated as required SES output metadata.",
  "source": ["tools/accessibility_validation.py", "docs/conformance/accessibility-fixtures.json", "docs/15-accessibility-expression.md"],
  "method": ["local valid accessibility validation", "typed invalid-fixture validation"],
  "result": "pass",
  "observations": ["valid name and role pass", "relationship targets are checked", "four invalid accessibility cases produce typed failures"],
  "limitations": ["No browser accessibility tree or assistive-technology run is performed"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-033-evidence.json (11 lines, 0.6 KiB) ---
{
  "id": "SES-033-EV-001",
  "issue": "SES-033",
  "claim": "Keyboard order and focus obligations are validated independently of host rendering.",
  "source": ["tools/keyboard_focus_validation.py", "docs/conformance/keyboard-focus-fixtures.json", "docs/15-accessibility-expression.md"],
  "method": ["local valid keyboard/focus validation", "typed invalid-fixture validation"],
  "result": "pass",
  "observations": ["semantic and keyboard order match", "focus visibility is required", "unreachable controls fail"],
  "limitations": ["No browser keyboard automation or assistive technology execution is performed"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-034-evidence.json (11 lines, 0.6 KiB) ---
{
  "id": "SES-034-EV-001",
  "issue": "SES-034",
  "claim": "Responsive contexts preserve required content and operations and use declared state transitions.",
  "source": ["tools/responsive_validation.py", "docs/conformance/responsive-fixtures.json", "docs/14-responsive-invariants.md"],
  "method": ["local valid responsive validation", "typed invalid-fixture validation"],
  "result": "pass",
  "observations": ["wide and narrow contexts pass", "overflow, hidden content, clipping, and invalid transition cases fail with typed codes"],
  "limitations": ["No real browser viewport or layout engine is exercised"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-035-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-035-EV-001",
  "issue": "SES-035",
  "claim": "Reduced-motion and high-contrast contexts produce explicit accessible expression handling without changing semantic identity.",
  "source": ["tools/accessibility_modes.py", "docs/conformance/accessibility-mode-fixtures.json", "docs/15-accessibility-expression.md"],
  "method": ["local accessibility-mode execution", "typed fallback failure checks"],
  "result": "pass",
  "observations": ["motion is disabled under reduced-motion", "declared motion fallback is retained", "high-contrast expression is required", "accessibility context flags are emitted"],
  "limitations": ["No OS preference, browser media query, or assistive technology is exercised"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-036-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-036-EV-001",
  "issue": "SES-036",
  "claim": "Expression inputs are constrained to data-only values with safe resource schemes and namespaced custom sources.",
  "source": ["tools/security_validation.py", "docs/conformance/security-fixtures.json", "docs/21-security-trust-boundaries.md"],
  "method": ["local valid trust-boundary validation", "typed unsafe-input validation"],
  "result": "pass",
  "observations": ["fixture sources pass", "executable key is rejected", "javascript and filesystem sources are rejected", "unnamespaced custom source is rejected"],
  "limitations": ["No network request, asset decoding, capability probe, or sandbox execution is performed"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-037-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-037-EV-001",
  "issue": "SES-037",
  "claim": "The local resolver and DOM/CSS adapter have repeatable p50/p95 timing measurements with method and environment recorded.",
  "source": ["tools/measure_pipeline.py", "docs/conformance/performance-fixture.json", "docs/22-performance-budgets.md"],
  "method": ["1000-sample local timing run"],
  "result": "pass",
  "observations": ["resolver and renderer adapter are measured separately", "provisional resolver budget is evaluated", "environment and timing method are emitted"],
  "limitations": ["Local warm process only; no production workload or cross-machine comparison"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-038-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-038-EV-001",
  "issue": "SES-038",
  "claim": "A host application can map state into SES, receive renderer-neutral output, and hand operations back without transferring external concerns to SES.",
  "source": ["tools/framework_neutral_adapter.py", "docs/conformance/host-adapter-fixture.json", "docs/24-protocol-neutral-adoption.md"],
  "method": ["local host-adapter execution", "ownership-boundary assertions"],
  "result": "pass",
  "observations": ["semantic/expression/context mapping is explicit", "operation envelope is host-owned", "external concern ownership is recorded"],
  "limitations": ["No framework runtime, transport, persistence, authorization, or renderer integration is executed"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-039-evidence.json (11 lines, 0.7 KiB) ---
{
  "id": "SES-039-EV-001",
  "issue": "SES-039",
  "claim": "Python and JavaScript agree on the canonical semantic projection summary, and representative identity mutations are detected.",
  "source": ["tools/cross_language_equivalence.py", "tools/cross_language_projection.mjs", "docs/conformance/cross-language-fixture.json"],
  "method": ["local cross-runtime comparison", "target and operation mutation checks"],
  "result": "pass",
  "observations": ["Python and JavaScript agree on identity, operations, and three Visual Languages", "target mutation is rejected", "operation mutation is detected"],
  "limitations": ["This compares semantic summaries, not full runtime or host-renderer implementations"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-040-evidence.json (11 lines, 0.8 KiB) ---
{
  "id": "SES-040-EV-001",
  "issue": "SES-040",
  "claim": "SES-040-candidate-001 is a traceable local implementation candidate with explicit maturity limits and evidence gaps.",
  "source": ["docs/candidates/SES-040-candidate.json", "work/SES-021.md", "work/SES-039.md", "evidence/SES-021-evidence.json", "evidence/SES-039-evidence.json", "PROJECT_PROFILE.json"],
  "method": ["IEPE evidence-bundle qualification", "issue/evidence linkage audit", "local reproduction checks"],
  "result": "pass",
  "observations": ["candidate binds SES-021 through SES-039", "maturity is limited to implemented-and-locally-tested", "excluded protected actions are explicit", "independent evaluator gaps are retained"],
  "limitations": ["Candidate is not empirically validated or release-ready", "promotion authority remains unassigned"],
  "authority": "coordinator.local"
}


--- FILE: evidence/SES-041-evidence.json (1 lines, 0.5 KiB) ---
{"item": "SES-041", "status": "completed", "claims": [{"claim": "package.json added exposing the normative schemas for downstream pinning; no normative content changed", "evidence": "git show HEAD -- package.json work/SES-041.md; node -e \"JSON.parse(require('fs').readFileSync('package.json'))\" exits 0; docs/ and tools/ untouched in the same commit"}], "limitations": ["Not published to any registry — local/git pinning only until the owner authorizes publication", "No build or test tooling added; the schemas are consumed as-is"]}



========================================================================
## SUBSYSTEM: OTHER SYSTEM MODULES (1 files)
========================================================================

--- FILE: package.json (15 lines, 0.7 KiB) ---
{
  "name": "semantic-expression-system",
  "version": "1.0.0",
  "description": "Semantic Expression System (SES): protocol-neutral separation of interface meaning from interface expression. This package exposes the normative schemas and TypeScript types; the specification and conformance corpus live in docs/.",
  "license": "Apache-2.0",
  "type": "module",
  "files": ["docs/schemas/", "docs/SES-SPECIFICATION.md", "LICENSE", "README.md"],
  "exports": {
    ".": { "types": "./docs/schemas/ses-schema.ts" },
    "./schema.json": "./docs/schemas/ses.schema.json",
    "./schema.ts": "./docs/schemas/ses-schema.ts"
  },
  "keywords": ["semantic", "expression", "projection-contract", "design-system", "specification"],
  "private": false
}