155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# Artifact Internals
|
|
|
|
## Purpose
|
|
|
|
Describes public artifact conversion and validation internals for merge output,
|
|
trim, and normalize.
|
|
|
|
## Artifact contracts
|
|
|
|
Public contracts live in `schema/`:
|
|
|
|
- full: `schema.Transcript`
|
|
- intermediate: `schema.IntermediateTranscript`
|
|
- minimal: `schema.MinimalTranscript`
|
|
|
|
Machine-readable schemas:
|
|
|
|
- `schema/full-output.schema.json`
|
|
- `schema/intermediate-output.schema.json`
|
|
- `schema/minimal-output.schema.json`
|
|
|
|
## Schema selection
|
|
|
|
Merge pipeline conversion uses `internal/artifact.SelectedFromMerged`:
|
|
|
|
- `seriatim-full` -> `artifact.FromMerged`
|
|
- `seriatim-intermediate` -> `artifact.IntermediateFromMerged`
|
|
- `seriatim-minimal` -> `artifact.MinimalFromMerged`
|
|
|
|
Unknown/empty selection falls back to intermediate conversion.
|
|
|
|
## Merge conversion behavior
|
|
|
|
`internal/artifact` converts `model.MergedTranscript` to public contracts:
|
|
|
|
- full schema preserves source/provenance, overlap groups, and metadata module
|
|
lists.
|
|
- intermediate schema emits segment timing/text/speaker with optional
|
|
categories and compact metadata.
|
|
- minimal schema emits compact segment timing/text/speaker and compact
|
|
metadata.
|
|
|
|
## Validation behavior
|
|
|
|
`schema/output.go` validates both structure and semantics:
|
|
|
|
- embedded JSON Schema validation via `jsonschema/v6`
|
|
- semantic checks for sequential segment IDs starting at `1`
|
|
- semantic checks for non-inverted segment timing (`end >= start`)
|
|
- full schema overlap-group timing checks (`group.end >= group.start`)
|
|
|
|
## Trim internals
|
|
|
|
`internal/trim` handles artifact-level projection and does not execute merge
|
|
pipeline modules.
|
|
|
|
Run layer (`run.go`):
|
|
|
|
1. Parse selector from validated config.
|
|
2. Read and parse input artifact JSON.
|
|
3. Apply trim projection through schema-aware artifact handling.
|
|
4. Resolve output schema (preserve input schema unless overridden).
|
|
5. Validate output artifact.
|
|
6. Write output JSON.
|
|
7. Optionally write report JSON with `trim-audit`.
|
|
|
|
Apply layer (`apply.go`):
|
|
|
|
- one shared projection policy for selector mode, input ID validation, selected
|
|
ID existence checks, keep/remove filtering, removed IDs, and old-to-new ID
|
|
mappings
|
|
- schema-specific segment reconstruction for full/intermediate/minimal outputs
|
|
- overlap-group recomputation only for full-schema outputs
|
|
|
|
Artifact layer (`artifact.go`):
|
|
|
|
- schema detection for full/intermediate/minimal artifacts
|
|
- schema-preserving trim application
|
|
- supported schema conversions:
|
|
- full -> intermediate/minimal
|
|
- intermediate -> minimal
|
|
- minimal -> intermediate
|
|
- rejected conversion:
|
|
- intermediate/minimal -> full
|
|
|
|
Trim invariants:
|
|
|
|
- selected IDs must exist in input.
|
|
- input IDs must be positive, unique, sequential.
|
|
- retained segment order follows input transcript order.
|
|
- output IDs are reassigned to `1..N`.
|
|
|
|
## Normalize internals
|
|
|
|
`internal/normalize` canonicalizes transcript-like JSON input into a selected
|
|
public schema.
|
|
|
|
Parse layer (`parse.go`):
|
|
|
|
- accepts object-with-`segments` or bare segment array
|
|
- repairs missing timing deterministically
|
|
- swaps inverted timing
|
|
- fills missing/blank speaker with `Unknown_Speaker`
|
|
- drops missing/blank text segments
|
|
|
|
Build layer (`build.go`):
|
|
|
|
- sorts deterministically by `(start, end, input_index, speaker)`
|
|
- reassigns output IDs sequentially
|
|
- builds minimal/intermediate/full output shape
|
|
- validates selected output schema before write
|
|
|
|
Run layer (`normalize.go`):
|
|
|
|
- writes output JSON
|
|
- optionally writes report with `normalize-audit`
|
|
|
|
Normalize invariant:
|
|
|
|
- report events do not embed transcript text.
|
|
|
|
## Boundaries
|
|
|
|
- CLI flag semantics belong to `docs/cli.md`.
|
|
- Runtime config/env surfaces belong to `docs/config.md`.
|
|
- This doc describes internal conversion/validation behavior only.
|
|
|
|
## Failure behavior
|
|
|
|
Representative failure classes:
|
|
|
|
- malformed or unsupported input JSON shape
|
|
- schema validation failure for parsed artifact or built output
|
|
- unsupported schema conversion path (trim)
|
|
- selector or input-ID consistency errors (trim)
|
|
- output/report file write failures from command paths
|
|
|
|
## Tests to inspect before changes
|
|
|
|
- `schema/output_test.go`
|
|
- `internal/artifact/transcript_test.go`
|
|
- `internal/trim/selector_test.go`
|
|
- `internal/trim/artifact_test.go`
|
|
- `internal/trim/apply_test.go`
|
|
- `internal/normalize/parse_test.go`
|
|
- `internal/cli/trim_test.go`
|
|
- `internal/cli/normalize_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Public artifacts are validated through `schema` before acceptance.
|
|
- Segment IDs in emitted artifacts are sequential and deterministic.
|
|
- Internal-only fields are not emitted in minimal/intermediate contracts.
|
|
- Trim and normalize stay artifact-level and do not execute merge modules.
|