textflowkit 0.1.6__tar.gz → 0.1.8__tar.gz

{textflowkit-0.1.6 → textflowkit-0.1.8}/.github/workflows/publish-pypi.yml

@@ -149,12 +149,24 @@ jobs:
           packages-dir: dist/main/
 
   publish-github-release:
-    # Deliberately no `if:` here. The implicit `success()` plus the default skip
-    # propagation is the gate that matters: a core upload that failed or was
-    # skipped for any reason skips this job too, so a failed release cannot end
-    # in a public GitHub release. Adding a status check function here would
-    # weaken that, not strengthen it.
+    # The release exists only to advertise a core version that is on PyPI, so it
+    # runs exactly on a successful core upload and nothing else. The condition is
+    # written out rather than left implicit for the same reason as the core
+    # upload above: a status check function must defeat skip propagation. An
+    # implicit `success()` here is still subject to it, and on a reused fonts
+    # release the workflow-wide propagation from the *skipped* fonts job reaches
+    # this job through `publish-main` and its skipped fonts dependency - v0.1.7
+    # initially skipped the release even though core reached PyPI, and the
+    # recovery published it.
+    #
+    # `always()` would also defeat the propagation, but it runs the job in a
+    # cancelled run too, so it is not used. Only a `success` core upload reaches
+    # the release: a failed, skipped or cancelled core upload, a cancelled run,
+    # and a build that did not succeed all leave no public release, so the
+    # release can never advertise a core version that is not on PyPI.
     needs: publish-main
+    if: >-
+      ${{ !cancelled() && needs.publish-main.result == 'success' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write

textflowkit-0.1.8/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+## v0.1.8 — 2026-10-02
+
+The 2026-10-02 audit-lite repair release. Core version: 0.1.8; unchanged optional fonts: 0.1.6. It carries the four fixes for the post-release audit-lite of 2026-10-01 (findings AL-001 – AL-004). Release artifacts and publication status are recorded on [GitHub Releases](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8). Local source-candidate verification does not establish installed-package or individual harness compatibility.
+
+### Engineering fixes
+
+- **AL-001 — CLI owning-process startup recovery.** A CLI invocation that was
+  interrupted left its PENDING/RUNNING row active; because the CLI submits with
+  `background=False` it never started the recovering executor, so a later
+  `--resume` read the orphan as "already active" and refused a job whose expensive
+  work was saved. Recovery now runs once per owning process at the CLI's
+  process/store boundary (`cli.main`), before single or batch resume selection,
+  through the shared per-store owner. It is deliberately **not** an unconditional
+  reap in every `submit_request(background=False)`: an embedding process can hold
+  genuinely live work. A recovery write failure is reported as a clear error with
+  a nonzero exit, not a false success or a raw traceback. The documented
+  one-owning-process-per-database model is unchanged.
+- **AL-002 — preserve the completed transcript across resume setup failures.** The
+  source checkpoint serialized the local transcript (still `None`) before
+  hydrating the previous transcript, so a directory/`mkdtemp` failure replaced a
+  durable completed transcript with `null` while still listing `transcribe` as
+  finished. Reuse is now hydrated and validated **before** any directory setup,
+  and a replacement snapshot can no longer drop a still-finished transcript. A
+  changed local source is still refused, stages are never falsely marked complete,
+  and a healthy retry reuses the recognized work.
+
+### Documentation corrections
+
+- **AL-003 — MCP batch cookie capability.** The adapter guide said
+  `submit_batch_media` has no `cookies_from_browser` parameter. It does: the tool
+  accepts one shared value and forwards it to every request, and the production
+  refusal is enforced by the same shared guard as the other surfaces. The matrix
+  and paragraph (and the historical DOC-003 changelog text) were corrected, with a
+  schema-consistency regression test that reads the real SDK-generated tool schema.
+- **AL-004 — roadmap evidence.** The POSIX file-mode and fonts-reuse follow-ups
+  are marked done against their exact receipts: current-main CI run 36961982098
+  (12 OS/Python test jobs + three installed-wheel jobs + Ruff) verifies POSIX modes
+  on Linux/macOS, and release-workflow run 36961162844 built the reused 0.1.6
+  fonts, skipped the fonts upload, and published core to PyPI. The GitHub-release
+  job skip, its manual recovery, and the PR #23 condition repair are recorded
+  without claiming the original workflow was all green or the repaired automatic
+  path has been live-tested. The v0.1.7 history and version are preserved.
+
+## 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 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.
+  *Correction (2026-10-01, audit-lite AL-003):* the v0.1.7 text of this entry
+  claimed the MCP batch tool exposes **no** `cookies_from_browser` parameter.
+  That was wrong. `submit_batch_media` accepts `cookies_from_browser` and
+  forwards the one shared value to every request it builds; the production
+  refusal is enforced by the same shared guard as the other surfaces. The
+  adapter guide was corrected to match the generated tool schema.
+- **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.8 release notes, followed by 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.8}/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.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: textflowkit
-Version: 0.1.6
+Version: 0.1.8
 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.8](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8).**
 
 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.8 release.** Core, CLI, MCP, and HTTP have automated
+coverage. This release carries the four fixes for the 2026-10-01 post-release
+audit-lite (findings AL-001 – AL-004): CLI owning-process startup recovery so an
+interrupted run's saved work can be resumed instead of being refused as
+"already active", preservation of the completed transcript across resume setup
+failures, a correction to the MCP batch cookie capability, and corrected roadmap
+evidence receipts. It builds on the v0.1.7 audit repair set and the v0.1.6
+review repairs that precede it. The preceding v0.1.7 source candidate was verified with real CLI, HTTP and MCP speech, seven-format exports and completed resume. The v0.1.8 runtime fixes were independently checked through fresh-process CLI restart probes, real SQLite setup-failure tests, and the full Windows test suite; those checks are not new individual-harness receipts. 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.8.
+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.8, 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.8}/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.8](https://github.com/scottconverse/textflowkit/releases/tag/v0.1.8).**
 
 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.8 release.** Core, CLI, MCP, and HTTP have automated
+coverage. This release carries the four fixes for the 2026-10-01 post-release
+audit-lite (findings AL-001 – AL-004): CLI owning-process startup recovery so an
+interrupted run's saved work can be resumed instead of being refused as
+"already active", preservation of the completed transcript across resume setup
+failures, a correction to the MCP batch cookie capability, and corrected roadmap
+evidence receipts. It builds on the v0.1.7 audit repair set and the v0.1.6
+review repairs that precede it. The preceding v0.1.7 source candidate was verified with real CLI, HTTP and MCP speech, seven-format exports and completed resume. The v0.1.8 runtime fixes were independently checked through fresh-process CLI restart probes, real SQLite setup-failure tests, and the full Windows test suite; those checks are not new individual-harness receipts. 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.8.
+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.8, 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.8}/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.