Output Contract v1

Single source of truth for TranscriptX analysis output layout, naming, manifest schemas, and speaker-exclusion rules. Implementation: output_standards.py, manifest_builder.py, run_manifest.py, run_schema.py.

Authority boundary:

• This contract defines what files and directories exist after a run and how they are named and organized.

• It also defines the JSON structure for manifests and related output files.

• It does not define success/failure or run/module statuses, nor any truth about whether a run “succeeded” or “failed”; those are owned exclusively by docs/run_outcome_contract.md.

1. Directory layout

• Root: TRANSCRIPTX_OUTPUT_DIR (default {DATA_DIR}/outputs).

• Run root: outputs/<slug>/<run_id>/ where:

  • slug is the human-friendly folder name from the slug manager (derived from transcript identity).

  • run_id is YYYYMMDD_HHMMSS_<8-char-uuid> (or overridden via RunManifestInput.run_id).

• Per run: At run root:

  • manifest.json — artifact index (see §4).

  • run_results.json — run summary (schema in run_schema.RunResultsSummary).

  • report.json / report.md / report.txt — run-level report projections generated by supported reporting modules (when enabled in the run profile).

  • .transcriptx/manifest.json — run manifest for reproducibility (manifest_type: "run_manifest").

  • .transcriptx/run_config_effective.json — effective config snapshot.

• Per module: <run_root>/<module_name>/ with standard subdirs:

  • data/global/ — global (all-speaker) data files.

  • data/speakers/ — per-speaker data (when applicable).

  • charts/ (or charts/global/, charts/speakers/) — chart outputs.

• Versioned namespaces: Modules that need a stable contract use <run_root>/<namespace>/<version>/ (e.g. voice/v1/). See ModuleInfo.output_namespace and output_version.

2. Naming rules

• Canonical base name: From _path_core.get_canonical_base_name(transcript_path) (used for run dir and file prefixes).

• File prefixes: Module artifacts use the canonical base name where applicable; e.g. {base_name}_{module}_{descriptor}.{ext} or as defined by create_standard_output_structure() and helpers in output_standards.py.

• Manifest and run summary: manifest.json and run_results.json at run root only.

3. Required artifacts and scope

• Per-module: Modules use create_standard_output_structure() and the helpers (save_global_data, save_speaker_data, save_global_chart, etc.) so paths stay consistent.

• Global vs per-speaker: Unidentified speakers (e.g. SPEAKER_00) are excluded from per-speaker outputs when exclude_unidentified_from_speaker_charts (or equivalent) is true. Exceptions: transcript/CSV output and NER include all speakers.

• NER: May use a distinct path for entity maps (e.g. ner/maps/ or ner/{base}_ner-entities.json); see module implementation.

4. Manifest schemas

4.1 Artifact manifest (manifest.json at run root)

• Discriminator: manifest_type: "artifact_manifest" (required in new manifests; backward compat accepts missing as artifact).

• Required keys: schema_version, run_id, run_metadata, artifacts.

• run_metadata: Includes transcript_key, modules_enabled, version_hash, config_effective_path, config_hash, config_schema_version, config_source.

• artifacts: List of entries with id, kind, rel_path, mime, tags; optional module, scope, speaker. Load via load_artifact_manifest(path); do not raw json.load() and guess type.

4.2 Run manifest (.transcriptx/manifest.json)

• Discriminator: manifest_type: "run_manifest".

• Used for reproducibility. Load via load_run_manifest(path).

4.3 Run results (run_results.json)

• Current: schema_version: 1 — includes module_outcomes (canonical execution rows) and modules_skipped[] entries with optional execution_status (skipped | blocked). Pre-epoch schema_version values are refused; strict loaders use transcriptx.core.pipeline.module_outcomes.assert_run_results_schema_supported.

• Typed load path: transcriptx.core.pipeline.manifest_loader.load_run_results rejects non-epoch-1 schema_version via assert_run_results_schema_supported before applying any default-filling for missing keys. Use that loader (or load_run_outcome_context) rather than raw json.load for truth-path consumption.

• Semantics: Placement and schema shape for run_results.json live here; status meanings, precedence, and truth rules live in docs/run_outcome_contract.md.

5. Speaker exclusion (unidentified)

• Default: Unidentified speakers (e.g. SPEAKER_00) are excluded from per-speaker charts and per-speaker data when config says so (analysis.exclude_unidentified_from_speaker_charts or equivalent).

• Included: Transcript output, CSV export, and NER entity lists include all speakers (including unidentified).

• Predicate: is_named_speaker() in text_utils (or equivalent) determines eligibility for per-speaker outputs.

6. Schema stamps (transcript JSON)

• Speaker mapping: After any mapping write, transcript JSON must include:

  • speaker_map_schema_version (integer 1).

  • speaker_map_provenance (tool, version, timestamp, method) when written via SpeakerMappingService / TranscriptStore.

7. Exceptions and versioning

• NER: Path variance allowed for entity maps; see NER module.

• Voice: Versioned namespace voice/v1/ (and possible voice/v2/ later).

• Stability (v0.41+): Do not rename output folders or top-level layout without versioning. Prefer versioned namespaces for new layouts.

---

Contract violations

This section describes output contract violations related to layout and manifest structure. Execution truth and run outcome semantics remain the responsibility of docs/run_outcome_contract.md.

• Invalid states (examples):

  • manifest.json entries whose rel_path does not exist on disk or lives outside the expected run root.

  • Artifacts written to ad hoc paths that do not follow the standard layout, versioned namespaces, or naming rules in this contract.

  • Multiple artifacts that claim the same identity or path in ways that conflict with manifest uniqueness assumptions.

  • run_results.json present at locations other than the run root, or missing entirely when other run artifacts exist.

• Detection:

  • Loaders and helpers that validate manifest schemas and run directory layout.

  • Tests that assert that module outputs are registered in manifest.json with consistent rel_path, kind, and mime fields.

  • Sanity checks that the run root contains exactly one manifest.json and one run_results.json.

• Expected behavior:

  • Violations are treated as fail-fast for contract-aware tools: reject invalid manifests or layouts, log clear errors, and avoid guessing about artifact meaning.

  • Where possible, maintenance tools may offer migration or cleanup commands that repair outdated layouts, but they must not silently reinterpret invalid structures as valid.

---

This document supersedes output_conventions.md as the authority for output layout and contracts. Keep output_conventions.md for backward reference or redirect to this file.