diff --git a/README.md b/README.md index be786e3..2a3d25e 100644 --- a/README.md +++ b/README.md @@ -27,19 +27,19 @@ go run ./cmd/seriatim merge \ - Configuration reference: [docs/config.md](docs/config.md) - Operations guide: [docs/operations.md](docs/operations.md) - Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md) -- Integrations: +- Integration references: - [docs/integrations/whisperx-json.md](docs/integrations/whisperx-json.md) - [docs/integrations/output-schemas.md](docs/integrations/output-schemas.md) -- Development architecture policy: [docs/policy/architecture.md](docs/policy/architecture.md) -- Contributor workflow: [docs/policy/development.md](docs/policy/development.md) -- Documentation policy: [docs/policy/documentation.md](docs/policy/documentation.md) -- Internal implementation docs: +- Development policies: + - [docs/policy/architecture.md](docs/policy/architecture.md) + - [docs/policy/development.md](docs/policy/development.md) + - [docs/policy/documentation.md](docs/policy/documentation.md) +- Internal implementation references: - [docs/internal/pipeline.md](docs/internal/pipeline.md) - [docs/internal/artifacts.md](docs/internal/artifacts.md) - [docs/internal/modules.md](docs/internal/modules.md) -- Public JSON schemas: +- Public JSON schema files: - [schema/minimal-output.schema.json](schema/minimal-output.schema.json) - [schema/intermediate-output.schema.json](schema/intermediate-output.schema.json) - [schema/full-output.schema.json](schema/full-output.schema.json) - Synthetic examples: [examples/README.md](examples/README.md) -- Documentation roadmap: [docs/roadmap/documentation.md](docs/roadmap/documentation.md) diff --git a/docs/cli.md b/docs/cli.md index f8f05c0..162d704 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -179,4 +179,3 @@ go run ./cmd/seriatim normalize \ - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json) - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json) - [../schema/full-output.schema.json](../schema/full-output.schema.json) -- Documentation roadmap: [roadmap/documentation.md](roadmap/documentation.md) diff --git a/docs/config.md b/docs/config.md index b69c658..3a7a21c 100644 --- a/docs/config.md +++ b/docs/config.md @@ -165,4 +165,3 @@ All commands: - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json) - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json) - [../schema/full-output.schema.json](../schema/full-output.schema.json) -- Documentation roadmap: [roadmap/documentation.md](roadmap/documentation.md) diff --git a/docs/internal/artifacts.md b/docs/internal/artifacts.md index f18df28..7956141 100644 --- a/docs/internal/artifacts.md +++ b/docs/internal/artifacts.md @@ -51,37 +51,45 @@ Unknown/empty selection falls back to intermediate conversion. ## Trim internals -`internal/trim` is artifact-level projection, not merge reprocessing. +`internal/trim` handles artifact-level projection and does not execute merge +pipeline modules. -Core flow: +Run layer (`run.go`): -1. Parse selector (`internal/trim/selector.go`). -2. Parse input artifact and detect schema (`ParseArtifactJSON`). -3. Apply keep/remove projection with sequential ID renumbering. -4. Recompute overlap groups only for full-schema artifacts. -5. Optionally convert output schema when supported. -6. Validate output artifact before write. +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`. -Schema-conversion limits: +Apply layer (`apply.go`): -- full -> intermediate/minimal supported. -- intermediate -> minimal supported. -- minimal -> intermediate supported. -- intermediate/minimal -> full is rejected. +- 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 order follows input transcript order. +- retained segment order follows input transcript order. - output IDs are reassigned to `1..N`. -Run layer (`run.go`): - -- executes end-to-end trim orchestration from validated config -- writes output JSON -- optionally writes report JSON with `trim-audit` - ## Normalize internals `internal/normalize` canonicalizes transcript-like JSON input into a selected diff --git a/docs/internal/modules.md b/docs/internal/modules.md index 98b5e21..c62ddae 100644 --- a/docs/internal/modules.md +++ b/docs/internal/modules.md @@ -55,7 +55,8 @@ Output writer: - `autocorrect`: applies YAML replacement rules when configured. - `assign-ids`: assigns final sequential IDs. - `validate-output`: validates selected public artifact shape. -- `json`: writes artifact JSON to `cfg.OutputFile`. +- `json`: writes artifact JSON to `cfg.OutputFile` through shared deterministic + JSON file writing. Filesystem side effects are limited to: diff --git a/docs/roadmap/audit.md b/docs/roadmap/audit.md index f5c55d8..523b15d 100644 --- a/docs/roadmap/audit.md +++ b/docs/roadmap/audit.md @@ -28,7 +28,7 @@ Reviewed documentation and policy: - `docs/internal/modules.md` - `docs/integrations/output-schemas.md` - `docs/integrations/whisperx-json.md` -- `docs/roadmap/documentation.md` +- `docs/roadmap/cleanup.md` Reviewed implementation areas: