<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename/</id>
  <title>`surface` names two unrelated domains — split the vocabulary, rename to `ToolSurfaceKind` and `TopologySurface`</title>
  <updated>2026-07-23T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename/"/>
  <summary>The overloaded word `surface` splits into two named types: `ToolSurfaceKind` for tool-facing artifacts and `TopologySurface` for the physical tree an artifact lives in.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-07-23&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Operator (Stijn Dejongh); recorded by &lt;code dir=&quot;auto&quot;&gt;curator-carla&lt;/code&gt; under governed
tidy-first Op &lt;code dir=&quot;auto&quot;&gt;01KY7ECRZCB99JAD3WAQ9ZTSSS&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; coord-trust remediation branch &lt;code dir=&quot;auto&quot;&gt;remediation/coord-lifecycle-gates&lt;/code&gt;
(tracker &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2841&quot;&gt;#2841&lt;/a&gt;); motivating
defects &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1834&quot;&gt;#1834&lt;/a&gt; and
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2885&quot;&gt;#2885&lt;/a&gt;; sibling disambiguation
work &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2653&quot;&gt;#2653&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt;).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The word &lt;strong&gt;surface&lt;/strong&gt; currently names two unrelated concepts in this codebase, in two
bounded contexts that never touch each other:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Tool surface&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;SurfaceKind&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tool_surface/enums.py:13&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;COMMAND_SKILL&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;DOCTRINE_SKILL&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CONTEXT_FILE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;RULE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;HOOK&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;AGENT_PROFILE&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;PLUGIN_MANIFEST&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;NATIVE_CONFIG&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;COMMAND_FILE&lt;/code&gt;): &lt;em&gt;what kind of agent-facing
artifact or configuration entry a definition describes&lt;/em&gt;. Its domain is install /
verify / repair / package for a concrete execution tool.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mission topology surface&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;Surface&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py:23&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;PRIMARY&lt;/code&gt; | &lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt;, with a &lt;code dir=&quot;auto&quot;&gt;str&lt;/code&gt; mixin and an &lt;code dir=&quot;auto&quot;&gt;ArtifactSurface&lt;/code&gt; back-compat
alias): &lt;em&gt;which physical tree a mission artifact resolves to&lt;/em&gt;. Its domain is artifact
placement, read/write paths, and commit targets.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Two unrelated types both named &lt;code dir=&quot;auto&quot;&gt;Surface&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;SurfaceKind&lt;/code&gt; is exactly the failure mode this
project has already paid for twice — the four senses of &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; and the three senses of
&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; (#2653), whose load-bearing trap was reading one sense as another. &lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt; is on
the same trajectory: the glossary’s &lt;code dir=&quot;auto&quot;&gt;PRIMARY partition&lt;/code&gt; entry already had to write “which
surface an artifact kind is written to” while &lt;code dir=&quot;auto&quot;&gt;repository root checkout&lt;/code&gt; had to retire
“primary surface” as an alias.&lt;/p&gt;
&lt;p&gt;The concrete architectural finding that made this urgent is narrower than naming. &lt;strong&gt;There
is no single surface→filesystem translation seam.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;artifact_home_for&lt;/code&gt; returns a
&lt;code dir=&quot;auto&quot;&gt;Surface&lt;/code&gt; &lt;em&gt;label&lt;/em&gt; plus a commit target — it stops at the label. The actual translation
from that label to a directory on disk is scattered across at least six call paths:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_runtime.resolution.placement_seam(...).read_dir&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission_runtime.resolution.coord_read_dir_for&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli.missions._read_path_resolver.resolve_planning_read_dir&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli.acceptance.gates_core._acceptance_matrix_read_dir&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli.post_merge.review_artifact_consistency._resolve_review_cycle_read_dir&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;feature_dir_for_preview&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Together these are referenced from ~20 modules. Every one of them re-derives “where does
this actually live” from topology, existence checks, and fallbacks. That scattering is the
root of two active P0 defects, #1834 and #2885. A surface &lt;em&gt;vocabulary&lt;/em&gt; that cannot be read
unambiguously is what allows six independent translations to drift without anyone noticing
they are the same operation.&lt;/p&gt;
&lt;p&gt;This ADR records the vocabulary decision. It does not implement the seam.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; (charter governing principle) — one word must name one
concept, and one operation must have one seam. Both are violated today.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Precedent set by #2653&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; were disambiguated by naming every
sense explicitly and adding “Do NOT use when” guards, not by leaving context to
disambiguate. &lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt; gets the same treatment or the precedent is arbitrary.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The missing translation seam&lt;/strong&gt; — the enum is the vocabulary a future single seam will
speak. Fixing the names before extracting the seam means the seam is born with the right
vocabulary rather than inheriting a colliding one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Explicitness over avoidance&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt; was chosen historically to avoid the
&lt;em&gt;word&lt;/em&gt; “coord” while keeping the &lt;em&gt;concept&lt;/em&gt;. Avoiding the word does not avoid the
coupling; it only makes the coupling unreadable.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Existing three-sense overload of &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt;&lt;/strong&gt; — any new member naming the
post-consolidation state must not re-import that ambiguity.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1 (chosen)&lt;/strong&gt; — Split the vocabulary: rename &lt;code dir=&quot;auto&quot;&gt;SurfaceKind&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;ToolSurfaceKind&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;Surface&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt;, expand the topology members to
&lt;code dir=&quot;auto&quot;&gt;PRIMARY | COORD | LANE | CONSOLIDATED | TEMP&lt;/code&gt;, and govern both senses in the glossary
with cross-context “Do NOT use when” guards.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2 (rejected)&lt;/strong&gt; — Leave both types named &lt;code dir=&quot;auto&quot;&gt;Surface*&lt;/code&gt; and rely on import path /
module context to disambiguate.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3 (rejected)&lt;/strong&gt; — Rename only one side (e.g. only the topology type), leaving
&lt;code dir=&quot;auto&quot;&gt;SurfaceKind&lt;/code&gt; bare.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option 1 — split the vocabulary and rename both sides.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;the-two-vocabulary-distinction&quot;&gt;The two-vocabulary distinction&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt; is governed as an overloaded term with exactly two senses, mirroring the
&lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; (Senses A–D) and &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; (Senses 1–3) treatment:&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;&lt;/th&gt;&lt;th&gt;&lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt; &lt;strong&gt;Sense 1&lt;/strong&gt;&lt;/th&gt;&lt;th&gt;&lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt; &lt;strong&gt;Sense 2&lt;/strong&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Canonical term&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;/context/execution/#tool-surface&quot;&gt;Tool Surface&lt;/a&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;/context/orchestration/#topology-surface&quot;&gt;Topology Surface&lt;/a&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Question answered&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;em&gt;What kind of tool-facing artifact is this?&lt;/em&gt;&lt;/td&gt;&lt;td&gt;&lt;em&gt;Which physical tree does this artifact live in?&lt;/em&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Bounded context&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Execution (install / doctor / package)&lt;/td&gt;&lt;td&gt;Orchestration (placement / read-write paths)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Type&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ToolSurfaceKind&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Module&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli/tool_surface/enums.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_runtime/artifacts.py&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The two senses share no members, no consumers, and no lifecycle. Nothing is unified by the
shared word; only confusion is.&lt;/p&gt;
&lt;h3 id=&quot;the-rename-decisions&quot;&gt;The rename decisions&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SurfaceKind&lt;/code&gt; → &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;ToolSurfaceKind&lt;/code&gt;&lt;/strong&gt;. The module is already &lt;code dir=&quot;auto&quot;&gt;tool_surface&lt;/code&gt;; the type
name now matches the bounded context it lives in.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Surface&lt;/code&gt; → &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt;&lt;/strong&gt;, with the &lt;code dir=&quot;auto&quot;&gt;ArtifactSurface&lt;/code&gt; back-compat alias retired
along with the old name. Per ADR
&lt;a href=&quot;/adr/3.x/2026-07-01-1-no-legacy-compat-branches-in-resolvers/&quot;&gt;2026-07-01-1&lt;/a&gt;, a legacy alias
kept “just in case” is a resolver-shaped fallback in type clothing; require the canonical
name and migrate.&lt;/li&gt;
&lt;li&gt;Members expand from &lt;code dir=&quot;auto&quot;&gt;PRIMARY | PLACEMENT&lt;/code&gt; to
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;PRIMARY | COORD&lt;/code&gt;&lt;/strong&gt; as landed in the rename, expanding to the full
&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;PRIMARY | COORD | LANE | CONSOLIDATED | TEMP&lt;/code&gt;&lt;/strong&gt; — the full set of physical trees a
mission artifact can resolve to, not just the two the current two-way partition needed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;placement--coord&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt; avoided the &lt;em&gt;word&lt;/em&gt; rather than the &lt;em&gt;concept&lt;/em&gt;. The member has always meant “the
coordination surface”; every consumer read it that way, and &lt;code dir=&quot;auto&quot;&gt;coord_read_dir_for&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;_PLACEMENT_ARTIFACT_KINDS&lt;/code&gt; sit one call apart proving it. Naming it &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt; makes the
existing meaning legible instead of encoding it in tribal knowledge.&lt;/p&gt;
&lt;h3 id=&quot;consolidated-not-merged&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt;, not &lt;code dir=&quot;auto&quot;&gt;MERGED&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;The post-consolidation surface is named &lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt; because &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; is already a
three-sense overloaded term here —
&lt;a href=&quot;/context/orchestration/#lane-consolidation&quot;&gt;Lane Consolidation&lt;/a&gt;,
&lt;a href=&quot;/context/orchestration/#branch-integration--git-merge&quot;&gt;Branch Integration / Git Merge&lt;/a&gt;,
and &lt;a href=&quot;/context/orchestration/#publish-to-originmain&quot;&gt;Publish to origin/main&lt;/a&gt;. A
member named &lt;code dir=&quot;auto&quot;&gt;MERGED&lt;/code&gt; would not say which of the three had occurred, and in a git-based
codebase every reader would guess a different one. &lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt; names exactly one: the
surface that exists after lane consolidation. This is the same reasoning that governs
&lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;base&lt;/code&gt; — when a word already carries N senses, do not spend it on an
N+1st.&lt;/p&gt;
&lt;h3 id=&quot;naming-a-surface-coord-is-not-conditioning-on-topology&quot;&gt;Naming a surface &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt; is not conditioning on topology&lt;/h3&gt;
&lt;p&gt;The standing rule is that behaviour must not branch on topology — a caller must consume a
&lt;em&gt;resolved&lt;/em&gt; path, not re-derive one from &lt;code dir=&quot;auto&quot;&gt;if topology is COORD&lt;/code&gt;. Naming a member &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;
does not violate that rule and must not be read as licence to reintroduce it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Allowed (naming)&lt;/strong&gt; — a surface value that &lt;em&gt;identifies&lt;/em&gt; a real physical tree, so a
resolver can return “this artifact lives on the COORD surface” instead of returning an
unlabelled path.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Forbidden (conditioning)&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;if surface is TopologySurface.COORD: &amp;#x3C;inline path derivation&gt;&lt;/code&gt; at a call site, in place of asking the seam for the resolved directory.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The distinction is the whole point of having a translation seam: the label is the seam’s
&lt;em&gt;output vocabulary&lt;/em&gt;, not an input to per-call-site branching.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Two unrelated types stop colliding on one word; a reader who sees &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;ToolSurfaceKind&lt;/code&gt; knows the domain without opening the import.&lt;/li&gt;
&lt;li&gt;The expanded member set gives the future translation seam a complete vocabulary — &lt;code dir=&quot;auto&quot;&gt;LANE&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;TEMP&lt;/code&gt; are trees that already exist in the system but had no name in
this type, which is part of why six call paths each invented their own handling.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;surface&lt;/code&gt; glossary treatment now matches the &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; treatment, so the
disambiguation discipline reads as a rule rather than as three one-off calls.&lt;/li&gt;
&lt;li&gt;Retiring &lt;code dir=&quot;auto&quot;&gt;ArtifactSurface&lt;/code&gt; removes a legacy alias before it acquires consumers.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A broad mechanical rename across &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;. It is a bulk edit and carries the
usual occurrence-classification obligation.&lt;/li&gt;
&lt;li&gt;Dropping the &lt;code dir=&quot;auto&quot;&gt;str&lt;/code&gt; mixin (if the rename does so) breaks any surviving
&lt;code dir=&quot;auto&quot;&gt;== &quot;primary&quot;&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;== &quot;placement&quot;&lt;/code&gt; literal comparison; those comparisons are exactly the
scattered-translation smell this ADR documents, so they must be converted, not preserved.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Landed state vs end state.&lt;/strong&gt; The rename commit ships only &lt;code dir=&quot;auto&quot;&gt;PRIMARY | COORD&lt;/code&gt; (the two members
the old &lt;code dir=&quot;auto&quot;&gt;Surface&lt;/code&gt; carried, &lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt; renamed to &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;LANE&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CONSOLIDATED&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;TEMP&lt;/code&gt;
are the decided end state but are &lt;strong&gt;not&lt;/strong&gt; declared until the surface→filesystem translation seam
that resolves them lands (mission IC-11) — a member no caller can resolve is a phantom, which the
anti-phantom rule forbids. So code shows two members and this ADR describes five; that is intended,
not drift. Anyone reading the enum before IC-11 sees two.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;This ADR changes vocabulary only. The scattered translation remains scattered; #1834 and
#2885 remain open. The seam extraction is separate work, and this ADR is deliberately
the vocabulary prerequisite for it rather than a bundled fix.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;MissionArtifactKind&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;_PRIMARY_ARTIFACT_KINDS&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_PLACEMENT_ARTIFACT_KINDS&lt;/code&gt;
partition sets are untouched by the vocabulary decision beyond the &lt;code dir=&quot;auto&quot;&gt;PLACEMENT&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt;
member name.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;The decision is confirmed when: (a) no module outside &lt;code dir=&quot;auto&quot;&gt;mission_runtime/artifacts.py&lt;/code&gt;
declares or aliases a bare &lt;code dir=&quot;auto&quot;&gt;Surface&lt;/code&gt; type; (b) &lt;code dir=&quot;auto&quot;&gt;ArtifactSurface&lt;/code&gt; has no remaining
references; and (c) a future seam-extraction slice can state its contract as
“&lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt;” without first having to define what a surface is. Failure
signal: a new call site re-deriving a coordination directory inline rather than consuming
a resolved path — that would mean the label was read as a branching input, which
§“Naming a surface &lt;code dir=&quot;auto&quot;&gt;COORD&lt;/code&gt; is not conditioning on topology” forbids.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1--split-the-vocabulary-rename-both-sides&quot;&gt;Option 1 — split the vocabulary, rename both sides&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Each type name states its bounded context.&lt;/li&gt;
&lt;li&gt;Consistent with the &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; (#2653) and &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; disambiguation precedent.&lt;/li&gt;
&lt;li&gt;Gives the future translation seam a complete, unambiguous output vocabulary.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Bulk rename cost across two packages plus tests.&lt;/li&gt;
&lt;li&gt;Names three members ahead of their consumers.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2--leave-both-named-surface-disambiguate-by-import-path&quot;&gt;Option 2 — leave both named &lt;code dir=&quot;auto&quot;&gt;Surface*&lt;/code&gt;, disambiguate by import path&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero code churn.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Import-path disambiguation fails exactly where it matters — in prose, in review comments,
in agent-authored plans, and in &lt;code dir=&quot;auto&quot;&gt;from ... import Surface&lt;/code&gt; lines read out of context.&lt;/li&gt;
&lt;li&gt;Repeats the &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; failure the project has already paid to fix twice.&lt;/li&gt;
&lt;li&gt;Leaves the future seam speaking a colliding vocabulary.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3--rename-only-the-topology-side&quot;&gt;Option 3 — rename only the topology side&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Smaller diff; fixes the side with the active defects.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Leaves a bare &lt;code dir=&quot;auto&quot;&gt;SurfaceKind&lt;/code&gt; that still reads as “the surface type” to anyone who has not
met &lt;code dir=&quot;auto&quot;&gt;TopologySurface&lt;/code&gt;, so the collision persists asymmetrically.&lt;/li&gt;
&lt;li&gt;Half-applied disambiguation is worse than none: it implies the remaining bare name is
&lt;em&gt;the&lt;/em&gt; canonical sense.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Glossary entries: &lt;a href=&quot;/context/orchestration/#topology-surface&quot;&gt;Topology Surface&lt;/a&gt;
and &lt;a href=&quot;/context/orchestration/#coord-partition&quot;&gt;COORD partition&lt;/a&gt; (Orchestration
context); &lt;a href=&quot;/context/execution/#tool-surface&quot;&gt;Tool Surface&lt;/a&gt; (Execution context).&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-07-01-1-no-legacy-compat-branches-in-resolvers/&quot;&gt;2026-07-01-1 — No legacy-compat branches in resolvers&lt;/a&gt;
— why &lt;code dir=&quot;auto&quot;&gt;ArtifactSurface&lt;/code&gt; is retired rather than kept as an alias.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-06-24-1-kind-and-topology-aware-artifact-placement/&quot;&gt;2026-06-24-1 — Kind- and topology-aware artifact placement&lt;/a&gt;
— the placement model whose labels this ADR renames.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-06-26-1-single-authority-seam-and-call-site-gate/&quot;&gt;2026-06-26-1 — Single-authority seam + call-site gate&lt;/a&gt;
— the seam pattern the missing surface→filesystem translation should eventually follow.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
