📐fish-annotation-contract

The groupant beside tools/fish/src/annotation.rs in the Mova repository: what the code computes, what it never does, how to go back from its outputs, its invariants, cost and checks.

Facts

Components

Obernants

The typed relations around the forward model: the behaviour complement (what the code never does), the reverse reconstruction (every input compatible with an output) and specialised views.

Model text

descriptant

Fish annotation specialization

This source implements native bounded syntax/pragmatic preparation and separate review/admission artifacts. The public default is Sonnet (2026-11-04; Haiku before); explicit Haiku and Terra/Sol deployment profiles and existing legacy runtime remain separate. Seven local tests are finite software evidence; no teacher/training/model/corpus call ran.

2026-11-01 follow-up: raw policy fields must equal the semantic enum's serialized surface. A compiled baseline fixture demonstrated that trimming-only validation admitted padded character voice without speaker/scope findings. Exact roundtrip rejection now closes that mismatch while preserving source hashes and opaque provenance. Canonical, Unicode, case/alias and missing-speaker controls are finite evidence; shared parser/legacy worker compatibility remains separate.

On 2026-11-02 an actual bounded worker-log review found registry failures collapsed into one generic message. The native reason vector now survives through a bounded, lemma-redacted diagnostic with sentence ordinal, token ID and UPOS. Admission and quarantine predicates are unchanged; ambiguous semantics, unsupported multiword-token representation and escaped transport remain separate failures. No deployment or automatic replay follows from this source change.

model

Fish syntax/pragmatics contract

forward

Domain: schema1 source-bound windows with 1–16 context lines, 1–8 targets, 2–4 versioned candidate producers and bounded native witness rows. Observation: errors, findings, prepared model request and optional GPU-admission candidate. Evaluate binds task/context/candidate/witness hashes, source ids/text, compiled agreement code revision and actual native implementation/data hashes. Six pragmatic surfaces must exactly equal their parsed enum serialization; permissive shared-parser trimming does not widen this admission domain. It reuses en::conllu::Doc::parse, en::convert::tree_gate, en::udreg::Registry, prag::schema and prag::agree::run. No model or trainer is invoked.

composition

The same pragmatic agreer is used by cycle::prag_reading. Native structural and UD registry gates do not duplicate every treeagree rule; the existing full treeagree and reviewed-source/split/provenance/heldout gates remain downstream. Public default Sonnet preparation, explicit Haiku, and explicit deployment Terra/Sol overrides are separate from legacy controller behavior. No automatic migration, fallback or promotion of a teacher report to gold.

invariant

Every target's source id/text and source characters apart from whitespace are preserved. An admitted six-label surface s satisfies encode(decode(s))=s; raw context comparisons therefore consume the same spelling as the admitted enum. No label or opaque provenance byte is rewritten. All candidate rows are retained in teacher context; disagreements are findings, not silent corrections. Unknown window context, speaker/referent gaps, witness conflict, changed native labels or nonteaching phase prevent queue eligibility. GPU candidates always have training_authorized=false and teacher_answer_used=false. A teacher request exists independently of admission eligibility for a valid bounded request.

cost

Let B be input bytes <=512KiB, T<=8 targets, C<=4 candidates, and n<=256 words per target. Native parse/registry work scales with source rows, native structural gate has its own graph walk, and agreement/table operations use bounded ordered maps. Request rendering serializes task plus native evidence and rejects when final UTF8 text exceeds100000bytes. Bound checking is not a throughput claim; partial output after I/O error remains possible.

descriptant (model)

Fish have an annotation-specific path. Distinct producer names and context observations are declarations, not proof of independence or correct semantics. A declared whole-document hash does not rehash an unseen document. Morphosyntax and simple pragmatic consistency remain narrower than general understanding. No universal executor or numeric approximation percentage is claimed.

behavior_complement

Within the declared domain, invalid source/version/hash/id/tree/TSV states cannot publish a prepared output directory. Well-formed disagreement, unknown context or evaluation phase cannot publish a GPU-admission candidate. Oversize final request cannot truncate or switch models. These are inner bounds on excluded outputs, not an exhaustive natural-language error model. Counterexample to complete semantic coverage: matching candidate trees can share the same incorrect analysis. Evidence: source-derived gates and seven finite unit/fixture tests.

