# Semantic Surface System — FULL RESEARCH CORPUS
Abbreviation: sss
Version: v0.1.0 | Generated: unspecified | Files: 12 | Lines: 1,436 | Payload: 41.0 KiB
Source path: /Users/zachshallbetter/Projects/_protocols/semantic-surface-model
Bundle name: llm-full-docs-sss

Corpus Payload SHA-256: f7dbfdfb0af463e85d3562a7e92ac3095734f28a60d99f478153bd4ce792a3ed

TABLE OF CONTENTS:
  - INTENT.md (62 lines, 2.8 KiB)
  - LICENSE (21 lines, 1.0 KiB)
  - README.md (92 lines, 5.1 KiB)
  - VERSION (1 lines, 0.0 KiB)
  - docs/ARCHITECTURE.md (136 lines, 3.6 KiB)
  - docs/CHANGELOG.md (22 lines, 0.7 KiB)
  - docs/CONFORMANCE.md (109 lines, 3.7 KiB)
  - docs/IMPLEMENTATION_BOUNDARY.md (94 lines, 2.3 KiB)
  - docs/RELATIONSHIPS.md (92 lines, 2.9 KiB)
  - docs/SSS-SPECIFICATION.md (738 lines, 16.8 KiB)
  - docs/VERSIONING.md (58 lines, 1.7 KiB)
  - package.json (11 lines, 0.3 KiB)

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

========================================================================
## FILE: INTENT.md (62 lines, 2.8 KiB)
========================================================================

# Semantic Surface System — Intent

**Protocol ID:** `sss:protocol/semantic-surface`  
**Version:** `0.1.0`  
**Status:** Normative Candidate

## Purpose

The Semantic Surface System (SSS) exists to define a reusable, protocol-neutral boundary between domain truth and interface expression.

SSS answers one question:

> Given available semantic state and a declared situation, what semantic surface is warranted here?

It resolves canonical or otherwise authoritative domain state, context, access, relationships, evidence, and time into a bounded, inspectable, renderer-neutral semantic surface.

SSS does not own canonical domain truth, graphical expression, authorization, consequential interaction execution, workflow state, qualification authority, or empirical interpretation.

## Protected qualities

A conforming SSS implementation preserves the following qualities:

- domain truth remains owned by the domain authority;
- surface resolution is read-only with respect to canonical state;
- access projection occurs before participation resolution;
- context may affect selection and emphasis but may not silently rewrite meaning;
- observations remain observations and derived relevance remains derived;
- relation presence does not imply causal coupling;
- semantic priority does not prescribe graphical form;
- operation exposure does not imply permission, enablement, authority, execution, or success;
- every surface is attributable to identifiable source state and resolver inputs;
- every included member has an inspectable participation basis;
- uncertainty, absence, withholding, and ineligibility remain distinguishable;
- graphical realization remains the responsibility of an expression system or host renderer.

## Beneficiaries

- Application and product architects separating selection from presentation.
- Domain-system owners exposing contextual views without surrendering semantic authority.
- Expression-system implementers consuming renderer-neutral surface structures.
- Agent-system implementers needing bounded semantic slices with provenance.
- Researchers and evaluators inspecting why a surface was assembled.
- Operators requiring access-safe, traceable, deterministic surface resolution.

## Non-goals

SSS is not:

- a content-management system;
- a publication model;
- a design system;
- a rendering engine;
- a recommendation engine;
- a workflow engine;
- an authorization framework;
- a policy engine;
- a replacement for interaction, evidence, or empirical protocols;
- a universal theory of relevance, preference, attention, or behavior.

## Success condition

SSS succeeds when the same protocol can resolve semantically meaningful surfaces over materially different domains while preserving domain authority, access boundaries, provenance, deterministic explanation, and downstream expression freedom.

========================================================================
## FILE: LICENSE (21 lines, 1.0 KiB)
========================================================================

MIT License

Copyright (c) 2026 Zach Shallbetter

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

========================================================================
## FILE: README.md (92 lines, 5.1 KiB)
========================================================================

# Semantic Surface System

SSS is a protocol-neutral specification for deciding what belongs on a surface. Given canonical state and a declared situation (purpose, subject, context, lens, access and time), it resolves a bounded, inspectable, renderer-neutral `ResolvedSurface`, and leaves domain truth, visual expression, consequential interaction and interpretation of evidence to the systems that own them.

**Protocol ID:** `sss:protocol/semantic-surface` · **Version:** 0.1.0 · **Status:** Normative candidate

## What it does

SSS answers one question: given available semantic state and a declared situation, what semantic surface is warranted here? It sits between a domain system and an expression system. The domain says what exists; SSS says what matters here; expression decides how it may appear; interaction decides what may happen; evidence decides which claims are supported.

```text
Domain system: what exists.
SSS:           what matters here.
Expression:    how it may appear.
Interaction:   what may happen.
Evidence:      what claims are supported.
```

## Features

