N'Ko Speech Inscription Bridge v0

N'Ko Speech Inscription Bridge v0

Created: 2026-06-04
Status: Active implementation spec

Purpose

The live mic harness must not display unstable CTC output as if it were language. A live or recorded run now has to compile into a governed speech inscription packet:

audio evidence
  -> transcript decision
  -> acoustic/FAC claim scaffold
  -> controlled N'Ko proof rendering

This follows the CC Inscriptions invariant:

Evidence -> typed claim IR -> controlled N'Ko surface -> proof scaffold

The N'Ko surface is not the source of truth. The typed decision and archived evidence are.

Source Invariants

• IR primacy: the transcript decision is authoritative; the rendered N'Ko line is a surface.
• Controlled register: this is not natural-language N'Ko prose and not translation.
• Determinism: same archived audio/logits/argmax/config must reproduce the same decision.
• Provenance: each decision points back to captured audio, prepared audio, logits, argmax, file hashes, and manifest sidecar hash.
• Non-retroactivity: once saved, calibration packets are not rewritten. Later models may reinterpret them as derived views.

The public Learn N'Ko technical docs describe the same chain as evidence, IR, surface, and proof scaffold. The NIP docs frame evidence admissibility, deterministic commitment, limits of translation, and human feedback as constitutional concerns. Speech v0 is an application of those laws to audio.

v0 Packet

Each speech calibration directory is the local evidence archive:

Documents/NKOLiveCalibration/<id>/
  captured_audio_16k_f32.bin
  prepared_audio_16k_f32.bin
  head_logits_f32.bin
  head_argmax_i32.bin
  recording.caf               optional
  manifest.json
  manifest.sha256

The manifest schema is `nko_live_calibration_v2`.

The `sourceKind` field separates:

• `live_mic`: microphone capture with optional copied `recording.caf`.
• `recorded_fixture`: bundled real-audio fixture proof.

Required objects:

• `audioEvidenceBundle`: archive reference, sample rate, evidence files, hashes, replay requirements.
• `transcriptDecision`: typed decision and decode statistics.
• `acousticClaimScaffold`: FAC feature slots plus v0 CTC stability/boundary evidence.
• `nkoProofRendering`: controlled proof line shown in the app on rejection.
• `provenanceWitness`: local replay witness with surface hash, detector config hash, archive ref, and manifest sidecar.

Transcript Decisions

Allowed decision states:

accepted_transcript
rejected_unstable
rejected_non_nko
rejected_overfire
rejected_low_audio
needs_label

Interpretation:

• `accepted_transcript`: quality gate passed and corrected/stable text may be shown as transcript.
• `rejected_overfire`: CTC emitted too many nonblank frames or too many scalars.
• `rejected_non_nko`: output contains non-N'Ko scalars.
• `rejected_low_audio`: audio was too short or too quiet to support a transcript decision.
• `rejected_unstable`: audio existed, but stable high-margin N'Ko evidence was insufficient.
• `needs_label`: the run requires human labeling or calibration before it can become training data.

FAC Scaffold

V0 does not claim full articulatory recognition. It reserves the FAC slots and only asserts the evidence that exists:

voicing:       not_implemented_v0
place:         not_implemented_v0
manner:        not_implemented_v0
nasality:      not_implemented_v0
tone:          not_implemented_v0
length:        not_implemented_v0
vowelHeight:   not_implemented_v0
vowelBackness: not_implemented_v0
rounding:      not_implemented_v0
boundary:      observed_v0
ctcStability:  accepted_v0 | rejected_v0

That honesty matters. The current system can evaluate CTC stability and transcript admissibility. It cannot yet infer tone, place, manner, or voicing as independent facts.

Controlled Rendering

Rejected runs render a proof line instead of raw CTC garbage:

ߥ ⟦<evidence-id>⟧ : transcript_decision=<status> ; raw_ctc=<n> ; stable_ctc=<n> ; c=<margin>

This is an inscription diagnostic, not a natural utterance. It says what the system decided about the evidence.

Out of Scope

• Real-time English translation.
• Claiming live Malinke recognition before calibration supports it.
• ANE acceleration proof.
• TurboQuant iPhone latency proof.
• Full FAC model training.

Those are separate proof lanes.

Current Implementation Hook

iOS harness:

/Volumes/HD1/nko_coreml/AnchorHeadDeviceHarness/AnchorHeadDeviceHarness/AnchorHeadDeviceHarnessApp.swift

The bridge is implemented in both speech execution paths:

runLiveAudioPipeline
  -> stabilizeLiveCTC
  -> liveDecodeQuality
  -> TranscriptDecision
  -> saveLiveCalibration
  -> nkoProofRendering

runRealAudioPipeline
  -> full split encoder fixture proof
  -> TranscriptDecision(accepted_transcript | rejected_unstable)
  -> saveLiveCalibration(sourceKind=recorded_fixture)
  -> nkoProofRendering

Verification Gates

• `cc-inscription` tests pass.
• iOS harness builds with `/tmp/NKOFullAppHarnessDD`.
• Overfiring live output shows a typed rejected decision, not raw CTC text.
• Rejected live paths render the controlled proof line and must not output `head.greedyText` or `displayOutput(head.greedyText)`.
• `manifest.json` contains `audioEvidenceBundle`, `transcriptDecision`, `acousticClaimScaffold`, `nkoProofRendering`, and `provenanceWitness`.
• `manifest.sha256` exists beside each saved manifest.
• `validate_speech_inscription_manifest_v0.py` accepts copied-off-device packets only when hashes, decision semantics, FAC placeholders, proof rendering, and provenance witness fields are intact.
• `run_speech_inscription_live_proof.py` can install/launch the harness on a reachable iPhone, copy `Documents/NKOLiveCalibration` from the app data container, and produce a fail-closed live proof summary from the validator.
• The harness also supports `--nko-headless-live-proof`, a devicectl launch argument that records a short live mic sample, runs the same live ASR bridge, and writes a v2 `live_mic` packet without manual UI taps.

Next Stage: Calibration

The next-stage compiler is documented in `SPEECH-CALIBRATION-ACOUSTIC-IMPROVEMENT-V0.md` and implemented by `build_speech_calibration_set_v0.py`. It scans copied `NKOLiveCalibration` packets, reuses this validator, buckets valid packets by transcript decision, joins optional expected labels, and marks each packet as evaluation-ready or training-admissible without treating raw CTC output as a label.