reverse_reconstruction

Given an evaluation/request hash, compatible antecedents include all tasks whose canonical serialized identity and native outputs satisfy the gates. Producer independence, full document contents and a model's hidden reasoning cannot be recovered from artifact hashes. Equal final labels can arise from several native rule paths, whose agreement report is retained. No unique inverse is claimed. Evidence: source relation and deterministic repeated native evaluation, not an injectivity theorem.

source_character_binding

Domain: plain word rows with exactly one source id/text anchor. Necessary admitted alignment is concatenate(forms)=remove_whitespace(source_text). A changed token while comments remain unchanged is excluded, even with a freshly recomputed candidate digest. This does not establish unique token boundaries or accommodate every UD multiword convention. Counterexample to hash-only grounding: a new hash authenticates changed token bytes but not their agreement with the source text. Evidence: focused wrong-token and wrong-context controls.

disagreement_partition

Let A_j(t) be producer j's ten-column word rows and P_j(t) its six pragmatic labels. Syntax disagreement is any A_j!=A_0; pragmatic disagreement is any P_j!=P_0. Witness act disagreement/conflict and native written-rule changes are additional independent findings, not erased by majority. Any finding blocks eligibility. Counterexample: two matching candidates do not override a conflicting open witness. Evidence: native candidate, witness, speaker/referent and phase fixtures; statistical independence remains an assumption.

rendered_budget

For chosen profile p, define R=EnglishWrapper+JSON(task)+JSON(native_evaluation)+EndWrapper. Admission to request publication requires |UTF8(R)|<=100000. The chosen family/model is embedded in executable argv, with no fallback. Exact100000-byte payload passes; adding a two-byte character fails. Hidden terminal history is outside this measurement. Evidence: exact boundary plus multibyte overflow fixture; no actual transport/model execution.

training_admission_separation

For valid task t, let F(t) be findings. Eligible(t) iff dataset_use=teaching and F(t)=empty. Eligible produces only an external candidate artifact with native agreed bytes and training_authorized=false. It is not a reviewed-source training allowlist. Unknown/nonteaching/disagreement yields teacher-review request and evaluation without a GPU candidate. Counterexample to teacher-as-gold: no teacher answer is even an input to this preparation. Evidence: separate-artifact fixtures and source inspection; downstream authorization remains unexecuted.

context_exclusion

Bounded context observations carry speaker, explicit pronoun referents, grammatical negation and narration/direct-speech scope. Unknowns anywhere in the window prevent admission. Character voice needs a speaker; declared scope is compared with labels; negative-marker conflict and missing pronoun maps remain review findings. Negation is not evaluation polarity, and pronouns do not imply species or physical traits. Counterexample to universal coverage: unmarked irony or a falsely declared resolved referent may pass. Evidence: finite conservative controls, not a general semantic guarantee.

label_surface_admission

Domain: the six raw form/act/indirect/hedge/polarity/voice fields of a bound pragmatic row; opaque provenance is outside this projection. Let D be the shared parser and E its canonical six-field serializer. Fish admits s only when D(s) exists and E(D(s))=s. Excluded raw surfaces include padded, case-altered or aliased spellings even if a future permissive D accepts them. For admitted s, any current exact-string policy P sees P(s)=P(E(D(s))); this does not prove the policy's semantic adequacy. Counterexample on the unmodified baseline: both candidates use voice « character » with narrator scope and no speaker, fresh valid hashes and otherwise valid fixtures. D trims it to Character, but raw voice tests miss both exclusions; executed red control reported findings=[] and eligible_for_gpu_admission_queue=true. The new canonical roundtrip rejects it before agreement/admission without rewriting data. Canonical character still retains missing-speaker/scope findings; canonical declared direct speech with a bound speaker remains admissible. Current native enum parsers are case-sensitive literal matches, with trimming in parse_labels; the roundtrip also excludes future aliases independently of trimming. Evidence: baseline red exit101, fixed green, 24 ASCII/Unicode padded-field controls, 12 case/alias controls and canonical/provenance controls; these are finite checks plus source-derived necessity, not universal language understanding. Compatibility narrows only Fish annotation preparation; shared schema parser, teacher/provenance bytes and legacy runtime are unchanged.