- A single transformation from state plus purpose, subject, context, lens, access and time to a `ResolvedSurface`.
- Access projection that runs before any candidate is considered, so a lens can narrow what is visible but never widen it.
- Explicit steps for eligibility, membership, grouping, priority, neighborhoods, controlled comparison, attention and temporal resolution.
- Operation exposure that lists what a surface could offer without implying permission, enablement or execution.
- A resolution trace, dependency fingerprints and clearly non-canonical counterfactual surfaces.
- Seven standard profiles: `focus`, `collection`, `neighborhood`, `comparison`, `attention`, `temporal` and `explain`.
- Sixteen core invariants (`SSS-INV-001` to `SSS-INV-016`) and a list of named failure classes that fail closed.
- Five layered conformance levels, S0 to S4, where passing one does not imply another.

## How it works

```text
DOMAIN / CANON
      │
      ▼
ACCESS PROJECTION
      │
      ▼
SSS
purpose + subject + context + lens + time
      │
      ▼
ResolvedSurface
      │
      ▼
EXPRESSION SYSTEM
      │
      ▼
HOST / RENDERER
```

Resolution is read-only with respect to canonical state. Every included member carries an inspectable basis for why it is there, and unknown, absent, withheld and ineligible states stay distinguishable. Semantic priority is recorded but does not dictate graphical form. Any consequential operation a surface exposes leaves SSS and crosses the appropriate interaction and authority boundary.

In the wider stack, SSS sits between the Semantic Expression System (meaning separated from expression) and the Semantic Publication Substrate (published truth separated from presentation). `docs/RELATIONSHIPS.md` states each boundary.

## What this explores

- Separating "what should be shown" from "how it should look" so the same resolved surface can drive very different renderers.
- Making a selection explainable from the resolver's real mechanics rather than an after-the-fact justification.
- Keeping observed, derived and declared state apart so relevance scores never quietly become canonical importance.
- Conformance levels that test boundaries (S2) and portability across renderers and domains (S3, S4), not just schema validity.

## Contents

| File | What it holds |
| :--- | :--- |
| [`INTENT.md`](INTENT.md) | Originating intent, protected qualities and intended beneficiaries |
| [`docs/SSS-SPECIFICATION.md`](docs/SSS-SPECIFICATION.md) | The normative specification (sections 0–29) |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | System boundary and resolution lifecycle |
| [`docs/RELATIONSHIPS.md`](docs/RELATIONSHIPS.md) | Relationship to adjacent systems and protocols |
| [`docs/IMPLEMENTATION_BOUNDARY.md`](docs/IMPLEMENTATION_BOUNDARY.md) | What implementations own and what they must not absorb |
| [`docs/CONFORMANCE.md`](docs/CONFORMANCE.md) | Conformance levels, invariants and mandatory negative tests |
| [`docs/VERSIONING.md`](docs/VERSIONING.md) | Protocol, schema, resolver and package versioning rules |
| [`docs/CHANGELOG.md`](docs/CHANGELOG.md) | Release history |
| [`VERSION`](VERSION) | Current version |

The `schemas/` and `conformance/` folders are present but empty in this version.

## How to read this

1. Read [`INTENT.md`](INTENT.md) for the question SSS answers and the qualities it protects.
2. Read [`docs/SSS-SPECIFICATION.md`](docs/SSS-SPECIFICATION.md) sections 0–3 for the abstract, the governing separation and the definition of a surface, then section 26 for the invariants.
3. Read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) and [`docs/RELATIONSHIPS.md`](docs/RELATIONSHIPS.md) to see where SSS stops.
4. If you are implementing it, read [`docs/IMPLEMENTATION_BOUNDARY.md`](docs/IMPLEMENTATION_BOUNDARY.md) and [`docs/CONFORMANCE.md`](docs/CONFORMANCE.md).

Status: `Documented != Implemented != Tested != Empirically Validated`. This package defines SSS 0.1.0 as a documented normative candidate. It does not claim implementation or empirical validation.

## License

MIT © Zach Shallbetter

