DECISION: which orphan invariant does VisionSet enforce? (active-version vs. per-annotation-version)

[JArmandoAnaya]

This issue is a decision, not a task. Nothing here is implemented, closed, or resolved by an
agent. It exists so the choice is made once, in writing, and everything blocked on it can point at
the answer.

All citations are at e61d3ed.

The finding

The kernel judges annotation writes against Batch.schema_version — the version pinned when the
batch was approved — and never against the project's active version.

src/visionset/kernel/services/annotation_service.py:19-25 states it as a design decision:

The version is the batch's, not the project's. Every write is judged against
Batch.schema_version — pinned at approval and moved only by an explicit BatchService.repin —
so a create_version while annotators are working does not change the rules under them.

The implementation follows it: annotation_service.py:159 reads schema = self._pinned_schema(batch),
_pinned_schema is defined at :339, and _validate at :490 checks annotation.label_class
against schema.classes — the pinned version's classes.

The orphan veto, meanwhile, is computed only against the active version.
src/visionset/kernel/services/schema_service.py:242 diffs the proposal against the active version,
:244 calls _refuse_narrowing, and :276-277 counts annotations project-wide and intersects them
with diff.destructive_classes.

The consequence, as a deterministic sequence

No race. No concurrency. No flag abuse. Reachable from REST, CLI, MCP and the SDK alike.

1. Project has schema v1 declaring car. A batch is approved, so it pins v1.
2. Nobody has labeled car yet. Publish v2 without car, with allow_destructive=True. The orphan
   count for car is 0, so the publish is accepted — correctly, by the check's own terms.
3. An annotator writes an annotation with label_class="car" into the still-open batch. _validate
   reads v1, which declares car. Accepted.
4. The trunk now holds an annotation naming a class the active version does not declare.

Nothing re-detects this afterwards. The veto only ever fires on a diff against the active version at
publish time, so no later publish, promotion, release publish or ReleaseService.verify looks for
it.

The code that already assumes this cannot happen

src/visionset/kernel/services/release_service.py:805-809:

                # A class the manifest's own `classes` does not declare cannot
                # happen — `SchemaChangeWouldOrphan` refuses to remove a class
                # annotations depend on — but a report that dropped a label it
                # could not place would be silently wrong, so it is placed by the
                # geometry it actually carries.

A manifest's classes come from the active version at publish time while each annotation carries
its own pinned schema_version, so the state this comment calls impossible is reachable by the
sequence above and lands in a release manifest. The comment is wrong at HEAD under the implemented
semantics, regardless of which invariant is chosen below — either it describes a guarantee the
kernel does not make, or (under Option A) it describes one the kernel would newly have to enforce.
The defensive branch beneath it is load-bearing today.

The two invariants

Presented as options. Neither is recommended here.

Option A — the active-version invariant (strong)

No annotation may reference a class the active schema version no longer declares.

Publishing a version that removes a class would have to account for open batches pinned to versions
that still declare it — either refusing the publish, or requiring those batches to be closed or
re-pinned first.

• Simpler global reasoning for release and export: the manifest's class list is a complete
  description of what the manifest contains, and release_service.py:805-809 becomes true.
• More restrictive. A publish can be blocked by a batch somebody left open days ago, and the remedy
  is administrative rather than a schema decision.
• Changes what the batch pin means. The pin currently exists so that "a create_version while
  annotators are working does not change the rules under them"
  (annotation_service.py:21-23); under Option A a publish can reach into open batches.

Option B — the per-annotation-version invariant (the one implemented today)

An annotation is valid against its own batch's pin. The trunk may contain classes the active version
no longer declares.

• Releases and exports gate content, and must handle absent-class annotations explicitly —
  declared before writing, never dropped silently, which is the discipline the exporters already
  follow.
• The orphan veto at publish stays, as hygiene for annotations that already exist at the moment
  of the publish. Its value does not depend on this decision.
• Consistent with the ratified G5 formulation — promotion gates membership; releases gate content —
  and with the batch pin model in the batch-lifecycle skill.