reply_binding_and_context

Domain: a strict AnnotationDraft returned to a valid native Task and its current Evaluation. Observation: schema rejection or review-only source/native comparison. For task t and draft d, require d.task_id=t.id and d.task_sha256=SHA256(typed_JSON(t)); required fields cannot be omitted and unknown fields cannot add authority. Let A(d) and P(d) be the native parsed target AST and six-label tables. Admit their structural comparison only if keys(A)=keys(P)=target_ids(t), source characters and source id/text are preserved, tree/registry checks hold, and P uses exact enum surfaces. No numerical error allowance applies to these categorical gates.

For every original candidate j retain the predicates A(d)!=A(j) and P(d)!=P(j). To reuse native contextual checks, construct a local two-observation evaluation with d first and the original first candidate second; its synthetic identity is not a real model-revision or independence assertion. Keep that evaluation's findings separately from the original input findings. Character voice without a speaker, altered scope, missing referents and negative-marker conflicts therefore remain visible even when introduced only by the draft. Return unresolved strings unchanged. No GPU candidate or trainer authorization is generated by this validation function.

Counterexamples: a reply can pass all native structural checks and still choose the wrong attachment; a narrator input followed by a canonical character draft can be structurally valid while adding speaker/scope findings. These are review outcomes, not semantic success. Evidence: focused fake-envelope, wrong token, missing target, padded label, stale task hash, unknown field and reply-only character-context controls. Finite observations and source-derived relations, no semantic completeness proof.

structured_transport_budget

Domain: source-bound rendered profiles and strict annotation replies. Claude CLI argv carries a JSON Schema with exact task-id/hash constants, no extra properties, all required fields and explicit scalar/cardinality limits. Define B=|UTF8(stdin)|+|UTF8(schema_argument)| for that transport (schema bytes zero without that argument). Require B<=100000 before publication/launch; rendered_utf8_bytes still measures exact stdin alone. This refines the earlier prompt-only rendered_budget model. Native annotation limits remain byte limits; JSON Schema maxLength is a character limit and is insufficient by itself. Concise unresolved observations are requested at <=480 bytes; native validation still refuses >512 bytes or >32 entries without truncation.

Counterexample: 257 instances of a two-byte character satisfy a 512-character schema bound but exceed 512 native bytes. A Markdown-fenced result may contain valid JSON without being an admitted strict result string. Official structured_output avoids relying on textual repair. Evidence: combined-budget/multibyte controls, bound schema constants and structured/native observation regression; no universal provider-conformance proof.

registry_diagnostic_projection

Type: error_partition. Subject: the native trees registry-failure branch, after the unchanged source-anchor, character, plain-word, tree, UPOS/FEATS/relation gates. Domain: source-bound plain-word AST rows admitted by those preceding gates. For row r, let V(r) be the ordered Registry::check reason vector. Rejection remains exactly V(r) != []; the first failing row still stops validation. A successful AST and every earlier error branch retain their prior behavior. This is an error-observation refinement, not additional inference or an automatic annotation correction.

The failure observation includes one-based sentence ordinal, numeric token ID, parsed UPOS, |V(r)|, and a projection Q(V): take the first three reasons in native order, replace their quoted lemma with [redacted], retain at most 96 Unicode scalars per reason, join with semicolons, and explicitly mark when further reasons are omitted. Source sentence ID, source text, token form and lemma are not echoed. At most three projected reason bodies contribute 1152 UTF-8 bytes; the numeric/enum envelope is separately bounded by the admitted plain-word domain. Existing registry English reason templates and parsers are assumptions. The source fixture verifies the resulting diagnostic stays below 1400 bytes even with a long multibyte lemma; that finite check is not a general log-system theorem.

Counterexample to the previous observation: two rejected NOUN feature assignments, Tense=Past and VerbForm=Part, were indistinguishable from a disallowed AUX lemma because all produced only UD registry violation. The new message retains the native reason partition without accepting either AST. Q is intentionally many-to-one: redacted lemmas, omitted later reasons and different source sentences can share one diagnostic. It does not reconstruct the original AST or establish that another suggested parse is correct. Native structural validity remains distinct from semantic correctness and training authority. A registry rejection describes compatibility with Mova's current imported registry, not a universal grammar or standard-UD error. In particular, standard multiword-token representations remain outside the existing Fish plain-word domain; this diagnostic change neither admits them nor labels their linguistic analysis incorrect.

