Boundaries Before Reuse

Reuse becomes dangerous when the public API carries the first product's worldview. A parameter called quest_slug, a status called published, or an error that says corpus may be harmless locally. Put it in a root package and every future workshop must either pretend those words fit or add translation layers around the abstraction.

The safer seam is capability-shaped. The kernel can know a work item key, a pipeline key, a claim token, required stages, review rounds, and a landing record. It does not need to know whether the item is a quest, an audit, or a release. Concrete layers map their language onto those capabilities at the edge.

Neutral does not mean vague. Generic names still need precise semantics. A work item key is immutable. A claim has one live owner. A required stage is an ordered proof entry, not an arbitrary tag. Removing domain nouns while weakening the contract would produce a reusable interface nobody can reason about.

Error messages are part of the boundary too. Kernel errors should describe violated mechanics; concrete layers may add product context. That separation lets tests assert stable root behavior while the user-facing workshop remains fluent in its own vocabulary.

Run the Vocabulary Audit

Search public types, function names, serialized fields, exceptions, and log event kinds. Highlight every noun borrowed from one product. For each, decide whether it expresses a genuine shared capability or a local metaphor. Rename only the former into neutral, precise language; keep the latter in the adapter.

Reuse starts with a refusal list. Before extracting shared machinery, state what the kernel will never own: domain judgment, destination semantics, and product-specific success criteria. A reusable layer is trustworthy when its exclusions are as crisp as its API.

Code

Map domain vocabulary at the adapter edge·python

from dataclasses import dataclass

@dataclass(frozen=True)
class WorkItem:
    key: str
    state: str

DOMAIN_TO_KERNEL = {"draft": "queued", "in-review": "taken", "published": "landed"}

def adapt(quest_id: str, quest_state: str) -> WorkItem:
    return WorkItem(key=quest_id, state=DOMAIN_TO_KERNEL[quest_state])

assert adapt("sample", "published").state == "landed"

Boundaries Before Reuse