Built by [Zach Shallbetter](https://zachshallbetter.com).

========================================================================
## FILE: VERSION (1 lines, 0.0 KiB)
========================================================================

0.1.0

========================================================================
## FILE: docs/ARCHITECTURE.md (136 lines, 3.6 KiB)
========================================================================

# Semantic Surface System — Architecture

**Version:** `0.1.0`

## 1. Architectural position

SSS sits between authoritative domain state and downstream expression.

```text
DOMAIN / CANON
      │
      ▼
ACCESS PROJECTION
      │
      ▼
SSS
      │
      ▼
ResolvedSurface
      │
      ▼
EXPRESSION SYSTEM
      │
      ▼
HOST / RENDERER
```

Interaction governance, qualification, measurement, and empirical interpretation are orthogonal concerns and remain external.

## 2. Source-of-truth ownership

| Layer | Owns | Must not own |
|---|---|---|
| Domain / Canon | entity identity, domain meaning, authoritative state, relation meaning | surface-specific emphasis or visual expression |
| Access / Entitlement | visibility, entitlement, scoped disclosure | semantic ranking or visual form |
| SSS | purpose-bound eligibility, membership, grouping, ordering, semantic priority, operation exposure, explanation | canonical meaning, graphical expression, authorization, mutation |
| Expression | semantic-to-presentation transformation, morphology, appearance, responsive realization | canonical truth or SSS membership decisions |
| Host / Renderer | concrete rendering, routes, modality, platform integration | redefining upstream semantics |
| Interaction authority | permission, verification, mutation, receipts, recovery | visual styling or surface membership |

## 3. Resolution pipeline

```text
identify
→ freeze
→ project access
→ bind context
→ apply lens
→ evaluate eligibility
→ resolve membership
→ group
→ order / prioritize
→ expose operations
→ trace
→ fingerprint
→ emit
```

The pipeline is read-only with respect to canonical state.

## 4. Determinism

A deterministic resolution is a pure function of:

```text
source snapshot
surface request/definition
access projection
relevant context
resolver version
```

Ambient time, random values, network results, and mutable global state must not participate unless supplied as explicit identified inputs. Non-deterministic inputs must be represented as observations or declared external inputs.

## 5. Access-before-resolution

Access filtering precedes candidate discovery and participation. A resolver must never compute a full privileged surface and then hide members from a lower-access user.

This is both a semantic and side-channel boundary.

## 6. Read/write separation

SSS may reveal an operation. It does not execute a consequential operation.

```text
ResolvedSurface.operation
       ↓ user/agent selects
Interaction boundary
       ↓ authority + verification + checks
Mutation / effect
       ↓
New domain state
       ↓
Future SSS resolution
```

## 7. Expression boundary

The SSS output contains semantic participation, not graphical morphology.

Allowed in SSS:

```text
primary
supporting
comparison
warning
priority
required operation
```

Not owned by SSS:

```text
hero
rail
grid
portal
full bleed
3-column
floating card
ink texture
compact density
```

## 8. Temporal model

SSS may resolve current, revision-bound, world-time, semantic-time, or replay surfaces. Historical resolution must not incorporate information unavailable at the requested temporal coordinate unless explicitly marked as later annotation.

## 9. Counterfactual model

A counterfactual surface resolves an explicit hypothetical overlay over a frozen base snapshot. The overlay remains non-canonical and must be visible in provenance.

## 10. Agent use

Agents may consume `ResolvedSurface` directly as structured semantic context. This avoids requiring a machine participant to scrape a human rendering or receive unrestricted raw domain state.

========================================================================
## FILE: docs/CHANGELOG.md (22 lines, 0.7 KiB)
========================================================================

# Semantic Surface System — Changelog

## 0.1.0 — Normative Candidate

Initial formal definition of the Semantic Surface System.

Introduces:

- domain/surface/expression/representation separation;
- Subject, Purpose, SurfaceContext, SurfaceLens;
- Candidate, Eligibility, Membership, Grouping, Priority;
- Neighborhood, Comparison, Attention, Temporal, and Counterfactual resolution;
- operation exposure without authority transfer;
- renderer-neutral `ResolvedSurface`;
- deterministic `ResolutionTrace`;
- access-before-resolution rule;
- dependency fingerprinting;
- Workspace composition;
- standard surface profiles;
- S0–S4 conformance ladder;
- sixteen core invariants;
- implementation and adjacent-system boundaries.

========================================================================
## FILE: docs/CONFORMANCE.md (109 lines, 3.7 KiB)
========================================================================

# Semantic Surface System — Conformance

**Version:** `0.1.0`

Conformance is layered. Passing one level does not imply another.

## S0 — Structural conformance

A conforming artifact:

- identifies the SSS protocol version;
- validates required surface/request/result structures;
- uses typed outcomes for absence and failure;
- preserves identifiers and provenance references;
- does not place renderer-specific morphology in protected SSS fields.

## S1 — Resolution conformance

A conforming resolver demonstrates deterministic behavior for:

- candidate discovery;
- eligibility;
- membership;
- grouping;
- ordering;
- priority;
- operation exposure;
- resolution trace;
- dependency fingerprint.

Golden vectors must include positive and negative cases.

## S2 — Boundary conformance

The implementation demonstrates that:

- inaccessible data cannot affect visible membership, ordering, counts, explanation, or invalidation;
- surface resolution cannot mutate canonical state;
- operation exposure does not bypass authority or interaction contracts;
- graphical expression cannot silently rewrite protected surface participation;
- observed or derived state is not promoted into declared domain state.

## S3 — Cross-expression conformance

The same `ResolvedSurface` is consumed by at least two materially different expression implementations while preserving:

- member identity;
- semantic grouping;
- required priority;
- required operation exposure;
- access constraints;
- explanation identity.

Pixel or morphology equality is not required.

## S4 — Cross-domain conformance

The unchanged protocol resolves surfaces over at least two materially unrelated domains.

The test must demonstrate that SSS does not require domain-specific canonical concepts to function.

## Core invariants

```text
SSS-INV-001  ResolvedSurface != canonical domain state.
SSS-INV-002  Resolution is read-only with respect to canonical state.
SSS-INV-003  Access projection precedes participation.
SSS-INV-004  A lens narrows but never enlarges power.
SSS-INV-005  Observed != declared.
SSS-INV-006  Derived relevance != canonical importance.
SSS-INV-007  Relation != causal coupling.
SSS-INV-008  Semantic priority != graphical presentation.
SSS-INV-009  SSS does not own graphical morphology.
SSS-INV-010  Operation exposure != permission or execution.
SSS-INV-011  Every resolution binds to source state.
SSS-INV-012  Every included member has a traceable participation basis.
SSS-INV-013  Unknown, absent, withheld and ineligible remain distinguishable internally.
SSS-INV-014  Counterfactual state remains non-canonical.
SSS-INV-015  Expression cannot silently redefine protected surface semantics.
SSS-INV-016  Explanation reflects actual resolver mechanics.
```

## Mandatory negative tests

At minimum the conformance suite should prove failure for:

1. an inaccessible record affecting ordering;
2. a hidden record changing a low-access surface fingerprint;
3. a resolver mapping `unknown` to `ineligible` without declaration;
4. an observed metric becoming canonical importance;
5. a relation automatically producing a causal coupling;
6. `role=primary` forcing `hero` graphical morphology;
7. an exposed operation executing without its governing interaction boundary;
8. a replay surface using current observations as historical inputs;
9. an undisclosed random or wall-clock dependency changing output;
10. a generated natural-language rationale diverging from the mechanical trace.

## Status language

Implementations should report the strongest supported state only:

```text
Documented
Implemented
Tested
Empirically Validated
```

Structural or deterministic conformance does not establish empirical usefulness, usability, or behavioral benefit.

========================================================================
## FILE: docs/IMPLEMENTATION_BOUNDARY.md (94 lines, 2.3 KiB)
========================================================================

# Semantic Surface System — Implementation Boundary

**Version:** `0.1.0`

## 1. Required implementation responsibilities

A conforming implementation needs, at minimum:

- input adapters for identified domain snapshots;
- access projection hook or adapter;
- surface-definition/request validation;
- deterministic candidate discovery;
- eligibility evaluation;
- membership/grouping/ordering resolution;
- operation exposure mapping;
- resolution trace production;
- dependency collection;
- stable fingerprinting;
- typed failures.

## 2. Explicitly external responsibilities

SSS implementations must not absorb these merely for convenience:

- database ownership;
- domain schema ownership;
- canonical identity assignment;
- authentication or authorization;
- entitlement authority;
- interaction execution;
- workflow orchestration;
- evidence qualification;
- rendering;
- visual language;
- theme or token systems;
- graphical morphology;
- empirical inference;
- recommendation claims such as "the user likes X" unless supplied as a declared external fact.

## 3. Renderer-neutral output

The resolver output must be usable by materially different consumers without changing its protected semantics.

Examples:

```text
web renderer
voice renderer
native UI
agent JSON
print/static export
API client
```

## 4. Resolver purity

The core resolver should be pure and host-independent.

Forbidden ambient dependencies include:

```text
current wall clock
random generator
network fetch
mutable singleton
unscoped user session
implicit locale
implicit access level
```

When required, these enter as explicit declared inputs.

## 5. No post-hoc authority

Persisting or caching a `ResolvedSurface` does not make it authoritative domain state.

Likewise, a generated explanation does not become the source of the mechanics it summarizes.

## 6. Operation bridge

Hosts may bind `ResolvedOperation` identities to interaction contracts or equivalent governed actions. The bridge is an adapter; the surface model itself remains read-only.

## 7. Recommended package boundary

A reusable implementation package should expose only stable protocol artifacts and resolver interfaces:

```text
schemas/
TypeScript or language-neutral model types
conformance vectors
resolver API
```

Host renderers and product-specific adapters should remain separate packages.

========================================================================
## FILE: docs/RELATIONSHIPS.md (92 lines, 2.9 KiB)
========================================================================

# Semantic Surface System — Relationship to Adjacent Systems

**Version:** `0.1.0`

This document defines non-overlap boundaries. SSS composes adjacent capabilities but does not absorb them.

## 1. SSS and SES

**SES owns:** semantic interface representation and expression: Elements, Slots, Blocks, Sockets, Compositions, Operations, Projection Contracts, Visual Languages, Themes, Recipes, Morphology, Appearance, Tokens, Assets, and expression resolution.

**SSS owns:** purpose-bound semantic participation before expression: eligibility, membership, grouping, ordering, semantic priority, operation exposure, and resolution explanation.

Normative relationship:

```text
SSS: what participates and why
             ↓
       ResolvedSurface
             ↓
SES: how that semantic surface may be expressed
```

SSS may say `role=primary`; it must not say `render-as-hero`.

## 2. SSS and SPS or another domain substrate

A domain substrate owns domain meaning.

For a publication domain, that includes publication identity, edition, reading order, resource identity, text entitlement, and publication-specific relationships.

SSS must not redefine those concepts.

```text
Domain: what exists and what its relations mean.
SSS:    which domain objects participate here.
```

## 3. SSS and ICP

SSS may expose operation identities but does not decide whether an actor may execute them.

```text
SSS exposure
   ↓
operation selected
   ↓
ICP / interaction authority
   ↓
permission + checks + verification + transition + recovery + receipt
```

Exposure, permission, enablement, selection, execution, and success remain distinct.

## 4. SSS and FCI

SSS uses disciplined distinctions among state, projection, representation, observation, interpretation, opportunity, and measurement.

SSS does not infer intent, trust, understanding, preference, strategy, or cause from observations unless an external evidence-bearing interpretation contract supplies such a claim.

Example:

```text
observed: viewed recently
computed: recency = .87
surface effect: eligible for recent-items
```

is valid.

```text
canonical fact: user likes item
```

is not valid without a separate authority/evidence path.

## 5. SSS and qualification systems

Qualification systems determine whether evidence supports a claim under a declared profile.

SSS may consume qualification state as an input to eligibility or emphasis. It must not manufacture qualification or promotion authority.

## 6. SSS and field/metric systems

Field engines may compute metrics such as attention, heat, entropy, memory, coherence, or staleness.

SSS may consume those values to affect contextual selection or grouping, but the metric source remains authoritative for metric definition and provenance.

## 7. SSS and host applications

Hosts own routing, transport, platform integration, loading, concrete rendering, and modality-specific behavior.

Hosts must not silently alter protected SSS participation semantics.

========================================================================
## FILE: docs/SSS-SPECIFICATION.md (738 lines, 16.8 KiB)
========================================================================

# Semantic Surface System Specification

**Identifier:** `sss:protocol/semantic-surface`  
**Version:** `0.1.0`  
**Status:** Normative Candidate

## 0. Abstract

The **Semantic Surface System (SSS)** is a protocol-neutral architecture for resolving available semantic state into bounded, contextual, inspectable surfaces for human and machine use.

SSS determines **what should participate in a surface, under what context, in what semantic organization, and why**.

SSS does not determine graphical expression, own canonical domain truth, authorize or execute consequential mutation, or infer psychological, causal, behavioral, or scientific claims beyond supplied evidence.

Its fundamental transformation is:

```text
available semantic state
        +
      purpose
        +
      subject
        +
      context
        +
        lens
        +
      access
        +
       time
        ↓
 surface resolution
        ↓
 ResolvedSurface
```

The output is renderer-neutral and may be consumed by an expression system, agent runtime, API, voice interface, or other host.

## 1. Governing separation

The central invariant is:

```text
CANON != SURFACE != EXPRESSION != REPRESENTATION
```

- **Canon / Domain State** owns what the relevant authority declares, records, or recognizes as domain truth.
- **Surface** owns contextual semantic participation: what is included, grouped, ordered, prioritized, exposed, or withheld for the present purpose.
- **Expression** owns permitted transformation into presentation structures, visual language, morphology, appearance, tokens, assets, and modality-specific realization.
- **Representation** is the actual artifact encountered by a participant.

SSS operates only at the Surface layer.

## 2. Scope

SSS owns the semantics of:

```text
purpose
subject
context
lens
eligibility
candidate state
membership
grouping
ordering
priority
semantic emphasis
operation exposure
surface dependencies
resolution explanation
surface provenance
surface uncertainty
```

SSS does not own:

```text
canonical domain truth
publication semantics
storage
schema authority outside SSS
visual language
theme
recipe
graphical morphology
appearance
rendering
persistent mutation
authorization
workflow execution
qualification authority
causal inference
psychological inference
empirical interpretation
```

## 3. Semantic Surface

A **Semantic Surface** is a bounded semantic organization produced from an identifiable source state for a declared purpose and context.

Formally:

```text
S = Resolve(D, P, Q, C, L, A, T)
```

Where:

```text
D = available domain state
P = purpose
Q = subject
C = context
L = lens
A = access projection
T = temporal coordinate
```

The output is a `ResolvedSurface`.

A surface is derived state. It does not become canonical merely because it is persisted, cached, rendered, named, or frequently reused.

## 4. Subject

The **Subject** is the semantic center around which resolution occurs.

A Subject may be:

- one canonical entity;
- one relation;
- one revision;
- one collection;
- one conceptual identifier;
- multiple explicit anchors;
- absent when the purpose concerns a broader scope such as current work, unresolved state, or recent change.

Subject identity originates outside SSS. SSS must not manufacture canonical identity.

## 5. Purpose

A **Purpose** declares what the surface exists to enable.

Initial standard vocabulary:

```text
consume
understand
discover
compare
inspect
edit
resolve
decide
monitor
trace
replay
simulate
operate
```

Projects may specialize this vocabulary. A specialization should identify its nearest parent purpose when one exists.

Purpose may influence eligibility, membership, priority, grouping, ordering, required context, and operation exposure.

Purpose must not enlarge authority or access.

## 6. Context

A **SurfaceContext** contains situation-specific information legitimately available to resolution.

Reference shape:

```ts
interface SurfaceContext {
  actor?: ActorRef;
  task?: TaskRef;
  session?: SessionRef;

  selected?: SubjectRef[];
  recent?: ObservationRef[];

  declared?: Record<string, unknown>;
  observed?: Record<string, ObservationRef>;

  temporal?: TemporalContext;
}
```

Context values retain provenance. A declared preference and an observed behavior are not interchangeable merely because both influence resolution.

Context may affect participation, ordering, grouping, or semantic emphasis. It must not silently change canonical identity, entitlement, authority, required semantic meaning, or protected operations.

## 7. Lens

A **SurfaceLens** restricts and organizes the semantic state that may participate.

Reference shape:

```ts
interface SurfaceLens {
  roots?: SubjectSelector[];

  include?: {
    kinds?: string[];
    relations?: string[];
    metrics?: string[];
    observations?: string[];
  };

  traversal?: {
    radius?: number;
    direction?: "incoming" | "outgoing" | "both";
    relationTypes?: string[];
  };

  where?: Predicate[];

  hold?: DimensionRef[];
  vary?: DimensionRef[];

  groupBy?: GroupingRule[];
  orderBy?: RankingRule[];

  limit?: number;
}
```

A lens is subtractive with respect to power:

```text
Power(output) <= Power(input)
```

A lens must not grant access, create authority, manufacture evidence, invent canonical relationships, or convert uncertainty into certainty.

## 8. Access projection

Access projection occurs before candidate participation.

Required order:

```text
source state
   ↓
access projection
   ↓
accessible state
   ↓
surface lens
   ↓
resolution
```

The following is non-conformant:

```text
full source state
   ↓
resolve surface
   ↓
hide unauthorized members afterward
```

Post-resolution hiding may leak protected state through membership, ordering, counts, dependency invalidation, timing, explanation, or derived metrics.

## 9. Candidate

A **SurfaceCandidate** is a semantic subject under consideration for participation.

```ts
interface SurfaceCandidate {
  subject: SubjectRef;
  eligibility: EligibilityResult;
  evidence?: EvidenceRef[];
  observations?: ObservationRef[];
  scores?: DerivedSurfaceMetric[];
}
```

Candidate status is derived and temporary.

## 10. Eligibility

Eligibility answers whether a candidate may participate under the active purpose, lens, access, and context.

Canonical outcomes:

```text
eligible
ineligible
unknown
withheld
unsupported
```

These are not interchangeable.

- `unknown` is not `ineligible`.
- `withheld` is not `absent`.
- `unsupported` is not `false`.

A low-access surface may intentionally map an internal distinction to a less revealing external representation when that omission is declared by the host projection contract.

## 11. Membership

**SurfaceMembership** records participation in the resolved surface.

```ts
interface SurfaceMembership {
  subject: SubjectRef;
  group: string;
  role?: string;
  priority?: number;
  basis: ResolutionBasis[];
}
```

Membership is derived and must retain sufficient basis for explanation.

## 12. Grouping

A **SurfaceGroup** is a semantic organization of members.

```ts
interface SurfaceGroup {
  id: string;
  role:
    | "primary"
    | "supporting"
    | "context"
    | "relationship"
    | "comparison"
    | "history"
    | "evidence"
    | "warning"
    | "attention"
    | "action"
    | "alternative"
    | "unknown";
  members: SurfaceMembership[];
  ordering?: OrderingRule;
}
```

Group roles describe semantic function, not visual form.

`role = primary` does not imply hero, large, first, centered, full-bleed, or any other graphical decision.

## 13. Priority and semantic emphasis

SSS may establish semantic priority or emphasis.

Example:

```text
priority 0 = required
priority 1 = primary
priority 2 = supporting
priority 3 = peripheral
```

Priority must not define pixels, size, color, layout, animation, typography, enclosure, orientation, or graphical topology.

## 14. Neighborhood resolution

A **Neighborhood Surface** traverses typed relationships around a subject.

```text
Neighborhood = Traverse(
  subject,
  allowedRelationTypes,
  radius,
  direction,
  predicates
)
```

Relation presence may affect participation. It does not automatically create causal behavior or field coupling.

## 15. Controlled comparison

SSS supports explicit comparison frames.

```ts
interface ComparisonLens {
  anchors: SubjectRef[];
  hold?: DimensionRef[];
  vary?: DimensionRef[];
  metric?: ComparisonMetricRef;
  tolerance?: ComparisonTolerance;
}
```

This supports questions such as:

```text
similar to A
similar to A except X
hold X constant and vary Y
compare A and B on Z
maximize difference on Y
```

The resolver must preserve the distinction among declared relation, computed similarity, observed co-occurrence, and human interpretation.

## 16. Attention resolution

SSS may consume externally supplied or computed semantic-field signals such as:

```text
attention
heat
coherence
entropy
memory
phase
pressure
staleness
```

SSS does not own the meaning or computation of those metrics. A consuming definition identifies their source and provenance.

Attention-oriented outputs may include:

```text
needs-attention
quietly-accumulating
recently-changing
uncertain
stale
conflicted
```

These remain surface interpretations unless separately promoted into domain state by the owning authority.

## 17. Temporal resolution

A surface may resolve against a temporal coordinate.

Reference modes:

```text
current
revision
world-time
semantic-time
replay
```

A historical or replay surface must use state and observations admissible at that coordinate. Current observations must not be injected as though historically available.

## 18. Operation exposure

A surface may expose stable semantic operation identities.

```ts
interface ResolvedOperation {
  id: OperationRef;
  subject?: SubjectRef;
  exposure:
    | "required"
    | "available"
    | "withheld"
    | "unavailable"
    | "unknown";
}
```

Operation exposure does not establish permission, enablement, authority, execution, or success.

Any persistent consequential effect leaves SSS and crosses the governing interaction and authority boundary.

## 19. ResolvedSurface

Reference shape:

```ts
interface ResolvedSurface {
  protocol: "sss";
  protocolVersion: string;

  resolutionId: string;
  definitionRef?: string;

  purpose: SurfacePurpose;
  subject?: SubjectRef;

  sourceSnapshot: SnapshotRef;
  accessProjection: AccessProjectionRef;

  groups: SurfaceGroup[];
  operations: ResolvedOperation[];

  consistency?: ConsistencyState;

  provenance: SurfaceProvenance;
  explanation: ResolutionTrace;

  dependencies: SurfaceDependency[];
  fingerprint: string;
}
```

A `ResolvedSurface` is renderer-neutral.

It must not contain graphical morphology, component references, CSS, DOM structure, native-view types, typographic decisions, theme values, or visual recipes as normative surface semantics.

## 20. Resolution trace

Every conforming resolution is explainable.

```ts
interface ResolutionTrace {
  inputs: TraceInput[];
  candidates: CandidateTrace[];
  included: InclusionTrace[];
  excluded: ExclusionTrace[];
  traversals?: TraversalTrace[];
  comparisons?: ComparisonTrace[];
  grouping: GroupingTrace[];
  ordering: OrderingTrace[];
  operationExposure?: OperationTrace[];
  transformations: TransformationTrace[];
}
```

Subject to access constraints, the trace must support answers to:

```text
Why is this here?
Why is this not here?
Why is A above B?
Why are A and B grouped?
Which relations were traversed?
Which observations contributed?
Which rule affected eligibility?
What uncertainty remains?
```

An LLM or other system may summarize the trace, but generated prose must not replace the trace as the authoritative record of resolver mechanics.

## 21. Dependencies and fingerprints

Each resolution records its observable dependencies.

```ts
interface SurfaceDependency {
  subject: SubjectRef;
  revision?: string;
  paths?: string[];
}
```

A fingerprint should be derived from:

```text
accessible dependencies
+ surface definition or request
+ relevant context
+ resolver identity/version
```

Changes outside the observable dependency set should not invalidate the surface.

## 22. Counterfactual surfaces

Counterfactual resolution is optional in SSS 0.1.

It operates on:

```text
FrozenSnapshot + HypotheticalOverlay
```

Reference shape:

```ts
interface HypotheticalOverlay {
  additions?: CandidateRecord[];
  substitutions?: CandidateRecord[];
  removals?: SubjectRef[];
}
```

A counterfactual surface must identify itself as hypothetical, remain non-canonical, and must not emit ordinary mutation receipts.

## 23. Workspace composition

A **Workspace** coordinates multiple semantic surfaces under shared context.

```ts
interface WorkspaceDefinition {
  id?: string;
  purpose: string;
  context: SurfaceContext;
  surfaces: SurfaceRequest[];
}
```

Workspace is intentionally weak. It coordinates semantic surfaces but does not prescribe geometry, tabs, panels, columns, routes, or visual layout.

## 24. Standard surface profiles

SSS 0.1 defines seven standard profiles:

| Profile | Meaning |
|---|---|
| `focus` | One subject plus immediately relevant context |
| `collection` | A set resolved under one lens |
| `neighborhood` | A relational neighborhood around one or more anchors |
| `comparison` | Controlled comparison over declared dimensions |
| `attention` | Conditions warranting awareness or intervention |
| `temporal` | State or change resolved over time |
| `explain` | Resolution provenance and mechanics |

Profiles specialize `SurfaceDefinition`; they do not define independent runtimes.

## 25. Resolution lifecycle

A conforming SSS resolver follows this logical sequence:

```text
IDENTIFY
subject + purpose

↓
FREEZE
source snapshot

↓
PROJECT ACCESS
remove inaccessible state

↓
BIND CONTEXT
actor / task / session / time

↓
APPLY LENS
candidate discovery and traversal

↓
EVALUATE ELIGIBILITY
candidate participation

↓
RESOLVE MEMBERSHIP
include / exclude / withhold / unknown

↓
GROUP
semantic organization

↓
ORDER + PRIORITIZE
semantic emphasis

↓
RESOLVE OPERATIONS
surface operation exposure

↓
TRACE
mechanical explanation

↓
FINGERPRINT
dependencies + resolver identity

↓
EMIT
ResolvedSurface
```

Rendering is not part of this lifecycle.
Persistent mutation is not part of this lifecycle.

## 26. Core invariants

```text
SSS-INV-001  A ResolvedSurface is not canonical domain state.
SSS-INV-002  Surface resolution does not persistently mutate canonical state.
SSS-INV-003  Access projection occurs before candidate participation.
SSS-INV-004  A lens may narrow but never enlarge power.
SSS-INV-005  Observed state never silently becomes declared state.
SSS-INV-006  Derived relevance never silently becomes canonical importance.
SSS-INV-007  Relationship does not imply causal coupling.
SSS-INV-008  Semantic priority does not prescribe graphical presentation.
SSS-INV-009  SSS does not own graphical morphology.
SSS-INV-010  Operation exposure does not imply permission or execution.
SSS-INV-011  Every resolution binds to identifiable source state.
SSS-INV-012  Every included member has an inspectable participation basis.
SSS-INV-013  Unknown, absent, withheld and ineligible remain distinguishable internally.
SSS-INV-014  Counterfactual state remains explicitly non-canonical.
SSS-INV-015  Renderer-specific expression cannot silently redefine protected surface semantics.
SSS-INV-016  Resolution explanation describes actual resolver mechanics, not post-hoc justification.
```

## 27. Failure classes

At minimum, implementations should distinguish:

```text
subject-not-found
subject-inaccessible
invalid-purpose
invalid-lens
unknown-relation-type
unavailable-metric
incompatible-comparison
insufficient-context
access-projection-failure
resolution-cycle
non-deterministic-input-undisclosed
dependency-unresolved
projection-contract-conflict
resolver-version-unsupported
```

Failure is closed where proceeding could change semantic meaning or disclose protected state.

## 28. Conformance

SSS conformance is layered:

- **S0 — Structural:** schema-valid definitions and outputs.
- **S1 — Resolution:** deterministic eligibility, membership, grouping, ordering, operation exposure, and trace behavior against golden vectors.
- **S2 — Boundary:** access, mutation, expression, and authority boundaries are not bypassable through SSS.
- **S3 — Cross-expression:** one `ResolvedSurface` can be consumed by at least two materially different expression implementations without changing protected semantic participation.
- **S4 — Cross-domain:** the unchanged SSS protocol resolves surfaces over two materially unrelated domains.

Passing one level does not imply another.

## 29. Canonical definition

> **The Semantic Surface System (SSS) is a protocol-neutral architecture for selecting and assembling bounded semantic surfaces from canonical state, declared context, access, relationships, evidence, and time, while leaving domain truth, graphical expression, consequential interaction, and empirical interpretation to their owning systems.**

========================================================================
## FILE: docs/VERSIONING.md (58 lines, 1.7 KiB)
========================================================================

# Semantic Surface System — Versioning

**Version:** `0.1.0`

SSS versions independent artifact axes separately.

## 1. Version axes

```text
protocol specification
interchange schemas
resolver implementation
conformance vectors
language packages
host adapters
```

Equal version numbers across axes imply nothing unless compatibility is explicitly declared.

## 2. Protocol versioning

Use semantic versioning for the normative protocol:

- **PATCH** — editorial correction that restores intended meaning without changing requirements;
- **MINOR** — additive compatible semantics, optional fields, new standard purpose/profile values that do not invalidate prior conforming artifacts;
- **MAJOR** — semantic replacement, changed invariant, changed ownership boundary, or incompatible required structure.

## 3. Stable identities

Stable concept identifiers must not change merely because a compatible protocol release occurs.

A semantic replacement receives a new identity.

## 4. Schema compatibility

Schema compatibility is explicit. A structurally valid artifact may still be semantically incompatible with a resolver version.

## 5. Resolver compatibility

A resolver release should declare:

```text
minimum protocol version
maximum tested protocol version
supported schema versions
supported conformance vector set
known semantic exclusions
```

## 6. Re-pin behavior

Downstream projects should pin an immutable revision, digest, or published package version.

Changing the pin is a compatibility event, not a routine dependency refresh.

## 7. Generated artifacts

Generated corpora, rendered docs, compiled bundles, and test reports are derivatives. They do not define protocol meaning.

========================================================================
## FILE: package.json (11 lines, 0.3 KiB)
========================================================================

{
  "name": "@semantic-systems/surface",
  "version": "0.1.0",
  "private": true,
  "description": "Protocol-neutral semantic surface selection and assembly contracts.",
  "license": "UNLICENSED",
  "exports": {
    "./spec": "./docs/SSS-SPECIFICATION.md",
    "./conformance": "./docs/CONFORMANCE.md"
  }
}