• Costs: "which classes does this dataset actually use" stops being answerable from the active schema
  alone, and every consumer of a manifest needs the absent-class path.

What is blocked on this

• The release_service.py:805-809 comment and the branch under it: stale comment, or a guarantee to
  start enforcing.
• The schema class-removal UI flow (cf. UI: schema class-removal flow — three dialogs, contradictory promises, raw API text #588) — its copy has to state which invariant holds.
• Whether SchemaService.create_version must inspect open-batch pins at all.

Not blocked on this: the typed error contract (cf. #587). The orphan veto over already-existing
annotations survives both options, so the refusal's shape can be settled independently — and the
snapshot-isolation defect (cf. #586) is a defect under either reading.

Provenance

Found by a read-only audit of the schema-narrowing / orphan gate at e61d3ed. The audit's full
findings list is in a comment on this issue.

[JArmandoAnaya]

Audit flags (verbatim, for review)

Copied unchanged from the read-only audit of the schema-narrowing / orphan gate at e61d3ed, section 4. This is the durable home for that content; the temporary report file has been deleted.

---

4. Flags for Armando

Findings only. No fixes, no proposals.

1. The invariant the dispatch states and the invariant the kernel implements are different.
   The kernel guarantees per-annotation: "your own recorded version still declares your class",
   which holds trivially (versions immutable, writes validated against the pin). The dispatch asks
   for active-version consistency. The batch pin is a deliberate, documented design choice
   (annotation_service.py:19-25, batch_service.py:392-418) that makes the second unachievable
   without changing what the pin means. This is a domain decision, not a bug fix.

2. release_service.py:804-809 asserts in a comment that an undeclared class "cannot happen"
   and then handles it anyway. The comment is wrong at HEAD (A1). Whether the defensive branch is
   load-bearing or the comment is stale is worth settling; today it is both.

3. SchemaService.preview has one caller in the entire repo (mcp/schemas.py:139) and no REST
   route, despite a docstring written for exactly the surface that lacks it
   (schema_service.py:147-156). SchemaService.compare has a REST route; preview does not.

4. The UI's pre-warning count and the kernel's veto scope agree by coincidence.
   ProjectService.stats (project_service.py:132-150) and
   SchemaService._annotated_classes (schema_service.py:398-413) are two independently written
   N+1 walks over the same set. No test asserts they stay in step. If either is ever narrowed —
   e.g. stats moved onto the curated trunk to match DatasetService.stats — the dialog at
   SchemaEditor.tsx:911-913 starts telling users a removal "costs nothing" for removals that will
   be refused.

5. Case-sensitivity is asymmetric across the two rules. _require_coherent
   (schema_service.py:387-395) folds case to reject Car beside car within one version, while
   _validate (annotation_service.py:506) and diff_classes (schema_diff.py:89-90) match
   case-sensitively across versions. Consistent with the "exact match" doctrine, but it means a
   pure re-casing of a class name is a destructive remove+add.

6. Attribute-level narrowing is refused at class granularity. Removing one optional attribute
   from a class carrying any annotations is unpublishable, because
   diff.destructive_classes is a set of class names (schema_diff.py:66-70) and the veto
   intersects it with a per-class count. Over-strict rather than unsafe, but it likely surfaces as
   "I can never edit this class again" once a project has data.

7. SCHEMA_CHANGE_WOULD_ORPHAN discards structure it already computed. affected and
   annotated[name] at schema_service.py:277-279 are exactly the per-class report a client would
   need; they are interpolated into a sentence and lost. LossyExportNotConsented
   (server/errors.py:473-486) is the in-repo precedent for putting such a report in detail.

8. The CLI and MCP messages leak the project UUID into user-facing prose
   (schema_service.py:281). Not a security issue — the caller already holds the id — but it makes
   the sentence unreadable at a terminal and is the kind of thing cli/_errors.py's _HINTS map
   exists to soften; there is no entry for it.