Vocabulary pass, layer 2 + Dataset & Releases (DISCUSSION FIRST — do not implement)

[JArmandoAnaya]

Audited 2026-08-16 at f31653d: description updated to match HEAD. All four questions are
still open and still accurate; three file citations had gone stale and are corrected below.
The DISCUSSION FIRST banner in the title still governs.

Motivation

Layer 1 of the vocabulary pass (#292) was mechanical work: raw kernel identifiers were replaced by existing or obvious labels, and the Versions tab was renamed. What remains is not mechanical. It renames concepts — promote, partition, trunk, manifest — whose current words are the kernel's own, it redesigns an error surface, and it merges two navigation destinations. Each of those needs a decision before any code is written, so this issue exists for tracking and discussion only.

Do not implement from this issue. Every item below needs a founder decision first.

Open questions

1. Promote, partition, trunk and manifest as user-facing copy. These words appear in user-facing prose in BatchesScreen.tsx, BatchLifecycle.tsx and DatasetScreen.tsx, and they are simultaneously the kernel's exact vocabulary. (Citation corrected 2026-08-16: the approve dialog is no longer its own ApproveDialog file — it lives in frontend/ui-core/src/screens/BatchLifecycle.tsx, whose approve step is reached by approve-go-schema at BatchLifecycle.tsx:285.) The same-sentence rule — a refusal and the screen describing it share their wording — is load-bearing here. Renaming them for users means either a translation layer that must never drift, or accepting the kernel's words as the product's words. Which of the two?

2. Error codes used as headings. patterns/AsyncStates.tsx:116 renders the machine-readable code as the error heading, so a user sees a title reading "SCHEMA_NOT_FOUND". This is a design decision rather than a bug: the code is what a bug report should quote and what a client branches on. If it changes, the redesign has to keep the code visible somewhere a reader can copy it from.

3. Renaming the Dataset destination to "Dataset & Releases". (Premise updated 2026-08-05: this question originally read as a merge between the "Versions" tab and the Dataset screen. The IA restructure (IA restructure: Dataset is a tab, Schema history nests, Overview is a dashboard #310) removed the Versions tab — schema history now nests inside the Schema tab, ?tab=versions redirects there, and the information-architecture skill states the ledger/reader division.) What remains is the split between the Schema tab and the Dataset tab: schema versioning lives entirely inside Schema, while releases — the thing a version is eventually exported as — live under Dataset. The narrowed question is whether the Dataset destination is renamed "Dataset & Releases" to say so.

   Citations corrected 2026-08-16. Renaming touches roughly six sites (frontend/ui-core/src/screens/dataset.test.tsx, frontend/ui-core/src/screens/navigation.test.tsx, frontend/app/e2e/shell.spec.ts, frontend/app/e2e/navigation.spec.ts, plus the route and parent-label sites). The rail's pinned-destination contract is three links, not two, and now sits at frontend/app/e2e/shell.spec.ts:176-189 — the assertion is toHaveCount(3) at :183, Inference having become a top-level destination since this was filed. Nothing in this question depends on the count; the citation is corrected so a pickup does not go looking at :157 for a two-link rule that no longer exists.

4. Inline schema creation from the approve dialog, deferred out of the work that humanized SCHEMA_NOT_FOUND in that dialog (Humanize SCHEMA_NOT_FOUND in the approve dialog #291). Should the dialog offer creating version 1 in place, or is the link out to the schema tab (approve-go-schema) the right scope forever? Still a link out at HEAD.

Exit criteria

A decision comment per question, then implementation issues filed for whatever survives.

Original description, as it stood before the 2026-08-16 audit

Motivation

Layer 1 of the vocabulary pass (#292) was mechanical work: raw kernel identifiers were replaced by existing or obvious labels, and the Versions tab was renamed. What remains is not mechanical. It renames concepts — promote, partition, trunk, manifest — whose current words are the kernel's own, it redesigns an error surface, and it merges two navigation destinations. Each of those needs a decision before any code is written, so this issue exists for tracking and discussion only.

Do not implement from this issue. Every item below needs a founder decision first.

Open questions

1. Promote, partition, trunk and manifest as user-facing copy. These words appear in user-facing prose in BatchesScreen, ApproveDialog and DatasetScreen, and they are simultaneously the kernel's exact vocabulary. The same-sentence rule — a refusal and the screen describing it share their wording — is load-bearing here. Renaming them for users means either a translation layer that must never drift, or accepting the kernel's words as the product's words. Which of the two?

2. Error codes used as headings. patterns/AsyncStates.tsx:116 renders the machine-readable code as the error heading, so a user sees a title reading "SCHEMA_NOT_FOUND". This is a design decision rather than a bug: the code is what a bug report should quote and what a client branches on. If it changes, the redesign has to keep the code visible somewhere a reader can copy it from.

3. Renaming the Dataset destination to "Dataset & Releases". (Premise updated 2026-08-05: this question originally read as a merge between the "Versions" tab and the Dataset screen. The IA restructure (IA restructure: Dataset is a tab, Schema history nests, Overview is a dashboard #310) removed the Versions tab — schema history now nests inside the Schema tab, ?tab=versions redirects there, and the information-architecture skill states the ledger/reader division. The split is therefore no longer Versions against Dataset.) What remains is the split between the Schema tab and the Dataset tab: schema versioning lives entirely inside Schema, while releases — the thing a version is eventually exported as — live under Dataset. The narrowed question is whether the Dataset destination is renamed "Dataset & Releases" to say so, now that nothing about schema versions competes for the name. Renaming touches roughly six test files (dataset.test.tsx, navigation.test.tsx, shell.spec.ts, navigation.spec.ts, plus the route and parent-label sites) and the left rail's pinned two-link contract at shell.spec.ts:157.

4. Inline schema creation from the approve dialog, deferred out of the work that humanized SCHEMA_NOT_FOUND in that dialog (Humanize SCHEMA_NOT_FOUND in the approve dialog #291). Should the dialog offer creating version 1 in place, or is the link out to the schema tab the right scope forever?

Exit criteria

A decision comment per question, then implementation issues filed for whatever survives.

[JArmandoAnaya]

Q3's premise updated, and the milestone removed, following the 2026-08-05 backlog audit.

Q3 was written against a world that still had a "Versions" tab in it. The IA restructure (#310, landed as 92337cf) removed that tab: schema history now nests below the Schema editor, ?tab=versions redirects through resolveProjectTab, and the information-architecture skill states the ledger/reader division outright. Q3 has been rewritten to the split that actually remains — Schema tab against Dataset tab — and narrowed to the rename alone. Its stale citation is corrected in the same edit: the rail's two-link assertion sits at shell.spec.ts:157, not :153.

Q1, Q2 and Q4 were re-verified at HEAD 47dc1f0 and are accurate as written. The kernel's vocabulary is still in user-facing prose, AsyncStates.tsx:116-118 still renders code as the heading, and the approve dialog still links out to the schema tab through approve-go-schema rather than creating version 1 in place. All three are untouched.

The milestone has been removed and Journey navigation closed. This was the last open issue in that milestone, and the issue is discussion-only by its own first line — holding a milestone open on a ticket that must not be implemented from measures nothing.

[JArmandoAnaya]

Milestoned 0.1.0 per the default rule (Armando, 2026-08-07): everything lands in 0.1.0 unless explicitly moved.

The DISCUSSION FIRST banner in the title still governs — milestone membership does not make this issue implementable.

[JArmandoAnaya]

Decision (Armando, 2026-08-16): the four words are settled one at a time, and without a
translation layer. trunk leaves user-facing copy for "the dataset"; promote stays; the approve
dialog's Partition field label is replaced with plainer wording; manifest stays where it names
a file a person downloads. Kernel identifiers, test ids and code comments are untouched.

The premise this question was filed under — that renaming means either a translation layer that
must never drift, or accepting the kernel's words as the product's — does not hold at HEAD
3919f55. Of the four, only manifest reaches a person inside a refusal:
frontend/ui-core/src/data/refusals.ts:76 spells UNSERIALIZABLE_MANIFEST as "This release's
manifest cannot be read back", and src/visionset/kernel/services/release_service.py:715 raises
"is not a readable manifest". The refusal map contains no occurrence of promote, partition or
trunk, and the four InvalidPartition refusals in
src/visionset/kernel/domain/partition.py:95-109 are written in segment, job and asset terms
without ever using the word "partition". The strategy that raises them, BySegments, is not
offered in the approve form at all — the form gives "One job for the whole batch" and "Jobs of N
assets". There is no coupled sentence for a rename to drift away from, so the same-sentence rule is
not load-bearing on three of the four words.

What the audit did find is a shipped inconsistency rather than a hypothetical cost. PromoteButton.tsx
already calls the destination "the dataset" three times — "Promoted N assets to the dataset",
"Already in the dataset — nothing new to promote", "N of M in the dataset" — while
DatasetScreen.tsx calls the same collection "the trunk" in five places and OverviewPanel.tsx:257
labels its stat "assets promoted to the trunk". Both spellings are in front of users today. This
picks the one already in the majority, and the one a person arrives already knowing.

promote stays because it is ordinary English for what it does, and because it is simultaneously
the capability key BATCH_ACTION.promote and the activity kind batch_promoted — renaming the copy
alone would open exactly the gap between machine word and human word this question was worried
about, for no gain. manifest stays because it names an artifact a person downloads and can open.

Most occurrences of all four words are in docstrings and comments, which are read by whoever
maintains the file and keep the kernel's vocabulary.

The work that follows is a copy edit rather than an architecture, and it is filed as the change
removing trunk from user-facing prose (#631).

[JArmandoAnaya]

Decision (Armando, 2026-08-16): an error leads with its sentence, and the machine-readable code
moves to the mono meta line beside the incident id. The code stays on screen and stays selectable —
it stops being the title.

At HEAD 3919f55 three call sites pass code into ErrorState: the shared async wrapper at
frontend/ui-core/src/data/Async.tsx:76, the schema panel at screens/ProjectScreen.tsx:830, and
the annotator at annotator/AnnotationPage.tsx:617. Because Async is the wrapper every list and
detail read goes through, the raw identifier is not confined to one screen. Every other caller
already omits code and passes refusalProse(...) as the message, so this brings three outliers
into line with the majority rather than inventing a shape.

The place to put the code already exists. patterns/AsyncStates.tsx:122-124 renders
Incident {incidentId} in font-mono text-meta, and the code belongs on that line for the same
reason the incident id does: it is what a report quotes. The same three sites also pass the
server's raw message rather than refusalProse(...), which skips the one vocabulary
data/refusals.ts exists to hold, and that goes with the change.

Filed as the error-heading redesign (#632).

[JArmandoAnaya]

Decision (Armando, 2026-08-16): the Dataset tab keeps its name. It is not renamed to "Dataset &
Releases", and nothing is filed from this question.

The tab bar is four single words carrying icons — Overview, Schema, Batches, Dataset (TAB_LABELS
in frontend/ui-core/src/screens/ProjectScreen.tsx:195-200), declared in the order the work
happens in. A two-noun label admits the destination holds two things, and where a screen genuinely
reads that way the answer is a section heading inside it rather than a longer word in the bar. The
sitemap in the information-architecture skill already records the tab as the trunk and its
releases, so the fact is written down where somebody building navigation looks for it. The rename
would have touched roughly six sites including two end-to-end specs, and it would have added no
information the screen does not already carry.