Surface

Description

What’s exposed to the outside — the part of a system that interacts with users, callers, attackers, or other systems. A surface has two flavors that frequently bleed together: the image-schema sense (a UI surface, a top layer, the visible part) and the force-dynamic sense (an attack surface, a friction surface, what’s exposed to outside pressure). Both senses share the property of mediating between internal and external.

Encounters

• “Attack surface” — security framing: what’s exposed to potential threats.
• “Primary scan surface” — KCC routing decisions: which interface a parent first sees and judges by.
• “Surface flavor is encoded in the route” — KCC URL-design doctrine: surface choice shouldn’t fight the path it’s on.
• “Change surface” — engineering risk: what gets modified and what stays stable across a refactor.
• “Cognitive surface” — explanatory-style observations: what a reader has to hold in attention to follow.

When it applies / triggers on

User-initiated: User names or implies a boundary between visible UI/API and internal mechanism. Most common phrasings: “does this thing belong here?”, “two surfaces or one?”, “reuse the X?”, or proposals to consolidate / split visible interaction points. The strongest real user-message signal is the word “thin” — “thin wrapper,” “thin layer,” “thin shell” — which appears in 9/26 (35%) of top-candidate triggers in the T2 mining. Two recurring sub-shapes:

• Splitting / unification — user wonders whether two surfaces should be one or one should be two; agent applies the “what does each do that the other can’t?” diagnostic. (Example: “are we complicating things with two surfaces to add camps to tray — browse directory vs autocomplete/search path?” → agent: “two surfaces competing on the same job is a real risk; two surfaces handling adjacent jobs is a funnel.“)
• Reuse-the-surface — user explicitly names the move (e.g., “could/should mirror the existing save modal — reuse the surface?”) and the agent elevates it to a principle: shared behavior lives in shared code.

Agent-initiated: Engine reaches for surface as a named-role decomposition partner — the substrate-surface-amplifier stack is the canonical case (surface as the named middle layer above substrate). Of 30 top T2 candidates, 26 are real user messages and only 4 come via <task-notification> flavor — surface is reached for in agent-side reasoning more than user-side framing.

Vocabulary cues: “thin wrapper,” “thin layer,” “thin shell,” “surface,” “attack surface,” “change surface,” “audit surface,” “error surface,” “primary scan surface,” “reuse the surface,” “two surfaces,” “exposed to,” “visible to,” “mediates between.”

Situation-shape signals: Multi-surface architecture decisions (whether to consolidate or split); surface-as-named-role in a layered architecture; same data shape covered at multiple visible boundaries with potentially-differing visual or interaction treatments.

Composes with

• seam — where two surfaces meet is a seam; the seam is often the failure point.
• load-bearing — thin surface over a load-bearing piece is often the right decomposition; load-bearing piece is the moat, surface is the polish.
• container — surfaces are the boundary of containers; the surface defines what’s “inside” vs. “outside.”

When it doesn’t apply

• Fully internal systems — pure libraries, pure data structures with no observable surface; the surface question is degenerate.
• “Surface” as synonym for “layer” — when used without the inside/outside semantics, the form’s specific work isn’t being done.

Sources

• Image-schema lineage (Lakoff/Johnson — visible boundary).
• Force-dynamic lineage (Talmy — exposure to outside force).
• Information-security tradition (attack surface).

Canonical exemplars from corpus (T2 2026-05-17)

• Substrate-surface-amplifier naming moment (cwd: campconnect, session: idx=1): “Surface (A): the ambient interaction layer. Makes the substrate land in the moment rather than as a thing-you-go-find. Without this, the substrate is a research demo, not a daily tool.”
• Two surfaces competing vs funneling (cwd: campconnect, session: idx=2): “Two surfaces competing on the same job is a real risk; two surfaces handling adjacent jobs is a funnel. The way to tell the difference is to ask ‘what does surface A do that B can’t, and vice versa?‘”
• Reuse the surface (cwd: campconnect, session: idx=8): “Your ‘reuse the surface’ instinct names a principle that’s easy to articulate but hard to apply consistently: shared behavior lives in shared code.”
• Primary scan surface asymmetry (cwd: campconnect, session: idx=5): “High-frequency + scan-by-kid-is-the-task surfaces can earn loud visual treatments that low-frequency admin surfaces can’t. Same data shape, different ROI on visual emphasis.”

Trigger pattern (T2): Surface surfaces when the user names or implies a boundary between visible UI/API and internal mechanism — most often when asking “does this belong here?”, “two surfaces or one?”, or “reuse the X?” — with a strong real trigger signal of the word “thin” in user messages (35% of top candidates).