textflowkit 0.1.6__tar.gz → 0.1.7__tar.gz

textflowkit-0.1.7/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## v0.1.7 — 2026-10-01
+
+The 2026-10-01 audit repair release. Core version: 0.1.7; unchanged optional fonts: 0.1.6. Release artifacts and publication status are recorded on [GitHub Releases](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.7). Local source-candidate verification does not establish installed-package or individual harness compatibility.
+
+### Engineering fixes
+
+- **Confined decoder boundary.** With `TEXTFLOWKIT_INPUT_ROOT` set, a confined
+  local input is staged and its decode is restricted to FFmpeg's self-contained
+  demuxers (`-format_whitelist`), and the `ffprobe` duration probe carries the
+  same whitelist. A playlist/manifest that would make the decoder open referenced
+  files is refused. The restriction covers a resume that re-decodes; a stage with
+  durable output is reused, not re-decoded. Owner runs without an input root stay
+  unrestricted.
+- **Atomic attempt ownership.** A worker pins the attempt generation it claimed;
+  every progress write, checkpoint write, and terminal finalize is guarded on it,
+  so a stale run cannot overwrite a newer attempt's label or verdict. The reopen
+  of a terminal row for resume is an atomic claim pinned to the observed attempt —
+  two callers racing one job id cannot both reopen it.
+- **Atomic worker startup and cancellation.** Worker-thread startup is atomic, and
+  the completion/cancellation race is decided in one place against the owned
+  attempt: the row becomes CANCELLED only if that generation carries an accepted
+  cancellation, DONE otherwise, so a finished DONE row can never still carry an
+  accepted cancel.
+- **DOCX identity.** Completed-output reuse for DOCX compares the archive bytes
+  with only the local and central ZIP time/date pairs blanked; every other byte
+  (member names and order, compression, flags, extra fields, comments, compressed
+  content) must be equal, and the comparison never inflates a member.
+- **Completed-stage reuse.** A run leaves a durable per-stage marker for each
+  expensive stage it finishes; resume reuses only stages finished for the
+  **requested configuration**, and a legacy coarse `postprocess` marker is honoured
+  only for the optional stages that record actually requested. The rule keys on
+  the marker, never on transcript metadata.
+- **Aggregate export preflight.** The whole requested format set is validated
+  (unsupported/duplicate names, then every dependency) and the aggregate rendered
+  bytes are bounded **before any destination file is written**, for every surface
+  that publishes output.
+- **Translation completeness.** The translator's result length is checked against
+  its input and every result is validated **before mutating any segment**: a
+  blank result for a non-blank segment raises and leaves the transcript exactly as
+  it was, rather than half-writing a set.
+- **Per-item batch validation.** Each batch entry is constructed and admitted
+  independently (HTTP and MCP): a non-object entry, a non-string/empty source, an
+  unsupported format, or an unusable engine is **that** entry's error, carrying its
+  original zero-based `index` and best-effort `source`, while the other entries
+  still queue, in submitted order. There is no whole-batch engine preflight.
+- **Terminal feedback.** A non-quiet CLI run streams live stage progress to
+  **stderr, flushed** (stdout stays clean for `--stdout`); quiet suppresses it.
+  Batch prints each item's result as it finishes. Job status exposes the recorded
+  stage.
+
+### Documentation corrections (DOC-001 – DOC-006)
+
+- **DOC-001** — the user manual now states that canonical saved/exported JSON
+  retains hidden segments and is an archive, not a redaction mechanism, and adds
+  a worked safe-publication-copy example that filters the copy without mutating
+  the stored transcript.
+- **DOC-002** — the adapter guide and manual now distinguish response shapes:
+  HTTP JSON returns a `transcript` object with page counts but no `next`, MCP
+  returns a JSON string under `content` and adds a `next` instruction, and HTTP
+  text reads carry no paging metadata. Time selection is described as
+  overlapping rather than clipped.
+- **DOC-003** — "same options" is replaced with a per-surface parameter matrix
+  (HTTP `formats` array vs MCP comma-separated string; HTTP batch options are
+  **per item**, MCP batch options are shared and expose **no**
+  `cookies_from_browser` parameter), and the batch contract now states that 202
+  means admission, not completion, with per-item indexed errors. MCP
+  `sources` is documented as a list of **strings**: a non-string entry (including
+  a nested object or a number) is that entry's own error, not a whole-call
+  refusal, while a string remains valid.
+- **DOC-004** — a full production settings reference (names, defaults, units,
+  required fields) is added to the adapter guide, and the production refusal of
+  browser-cookie submissions is stated across the adapter guide, the sources
+  guide, and `SECURITY.md`, including resume.
+- **DOC-005** — the install guide chooses the diarization install path (preserve
+  a working ROCm stack vs fresh CPU) **before** the first pip command, and the
+  manual's ROCm deep link now resolves to the actual heading.
+- **DOC-006** — new [architecture and lifecycle guide](docs/architecture.md)
+  maps the core/CLI/MCP/HTTP doors, single-owning-process SQLite, startup
+  recovery via the HTTP/MCP lifespans and the lazy executor, checkpoint reuse,
+  and output publication; the adapter guide's "reaped at startup" wording is
+  qualified to match. Linked from the README and `CONTRIBUTING.md`.
+
+The production settings reference lives in
+[docs/adapters.md](docs/adapters.md#production-settings-reference).
+
+### Deferred audit follow-ups — later fixes
+
+On 2026-10-01, the owner explicitly deferred the following findings from the
+full five-role audit. They remain open; they are not completed fixes, new release
+claims, or additions to the current core-bug repair goal. No release date is set.
+
+See [Later fixes in the roadmap](docs/roadmap.md#later-fixes--2026-10-01-audit)
+for the complete list and completion criteria. The current repair goal still
+covers decoder confinement, job lifecycle, publication/resume, translation and
+batch correctness, major terminal guidance/documentation, and its final gate.
+
+This changelog starts with the v0.1.7 release notes; published historical
+release notes remain on [GitHub Releases](https://github.com/scottconverse/textflowkit/releases).

{textflowkit-0.1.6 → textflowkit-0.1.7}/CONTRIBUTING.md

@@ -55,6 +55,13 @@ build of torch; see [docs/install.md](docs/install.md) for the torch-pinning tra
 Most tests do **not** need a GPU or a model download. If you add one that does,
 mark it so it can be skipped in CI.
 
+## How the pieces fit together
+
+[docs/architecture.md](docs/architecture.md) maps the core, CLI, MCP, and HTTP
+doors, the single-owning-process job lifecycle (including startup recovery),
+checkpoint reuse, and output publication. Read it before changing submission,
+executor, runner, or checkpoint behaviour.
+
 ## Pull requests
 
 - Keep the change scoped; state what it fixes.

{textflowkit-0.1.6 → textflowkit-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.6
+Version: 0.1.7
 Summary: Cross-platform media transcription toolkit: URL or file in, timestamped transcripts and subtitle files out.
 Project-URL: Homepage, https://www.textflowkit.org/
 Project-URL: Issues, https://github.com/scottconverse/textflowkit/issues
@@ -64,7 +64,7 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [GitHub releases](https://github.com/scottconverse/textflowkit/releases) ·
 [User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
 
-**Current release: [v0.1.6](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6).**
+**Current release: [v0.1.7](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.7).**
 
 The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
 Pages. GitHub remains the source and CI host; the website does not run the
@@ -140,6 +140,9 @@ the core; the interfaces are thin.
 Because the core owns the pipeline, adding a door is cheap — and adding a platform
 means writing one source adapter, not another tool.
 
+For the job lifecycle, process ownership, checkpoints, and output publication,
+see [docs/architecture.md](https://github.com/scottconverse/textflowkit/blob/main/docs/architecture.md).
+
 ## Recognized sources
 
 YouTube · TikTok · Facebook · Instagram · Vimeo · Twitch · Bilibili · Rumble ·
@@ -216,7 +219,7 @@ to preserve it.
 
 The same version's wheel and source archive are also on the
 [GitHub release page](https://github.com/scottconverse/textflowkit/releases/latest).
-Starting with the next release, every release published by this project's release
+Starting with v0.1.6, every release published by this project's release
 workflow carries a `SHA256SUMS` asset listing the SHA-256 hash of each wheel and
 source archive it contains, so you can check a download with
 `sha256sum -c SHA256SUMS`. Releases published before that change, v0.1.5
@@ -335,21 +338,43 @@ web frontend share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.6 release.** Core, CLI, MCP, and HTTP have automated
-coverage. This release is the post-v0.1.5 review repair set: security hardening
+**v0.1.7 release.** Core, CLI, MCP, and HTTP have automated
+coverage. This release is the 2026-10-01 audit repair set — the post-v0.1.6
+review follow-ups the owner accepted on 2026-10-01: a confined decoder boundary
+for rooted local inputs, atomic job-attempt ownership with atomic worker startup
+and cancellation finalization, DOCX completed-output identity, per-request
+completed-stage reuse, an aggregate export preflight, translation completeness
+and per-item batch validation, live terminal feedback, and major documentation
+corrections. Implementation was verified on a native-Windows source candidate with real CLI, HTTP and MCP speech, seven-format exports and completed resume. Release publication uses the tag workflow, which requires successful exact-commit main CI before PyPI uploads and creates the public GitHub release only afterward. Check the linked release for artifacts and workflow status; local source verification is not a fresh PyPI-install or individual-harness receipt.
+
+The v0.1.6 release was the post-v0.1.5 review repair set: security hardening
 for media acquisition and the HTTP and MCP adapters, safer subtitle wrapping and
 output-file publication, job and checkpoint storage corrections, an opt-in
 faster-whisper engine, a container example, and fail-closed release guards for
 tagged versions, README claims, and exact-commit CI.
 The v0.1.5 release added a speech-bearing self-test, full-media duration,
-retained word timings, optional PDF fonts, and tokenless PyPI publishing, and its
-live evidence is the only live evidence recorded on this page.
-Windows-native ROCm and a local Windows YouTube run on the v0.1.5 release commit were verified.
-That run's receipt records the clip, timestamps, and hashes; the checklist's
-recognized-speech assertion was added after it, so treat it as shape evidence for
-that commit rather than proof of what was said.
+retained word timings, optional PDF fonts, and tokenless PyPI publishing.
+Windows-native ROCm and a local Windows YouTube run on the v0.1.5 release commit
+were verified. That run's receipt records the clip, timestamps, and hashes; the
+checklist's recognized-speech assertion was added after it, so treat it as shape
+evidence for that commit rather than proof of what was said.
+The v0.1.6 release is public: the
+[v0.1.6 GitHub release](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6)
+and both [core](https://pypi.org/project/textflowkit/0.1.6/) and
+[fonts](https://pypi.org/project/textflowkit-fonts/0.1.6/) PyPI projects are
+live — that is the previous release's evidence, not a receipt for v0.1.7.
+Everything from here to the end of this section is the v0.1.6 release's
+historical record as published: it is not re-verified for v0.1.7, whose separate release evidence is not supplied by these historical paragraphs.
+Merged-main CI passed 16/16 on the tagged commit; the published wheel and
+sdist digests match the GitHub release assets and their SHA-256 list; and a fresh
+Windows Python 3.12 install of `textflowkit[export,mcp,http]==0.1.6` from PyPI
+passed `doctor`, `selftest`, and a tiny CPU transcription to JSON and PDF. A
+local native-Windows YouTube run on the same commit returned 3 timestamped
+segments and a whole-word `elephants` match; its receipt is stored outside this
+repository. One clip is not proof of the other 12 recognized platforms or of
+general accuracy.
 The GitHub-hosted YouTube attempt was blocked by a bot challenge, so hosted
-live transcription is not verified. No v0.1.6 tag, upload, or live run is verified here.
+live transcription is not verified.
 This does not imply that all 13 platforms or every harness workflow has been
 tested end to end. See the [user manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
 and [roadmap](https://github.com/scottconverse/textflowkit/blob/main/docs/roadmap.md).

{textflowkit-0.1.6 → textflowkit-0.1.7}/README.md

@@ -7,7 +7,7 @@ Cross-platform media transcription toolkit. **One core, one CLI, thin adapters.*
 [GitHub releases](https://github.com/scottconverse/textflowkit/releases) ·
 [User manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
 
-**Current release: [v0.1.6](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6).**
+**Current release: [v0.1.7](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.7).**
 
 The [static site deployment](https://github.com/scottconverse/textflowkit/blob/main/docs/site-deployment.md) is hosted on Cloudflare
 Pages. GitHub remains the source and CI host; the website does not run the
@@ -83,6 +83,9 @@ the core; the interfaces are thin.
 Because the core owns the pipeline, adding a door is cheap — and adding a platform
 means writing one source adapter, not another tool.
 
+For the job lifecycle, process ownership, checkpoints, and output publication,
+see [docs/architecture.md](https://github.com/scottconverse/textflowkit/blob/main/docs/architecture.md).
+
 ## Recognized sources
 
 YouTube · TikTok · Facebook · Instagram · Vimeo · Twitch · Bilibili · Rumble ·
@@ -159,7 +162,7 @@ to preserve it.
 
 The same version's wheel and source archive are also on the
 [GitHub release page](https://github.com/scottconverse/textflowkit/releases/latest).
-Starting with the next release, every release published by this project's release
+Starting with v0.1.6, every release published by this project's release
 workflow carries a `SHA256SUMS` asset listing the SHA-256 hash of each wheel and
 source archive it contains, so you can check a download with
 `sha256sum -c SHA256SUMS`. Releases published before that change, v0.1.5
@@ -278,21 +281,43 @@ web frontend share the job contract without blocking a request.
 
 ## Status
 
-**v0.1.6 release.** Core, CLI, MCP, and HTTP have automated
-coverage. This release is the post-v0.1.5 review repair set: security hardening
+**v0.1.7 release.** Core, CLI, MCP, and HTTP have automated
+coverage. This release is the 2026-10-01 audit repair set — the post-v0.1.6
+review follow-ups the owner accepted on 2026-10-01: a confined decoder boundary
+for rooted local inputs, atomic job-attempt ownership with atomic worker startup
+and cancellation finalization, DOCX completed-output identity, per-request
+completed-stage reuse, an aggregate export preflight, translation completeness
+and per-item batch validation, live terminal feedback, and major documentation
+corrections. Implementation was verified on a native-Windows source candidate with real CLI, HTTP and MCP speech, seven-format exports and completed resume. Release publication uses the tag workflow, which requires successful exact-commit main CI before PyPI uploads and creates the public GitHub release only afterward. Check the linked release for artifacts and workflow status; local source verification is not a fresh PyPI-install or individual-harness receipt.
+
+The v0.1.6 release was the post-v0.1.5 review repair set: security hardening
 for media acquisition and the HTTP and MCP adapters, safer subtitle wrapping and
 output-file publication, job and checkpoint storage corrections, an opt-in
 faster-whisper engine, a container example, and fail-closed release guards for
 tagged versions, README claims, and exact-commit CI.
 The v0.1.5 release added a speech-bearing self-test, full-media duration,
-retained word timings, optional PDF fonts, and tokenless PyPI publishing, and its
-live evidence is the only live evidence recorded on this page.
-Windows-native ROCm and a local Windows YouTube run on the v0.1.5 release commit were verified.
-That run's receipt records the clip, timestamps, and hashes; the checklist's
-recognized-speech assertion was added after it, so treat it as shape evidence for
-that commit rather than proof of what was said.
+retained word timings, optional PDF fonts, and tokenless PyPI publishing.
+Windows-native ROCm and a local Windows YouTube run on the v0.1.5 release commit
+were verified. That run's receipt records the clip, timestamps, and hashes; the
+checklist's recognized-speech assertion was added after it, so treat it as shape
+evidence for that commit rather than proof of what was said.
+The v0.1.6 release is public: the
+[v0.1.6 GitHub release](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6)
+and both [core](https://pypi.org/project/textflowkit/0.1.6/) and
+[fonts](https://pypi.org/project/textflowkit-fonts/0.1.6/) PyPI projects are
+live — that is the previous release's evidence, not a receipt for v0.1.7.
+Everything from here to the end of this section is the v0.1.6 release's
+historical record as published: it is not re-verified for v0.1.7, whose separate release evidence is not supplied by these historical paragraphs.
+Merged-main CI passed 16/16 on the tagged commit; the published wheel and
+sdist digests match the GitHub release assets and their SHA-256 list; and a fresh
+Windows Python 3.12 install of `textflowkit[export,mcp,http]==0.1.6` from PyPI
+passed `doctor`, `selftest`, and a tiny CPU transcription to JSON and PDF. A
+local native-Windows YouTube run on the same commit returned 3 timestamped
+segments and a whole-word `elephants` match; its receipt is stored outside this
+repository. One clip is not proof of the other 12 recognized platforms or of
+general accuracy.
 The GitHub-hosted YouTube attempt was blocked by a bot challenge, so hosted
-live transcription is not verified. No v0.1.6 tag, upload, or live run is verified here.
+live transcription is not verified.
 This does not imply that all 13 platforms or every harness workflow has been
 tested end to end. See the [user manual](https://github.com/scottconverse/textflowkit/blob/main/docs/user-manual.md)
 and [roadmap](https://github.com/scottconverse/textflowkit/blob/main/docs/roadmap.md).

{textflowkit-0.1.6 → textflowkit-0.1.7}/SECURITY.md

@@ -50,10 +50,53 @@ user accounts or multi-tenancy.
   `TEXTFLOWKIT_OUTPUT_ROOT` to confine less-trusted callers. With those roots
   set, paths outside them (including `..` and symlink escapes) are rejected.
   See `resolve_output_dir` and `resolve_input_path` in
-  `src/textflowkit/core/paths.py`. Confined local input is copied from a
-  path-verified open handle into isolated scratch before ffmpeg. Output paths
-  are rechecked at file publication. Keep configured roots non-writable by
-  untrusted local users to prevent races.
+  `src/textflowkit/core/paths.py`. Output paths are rechecked at file
+  publication. Keep configured roots non-writable by untrusted local users to
+  prevent races.
+
+- **The decoder boundary for confined input.** A local file can be a
+  *reference* to other files rather than media itself: an HLS/M3U playlist, an
+  ffmpeg concat script, a DASH manifest. The demuxer opens every path such a
+  file names. Confined local input is handle-verified and copied into isolated
+  scratch, but only the top-level file is copied, so a playlist inside the root
+  can name a file outside it — an absolute reference survives the copy
+  unchanged, and a relative one resolves against the scratch directory, where
+  `..` walks out. When an input root is set, every confined input is therefore
+  decoded under FFmpeg's `-format_whitelist`, listing only the demuxers this
+  product supports as *self-contained* starting formats:
+
+      wav, mp3, mov,mp4,m4a,3gp,3g2,mj2, matroska,webm, ogg, flac, aac
+
+  These are FFmpeg's own demuxer names (`ffmpeg -demuxers`), not the extension
+  list. A file whose content is not one of them — including a playlist or
+  manifest however it is named — is refused by FFmpeg itself, before any
+  reference is followed. The same restriction is applied to the `ffprobe`
+  duration check, which otherwise opens the staged file the same way.
+
+  This is the guarantee, stated exactly:
+
+  - **Confined local input cannot make FFmpeg open another file.** The demuxer
+    that would follow a reference is not selectable, so there is no reference to
+    check and none is followed. This is a decoder-format restriction, not a
+    filesystem sandbox.
+  - **It applies only to confined input** (an input root set) and only to the
+    media decode. Without an input root there is no boundary to protect, and the
+    documented workflow decodes what FFmpeg already decoded.
+  - **It rests on the demuxer list above.** A file that this build classifies as
+    one of those demuxers, but which in another FFmpeg build (or through a
+    container's own external-data mechanism) opens other files, is not covered.
+    The `-format_whitelist` names are checked against `ffmpeg -demuxers`; a
+    build whose demuxers differ is not verified here.
+  - **It is not a sandbox of FFmpeg or yt-dlp at large** (see "Not defended").
+
+- **Leading-byte manifest refusal (defense in depth).** On top of the decoder
+  whitelist, a confined input whose leading bytes are an HLS/M3U playlist
+  (`#EXT`), an MPEG-DASH manifest (`<`), or an ffmpeg concat script
+  (`ffconcat`) is refused before the staged copy is written, so a recognised
+  manifest leaves nothing behind. This is an extra layer, deliberately *not*
+  the boundary: it covers only the signatures in its list, and detection is by
+  content rather than extension. The decoder whitelist above is what holds if
+  this check is widened, narrowed, or removed.
 
 ### Not defended (by design — read before deploying)
 
@@ -64,10 +107,19 @@ user accounts or multi-tenancy.
   Streamable-HTTP MCP is separate and not covered by this Bearer middleware.
 - **No sandboxing of `ffmpeg` / `yt-dlp`.** They run as your user on input you
   supply. Media is untrusted data; treat a malformed file as you would any
-  untrusted input to those tools.
+  untrusted input to those tools. The confined-input decoder boundary above
+  limits which *formats* a confined input may be, and so which files the demuxer
+  can open; it does not confine the decoder process, its codecs, or anything
+  else on the system.
 - **Cookies are passed through, not stored.** `--cookies-from-browser` hands
   browser cookies to `yt-dlp` for content you are authorised to access. Using it
   to reach content you are not authorised to access is outside the intended use.
+  Browser-cookie input is a **developer/owner-profile** feature: while
+  `TEXTFLOWKIT_PROFILE=production`, every submission carrying the option is
+  refused before a job is written — on the CLI, MCP, and HTTP surfaces, and when
+  a saved request is resumed — because the server cannot distinguish an
+  owner-run session from a remote caller. See the [production settings
+  reference](docs/adapters.md#production-settings-reference).
 - **Transcript accuracy is not a security property.** Speech-to-text output
   contains errors and must not be relied on for legal, medical, safety-critical,
   or evidentiary purposes without human review.

{textflowkit-0.1.6 → textflowkit-0.1.7}/docs/adapters.md

@@ -1,6 +1,6 @@
 # Adapters and integration
 
-Current published release: [v0.1.6](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.6).
+Current published release: [v0.1.7](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.7).
 Start with the [user manual](user-manual.md) for everyday use. Harness versions
 in the compatibility table below identify **historical test sessions**, not
 the version of TextFlowKit currently published.
@@ -95,9 +95,52 @@ Tools: `list_sources`, `transcribe_media`, `submit_batch_media`, `resume_job`,
 Read-only tools carry `readOnlyHint: true`. Submission and export tools carry
 `openWorldHint: true`; resume and cancellation are marked as mutating.
 
-`transcribe_media` and `submit_batch_media` take the same options as the HTTP
-bodies above, `engine` included; a name that is unknown, or whose optional
-package is missing, comes back as `{"error": ...}` before any job is queued.
+The MCP tools share the **core** options with the HTTP bodies above, but the
+request *shapes* differ between surfaces - they are not interchangeable
+payloads. The table below is the contract; a caller must not build one from an
+HTTP batch item by hand.
+
+| Option | HTTP single (`POST /jobs`) / batch item | MCP `transcribe_media` | MCP `submit_batch_media` |
+|---|---|---|---|
+| Input | `source: string`, required | `source: string`, required | `sources: list[string]`, required |
+| `formats` | **list** of strings (e.g. `["json","srt"]`); default `json`,`srt`,`txt` | **comma-separated string** `"json,srt,txt"` | **comma-separated string** |
+| `language`, `output_dir`, `model`, `device`, `engine`, `diarize`, `translate_to` | same fields on the single item; on HTTP batch each item carries its **own** copy, applied only to that item | same | shared across all sources |
+| `cookies_from_browser` | accepted on the HTTP single `POST /jobs` and on each HTTP batch item | accepted | **not a supported parameter** - callers must not supply it |
+| Resume | batch wrapper `resume: bool`; single `POST /jobs/{id}/resume` | `resume_job` tool | `resume: bool` |
+
+The MCP batch tool's `cookies_from_browser` row is the one place the surfaces
+genuinely differ: `submit_batch_media`'s signature has no such parameter, so a
+caller cannot pass browser cookies through it — only through `transcribe_media`
+or an HTTP submission. On HTTP, batch options are **per item**: each entry of
+`jobs` is a full `TranscribeRequest`, so two items can name different models or
+languages. The MCP batch tool instead takes its options **once** and applies them
+to every source.
+
+`output_dir` omitted writes no rendered files, but a durable transcript is still
+kept: with `TEXTFLOWKIT_DB` set the transcript survives the process, so "no
+output files" is not "memory only."
+
+On `transcribe_media` an unknown engine name or a missing optional package comes
+back as `{"error": ...}` before any job is queued. On `submit_batch_media` each
+source is admitted independently, so such a refusal is that source's error in
+the returned `jobs` list - carrying its zero-based `index` and best-effort
+`source` - and the other sources are still queued, reported in submitted order.
+The MCP batch tool takes engine (and every other option) **once** for the whole
+call, so an unusable engine is not a per-source refusal: it means every item
+carries an admission error. The response `count` and each item's
+`state`/`error` describe **admission**, not completion: a queued item still has
+to be polled to a terminal state.
+
+**`sources` entries are expected to be strings.** The tool's schema types the
+argument as `list[Any]`, not `list[str]`, precisely so that a *bad entry* is that
+entry's own item error rather than a whole-call schema rejection: an entry that
+is not a string - a nested object, a number, or any other non-string value - is
+raised as a `TypeError` inside the per-item boundary and reported at its `index`
+while the remaining entries are still queued. A string is valid whether or not
+it is empty-but-shaped like a source; the error is *non-string*, not
+*non-object*. So the parameter is typed permissively but the contract is "one
+string per source" - pass `["https://...", "C:\\media\\clip.mp4"]`, not nested
+objects or numbers. A malformed entry is not a reason the whole batch fails.
 
 ### Harness configuration
 
@@ -152,19 +195,43 @@ textflowkit-http --host 127.0.0.1 --port 8767
 
 Both submission bodies (`POST /jobs` and each item of `POST /jobs/batch`) accept
 the same options: `source`, `language`, `formats`, `output_dir`, `model`,
-`device`, `engine`, `cookies_from_browser`, `diarize`, and `translate_to`.
+`device`, `engine`, `cookies_from_browser`, `diarize`, and `translate_to`. On
+`/jobs/batch` these are **per item**: each entry is its own full request, so an
+item's model/language/device apply only to that item (unlike the MCP batch tool,
+which takes one shared set for every source).
 `engine` defaults to `whisper` — openai-whisper on the torch stack: ROCm on AMD,
 CUDA on NVIDIA, CPU otherwise — and may be set to `faster-whisper`, the opt-in
 CTranslate2 engine for CPU and Apple Silicon that needs
 `pip install "textflowkit[faster-whisper]"`. The default is unchanged, and no
-speed or accuracy comparison between the engines is claimed. An unknown engine
-name, or a missing extra, is answered with **422 before a job record is written**;
-on `/jobs/batch` that refusal covers the whole request, so a fresh batch is never
-partly queued for one unusable engine. The choice is stored on the durable
-request and checked again when the job is resumed - except for a job that already
-finished, which is answered from its stored transcript and needs no engine. A
-resume refused for an unusable engine leaves the job's terminal state, error, and
-cancellation flag untouched, so nothing is left queued-less in `pending`.
+speed or accuracy comparison between the engines is claimed. On a **single**
+submission (`POST /jobs`) an unknown engine name or a missing extra is answered
+with **422 before a job record is written**. On `/jobs/batch` each item is
+admitted independently: an unusable engine (or any other per-item refusal - an
+unsupported format, an empty source) is reported as that item's error, in place,
+carrying its zero-based `index` and best-effort `source`, and the other items are
+still queued and reported in the submitted order. The envelope shape is the
+whole-request case: a batch body that fails `BatchRequest` — most obviously a
+`jobs` value that is not a list at all, but also a request body that does not
+decode to that model (a missing or non-object top-level body, or an invalid
+`resume`) — is a whole-request 422. An
+individual entry that is not an object (or carries a malformed field) is that
+entry's item error, never a whole-request refusal. The choice is stored on the
+durable request and checked again when the job is resumed - except for a job that
+already finished, which is answered from its stored transcript and needs no
+engine. A resume refused for an unusable engine leaves the job's terminal state,
+error, and cancellation flag untouched, so nothing is left queued-less in
+`pending`.
+
+**202 means admitted, not completed.** Both `POST /jobs` and `POST /jobs/batch`
+return a job handle as soon as work is queued; the response does not mean the
+transcription succeeded. `/jobs/batch` returns `{count, jobs}` where each entry
+carries its `index`, `source`, and either a `job_id`/`state` or an `error`, and
+the entry count always matches the number of submitted items. Poll each returned
+job to a terminal state (`done`, `error`, or `cancelled`) before treating it as
+finished. A missing or unusable **engine** is a per-item error on the batch route
+(HTTP 422 on the single route); a batch body that fails the envelope model — a
+`jobs` value that is not a list, or a body missing its required shape — is the
+whole-request 422 case.
 
 ### Developer mode and production profile
 
@@ -249,6 +316,48 @@ boundary described above and stands it down on `--allow-remote` /
 `TEXTFLOWKIT_ALLOW_REMOTE=1`, and should remain on loopback or behind a gateway;
 the JSON HTTP production token does not automatically secure it.
 
+**Browser cookies are refused in the production profile.** `core.service`
+rejects any submission carrying `cookies_from_browser` while
+`TEXTFLOWKIT_PROFILE=production`, before a job record is written. This applies to
+**every** surface that reaches the shared submission contract - a single or
+batch HTTP submission, an MCP submission, a CLI run, and the **resume** of a
+request saved earlier with the option - because the server cannot tell an
+owner-run CLI from a remote caller. Keep cookie-assisted jobs in the deliberate
+owner developer profile.
+
+#### Production settings reference
+
+Every numeric limit below is read by `core.service` at request time and must be a
+positive integer; a bad value fails the request closed rather than being ignored.
+The **five** "required" settings - `TEXTFLOWKIT_API_TOKEN`, `TEXTFLOWKIT_INPUT_ROOT`,
+`TEXTFLOWKIT_OUTPUT_ROOT`, `TEXTFLOWKIT_WORK_ROOT`, and `TEXTFLOWKIT_DB` - must be
+present (see the checks in `validate_production_config`) or the profile refuses to
+serve at all.
+
+| Environment variable | Default / requirement | Applies to |
+|---|---|---|
+| `TEXTFLOWKIT_PROFILE` | `developer`; set to `production` explicitly | Shared profile checks; JSON HTTP auth middleware |
+| `TEXTFLOWKIT_API_TOKEN` | **required**, ≥ 16 characters | JSON HTTP, every request including `/health` |
+| `TEXTFLOWKIT_INPUT_ROOT` | **required**, must be an existing directory | Local-input boundary |
+| `TEXTFLOWKIT_OUTPUT_ROOT` | **required**, created if absent | Rendered-output boundary |
+| `TEXTFLOWKIT_WORK_ROOT` | **required**, created if absent | Per-job scratch directory |
+| `TEXTFLOWKIT_DB` | **required**, on-disk SQLite (not `:memory:`) | Durable jobs; one owning process |
+| `TEXTFLOWKIT_MAX_REQUEST_BYTES` | 65,536 bytes (64 KiB) | Request body cap |
+| `TEXTFLOWKIT_RATE_PER_MINUTE` | 60 per client per process | Per-process rate limit, not a distributed quota |
+| `TEXTFLOWKIT_MAX_DURATION_SECONDS` | 14,400 s (4 hours) | Source and decoded duration |
+| `TEXTFLOWKIT_MAX_OUTPUT_BYTES` | 52,428,800 bytes (50 MiB) | Rendered output and read response |
+| `TEXTFLOWKIT_MAX_MEDIA_BYTES` | 1,073,741,824 bytes (1 GiB) | Download, media, and decoded-audio size |
+| `TEXTFLOWKIT_MAX_PENDING_JOBS` | 100 | Executor pending queue capacity |
+| `TEXTFLOWKIT_MAX_CONCURRENCY` | 1 | Executor worker count |
+| `TEXTFLOWKIT_EGRESS_PROXY` | **required for URL input**; absent means URL jobs fail closed | Operator SSRF-filtering egress |
+| `TEXTFLOWKIT_TRUSTED_PROXY_IPS` | unset = the TCP peer is the identity | Comma-separated IPs/CIDRs; a malformed value fails closed (503) |
+| `TEXTFLOWKIT_FFMPEG_TIMEOUT_SECONDS` | 600 s | Decode wall-clock; **all profiles**, not production-only |
+
+Two production read caps are numeric but are not environment variables: HTTP
+transcript paging defaults to `limit=100` and rejects `limit > 500` (HTTP 422),
+and HTTP search caps `limit` at 500 and `context` at 20. These are HTTP checks;
+MCP is a separate surface and does not share this token or these caps.
+
 ### Container example (Dockerfile and Compose)
 
 The repository root carries a `Dockerfile` and a `compose.yaml` that run this
@@ -400,10 +509,16 @@ TEXTFLOWKIT_DB=/var/lib/textflowkit/jobs.db textflowkit-mcp --transport http
 
 Backed by SQLite (WAL). Transcripts, outputs, and job states survive a restart.
 
-**Orphaned work is reaped at startup.** A job left in `pending` or `running` by a
-previous process has no worker, so it is failed with a reason rather than reported
-as a job that will never finish. This assumes **one owning process per store** -
-two processes sharing one `TEXTFLOWKIT_DB` would reap each other's live jobs.
+**Orphaned work is reaped before reads are served.** A job left in `pending` or
+`running` by a previous process has no worker, so it is failed with a reason
+rather than reported as a job that will never finish. The reap runs once per
+store from each server's startup lifespan (HTTP and Streamable-HTTP MCP both
+enter it) and, on the lazy path, the first time the executor starts from
+submission/enqueue - so a restarted server that only answers status/`/health`
+requests after the reap still reports the orphaned rows correctly. This assumes
+**one owning process per store** - two processes sharing one `TEXTFLOWKIT_DB`
+would reap each other's live jobs. See the [architecture guide](architecture.md)
+for the full lifecycle, ownership, and checkpoint map.
 
 ## Concurrency
 
@@ -578,10 +693,26 @@ If the transcript was translated, the optional word timings still refer to the
 also retains the original word timings.
 
 Filtering is time first, then offset/limit inside that window - `offset` counts
-from the start of the requested range, not the start of the transcript. The
-response reports `total_segments`, `returned`, and `has_more`, and when more
-remain it includes a `next` hint naming the offset to continue from. Truncation
-is never silent.
+from the start of the requested range, not the start of the transcript. Time
+selection keeps whole segments whose intervals **overlap** the inclusive window;
+it never trims a segment or a subtitle cue to the exact `start`/`end` seconds.
+`offset` counts **visible** segments inside the window, after hidden filtering.
+
+A slice reports `total_segments` (visible segments in the window), `returned`,
+and `has_more`. **What carries the "keep going" information differs by surface:**
+
+- **MCP** (`get_transcript`) adds a human-readable `next` string when more
+  segments remain.
+- **HTTP JSON** (`format=json`) returns `{job_id, total_segments, offset,
+  returned, has_more, start, end, transcript}` but **no `next` field**; a client
+  continues by requesting `offset + returned` within the same `start`/`end`.
+- **HTTP text** (`format=txt|srt|vtt|md`) returns the rendered text as the
+  response body with **no paging metadata at all**. Discover page boundaries with
+  `format=json` first, then fetch the text-format slice.
+
+So counts are never silent, but only MCP supplies a `next` instruction: an HTTP
+client that waits for one will stall, and one that ignores `has_more` will drop
+the remainder.
 
 ```jsonc
 // MCP
@@ -592,6 +723,7 @@ is never silent.
 ```bash
 # HTTP
 curl "http://127.0.0.1:8767/jobs/$ID/transcript?format=srt&start=300&end=320"
+curl "http://127.0.0.1:8767/jobs/$ID/transcript?format=json&offset=20&limit=20"
 curl "http://127.0.0.1:8767/jobs/$ID/search?q=neural%20network&context=1"
 ```
 
@@ -617,6 +749,31 @@ account:
   which is the point: an agent running on your behalf can reach your files.
 - Once `TEXTFLOWKIT_INPUT_ROOT` is set, paths outside that root, including
   `..` and symlink escapes, are rejected before the file is read.
+- A confined input must be **self-contained media**. With an input root set, the
+  decode is restricted to FFmpeg's self-contained starting formats — `wav`, `mp3`,
+  `mov`/`mp4`/`m4a`, `matroska`/`webm`, `ogg`, `flac`, `aac` (FFmpeg's demuxer
+  names, see `ffmpeg -demuxers`) — via `-format_whitelist`. A file that is
+  instead a playlist or manifest (HLS/M3U, MPEG-DASH, an ffmpeg concat script)
+  is refused by FFmpeg, even when it is inside the root: it names other files
+  that the decoder would open, and those references cannot be checked against
+  the root once the input has been copied into scratch. Detection is not by
+  extension — renaming the file does not change it. **Both** decode tools are
+  restricted this way: FFmpeg's decode and the `ffprobe` duration check carry the
+  same self-contained demuxer whitelist. The restriction holds on a **resume**
+  whose reacquired audio is decoded again, because the resume path stages the
+  confined input and applies the same whitelist; a stage whose output is already
+  recorded durable is reused and never re-decoded at all.
+
+  **What this is not.** The whitelist bounds what a confined input's *decode* can
+  open; it is not an OS sandbox, and it does not make an untrusted root safe to
+  point at. The root's own directories must still be kept from untrusted local
+  mutation, and the process keeps the full access of the account that started it
+  outside the decode. With no input root set there is no boundary at all: the
+  owner's own runs (CLI, MCP, HTTP under the developer profile) are deliberately
+  unconfined and decode playlists, manifests, and anything else FFmpeg already
+  decoded, exactly as before. Nothing here is a claim of complete URL-egress
+  protection; that belongs to the production egress-proxy requirement below, and
+  a local-file job needs no egress.
 
 ```bash
 TEXTFLOWKIT_INPUT_ROOT=/srv/media textflowkit-mcp --transport http