Evidence: two focused native tests cover valid input, two-feature rejection, four-reason cardinality/omission, lemma redaction and a long Unicode lemma. Restoring the original native gate while retaining those tests fails their assertions; exact source restoration then passes. The complete local Fish crate checks the unchanged strict reply/transport/admission paths with fake executables. Existing deployed binaries and historical attempts retain their original pinned implementation; upgrading requires a separate compatible deployment boundary. No model, corpus assessment, DB import or trainer was invoked for this change.

Cost: Registry::check already materializes V. The error branch adds a quoted-lemma allocation and at most three reason redaction scans, O(|lemma| + sum of selected reason bytes), followed by bounded diagnostic emission. Successful rows do not allocate the diagnostic. No measured annotation throughput or reduction in quarantine frequency is claimed.

model_default

Family::default() = Sonnet, so a profile with no family renders model sonnet through the claude provider; Haiku and Terra stay explicit. Changing the serde default changes only absent-field interpretation; explicit profiles render identically. Checked by the default/haiku/terra render fixtures (2026-11-04).

tests

Focused checks

Seven local tests pass, including six annotation-contract tests and the preserved legacy guard test. Native evaluate and rendered contract are deterministic; source/tree/hash/producer/version errors reject, disagreement/context/witness/speaker/referent gaps stay visible, queue and review artifacts stay distinct, and exact100000 UTF8 bytes pass while a multibyte overflow fails. CLI contract metadata is byte-identical in two fresh processes. Fake/local fixtures do not establish semantic accuracy, full treeagree equivalence or transport behavior.

2026-11-01 surface-admission regression: original test-only augmented baseline failed as expected (exit101) with findings=[] and GPU-admission-candidate eligibility=true for padded character voice. The same test passes after exact enum-roundtrip admission. All ten crate tests pass offline/locked with two jobs, including 24 ASCII/NBSP/EM-space/narrow-NBSP padded-field controls, 12 case/alias controls, opaque-provenance preservation, canonical character without speaker and canonical declared direct speech with a bound speaker. No teacher/model/training/DB/corpus/runtime call. Historical seven-test evidence above remains dated evidence, not the current total. 2026-11-02: 14 library tests plus the preserved legacy guard test pass offline/locked with two jobs. New fake-CLI checks cover exact stdin and safe/medium argv, strict schema, stale task hash, changed source, missing target, canonical labels, new reply-context findings, unresolved retention, declared-evaluation/deadline/oversize nonlaunch, Unknown review with not_teaching retained, durable malformed/timeout outcomes and replay refusal. Exact100000-byte and multibyte-overflow tests remain green. No live model, training, DB or corpus assessment was invoked. These are finite checks, not semantic accuracy, power-loss durability or exactly-once proofs.

2026-11-02 protocol followup:17 library tests plus the legacy guard pass offline/locked j2. Bound Claude JSON Schema and exact schema-plus-stdin100000-byte budget, strict structured/result envelope branches, UTF8-byte/cardinality controls, raw/typed profile pins, reaped plus actual ESRCH process-group observation, and provider/error-envelope partition are checked. Known-closed inner invalid_response is distinct from transport_error/child_failed; no replay, semantic/gold/training promotion or historical pilot artifact mutation. Fake executables only; deployment pilots separate.

2026-11-02 native registry diagnostics: two new tests pass, including unchanged valid-tree admission, precise two-feature reasons, four-reason count with explicit three-reason projection, no source ID/text/form echo, and redaction of a long multibyte AUX lemma with a bounded UTF-8 diagnostic. The original trees implementation with these tests fails assertions (exit 101), not compilation; exact final source restoration is checked. All 19 library tests and the preserved legacy guard test pass offline/locked with two build jobs; fake CLI paths only. No paid model/retry, corpus/held-out run, DB import, training, worker/config restart or historical response edit. The new diagnostic is evidence about the unchanged native rejection, not semantic validation or repaired annotation.

This page in Markdown → https://md.groupants.elamur.ai/free/en/mova/tools/fish/src/annotation.rs.groupant/