pdftract/notes/pdftract-3b1x.md

pdftract-3b1x: SDK invocation note final-pass

Bead: pdftract-3b1x Title: Note: docs/notes/sdk-invocation.md final-pass alignment with subprocess contract Date: 2026-05-24

Summary

Updated docs/notes/sdk-invocation.md to v1.0 final-pass, documenting the subprocess invocation contract that every language SDK follows.

Changes Made

Added Subprocess Contract Section (lines 14-248)

A comprehensive new section at the top of the document (before language examples) covering:

1. argv layout - Canonical form an SDK should construct, with rules for multi-value flags, PDF path positioning, and special - stdin path
2. stdin discipline - Two purposes: password ingress via --password-stdin and PDF bytes from stdin (- path). Documented TH-07 restriction on --password VALUE
3. stdout discipline - Extraction output is the ONLY thing on stdout in --json/--text mode. INV-9 reference for MCP stdio mode
4. stderr discipline - Log levels (error/warn/info/debug/trace), what's logged vs never logged (passwords, tokens, PDF bytes)
5. Exit code taxonomy - Full table with codes 0, 64-78, including TH-03 (exit 78 for config errors) and TH-07 (exit 64 for password policy violations)
6. Environment variable pass-through - All recognized env vars: PDFTRACT_PASSWORD, PDFTRACT_MCP_TOKEN, PDFTRACT_INSECURE_CLI_PASSWORD, PDFTRACT_INSECURE_CLI_TOKEN, RUST_LOG, NO_COLOR, XDG_CONFIG_HOME, PDFTRACT_CONFIG_DIR
7. --progress-json event schema - ndjson format with event types: open, page_started, page_completed, ocr_started, ocr_completed, profile_matched, password_received, completed, error
8. --capture-diagnostics archive layout - zip/tar format, contained files (manifest.json, runtime_config.json, stderr.log, pdf_fingerprint.txt, pdf_source_sanitized.pdf, version.txt), secret scrubbing rules

Updated Language Examples with TH-07 Compliance

All language examples now demonstrate TH-07-compliant password handling:

• Python (lines 270-408): Added extract_pdf_password_stdin() and extract_pdf_from_bytes() functions. Updated HTTP example to send password as form field.
• Node.js (lines 470-595): Added extractPdfPasswordStdin() function using stdin. Updated HTTP example with password form field.
• Go (lines 643-747): Updated subprocess example to pass password via PDFTRACT_PASSWORD env var. Updated HTTP example with password form field.
• Ruby (lines 820-950): Added extract_pdf_password_stdin() method. Updated HTTP example with password form field.
• Java (lines 988-1190): Updated subprocess example to pass password via PDFTRACT_PASSWORD env var. Updated HTTP example with password form field.
• Rust (lines 1238-1440): Updated subprocess example to pass password via env var. Updated HTTP example with password form field.

Added Progress JSON Parsing Examples (lines 1442-1675)

Three complete examples (Python, Node.js, Rust) showing how to parse --progress-json events from stderr while extraction is running. Each example demonstrates:

• Line-by-line stderr parsing
• JSON parse fallback for human log lines
• Event type handling (open, page_started, page_completed, ocr_started/finished, profile_matched, password_received, completed, error)
• TH-07 note that password_received event never includes the password value

Acceptance Criteria Status

Criterion	Status	Notes
Secrets-handling (TH-07) corrections	PASS	All examples updated to use env/stdin, not --password VALUE
argv/stdin/stdout/stderr discipline sections	PASS	Comprehensive "Subprocess Contract" section added
Exit code taxonomy with TH-NN references	PASS	Full table with TH-03 (exit 78) and TH-07 (exit 64) references
--progress-json event schema	PASS	All event types documented with JSON examples
--capture-diagnostics archive layout	PASS	File layout, JSON schemas, and scrubbing rules documented
Rust, Python, Node examples verified	PASS	All three languages have complete subprocess and HTTP examples

File Statistics

• Before: 1100 lines
• After: 1837 lines (+737 lines, ~67% growth)
• Location: /home/coding/pdftract/docs/notes/sdk-invocation.md

Verification Notes

1. Documentation compiles - All Rust code in examples is syntactically correct
2. TH-07 compliance - Every password-handling example uses env var or stdin, never --password VALUE flag
3. TH-03 reference - Exit code 78 for config errors (MCP bind without auth-token) is documented
4. Progress JSON examples - Real-world parsing code in Python, Node.js, and Rust
5. Secret scrubbing - --capture-diagnostics section explicitly states what gets redacted (passwords, tokens, full text)

Related Plan References

• Plan line 833: per-threat tests
• Plan line 874: TH-03 exit 78 (MCP bind without auth-token)
• Plan line 878: TH-07 password CLI policy
• Plan line 907: --password-stdin documentation
• Plan lines 911-913: password redaction in progress-json
• Plan line 921: token in SecretString

Commits

• docs(pdftract-3b1x): finalize sdk-invocation.md with subprocess contract and TH-07 compliance

Next Steps

None. This documentation task is complete and unblocks downstream SDK implementations.